Debi API (2022-08-01)

Debi (anteriormente TuCuota) tiene una API REST. Nuestra API tiene direcciones URL predecibles orientadas a los recursos, acepta solicitudes JSON, devuelve respuestas JSON y utiliza códigos de respuesta, autenticación y verbos HTTP estándar.

Las URLs de la API de Debi API son:

• Producción: https://api.debi.pro/
• Sandbox: https://api.debi-test.pro/

Content type

La API de Debi sólo soporta JSON. No te olvides de incluir el siguiente header en tus requests.

Content-Type Header

Content-Type: "application/json"

La API solo está disponible a través de HTTPS. Intentar acceder a la API a través de una conexión HTTP no segura devolverá un error tls_required.

Crear una clave API

Para crear nuevas claves API, visite la sección de desarrolladores de nuestro sitio.

Para cada entorno (producción y sandbox), encontrará dos tipos de claves de API:

• Pública (pk_...): puede aparecer en su código del lado del cliente para tokenizar los métodos de pago.
• Secreta (sk_...): Para ser utilizado en el lado del servidor. Debe ser secreto y almacenarse de forma segura en el código de su aplicación para comunicarse con la API de Debi.

Para autenticarse, debe utilizar la clave de API en un Header del request HTTP al realizar solicitudes en la API.

Example Authentication Header

Authorization: Bearer sk_live_...

Todas las solicitudes de API deben realizarse a través de HTTPS. Las llamadas realizadas a través de HTTP fallarán. Las solicitudes de API sin autenticación también fallarán.

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.

Respuestas de Error

Esta API devuelve códigos de error legibles por máquina y mensajes de error legibles por humanos cuando hay un error.

Ejemplos

Error de Validación

{
  "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."]
  }
}

Error Genérico

{
  "message": "Unauthenticated."
}

La API admite la idempotencia para volver a intentar solicitudes de forma segura sin realizar accidentalmente la misma operación dos veces. Esto es útil cuando una llamada API se interrumpe en tránsito y no recibe una respuesta. Por ejemplo, si una solicitud para crear un pago no responde debido a un error de conexión a la red, puede volver a intentar la solicitud con la misma clave de idempotencia para garantizar que no se cree más de un cargo.

Para realizar una solicitud idempotente, envía un encabezado Idempotency-Key: <key> adicional en la llamada HTTP.

La idempotencia funciona guardando el código de estado y el contenido de la primera solicitud realizada para cualquier clave de idempotencia dada, independientemente de si tuvo éxito o no. Las solicitudes posteriores con la misma clave devuelven el mismo resultado, incluidos los errores 500.

Una clave de idempotencia es un valor único generado por el cliente que el servidor utiliza para reconocer reintentos posteriores de la misma solicitud. La forma en que crea claves únicas depende de usted, pero sugerimos usar UUID V4 u otra cadena aleatoria con suficiente entropía para evitar colisiones.

Las claves son elegibles para eliminarse del sistema después de que tengan al menos 24 horas de antigüedad, y se genera una nueva solicitud si una clave se reutiliza después de que se eliminó la original. La capa de idempotencia compara los parámetros entrantes con los de la solicitud original y los errores a menos que sean los mismos para evitar el uso indebido accidental.

Los resultados solo se guardan si un extremo de la API comenzó a ejecutarse. Si los parámetros entrantes fallaron en la validación o la solicitud entró en conflicto con otra que se estaba ejecutando al mismo tiempo, no se guarda ningún resultado idempotente porque ningún extremo de la API comenzó a ejecutarse. Es seguro volver a intentar estas solicitudes.

Todas las solicitudes POST aceptan claves de idempotencia. El envío de claves de idempotencia en solicitudes GET y DELETE no tiene ningún efecto y debe evitarse, ya que estas solicitudes son idempotentes por definición.

Los siguientes objetos tienen un parámetro metadata que puedes usar para guardar pares de clave-valor:

• Clientes
• Adhesiones
• Pagos
• Devoluciones
• Métodos de Pago
• Suscripciones

La metadata es útil para almacenar información estructurada adicional sobre un objeto.

No almacene información confidencial (números de cuentas bancarias, detalles de tarjetas, etc.) como metadata.

Todos los recursos de la API pueden listarse a través de métodos de la API. Por ejemplo, puede obtener pagos, obtener clientes y obtener suscripciones. Estos métodos API de lista comparten una estructura común, tomando al menos estos tres parámetros: limit, starting_after y ending_before.

La respuesta de un método API de lista representa una sola página en un orden cronológico inverso. Si no especificas starting_after o ending_before, recibirás la primera página de este objecto, que contiene los objetos más nuevos. Puede especificar un ID en el campo starting_after para obtener la página de objetos más antiguos que aparecen inmediatamente después del objeto en cuestión. De manera similar, puedes especificar ending_before para recibir una página de objetos más nuevos que ocurren inmediatamente antes del objeto en cuestión. Los objetos de una página siempre aparecen en orden cronológico inverso. Solo se puede usar starting_after o ending_before.

Cada request a la API tiene un identificador de request asociado. Puede encontrar este valor en el header Request-Id. También puede encontrar estos IDs en logs de requests en su Panel.

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

En modo sandbox, las siguientes tarjetas de prueba y cuentas bancarias se pueden usar para crear pagos que producen respuestas específicas útiles para probar diferentes escenarios.

Si creas una tarjeta con el número 4000000320000021, recibirás un evento payment_method.automatically_updated similar al que recibirías durante una renovación de una tarjeta de crédito.

Los webhooks son URLs que puedes configurar para recibir notificaciones sobre eventos que suceden en tu cuenta de Debi. La mayoría de los usuarios configuran los webhooks desde el panel, que proporciona una interfaz de usuario para registrar y probar sus webhooks.

Webhook de ejemplo:

{
  "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"
}

Cuando ocurre un evento en su cuenta, lo enviaremos a cada webhook habilitado como una solicitud POST.

Tipos de eventos de Webhooks

• checkout.session.async_payment_failed
• checkout.session.async_payment_succeeded
• checkout.session.completed
• checkout.session.expired
• customer.created
• customer.disabled
• customer.restored
• customer.updated
• gateway.created
• gateway.disabled
• gateway.enabled
• gateway.updated
• import.processed
• mandate.created
• mandate.restored
• mandate.revoked
• payment.cancelled
• payment.created
• payment.retrying
• payment.updated
• payment_method.automatically_updated
• payment_method.created
• payment_method.updated
• refund.approved
• refund.created
• refund.failed
• subscription.automatically_paused
• subscription.cancelled
• subscription.created
• subscription.finished
• subscription.paused
• subscription.resumed
• subscription.updated
• user.updated_available_brands

Prueba de los webhooks en entornos locales

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 Debi can reach it with HTTP requests. If you’re working locally, the easiest way to do this is with ngrok.

Asegurando los Webhooks

Debi signs the webhook events it sends to your endpoints by including a signature in each event’s Debi-Signature header. This allows you to verify that the events were sent by Debi, 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.

Debi 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, Debi starts to sign each webhook it sends to the endpoint.

Webhooks authenticity validation steps

Debi 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.

Este objeto representa a un cliente de su organización. Le permite crear suscripciones y realizar un seguimiento de los pagos que pertenecen al mismo cliente.

Los eventos son nuestra forma de avisarte cuando sucede algo interesante en tu cuenta. Cuando ocurre un evento, creamos un nuevo objeto Evento. Por ejemplo, cuando se actualiza un pago, creamos un evento de pago actualizado. Tenga en cuenta que muchas solicitudes de API pueden provocar la creación de varios eventos. Por ejemplo, si crea una nueva suscripción para un cliente, recibirá un evento creado por la suscripción del cliente y un evento creado por el pago.

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.

Un gateway es una institución que autoriza y facilita los pagos. Puede ser un procesador de pagos, un banco o una red de tarjetas. En Debi, el objeto gateway representa la configuración específica y las credenciales que tu empresa utiliza para acceder a cada servicio.

Una Importación es un objeto que contiene datos para ser creados en Debi. Como estos objetos pueden ser grandes, se crearán y procesarán más tarde. Puede comprobar el estado de la importación.

Un Link es una URL compartible que llevará a sus clientes a una página de pago/adhesión. Los Links pueden crear adhesiones, pagos o suscripciones fácilmente. Un Link se puede compartir y utilizar varias veces.

Cuando un cliente abre un Link de pago, el siguiente paso creará una nueva Sesión de pago para mostrar la página. Puede utilizar los eventos de la Sesión de pago para realizar un seguimiento de los resultados.