Docs
ES

Goal

Build and maintain a whitelist of trusted beneficiary accounts — CLABEs, debit/credit card numbers, and DiMo phone numbers. The whitelist is used by the OCR pipeline to resolve masked account numbers and by your application to validate that a transfer destination is known before submission.

Prerequisites

  • An active API key (mxcep_…) with beneficiaries:read and beneficiaries:create.
  • To update: beneficiaries:update. To delete/archive: beneficiaries:delete.
  • To import many accounts at once from a spreadsheet, use POST /v1/beneficiaries/imports instead — see Bulk beneficiary import.

Steps

1. List existing beneficiaries

Retrieve your full whitelist. The response is not paginated; use with_archived to control visibility of archived accounts.

# Active accounts only
curl 'https://api.example.com/v1/beneficiaries?with_archived=0' \
  -H 'Authorization: Bearer mxcep_••••'
{
  "data": [
    {
      "type": "beneficiary",
      "id": 42,
      "attributes": {
        "alias": "Proveedor Alpha",
        "account": "012180004412345678",
        "account_type": "clabe",
        "bank_code": "40012",
        "bank_name": "BBVA MEXICO",
        "archived": false,
        "created_at": "2025-01-10T09:00:00Z"
      }
    }
  ]
}

2. Add a beneficiary

curl -X POST 'https://api.example.com/v1/beneficiaries' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "alias": "Proveedor Beta",
    "account": "646180157000001234",
    "account_type": "clabe"
  }'

For DiMo (phone number) accounts, set account_type to phone and provide the 10-digit number. Bank codes are derived automatically from the CLABE prefix or card BIN; you can override them explicitly if needed.

Response 201:

{
  "data": {
    "type": "beneficiary",
    "id": 87,
    "attributes": {
      "alias": "Proveedor Beta",
      "account": "646180157000001234",
      "account_type": "clabe",
      "bank_code": "90646",
      "bank_name": "STP",
      "archived": false,
      "created_at": "2025-04-22T14:15:00Z"
    }
  }
}

3. Update a beneficiary

Change the alias or any editable field. The account number itself is immutable — delete and re-add if you need to change it.

curl -X PUT 'https://api.example.com/v1/beneficiaries/87' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "alias": "Proveedor Beta S.A." }'

Returns 200 with the updated record.

4. Archive a beneficiary

Soft-delete an account to remove it from the active list without permanently deleting the history. Previously archived accounts with the same number are reactivated rather than duplicated on import.

curl -X DELETE 'https://api.example.com/v1/beneficiaries/87' \
  -H 'Authorization: Bearer mxcep_••••'

Returns 204. To view archived accounts: GET /v1/beneficiaries?with_archived=1.

5. Export the list

Download your complete beneficiary list as a file for audit or system sync:

curl 'https://api.example.com/v1/beneficiaries/export?format=csv' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output beneficiaries.csv

Use format=xlsx for a spreadsheet. The export respects the same with_archived filter as the list endpoint.

What's next