Set up your first direct debit

Want to set up a direct debit? Let's show you just how easy it is 😎.

📘

Prerequisites

Before you begin, make sure you:

• Generate your API keys.
• Set up a webhook to listen to events.
• Set up IP Whitelisting

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 bank account payment method for the customer
   A bank account payment method consists of your customer's bank account information, from where you will pull funds from.
3. Generate and confirm an agreement
   To debit funds from an account, you need your user to confirm that they agree to have their account debited.
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 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, confirm their agreement, and their account is succesfully registered, subsequent direct debit requests only require you to make POST Create a payment request.

General payment flow. Click to enlarge.

Create a customer

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

Customer request payload

{
  "firstname": "John", // Required. Your users's first name.
  "lastname": "Doe",  // Required. Your users's last name.
  "documentType": "mx_rfc",  // Required. Your users's ID document type number.
  "documentNumber": "11223344",  // Required. Your users's ID document number.
  "email": "[email protected]", // // Required. Your users's email address.
  "phone": "573457865" // Optional. Your user's phone number.
}

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 bank account payment method.

Customer response payload

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

Payment method request payload

{
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", // Required. The customerId.
  "accountType": "savings", // Required. The bank account type. Can be either savings or checking.
  "accountNumber": "445566790", // Required. The bank account number
  "bank": "mx_bancoppel", // Required. The bank institution where the account is held.
  "reference": "SAVINGS_445566790" // Optional. A descriptive reference for the direct debit.

}

You’ll 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.

Payout target response payload

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

📘

Note: The bank account payment method will not be active until you send a confirmed agreement from the user and the financial institution confirms the registration of the account. You will receive status updates via a payment method webhook .

Generate and confirm an agreement

In order to be able to debit money from an account, you need to generate an agreement for your user to sign (confirming that they agree to have money debited from their account).

Generate

To generate an agreement, you need to make a POST Generate an agreement request with the following payload:

Generate an agreement request payload

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

You’ll receive the following response from our API, with a url to the generated agreement that you need to send to your user. Make sure to save the id of the agreement as you will need to send this when confirming the agreement.

Generate an agreement response payload

{
  "id": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", // The agreementId - required for the next API call
  "url": "https://s3.amazonaws.com/path-to-agreement/...", // The URL of the agreement to send to the user
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c" // The associated paymentMethodId
}

Confirm

Once your user confirms the agreement, you need to make a POST Confirm an agreement request with the following payload:

Confirm agreement request body

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

You'll receive the following response from our API, confirming that the payment method is ready for use. We will send this information to the user's financial information.

Confirm an agreement response body

{
  "agreementAcceptanceId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "acceptanceDate": "2023-10-05T20:34:11.282Z",
  "agreementUrl": "https://s3.amazonaws.com/path-to-agreement/...",
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "bankAccountDetails": {
    "accountNumber": "445566790",
    "accountType": "savings",
    "bank": "mx_bancoppel"
  }
}

Create a payment request

After creating your payment method and having your user's agreement to debit their account, you need to make a POST Create a payment request call for the payment method with the following payload:

Payment request payload

{
  "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b", // Required. The payment method you want to debit funds from
  "currency": "cop", // Required. The currency of the debit amount
  "amount": "100000", // Required. The debit amount
  "reference": "Monthly Subscription" // Required. A description for the debit
}

Which will return the following payload from our API:

Payment request reponse payload

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

📘

Payment requests only get executed for active payment methods

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