# 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. 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). Solicitudes de Débito Directo Posteriores Después de que hayas creado inicialmente un Cliente, registrado su cuenta (método de pago) y obtenido su consentimiento para debitar fondos de sus cuentas, las solicitudes de débito directo posteriores solo requieren que realices un POST Crear una solicitud de pago. ```mermaid sequenceDiagram participant App as Aplicación participant Belvo as Belvo participant PI as Institución de Pago Note over App,PI: 1. Crea tu Cliente App->>Belvo: POST /customers Belvo-->>App: 201 - Creado + customerId Note over App,PI: 2. Crea un Método de Pago para tu Cliente App->>Belvo: POST /payment_methods/bank_accounts Belvo-->>App: 201 - Creado + paymentMethodId Belvo->>PI: Método de Pago enviado a la institución para confirmación Note over Belvo,PI: Ver Nota 5 abajo sobre la confirmación del webhook Note over App,PI: 3. Envía Documentos de Consentimiento de tu Cliente App->>Belvo: POST /consents Belvo-->>App: 201 - Creado + consentId App->>Belvo: POST /consents/{consentId}/files Belvo-->>App: 201 - Creado + Lista de Archivos de Consentimiento Note over App,PI: 4. Crea una Solicitud de Pago App->>Belvo: POST /payment_requests Belvo-->>App: 201 - Creado + paymentRequestId Belvo->>PI: Solicitud de Pago enviada a la Institución Note over Belvo,PI: Ver Nota 6 abajo sobre la confirmación del webhook Note over App,PI: 5. Espera la confirmación del método de pago (hasta 1 día hábil) Belvo->>App: WEBHOOK payment_method_registration_successful (paymentMethodId) App->>Belvo: GET /payment_methods/{paymentMethodId} Belvo-->>App: 200 + Detalles del Método de Pago Note over App,PI: 6. Espera la confirmación de la solicitud de pago (hasta 2 días hábiles) Belvo->>App: WEBHOOK payment_request_successful (paymentRequestId) App->>Belvo: GET /payment_requests/{paymentRequestId} Belvo-->>App: 200 + Detalles de la Solicitud de Pago ``` ## 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: ```json Create a Direct Debit Customer Request Body { "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, 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. ```json Create a Direct Debit Customer Response Body { "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: ```json Cuerpo de la Solicitud para Crear un Método de Pago por Débito Directo { "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 un Consentimiento y posteriormente Solicitudes de Pago. ```json Cuerpo de la Respuesta para Crear un Método de Pago por Débito Directo { "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" // [!code highlight] } ``` ## Crear un consentimiento para tu cliente Requerido para Solicitudes de Pago **No puedes crear Solicitudes de Pago hasta que el consentimiento esté confirmado.** Cada Método de Pago requiere su propio consentimiento con un estado `confirmed` antes de que se puedan debitar fondos. ¿Qué es el Consentimiento de Débito Directo? Un Consentimiento en Débito Directo es una prueba legal de que tu cliente te ha autorizado a debitar fondos de su cuenta. Este consentimiento debe incluir: - Fotos de la identificación emitida por el gobierno del cliente (frontal y trasera) - Una selfie del cliente - Un contrato firmado autorizando el débito directo **Cronograma**: La revisión del consentimiento generalmente toma de 1 a 2 días hábiles después de que se suban todos los archivos. 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`. ```mermaid sequenceDiagram participant App as Aplicación participant Belvo as Belvo Note over App,Belvo: 1. Inicializar el Consentimiento para un Método de Pago App->>Belvo: POST /consents Belvo->>App: 201 - Created + consentId Note over App,Belvo: 2. Subir archivos de Consentimiento App->>Belvo: POST /consents/{consentId}/files Belvo->>App: 201 - Created + Lista de Archivos de Consentimiento Note over App,Belvo: 3. Esperar la revisión del Consentimiento y actualización del estado App->>Belvo: GET Poll /consents/{consentId} Belvo->>App: 200 - OK + consentStatus ``` ### 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: ```json Create a Direct Debit Consent Request Body { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b" } ``` | Parámetro | Tipo | Requerido | Descripción | | --- | --- | --- | --- | | `paymentMethodId` | string | true | El `paymentMethodId` para el cual deseas crear el consentimiento. | 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. ```json Create a Direct Debit Consent Response Body { "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", // [!code highlight] "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 Upload Consent Files Request 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 ``` | Parámetro | Tipo | Requerido | Descripción | | --- | --- | --- | --- | | `id_front` | string (binary) | si | El lado frontal de la identificación del cliente. Puede ser una foto o una imagen escaneada en formato JPEG, PNG o PDF. El tamaño máximo del archivo es de 20MB. | | `id_back` | string (binary) | si | El lado posterior de la identificación del cliente. Puede ser una foto o una imagen escaneada en formato JPEG, PNG o PDF. El tamaño máximo del archivo es de 20MB. | | `selfie` | string (binary) | si | Una selfie del cliente (idealmente sosteniendo su tarjeta de identificación). Puede ser una foto o una imagen escaneada en formato JPEG, PNG o PDF. El tamaño máximo del archivo es de 20MB. | | `contract` | string (binary) | si | El contrato firmado por el cliente. Puede ser una foto o una imagen escaneada en formato JPEG, PNG o PDF. El tamaño máximo del archivo es de 20MB. | Nuestra API responderá con el siguiente payload, confirmando que los archivos de consentimiento fueron subidos exitosamente (un objeto por cada archivo de Consentimiento subido): ```json Upload Consent Files Response Body [ { "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. ```json // 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 Verificación de requisitos previos Antes de crear una solicitud de pago, asegúrate de: 1. El método de pago está creado 2. El estado del consentimiento es `confirmed` Si el consentimiento no está confirmado, tu solicitud de pago será rechazada. Una vez que tu consentimiento haya sido confirmado, realiza una llamada POST Crear una solicitud de pago: ```json Cuerpo de la solicitud para crear una solicitud de pago por débito directo { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b", "currency": "mxn", "amount": "100000", "reference": "Monthly Subscription" } ``` | Parámetro | Tipo | Requerido | Descripción | | --- | --- | --- | --- | | `paymentMethodId` | string | true | El `paymentMethodId` del cual deseas retirar (debit) fondos. | | `currency` | string | true | El código de moneda de tres letras ISO 4217 de la transacción. Puede ser: `mxn` o `usd`. | | `amount` | string | true | El monto de la transacción. | | `reference` | string | true | 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: ```json Cuerpo de respuesta de la solicitud de pago por débito directo { "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 cuando 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! ¡Felicidades! 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`.