# Introduction This guide will walk you through making your first direct debit payment request via the API. The general flow is: 1. **Create a customer** You need to create a customer for each user you want to retrieve funds from. 2. **Create a payment method for the customer** A payment method consists of your customer's bank account or debit card information, from which you will pull funds. 3. **Submit consent documents** You must submit the consent documents from your customer, authorizing you to debit funds from their account. Before making any payment requests, you must obtain explicit consent from your users authorizing you to debit funds from their accounts and send it to Belvo via the API. 4. **Create a payment request** A payment request is the actual amount that you want to debit from a user. 5. **Listen for webhooks** You will receive webhooks when the financial institution confirms that the payment method is registered and another when the payment request has been processed (and funds have been debited from your user's account). Subsequent Direct Debit Requests After you have initially created a Customer, registered their account (payment method), and obtained their consent to debit funds from their accounts, subsequent direct debit requests only require you to make a POST Create a payment request. ```mermaid sequenceDiagram participant App as Application participant Belvo as Belvo participant PI as Payment Institution Note over App,PI: 1. Create your Customer App->>Belvo: POST /customers Belvo-->>App: 201 - Created + customerId Note over App,PI: 2. Create a Payment Method for your Customer App->>Belvo: POST /payment_methods/bank_accounts Belvo-->>App: 201 - Created + paymentMethodId Belvo->>PI: Payment Method sent to the institution for confirmation Note over Belvo,PI: See Note 5 below regarding webhook confirmation Note over App,PI: 3. Submit Consent Documents from your Customer App->>Belvo: POST /consents Belvo-->>App: 201 - Created + consentId App->>Belvo: POST /consents/{consentId}/files Belvo-->>App: 201 - Created + List of Consent Files Note over App,PI: 4. Create a Payment Request App->>Belvo: POST /payment_requests Belvo-->>App: 201 - Created + paymentRequestId Belvo->>PI: Payment Request sent to Institution Note over Belvo,PI: See Note 6 below regarding webhook confirmation Note over App,PI: 5. Wait for payment method confirmation (up to 1 business day) Belvo->>App: WEBHOOK payment_method_registration_successful (paymentMethodId) App->>Belvo: GET /payment_methods/{paymentMethodId} Belvo-->>App: 200 + Payment Method Details Note over App,PI: 6. Wait for payment request confirmation (up to 2 business days) Belvo->>App: WEBHOOK payment_request_successful (paymentRequestId) App->>Belvo: GET /payment_requests/{paymentRequestId} Belvo-->>App: 200 + Payment Request Details ``` ## Prerequisites Before you begin, make sure you: 1. Generate your API keys. 2. Set up a webhook to listen to events. 3. Set up IP Whitelisting ## Create a customer To create a customer, make a POST Create a Direct Debit customer call with the following core information: ```json Create a Direct Debit Customer Request Body { "firstname": "John", "lastname": "Doe", "documentType": "mx_rfc", "documentNumber": "11223344", "email": "john.doe@me.com", "phone": "573457865" } ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `firstname` | string | true | Your user's first name. | | `lastname` | string | true | Your user's last name. | | `documentType` | string | true | Your user's ID document type. For Mexico, this can be one of the following:- `mx_rfc`: Tax Identification Number (Registro Federal de Contribuyentes) - `mx_curp`: Unique Population Registry Code (Clave Única de Registro de Población). | | `documentNumber` | string | true | The document number of the user. | | `email`$$ | string | true | The email of the user. | | `phone` | string | false | The phone number of the user (including country code). | You’ll receive the following response from our API, confirming that the customer was created. Make sure to save the `customerId` you receive, as this ID is required when creating a payment method. ```json Create a Direct Debit Customer Response Body { "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" } ``` ## Create a payment method for the customer After creating your customer, make a POST Create a payment method request for your customer with the following payload: ```json Create a Direct Debit Payment Method Request Body { "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "accountType": "savings", "accountNumber": "445566790", "bank": "mx_bancoppel", "reference": "SAVINGS_445566790" } ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `customerId` | string | true | The `customerId` that you want to create the payment method for. | | `accountType` | string | true | The bank account or card type. Can be either: `savings`, `checkings`, or `debit_card`. | | `accountNumber` | string | true | The bank account or debit card number. | | `bank` | string | true | The name of the Mexican bank where the account or card is held. For a full list of institutions, please see our dedicated Payment Institutions page. | | `reference` | string | false | An optional reference description for the bank account. | You will receive the following response from our API, confirming that the Payment Method was created. Make sure to save the `paymentMethodId` you receive, as this ID is required when generating a Consent and later Payment Requests. ```json Create a Direct Debit Payment Method Response Body { "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" // [!code highlight] } ``` ## Create a consent for your customer Required for Payment Requests **You cannot create Payment Requests until consent is confirmed.** Each Payment Method requires its own consent with a `confirmed` status before any funds can be debited. What is Direct Debit Consent? A Consent in Direct Debit is legal proof that your customer has authorized you to debit funds from their account. This consent must include: - Photos of the customer's government-issued ID (front and back) - A selfie of the customer - A signed contract authorizing the direct debit **Timeline**: Consent review typically takes 1-2 business days after all files are uploaded. After creating your payment method, you need to create a consent for your customer that is comprised of photos of their ID, a selfie, and a signed contract. This consent is required to authorize the direct debit. The consent creation process consists of the following steps: 1. **Initialize the Consent** - Create a consent record linked to your payment method 2. **Upload Required Files** - Submit ID photos, selfie, and signed contract 3. **Wait for Review and Status Update** - Belvo experts review the files (1-2 business days) and update the status. - Status can be `awaiting_information`, `submitted`, `incomplete_information` `confirmed`, or `rejected`. ```mermaid sequenceDiagram participant App as Application participant Belvo as Belvo Note over App,Belvo: 1. Initialize the Consent for a Payment Method App->>Belvo: POST /consents Belvo->>App: 201 - Created + consentId Note over App,Belvo: 2. Upload Consent files App->>Belvo: POST /consents/{consentId}/files Belvo->>App: 201 - Created + List of Consent Files Note over App,Belvo: 3. Wait for Consent review and status update App->>Belvo: GET Poll /consents/{consentId} Belvo->>App: 200 - OK + consentStatus ``` ### Initialize the Consent for a Payment Method Initialize the Consent for a Payment Method by making a POST Create a Direct Debit Consent call with the following payload: ```json Create a Direct Debit Consent Request Body { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b" } ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `paymentMethodId` | string | true | The `paymentMethodId` that you want to create the consent for. | Our API will respond with the following payload, confirming that the consent was created. Make sure to save the `consentId` you receive, as this ID is required when uploading the consent files. ```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 } ``` ### Upload Consent files After initializing the consent, you need to upload the required files. Make a POST Upload Consent Files call with the following 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 ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id_front` | string (binary) | true | The front side of the customer's ID. Can be a photo or a scanned image in JPEG, PNG, or PDF format. Maximum file size is 20MB. | | `id_back` | string (binary) | true | The back side of the customer's ID. Can be a photo or a scanned image in JPEG, PNG, or PDF format. Maximum file size is 20MB. | | `selfie` | string (binary) | true | A selfie of the customer (ideally holding their ID card). Can be a photo or a scanned image in JPEG, PNG, or PDF format. Maximum file size is 20MB. | | `contract` | string (binary) | true | The signed contract from the customer. Can be a photo or a scanned image in JPEG, PNG, or PDF format. Maximum file size is 20MB. | Our API will respond with the following payload, confirming that the consent files were uploaded successfully (one object per Consent file uploaded): ```json Upload Consent Files Response Body [ { "type": "id_front", "consentFileId": "8c56b4e7-d025-4b1a-a303-dd472b24f431", "consentId": "0494baff-3bbb-43c7-bb58-67ac6cba3e54" } ] ``` ### Monitor Consent Status Once you have uploaded all the required files, the status of the consent will change to `submitted` and then be reviewed by our experts. Once the review is complete, the status will change to `confirmed` or `rejected`. You can check the status of the consent by making a GET Get a Direct Debit Consent call. ```json // Example response { "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "status": "submitted", "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", "isBankNotified": false } ``` **Possible Statuses:** - `awaiting_information`: Waiting for file uploads - `submitted`: All files uploaded, under review - `incomplete_information`: Missing required files - `confirmed`: ✅ Approved - you can now create payment requests - `rejected`: ❌ Denied - check rejection reason and resubmit For more details on the consents states, check our dedicated Entity States article. ## Create a payment request Prerequisites Check Before creating a payment request, ensure: 1. Payment method is created 2. Consent status is `confirmed` If consent is not confirmed, your payment request will be rejected. After your consent has been confirmed, make a POST Create a payment request call: ```json Create a Direct Debit Payment Request Request Body { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b", "currency": "mxn", "amount": "100000", "reference": "Monthly Subscription" } ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `paymentMethodId` | string | true | The `paymentMethodId` that you want to pull (debit) funds from. | | `currency` | string | true | The three-letter ISO 4217 currency code of the transaction. Can be either: `mxn` or `usd`. | | `amount` | string | true | The amount of the transaction. | | `reference` | string | true | A description for the direct debit (to appear on the customer's statement). | This will return the following payload from our API: ```json Create a Direct Debit Payment Request Response Body { "paymentRequestId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" } ``` Payment requests only get executed for active payment methods The payment request will remain in the `initial` status until the payment method becomes `active`. You will receive webhooks indicating when the payment method has been successfully registered (`active`) and then a webhook that the payment request was successfully processed. ## Listen for webhook events You will receive webhooks when the financial institution confirms that the payment method is registered (`payment_method_registration_successful`) and another for when the payment request has been processed (`payment_request_successful`), indicating that funds have been debited from your user's account. #### `payment_method_registration_successful` The `payment_method_registration_successful` webhook indicates that the payment method is registered at the user's financial institution. Once you receive this webhook, your payment request will be processed. #### `payment_request_successful` The `payment_request_successful` webhook indicates that the payment request was processed and funds have been debited from the user's account. Done! Congratulations! You've just set up your first direct debit for a user. Subsequent debits for the same user will only require you to send a payment request and listen for the `payment_request_successful` webhook.