Introducción

Esta guía te guiará a través de la realización de tu primera solicitud de pago por débito directo a través de la API. El flujo general es:

Crear un cliente
Necesitas crear un cliente para cada usuario del que deseas recuperar fondos.
Crear un método de pago para el cliente
Un método de pago consiste en la información de la cuenta bancaria o tarjeta de débito de tu cliente, de la cual extraerás fondos.
Crear una solicitud de pago
Una solicitud de pago es la cantidad exacta que deseas debitar de un usuario.
Escuchar los webhooks
Recibirás webhooks cuando la institución financiera confirme que el método de pago está registrado y otro cuando la solicitud de pago haya sido procesada (y los fondos hayan sido debitados de la cuenta de tu usuario).

Importante: Acuerdos de usuario (consentimiento)

Antes de realizar cualquier solicitud de pago, debes:

Obtener el consentimiento explícito de tus usuarios, autorizándote a debitar fondos de sus cuentas.
Mantener evidencia documentada de este consentimiento.

Solicitudes de débito directo posteriores

Después de crear inicialmente un cliente y que su cuenta (método de pago) esté registrada con éxito, las solicitudes de débito directo posteriores solo requieren que realices un POST Create a payment request.

Requisitos previos

Antes de comenzar, asegúrate de:

Crear un cliente

Para crear un cliente, realiza una llamada POST Create a Direct Debit customer con la siguiente información básica:

{
  "firstname": "John",
  "lastname": "Doe",
  "documentType": "mx_rfc",
  "documentNumber": "11223344",
  "email": "john.doe@me.com",
  "phone": "573457865"
}

Parámetro	Tipo	Requerido	Descripción
`firstname`	string	si	El primer nombre de tu usuario.
`lastname`	string	si	El apellido de tu usuario.
`documentType`	string	si	El tipo de documento de identificación de tu usuario. Para 🇲🇽 México, esto puede ser uno de los siguientes: `mx_rfc`: Número de Identificación Fiscal (Registro Federal de Contribuyentes), `mx_curp`: Clave Única de Registro de Población.
`documentNumber`	string	si	El número de documento del usuario.
`email`	string	si	El correo electrónico del usuario.
`phone`	string	no	El número de teléfono del usuario (incluyendo el código de país).

Recibirás la siguiente respuesta de nuestra API, confirmando que el cliente fue creado. Asegúrate de guardar el customerId que recibas, ya que este ID es necesario al crear un método de pago.

{
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"
}

Crear un método de pago para el cliente

Después de crear tu cliente, realiza una solicitud POST Crear un método de pago para tu cliente con el siguiente payload:

{
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "accountType": "savings",
  "accountNumber": "445566790",
  "bank": "mx_bancoppel",
  "reference": "SAVINGS_445566790"
}

Parámetro	Tipo	Requerido	Descripción
`customerId`	string	si	El `customerId` para el que deseas crear el método de pago.
`accountType`	string	si	El tipo de cuenta bancaria o tarjeta. Puede ser: `savings`, `checkings`, o `debit_card`.
`accountNumber`	string	si	El número de cuenta bancaria o tarjeta de débito.
`bank`	string	si	El nombre del banco mexicano donde se encuentra la cuenta o tarjeta. Para una lista completa de instituciones, consulta nuestra página dedicada a Instituciones de Pago.
`reference`	string	no	Una descripción de referencia opcional para la cuenta bancaria.

Recibirás la siguiente respuesta de nuestra API, confirmando que el método de pago fue creado. Asegúrate de guardar el paymentMethodId que recibas, ya que este ID es necesario al generar una solicitud de pago.

{
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"
}

Crear una solicitud de pago

Después de crear tu método de pago, realiza una llamada POST Crear una solicitud de pago para el método de pago con el siguiente payload:

{
  "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b",
  "currency": "mxn",
  "amount": "100000",
  "reference": "Monthly Subscription"
}

Parámetro	Tipo	Requerido	Descripción
`paymentMethodId`	string	si	El `paymentMethodId` del cual deseas retirar (debit) fondos.
`currency`	string	si	El código de moneda de tres letras ISO 4217 de la transacción. Puede ser: `mxn` o `usd`.
`amount`	string	si	El monto de la transacción.
`reference`	string	si	Una descripción para el débito directo (para aparecer en el estado de cuenta del cliente).

Esto devolverá el siguiente payload de nuestra API:

{
  "paymentRequestId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"
}

Las solicitudes de pago solo se ejecutan para métodos de pago activos

La solicitud de pago permanecerá en el estado initial hasta que el método de pago se vuelva active. Recibirás webhooks indicando cuándo el método de pago ha sido registrado exitosamente (active) y luego un webhook de que la solicitud de pago fue procesada exitosamente.

Escuchar eventos de webhook

Recibirás webhooks cuando la institución financiera confirme que el método de pago está registrado (payment_method_registration_successful) y otro cuando la solicitud de pago haya sido procesada (payment_request_successful), indicando que los fondos han sido debitados de la cuenta de tu usuario.

`payment_method_registration_successful`

El webhook payment_method_registration_successful indica que el método de pago está registrado en la institución financiera del usuario. Una vez que recibas este webhook, tu solicitud de pago será procesada.

`payment_request_successful`

El webhook payment_request_successful indica que la solicitud de pago fue procesada y los fondos han sido debitados de la cuenta del usuario.

✳️ ¡Hecho! Acabas de configurar tu primer débito directo para un usuario. Los débitos posteriores para el mismo usuario solo requerirán que envíes una solicitud de pago y escuches el webhook payment_request_successful.