Direct Debit · Reference
Batch file specification
Columns, formats and limits for charge request files and the response files Monato returns.
This page describes the columns of charge request files (uploaded over SFTP or in the Portal) and of the response files Monato returns.
Charge request file columns
| Column | Allowed Values | Max Length | Required | Description |
|---|---|---|---|---|
instrument_type |
mx_clabe / mx_direct_debit_card |
— | Yes | The type of payment instrument to charge |
instrument_bank |
See Banks and institutions | — | Required when instrument_type is mx_direct_debit_card |
The bank the instrument belongs to |
instrument_identifier |
CLABE: 18 digits with a valid check digit and a supported bank prefix. Debit card: 13 to 19 digits that pass the card checksum (Luhn) | 50 characters | Yes | The CLABE or debit card number |
amount |
Decimal (e.g. 1250.23), greater than 0 and up to 50000.00 |
— | Yes | The amount to collect, in MXN |
document_type |
mx_rfc / mx_curp |
— | Yes | Customer identification type |
document_number |
Alphanumeric (RFC or CURP format) | 50 characters | Yes | Customer identification number |
customer_name |
Letters and spaces | 255 characters | Yes | Full name of the customer or payer |
reference |
Letters, numbers, - and _ |
100 characters | Yes | A merchant-assigned identifier to correlate the charge in your own systems |
days_due |
Integer (e.g. 60) |
— | No | Optional hint used by the platform to improve the likelihood of successful collection |
instrument_bank is not required for mx_clabe, because the bank is encoded in the CLABE itself. Use the bank ID value (for example mx_santander) from Banks and institutions.
instrument_type,instrument_bank,instrument_identifier
mx_direct_debit_card,mx_santander,0000000000000001Charge response file columns
Response files contain all columns from the request file, plus the following:
| Column | Allowed Values | Description |
|---|---|---|
result |
confirmed / declined / canceled |
The outcome of the charge attempt |
declined_reason |
Platform error code | Present when result is declined. See Platform Error Codes |
declined_reason_rail |
Bank error code | Present when result is declined. See Bank Error Codes |
Validation error file columns
If any row fails validation, the whole file is rejected (status errored) and no charges are created. The platform returns your original file with all request rows plus one column. The same report is returned over SFTP and is the file you download in the Portal for an errored upload.
| Column | Description |
|---|---|
validation_errors |
The validation errors for that row, one per line, each naming the field and the error. Empty for valid rows |
File format notes
- Files must be in CSV format with a header row. The header must list the columns in exactly the order of the table above. You can add an optional
customer_emailcolumn at the end. - The file name must contain only letters, numbers, hyphens (
-), and underscores (_). No spaces or special characters.
Limits
| Constraint | Limit |
|---|---|
| File size | 30 MB maximum |
| Data rows | At least 2 (excluding the header). No maximum row count; a file is bounded only by the 30 MB size limit and by finishing processing within the platform’s processing window |
| Amount per charge | Greater than 0, up to 50,000 MXN |
| Total batch amount | No limit |
There’s no automatic retry if a file fails to finish processing. For example, if a very large file doesn’t complete within the processing window, resubmit it.