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:

1. Crear un cliente
   Necesitas crear un cliente para cada usuario del que deseas recuperar fondos.

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

3. Enviar documentos de consentimiento
   Debes enviar los documentos de consentimiento de tu cliente, autorizándote a debitar fondos de su cuenta.

   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 y enviarlo a Belvo a través de la API.

4. Crear una solicitud de pago
   Una solicitud de pago es la cantidad exacta que deseas debitar de un usuario.

5. 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).

Requisitos previos

Antes de comenzar, asegúrate de:

1. Generar tus claves de API.
2. Configurar un webhook para escuchar eventos.
3. Configurar la lista blanca de IP

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

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

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 un Consentimiento y posteriormente Solicitudes de Pago.

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

Crear un consentimiento para tu cliente

Después de crear tu método de pago, necesitas crear un consentimiento para tu cliente que esté compuesto por fotos de su identificación, una selfie y un contrato firmado. Este consentimiento es necesario para autorizar el débito directo.

El proceso de creación del consentimiento consta de los siguientes pasos:

1. Inicializar el Consentimiento - Crear un registro de consentimiento vinculado a tu método de pago
2. Subir Archivos Requeridos - Enviar fotos de la identificación, selfie y contrato firmado
3. Esperar la Revisión y Actualización del Estado - Los expertos de Belvo revisan los archivos (1-2 días hábiles) y actualizan el estado.
   • El estado puede ser awaiting_information, submitted, incomplete_information, confirmed o rejected.

Inicializar el Consentimiento para un Método de Pago

Inicializa el Consentimiento para un Método de Pago realizando una llamada POST Create a Direct Debit Consent con el siguiente payload:

{
  "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b"
}

Nuestra API responderá con el siguiente payload, confirmando que el consentimiento fue creado. Asegúrate de guardar el consentId que recibas, ya que este ID es necesario al cargar los archivos de consentimiento.

{
  "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", 
  "status": "awaiting_information",
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "isBankNotified": false
}

Subir archivos de Consentimiento

Después de inicializar el consentimiento, necesitas subir los archivos requeridos. Realiza una llamada POST Upload Consent Files con el siguiente payload:

curl -i -X POST \
  'baseURL/consents/{consentId}/files' \
  -H 'Content-Type: multipart/form-data' \
  -H 'api-key-id: YOUR_API_KEY_HERE' \
  -H 'api-key-secret: YOUR_API_KEY_HERE' \
  -F id_front=string \
  -F id_back=string \
  -F selfie=string \
  -F contract=string

Nuestra API responderá con el siguiente payload, confirmando que los archivos de consentimiento fueron subidos exitosamente (un objeto por cada archivo de Consentimiento subido):

[
  {
    "type": "id_front",
    "consentFileId": "8c56b4e7-d025-4b1a-a303-dd472b24f431",
    "consentId": "0494baff-3bbb-43c7-bb58-67ac6cba3e54"
  }
]

Monitorear el Estado del Consentimiento

Una vez que hayas subido todos los archivos requeridos, el estado del consentimiento cambiará a submitted y luego será revisado por nuestros expertos. Una vez que la revisión esté completa, el estado cambiará a confirmed o rejected. Puedes verificar el estado del consentimiento haciendo una llamada GET Get a Direct Debit Consent.

// Ejemplo de respuesta
{
  "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "status": "submitted",
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "isBankNotified": false
}

Posibles Estados:

• awaiting_information: Esperando la carga de archivos
• submitted: Todos los archivos subidos, en revisión
• incomplete_information: Faltan archivos requeridos
• confirmed: ✅ Aprobado - ahora puedes crear solicitudes de pago
• rejected: ❌ Denegado - revisa la razón del rechazo y vuelve a enviar

Para más detalles sobre los estados de los consentimientos, consulta nuestro artículo dedicado Estados de Entidad.

Crear una solicitud de pago

Una vez que tu consentimiento haya sido confirmado, realiza una llamada POST Crear una solicitud de pago:

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

Esto devolverá el siguiente payload de nuestra API:

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

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.