# Belvo Direct Debit API Our Payment infrastructure aims to make moving money between businesses and people easy, fast, and modular. Version: 1.0.0 ## Servers ``` https://api.sandbox.directdebit.belvo.com ``` ## Security ### ApiKeyAuth Type: apiKey In: header Name: api-key-id ### ApiKeySecret Type: apiKey In: header Name: api-key-secret ## Download OpenAPI description [Belvo Direct Debit API](https://developers.belvo.com/_bundle/apis/BelvoPaymentsMexico.yaml) ## Institutions (Direct Debit Mexico) Use the Institutions resource to: list all the institutions you can make payments to and from. ### List all institutions - [GET /institutions](https://developers.belvo.com/apis/belvopaymentsmexico/institutions-(direct-debit-mexico)/listdirectdebitinstitutions.md): List all institutions available ## Customers (Direct Debit Mexico) A Customer is the end user, either an individual or a business, who owns the bank account involved in a debit or payout operation. Belvo Direct Debit stores the essential information of this Customer to simplify and reuse it across multiple payment methods and payout targets ### Create a customer - [POST /customers](https://developers.belvo.com/apis/belvopaymentsmexico/customers-(direct-debit-mexico)/createdirectdebitcustomer.md): Create a new Direct Debit customer ### List all customers - [GET /customers/](https://developers.belvo.com/apis/belvopaymentsmexico/customers-(direct-debit-mexico)/listdirectdebitcustomers.md): List all Direct Debit customers associated with your account ### Update a customer - [POST /customers/{customerId}](https://developers.belvo.com/apis/belvopaymentsmexico/customers-(direct-debit-mexico)/updatedirectdebitcustomer.md): Update an existing direct debit customer ### Get a customer's details - [GET /customers/{customerId}](https://developers.belvo.com/apis/belvopaymentsmexico/customers-(direct-debit-mexico)/detaildirectdebitcustomer.md): Get te details regarding a specific direct debit customer ## Payment Methods (Direct Debit Mexico) A Payment Method contains the details of the source bank account that you will debit funds from. ### Create a payment method - [POST /payment_methods/bank_accounts](https://developers.belvo.com/apis/belvopaymentsmexico/payment-methods-(direct-debit-mexico)/createdirectdebitpaymentmethod.md): Create a new payment method for a customer ### List all payment methods - [GET /payment_methods](https://developers.belvo.com/apis/belvopaymentsmexico/payment-methods-(direct-debit-mexico)/listdirectdebitpaymentmethods.md): List all payment methods associated with your account ### Get a payment method's details - [GET /payment_methods/{paymentMethodId}](https://developers.belvo.com/apis/belvopaymentsmexico/payment-methods-(direct-debit-mexico)/detaildirectdebitpaymentmethod.md): Get the details regarding a specific payment method ### Deactivate a payment method - [POST /payment_methods/{paymentMethodId}/deactivate](https://developers.belvo.com/apis/belvopaymentsmexico/payment-methods-(direct-debit-mexico)/deactivatedirectdebitpaymentmethod.md): Deactivate a specific payment method. > 📘 Info > > You can only deactivate a payment method when the status is in the active state and there are no pending payment requests (paymentRequest.status = processing) ## Payment Requests (Direct Debit Mexico) A Payment Request is the actual transaction that you want to execute to debit funds from an account. Each Payment Request must be associated with a previously created Payment Method. For each new transaction that you want to make, you need to create a new Payment Request. ### Create a payment request - [POST /payment_requests](https://developers.belvo.com/apis/belvopaymentsmexico/payment-requests-(direct-debit-mexico)/createdirectdebitpaymentrequest.md): Create a new payment request for an existing payment method. > 📘 Idempotency Keys > > This method supports idempotency keys. ### List all payment requests - [GET /payment_requests](https://developers.belvo.com/apis/belvopaymentsmexico/payment-requests-(direct-debit-mexico)/listdirectdebitpaymentrequests.md): List all payment requests associated with your account ### Get a payment request's details - [GET /payment_requests/{paymentRequestId}](https://developers.belvo.com/apis/belvopaymentsmexico/payment-requests-(direct-debit-mexico)/detaildirectdebitpaymentrequest.md): Get the details regarding a specific payment request ### Cancel a payment request - [POST /payment_requests/{paymentRequestId}/cancel](https://developers.belvo.com/apis/belvopaymentsmexico/payment-requests-(direct-debit-mexico)/canceldirectdebitpaymentrequest.md): Cancel a payment request. > 📘 Info > > You can only cancel a payment request when the status is in the initial state. ## Movements (Direct Debit Mexico) Use the Movements resource to list all the account Movements (transactions that occur inside your bank account). ### Get your account movements - [GET /account_movements](https://developers.belvo.com/apis/belvopaymentsmexico/movements-(direct-debit-mexico)/listdirectdebitaccountmovements.md): Get a statement of the movements that have occurred within your account. ## Payment Consents (Direct Debit Mexico) A Consent in Direct Debit is proof from your client that they confirmed that they will have funds debited from their account (Payment Method). This proof is comprised of photos of their ID, a selfie, and a signed contract. ### Create a Consent - [POST /consents](https://developers.belvo.com/apis/belvopaymentsmexico/payment-consents-(direct-debit-mexico)/createconsent.md): Create the initial Consent for a Payment Method. Once you create a Consent, you can upload supporting documents that serve as consent from your customer to debit their bank account using the Upload Consent Files endpoint. ### List all Consents - [GET /consents](https://developers.belvo.com/apis/belvopaymentsmexico/payment-consents-(direct-debit-mexico)/listallconsents.md): List all the Consents that you have created for your Payment Methods. ### Get a Consent's Details - [GET /consents/{consentId}](https://developers.belvo.com/apis/belvopaymentsmexico/payment-consents-(direct-debit-mexico)/getconsentdetails.md): Get the details of a specific consent. ### Upload Consent Files - [POST /consents/{consentId}/files](https://developers.belvo.com/apis/belvopaymentsmexico/payment-consents-(direct-debit-mexico)/uploadconsentfiles.md): Upload files that serve as consent from your customer to debit their bank account. You must upload all required files for a Consent (front and back scans of the ID card, a selfie of the user holding the ID, and a signed contract). Each file cannot be larger than 20MB. ### Get a Consent's Files - [GET /consents/{consentId}/files](https://developers.belvo.com/apis/belvopaymentsmexico/payment-consents-(direct-debit-mexico)/listconsentfiles.md): List all the files that have been uploaded for a specific Consent. ## Loans (Direct Debit Mexico) Use the Loans resource to register and track loan portfolio snapshots for direct debit customers. Each snapshot captures the current state of a customer's debt. Each snapshot is uniquely identified by `merchantCustomerId` + `targetCollectionDate`, where `targetCollectionDate` is the date Belvo will attempt to collect payment — set automatically to either the day that the request was made or the next business day in Mexico. You can only POST one snapshot per customer per day; a duplicate request on the same calendar day returns a `409 Conflict`. ### Create a loan snapshot - [POST /loans](https://developers.belvo.com/apis/belvopaymentsmexico/loans-(direct-debit-mexico)/createdirectdebitloan.md): Create a new loan snapshot for a customer. Each successful request triggers an automatic direct debit collection attempt on the same day or the next Mexico business day. The response returns the id of the newly created snapshot. When the collection attempt completes, Belvo sends a webhook notification with the outcome. ### List all loan snapshots - [GET /loans](https://developers.belvo.com/apis/belvopaymentsmexico/loans-(direct-debit-mexico)/listdirectdebitloans.md): List and filter loan history snapshots associated with your account. ### Get a loan snapshot's details - [GET /loans/{id}](https://developers.belvo.com/apis/belvopaymentsmexico/loans-(direct-debit-mexico)/detaildirectdebitloan.md): Get the details of a specific loan history snapshot.