Introduction

This guide will walk you through making your first direct debit payment request via the API. The general flow is:

Create a customer
You need to create a customer for each user you want to retrieve funds from.
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.
Create a payment request
A payment request is the actual amount that you want to debit from a user.
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).

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.
Maintain documented evidence of this consent.

Subsequent 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 a POST Create a payment request.

Prerequisites

Before you begin, make sure you:

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"
}

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.

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

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 payment request.

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

Create a payment request

After creating your payment method, 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"
}

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:

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