Notificación de débito

WEBHOOKdebit-incoming

Para las adhesiones suscriptas a Autopay, tapi notifica cada factura nueva enviando este webhook al endpoint del cliente.

Objetivo

Avisar al cliente que hay una factura para debitar de la cuenta del usuario final y entregarle el token necesario para confirmar el débito.

Request

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	String	Sí	tapi envía el payload como application/json.

Body Parameters

Parámetro	Tipo	Requerido	Descripción
type	String	Sí	Siempre debit-incoming.
agendaId	String	Sí	Identificador de la adhesión.
modalityId	UUID	Sí	Identificador de la modalidad del servicio.
companyCode	String	Sí	Código de la empresa.
amount	Number	Sí	Monto a debitar de la cuenta del usuario final.
currency	String	Sí	Moneda del monto.
exchangeDetail	Object[]	No	Detalle de conversión cuando aplica.
queryData	Object[]	Sí	Identificadores del servicio.
operationId	UUID	Sí	Identificador de la operación, se usa después en GET /operation/{operationId}.
expirationDate	Date	Sí	Fecha de vencimiento de la factura.
details	Object[]	No	Detalles adicionales de la deuda.
externalClientId	String	Sí	Identificador del usuario final.
taskToken	String	Sí	Token de continuidad. Hay que devolverlo tal cual en el confirm.
hash	String \| null	No	Firma del payload. Viene null si el cliente no tiene una publicKey configurada.

Ventana de confirmación: 300 segundos. Desde que tapi envía el webhook debit-incoming, la fintech tiene 5 minutos para llamar a POST /automatic-debit/confirm con el taskToken recibido. Si no confirma dentro de esa ventana, la notificación expira y el débito pasa a un ciclo de reintentos. Este valor es configurable por cliente; 300 segundos es el default.

El 200 OK confirma únicamente la recepción del mensaje, no el débito. El débito se confirma en una llamada aparte a POST /automatic-debit/confirm.

El taskToken es el que vincula tu confirmación con esta notificación puntual. Guardalo y devolvelo sin modificar en el campo token del confirm. Un token vencido o alterado produce AD0002.

hash sólo trae una firma si tu cliente tiene una publicKey configurada en tapi. Si no, el campo llega en null. Contemplá ese caso antes de validar la firma.

Response

Response Body

Parámetro	Tipo	Descripción
(sin cuerpo / no body)	—	El cliente debe responder 200 OK para acusar recibo de la notificación. No se espera cuerpo en la respuesta.

Consideraciones

Una vez debitada la cuenta del usuario final, el débito se confirma con POST /automatic-debit/confirm usando el taskToken de esta notificación.

Ver la librería de errores de esta referencia

CLIENT LIBRARIES

REQUEST EXAMPLE

curl --request POST \
--url https://tu-servidor.com/webhooks/debit-incoming \
--header 'x-authorization-token: YOUR_TOKEN_HERE' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
  "type": "debit-incoming",
  "modalityId": "51ea6bf3-819f-44cf-9df7-5eb25b404150",
  "companyCode": "MX-S-77777",
  "amount": 68,
  "currency": "MXN",
  "operationId": "00000000-0000-4000-8000-000000000001",
  "externalClientId": "external-client-mock",
  "agendaId": "external-client-mock#51ea6bf3-819f-44cf-9df7-5eb25b404150#9999999999",
  "taskToken": "AAAAKgAAAAIAAAAAAAAAA...",
  "expirationDate": "2026-11-22",
  "hash": "a3f5c8e1b2d4..."
}'

Recomendamos ingresar en Desktop

Referencia API