Bank Account MXN

Introduction

MXN Beneficiary is used as the destination when you transact with MXN (Mexican Peso) fiat. MXN payouts route through Avenia's MXN fiat rail using a single payment method:

Rail	Required fields	Use for
MXN Bank Transfer	Beneficiary identity + address, `bankAccountNumber` (CLABE) and `bankId`	Mexican bank-to-bank transfer to an 18-digit CLABE.

The destination account is identified by a CLABE (Clave Bancaria Estandarizada) — the 18-digit standardized account key every Mexican bank and wallet issues. There is no account-type or alias variant: the CLABE alone identifies the account.

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

warning

MXN transfers are irreversible once executed — ensure beneficiary details are correct before creating a payout ticket.

info

MXN is the narrowest of Avenia's LatAm rails. If you are porting an integration from ARS or COP, note that the MXN payload has no phoneNumber, no documentType, no documentNumber and no accountType. Sending them is unnecessary; the fields below are the complete set.

Supported Banks

The canonical list of supported Mexican banks lives at Supported Banks MXN. Use the bankId value from that page when registering a beneficiary.

Register an MXN Beneficiary Account

Endpoint:

POST https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/

Required fields

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "alias": "Maria CLABE Banorte",
  "description": "Cuenta principal de Maria en Banorte",
  "beneficiaryName": "Maria Fernanda Lopez",
  "beneficiaryType": "individual",
  "beneficiaryEmail": "maria@example.com",
  "beneficiaryAddress": {
    "address1": "Av Paseo de la Reforma 222",
    "address2": "Piso 12",
    "country": "MX",
    "subDivision": "CMX",
    "city": "Ciudad de Mexico",
    "postalCode": "06600"
  },
  "bankAccountNumber": "072180123456789014",
  "bankId": "bank_mxn_014"
}'

Field	Type	Required	Validation Rules	Description
`alias`	string	Yes	1–100 characters; unique per user	A custom name for the beneficiary.
`description`	string	No	Max 100 characters	Optional description.
`beneficiaryName`	string	Yes	—	Full legal name of the recipient.
`beneficiaryType`	string	Yes	`individual` or `business` (lowercase)	Type of account holder.
`beneficiaryEmail`	string	Yes	Valid email	Email of the beneficiary.
`beneficiaryAddress.address1`	string	Yes	—	Street address line 1.
`beneficiaryAddress.address2`	string	No	—	Apartment / floor.
`beneficiaryAddress.country`	string	Yes	—	ISO country code.
`beneficiaryAddress.subDivision`	string	Yes	—	Mexican state (e.g. `CMX` for Ciudad de Mexico).
`beneficiaryAddress.city`	string	Yes	—	City name.
`beneficiaryAddress.postalCode`	string	Yes	—	Mexican postal code.
`bankAccountNumber`	string	Yes	Exactly 18 digits; valid Modulo-10 check digit	The destination CLABE.
`bankId`	string	Yes	Must be from `/supported-banks`	Bank identifier.
`bankName`	string	No	Ignored — see below	Bank name.

info

The whole beneficiaryAddress object is capped at 4096 bytes when serialized as JSON. Long free-text address lines will be rejected before the registration reaches the rail.

warning

bankName is accepted but ignored. Unlike the ARS and COP rails — where the value you send is persisted and returned verbatim — the MXN rail overwrites bankName from Avenia's curated bank list using the bankId you provided. Whatever you send is discarded, and the GET responses will show Avenia's canonical name for that bank. Drive your UI from bankId.

About the CLABE

The bankAccountNumber must be a valid CLABE:

Exactly 18 digits. Any non-digit characters (spaces, dashes) are stripped before validation, so 072 180 123456789 014 and 072180123456789014 are treated identically.
The 18th digit is a Modulo-10 check digit computed over the first 17. Avenia validates it locally before forwarding the registration, so a typo is caught at registration time rather than at payout time.

warning

A CLABE that passes the check digit is still not proof that the account exists or belongs to the named beneficiary. Confirm the CLABE with the recipient — MXN payouts are irreversible.

Common Errors

Error	Cause
`bankAccountNumber is invalid`	Not exactly 18 digits, or the Modulo-10 check digit does not match.
`bankId is invalid`	`bankId` is not in `/supported-banks`.
`beneficiaryType is invalid`	Value is not `individual` or `business` (must be lowercase).
`alias is invalid`	Empty, longer than 100 characters, or already used by another beneficiary of yours.

JSON Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields Explained

Field	Type	Description
`id`	string (UUID)	Unique identifier for this beneficiary account — SAVE THIS for future payout operations

List all MXN beneficiaries bank accounts

To get all the MXN bank accounts, use the endpoint below, with filter fields:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/

Filter Fields

Field	Type	Description
subAccountId	string	The ID of a sub-account. If provided, data will be fetched for the sub-account; leave empty for main account.
createdAfter	int64	Unix epoch timestamp in milliseconds (UTC) — e.g. `1700000000000`. Returns results created on or after this instant (`created_at >= createdAfter`).
createdBefore	int64	Unix epoch timestamp in milliseconds (UTC) — e.g. `1800000000000`. Returns results created strictly before this instant (`created_at < createdBefore`).
cursor	string	Cursor for pagination. Pass the value from the previous response to retrieve the next set of results.
alias	string	Filters results to include only those with the specified alias.

Timestamp format

createdAfter / createdBefore are Unix epoch timestamps in milliseconds, UTC (13 digits for current dates, e.g. 1700000000000) — not seconds. If you have a value in seconds, multiply it by 1000. The lower bound is inclusive and the upper bound is exclusive, and the returned createdAt is an RFC3339 UTC string ending in Z. Convert local date boundaries to UTC before computing the epoch.

cUrl Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/?subAccountId=&createdAfter=1700000000000&createdBefore=1800000000000&cursor=NEXT_CURSOR&alias=Maria%20CLABE%20Banorte" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "bankAccounts": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "userId": "11111111-1111-1111-1111-111111111111",
      "alias": "Maria CLABE Banorte",
      "description": "Cuenta principal de Maria en Banorte",
      "beneficiaryName": "Maria Fernanda Lopez",
      "beneficiaryType": "individual",
      "beneficiaryEmail": "maria@example.com",
      "beneficiaryAddress": {
        "address1": "Av Paseo de la Reforma 222",
        "address2": "Piso 12",
        "country": "MX",
        "subDivision": "CMX",
        "city": "Ciudad de Mexico",
        "postalCode": "06600"
      },
      "bankAccountNumber": "072180123456789014",
      "bankId": "bank_mxn_014",
      "bankName": "Banorte",
      "createdAt": "2026-08-11T16:13:08.320462Z"
    }
  ],
  "cursor": "MzItMTc0MDA2NDM4ODMyMA..."
}

Response Fields Explained

Field	Type	Description
`bankAccounts`	array	Array of MXN beneficiary accounts for this user
`bankAccounts[].id`	string (UUID)	Unique account identifier
`bankAccounts[].userId`	string (UUID)	Your user ID (account owner)
`bankAccounts[].alias`	string	The friendly name you assigned
`bankAccounts[].description`	string	The description you provided
`bankAccounts[].beneficiaryName`	string	Full name of the account holder
`bankAccounts[].beneficiaryType`	string	`individual` or `business`
`bankAccounts[].beneficiaryEmail`	string	Beneficiary email
`bankAccounts[].beneficiaryAddress`	object	Full address used at registration
`bankAccounts[].bankAccountNumber`	string	18-digit CLABE
`bankAccounts[].bankId`	string	Bank identifier (e.g. `bank_mxn_014`)
`bankAccounts[].bankName`	string	Avenia's canonical name for `bankId` — not the value you sent at registration
`bankAccounts[].createdAt`	timestamp	ISO 8601 creation date
`cursor`	string	Pagination cursor for next page (only if more results exist)

Pagination

If cursor is present in the response, there are more results available
Pass this cursor value in the next request as a query parameter to fetch the next batch
No cursor in response means you've reached the last page

Get MXN beneficiary bank account by ID

To retrieve the details of a specific MXN bank account:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/00000000-0000-0000-0000-000000000000

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "bankAccount": {
    "id": "00000000-0000-0000-0000-000000000000",
    "userId": "11111111-1111-1111-1111-111111111111",
    "alias": "Maria CLABE Banorte",
    "description": "Cuenta principal de Maria en Banorte",
    "beneficiaryName": "Maria Fernanda Lopez",
    "beneficiaryType": "individual",
    "beneficiaryEmail": "maria@example.com",
    "beneficiaryAddress": {
      "address1": "Av Paseo de la Reforma 222",
      "address2": "Piso 12",
      "country": "MX",
      "subDivision": "CMX",
      "city": "Ciudad de Mexico",
      "postalCode": "06600"
    },
    "bankAccountNumber": "072180123456789014",
    "bankId": "bank_mxn_014",
    "bankName": "Banorte",
    "createdAt": "2026-08-11T16:13:08.320462Z"
  }
}

Delete MXN beneficiary bank Account

To delete a specific MXN bank account:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP DELETE Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/00000000-0000-0000-0000-000000000000

cUrl Example

curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/mxn/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{}

Status Code: HTTP 200 OK

Response: Empty JSON object — indicates successful deletion

Your MXN bank account has been deleted!

Sandbox behaviour

info

MXN beneficiary registration does not reach the rail in sandbox. The CLABE format, check digit and bankId are still validated locally, but no counterparty is created upstream. This differs from ARS and COP, where beneficiary registration hits the real staging rail even in sandbox. A sandbox MXN registration therefore succeeds as long as the payload is well formed.

Conclusion

In this section, you have learned how to manage MXN beneficiaries within the Avenia API system.

What we've covered:

✅ Reviewing Supported Mexican Banks — see Supported Banks MXN.
✅ Creating an MXN Beneficiary — identity, address, CLABE and bankId.
✅ Fetching All MXN Beneficiaries — Retrieve all registered beneficiaries.
✅ Fetching a Specific MXN Beneficiary by ID — Retrieve details by UUID.
✅ Deleting an MXN Beneficiary — Permanently remove the registration.

The returned id is used as beneficiaryMxnBankAccountId when creating MXN payout tickets — Avenia routes the payout to the registered CLABE.

Introduction​

Supported Banks​

Register an MXN Beneficiary Account​

Required fields​

About the CLABE​

Common Errors​

JSON Response​

Response Fields Explained​

List all MXN beneficiaries bank accounts​

HTTP GET Request​

Filter Fields​

cUrl Example:​

JSON Response​

Response Fields Explained​

Pagination​

Get MXN beneficiary bank account by ID​

HTTP GET Request​

cUrl Example​

JSON Response​

Delete MXN beneficiary bank Account​

HTTP DELETE Request​

cUrl Example​

JSON Response​

Sandbox behaviour​

Conclusion​

Introduction

Supported Banks

Register an MXN Beneficiary Account

Required fields

About the CLABE

Common Errors

JSON Response

Response Fields Explained

List all MXN beneficiaries bank accounts

HTTP GET Request

Filter Fields

cUrl Example:

JSON Response

Response Fields Explained

Pagination

Get MXN beneficiary bank account by ID

HTTP GET Request

cUrl Example

JSON Response

Delete MXN beneficiary bank Account

HTTP DELETE Request

cUrl Example

JSON Response

Sandbox behaviour

Conclusion