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.

   Important: User agreements (consent)

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

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:

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

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.

{
  "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:

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

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.

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

Create a consent for your customer

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.

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:

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

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.

{
  "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", 
  "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 -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

Our API will respond with the following payload, confirming that the consent files were uploaded successfully (one object per Consent file uploaded):

[
  {
    "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.

// 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

After your consent has been confirmed, make a POST Create a payment request call:

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

This will return the following payload from our API:

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

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.