Docs

Direct Debit · Guides

Customers and instruments

Store customers and their CLABE or debit card instruments so you can reuse them across charges.

Stored customers and instruments are optional. You can send the same data inline on each charge. Storing them lets you reuse them across charges, group and filter charges by customer or instrument, and keep payment data centralized with Monato.

Every instrument belongs to a customer, so create the customer first.

Customers

A customer stores a payer’s identifying information: name, document type and number, email and phone number.

Create a customer

curl -X POST https://directdebit.monato.com/customers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "name": "Jane Doe",
    "document_type": "mx_rfc",
    "document_number": "XXXX000000XXX",
    "email": "jane.doe@example.com",
    "phone_number": "+520000000000"
  }'
Field Required Notes
name Yes Full name, 1 to 255 characters
document_type Yes mx_rfc or mx_curp (the schema also accepts passport)
document_number Yes 1 to 255 characters
email No Email address
phone_number No Up to 20 characters

Save the id. You use it to link instruments and charges to this customer.

Retrieve and list customers

curl https://directdebit.monato.com/customers/{customer_id} \
  --header 'x-api-key: YOUR_API_KEY'

GET /customers paginates with skip (default 0) and limit (default 100).

Instruments

An instrument is a customer’s payment method: a CLABE or a debit card.

Type Description
mx_clabe An 18-digit CLABE bank account identifier
mx_direct_debit_card A Mexican debit card number with an associated bank

Create a CLABE instrument

Request
curl -X POST https://directdebit.monato.com/instruments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "type": "mx_clabe",
    "customer_id": "33333333-3333-4333-8333-333333333333",
    "mx_clabe": {
      "clabe": "000000000000000001"
    }
  }'

Create a debit card instrument

bank is required for debit cards. Valid values are listed in Banks and institutions.

curl -X POST https://directdebit.monato.com/instruments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "type": "mx_direct_debit_card",
    "customer_id": "33333333-3333-4333-8333-333333333333",
    "mx_direct_debit_card": {
      "card_number": "0000000000000001",
      "bank": "mx_santander"
    }
  }'

You can also send an optional description when you create an instrument.

Penny validation

When penny validation is enabled for your organization, a new CLABE or debit card instrument is created with status: "verification_in_progress" and Monato checks account ownership in the background. The instrument then becomes active (ownership matched) or errored (ownership no_match or errored), and you get an instrument_ownership_verification_result webhook. An errored instrument can’t be charged. See Penny validation.

Retrieve and list instruments

curl https://directdebit.monato.com/instruments/{instrument_id} \
  --header 'x-api-key: YOUR_API_KEY'

GET /instruments uses cursor pagination: limit (1 to 1000, default 100) and cursor (the next_cursor from the previous response). It has no other filters. To find the charges of a customer, filter GET /charges by customer_id.

Use them in a charge

Send customer_id and instrument_id in POST /charges. See Create charges.

Endpoints

Action Endpoint
Create a customer POST /customers
List customers GET /customers
Get a customer GET /customers/{customer_id}
Update a customer PUT /customers/{customer_id}
Delete a customer DELETE /customers/{customer_id}
Create an instrument POST /instruments
List instruments GET /instruments
Get an instrument GET /instruments/{instrument_id}
Update an instrument’s description PUT /instruments/{instrument_id}
Delete an instrument DELETE /instruments/{instrument_id}