Guides
API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

Set Up a Direct Debit (API)

Suggest Edits

📘

Prerequisites

Before you begin, make sure you:

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 where you will pull funds from.
  3. Create a payment request
    A payment request is the actual amount that you want to debit from a user.

    🚧

    Important: User agreements (consent)

    Before making any payment requests, you must:

    1. Obtain explicit consent from your users, authorizing you to debit funds from their accounts.
    2. Maintain documented evidence of this consent.
  4. Listen for webhooks
    You will receive webhooks for when the financial institution confirms that the payment method is registered and another for when the payment request has been processed (and funds have been debited from your user's account).

    👍

    Subsequest direct debit requests

    After you initially create a customer and their account (payment method) is successfully registered, subsequent direct debit requests only require you to make POST Create a payment request.

General payment flow. Click to enlarge.

General payment flow. Click to enlarge.

Create a customer

To create a customer, you need to make a POST Create a Direct Debit customer call with the following core information:

{
  "firstname": "John",
  "lastname": "Doe",
  "documentType": "mx_rfc",
  "documentNumber": "11223344",
  "email": "[email protected]",
  "phone": "573457865"
}
ParameterTypeRequiredDescription
firstnamestringtrueYour user's first name.
lastnamestringtrueYour user's last name.
documentTypestringtrueYour 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)
documentNumberstringtrueThe document number of the user.
emailstringtrueThe email of the user.
phonestringfalseThe 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.

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

Create a payment method for the customer

After creating your customer, you need to 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"

}
ParameterTypeRequiredDescription
customerIdstringtrueThe customerId that you want to create the payment method for.
accountTypestringtrueThe bank account or card type. Can be either: savings, checkings or debit_card.
accountNumberstringtrueThe bank account or debit card number.
bankstringtrueThe 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.
referencestringfalseAn optional reference description for the bank account.

You will receive the following response from our API, confirming that the customer was created. Make sure to save the paymentMethodId you receive, as this ID is required when generating an agreement.

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

Create a payment request

After creating your payment method you need to make a POST Create a payment request call for the payment method with the following payload:

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

ParameterTypeRequiredDescription
paymentMethodIdstringtrueThe paymentMethodId that you want to pull (debit) funds from.
currencystringtrueThe three-letter ISO 4217 currency code of the transaction. Can be either: mxn or usd.
amountstringtrueThe amount of the transaction.
referencestringtrueA description for the direct debit (to appear on the customer's statement).

Which will return the following payload from our API:

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

📘

Payment requests only get executed for active payment methods

The payment request will remain in the initialstatus 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! 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 🤓.

Updated about 19 hours ago