TuCuota serves a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The base URLs for the TuCuota API are:

• Live: https://api.tucuota.com/v1/
• Sandbox: https://sandbox.tucuota.com/api/

Content types

TuCuota API supports only JSON content types. Make sure to include the following header on your requests.

Content-Type Header

Content-Type: "application/json"

The API is only available over HTTPS. Attempting to access the API over an unsecured HTTP connection will return a tls_required error.

Get an API key

To create new API keys, please visit the developers section of our site.

For each environment (live and test) yo'll find two types of API Keys:

• Publishable (pk_...): can be publicly-accessible in your web client-side code to tokenize payment information.
• Secret (sk_...): To be used on the server-side. Must be secret and stored securely in your application's code to call TuCuota APIs.

To authenticate you must provide the API key in an Authorization request header (using the Bearer authentication scheme) when making API requests.

Example Authentication Header

Authorization: Bearer sk_live_...

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

This API uses HTTP status codes to communicate with the API consumer.

• 200 OK - Response to a successful GET, PUT, PATCH or DELETE.
• 201 Created - Response to a POST that results in a creation.
• 204 No Content - Response to a successful request that won't be returning a body (like a DELETE request).
• 400 Bad Request - Malformed request.
• 401 Unauthorized - When no or invalid authentication details are provided.
• 403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource.
• 404 Not Found - When a non-existent resource is requested.
• 405 Method Not Allowed - Method not allowed.
• 406 Not Acceptable - Could not satisfy the request Accept header.
• 415 Unsupported Media Type - Unsupported media type in request.
• 422 Unprocessable Entity - Form validation errors.

Error response

This API returns both, machine-readable error codes and human-readable error messages when there's an error.

Example

Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "organization_name": ["El campo debe tener algún valor."],
    "mobile_number": ["El campo debe tener algún valor."],
    "province": ["El campo debe tener algún valor."],
    "locality": ["El campo debe tener algún valor."],
    "address": ["El campo debe tener algún valor."]
  }
}

Generic Error

{
  "message": "Unauthenticated."
}

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a payment does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one charge is created.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request.

Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Keys are eligible to be removed from the system after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

The following objects have a metadata parameter that you can use this parameter to attach key-value data:

• Customer
• Mandate
• Payment
• Refund
• Payment Method
• Subscription

Metadata is useful for storing additional, structured information on an object.

Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list payments, list customers, and list subscriptions. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

The response of a list API method represents a single page in a reverse chronological stream of objects. If you do not specify starting_after or ending_before, you will receive the first page of this stream, containing the newest objects. You can specify starting_after equal to the object ID value of an item to retrieve the page of older objects occurring immediately after the named object in the reverse chronological stream. Similarly, you can specify ending_before to receive a page of newer objects occurring immediately before the named object in the stream. Objects in a page always appear in reverse chronological order. Only one of starting_after or ending_before may be used.

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard.

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

HTTP Methods

This API uses HTTP verbs (methods) as following:

• GET - Read - used to read (or retrieve) a representation of a resource,
• POST - Create - used to create new resources. In particular, it's used to create subordinate resources.
• PUT - Update/Replace - used for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful request, replaces identified resource with the request body.
• PATCH - Update/Modify - used for modify capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
• DELETE - Delete - used to delete a resource identified by a URI.

Representation of Date and Time

All exchange of date and time-related data MUST be done according to RFC339 standard.

Versioning

This API uses Api-Version header to identify requested version. Every minor version SHOULD be backward compatible. However, major versions MAY introduce breaking changes.

Api-Version:

This header SHOULD be present in every request. If not, API MUST use the newest available major release.

If requested version is not available, API SHOULD try to fall back to the next available minor release.

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version of the API is 2022-02-14.

Resource IDs

This API uses short non-sequential url-friendly unique ids. Every resource id MUST consists of 12 url-friendly characters: A-Z, a-z, 0-9, _ and -.

Example

PY6b3Rr6nRMo

In sandbox mode the following test cards and CBUs can be used to create payments that produce specific responses useful for testing different scenarios.

* Using the visa number 4532417816926690 will also trigger a payment_method.automatically_updated event, which informs that the payment method number has been changed automatically.

Webhooks are endpoints you can configure to be notified about events that happen in your TuCuota account. Most users configure Webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints.

Example webhook:

{
  "id": "EVPYeJeyeJ7r",
  "created_at": "2019-05-23T20:18:28-0300",
  "data": {
    "object": {
      "id": "CS9PL8eeo8aB",
      "paid": false,
      "amount": 1600,
      "status": "pending_submission",
      "gateway": "GWd1e9nQwK7v",
      "currency": "ARS",
      "customer": {
        "id": "CS9PL8eeo8aB",
        "name": "Máximo Irizarry",
        "email": "mirrizarry@paez.com",
        "livemode": true,
        "metadata": { "key": "value" },
        "created_at": "2018-05-01T11:45:14-0300",
        "updated_at": "2018-05-01T11:45:14-0300",
        "gateway_identifier": "001234",
        "mobile_number": "+5493812596655",
        "identification_type": "",
        "identification_number": ""
      },
      "livemode": true,
      "metadata": { "key": "value" },
      "retryable": false,
      "created_at": "2018-05-01T11:45:14-0300",
      "updated_at": "2018-05-01T11:45:14-0300",
      "charge_date": "2019-05-15",
      "description": "Pago extra",
      "subscription": null,
      "name": "Máximo Irizarry",
      "email": "mirrizarry@paez.com",
      "gateway_identifier": "456700",
      "mobile_number": "+5493812596655",
      "identification_type": "",
      "identification_number": ""
    }
  },
  "livemode": true,
  "resource": "payment",
  "resource_id": "PY6b3Rr6nRMo",
  "type": "payment.retrying"
}

When an event occurs in your account, we’ll send it to every enabled webhook endpoint as a POST request.

Webhooks types

• customer.created
• customer.disabled
• customer.restored
• customer.updated
• gateway.created
• gateway.disabled
• gateway.updated
• payment.cancelled
• payment.created
• payment.retrying
• payment.updated
• payment_method.automatically_updated
• payment_method.created
• payment_method.updated
• subscription.cancelled
• subscription.created
• subscription.finished
• subscription.paused
• subscription.resumed
• subscription.updated
• user.updated_available_brands

Testing the webhooks in local environments

You can easy create test webhooks using https://webhook.site/ With that you will be able to see what we are sending to our API consumers.

Also, to start integrating the webhooks, your code will need to be accessible from the internet so TuCuota can reach it with HTTP requests. If you’re working locally, the easiest way to do this is with ngrok.

Webhooks security

TuCuota signs the webhook events it sends to your endpoints by including a signature in each event’s TuCuota-Signature header. This allows you to verify that the events were sent by TuCuota, not by a third party.

Before you can verify signatures, you need to retrieve your endpoint’s secret "Secreto webhook" from your webhooks in our developers panel. Add or select the endpoint you want to obtain the secret for, then click the "mostrar" button.

TuCuota generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, note that the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on. After this setup, TuCuota starts to sign each webhook it sends to the endpoint.

Webhooks authenticity validation steps

TuCuota generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

The timestamp (as a string) The character . The actual JSON payload (that is, the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

This object represents a customer of your organization. It lets you create subscriptions and track payments that belong to the same customer.

Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when a payment updates, we create a payment.updated event. Note that many API requests may cause multiple events to be created. For example, if you create a new subscription for a customer, you will receive both a customer.subscription.created event and a payment.created event.

Los eventos ocurren cuando cambia el estado de otro recurso API. El estado del recurso al momento del cambio está embebido en el campo data del evento. Por ejemplo, un evento de payment.updated contendrá un pago y un evento customer.created contendrá un cliente.

A gateway is an object

An Import is an object which contains data to be created in TuCuota. As these objects may be big, they will be created and processed later. You can check the status of the import.

A link is a shareable URL that will take your customers to a hosted page. Links can create manddates, payments, or subscription easily. A link can be shared and used multiple times.

When a customer opens a payment link, the next step will create a new checkout session to render the page. You can use checkout session events to track the results.