Goal

Submit a SPEI transfer's fields to the Banxico CEP and receive a machine-readable verdict (valid, not_found, cep_unavailable, or error). When the transfer is confirmed you can download the official CEP certificate as PDF or XML.

Prerequisites

• An active API key (mxcep_…). Retrieve it from your profile at GET /v1/users/me/api-key.
• The transfer details: date (fecha), amount (monto), and at least one of: tracking key (clave_rastreo) or numeric reference (referencia_numerica). Also required: issuing bank (emisor), receiving bank (receptor), and beneficiary account (cuenta_beneficiaria — CLABE, card, or DiMo phone number).

Steps

1. Submit the validation

Send the transfer fields to POST /v1/validate. Provide clave_rastreo, referencia_numerica, or both — more identifiers increase precision.

curl -X POST 'https://api.example.com/v1/validate' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2025-03-15",
    "monto": 15000.50,
    "clave_rastreo": "MXBA20250315001234",
    "emisor": "BANCO NACIONAL DE MEXICO",
    "receptor": "BBVA MEXICO",
    "cuenta_beneficiaria": "012180004412345678"
  }'

Synchronous response (200) — the CEP query completed in-band:

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "validation",
    "attributes": {
      "status": "valid",
      "has_cep": true,
      "processing_time_ms": 1320,
      "created_at": "2025-03-15T14:22:10Z",
      "completed_at": "2025-03-15T14:22:11Z"
    },
    "links": {
      "self": "/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "cep_xml": "/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479/cep?format=xml",
      "cep_pdf": "/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479/cep?format=pdf"
    }
  }
}

Status values:

2. Handle the async path (status: "async")

Under high load or when you pass ?async=1, the API returns 202 and the validation runs in the background:

curl -X POST 'https://api.example.com/v1/validate?async=1' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "fecha": "...", "monto": ..., "clave_rastreo": "...", ... }'

Response 202:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "validation",
    "attributes": { "status": "queued" }
  }
}

Poll GET /v1/validations/{id} every 2–5 seconds until status reaches a terminal value (valid, not_found, cep_unavailable, error):

curl 'https://api.example.com/v1/validations/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer mxcep_••••'

3. Download the CEP certificate

When status is valid and has_cep is true, fetch the certificate:

# PDF (human-readable)
curl 'https://api.example.com/v1/validations/f47ac10b-.../cep?format=pdf' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output cep.pdf

# XML (machine-readable, Banxico canonical format)
curl 'https://api.example.com/v1/validations/f47ac10b-.../cep?format=xml' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output cep.xml

4. Enable automatic retries on non-valid outcomes

For not_found or cep_unavailable results, enable automatic retries so the platform polls Banxico again without additional calls from your side:

curl -X PUT 'https://api.example.com/v1/validations/a1b2c3d4-.../retry-policy' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "max_retries": 3,
    "interval_seconds": 600,
    "outcomes": ["not_found", "cep_unavailable"]
  }'

You can also pass retry_policy directly in the original POST /v1/validate body to configure retries in a single call. Check retry history with GET /v1/validations/{id}/retry-attempts.

5. Avoid duplicate submissions

Use the Idempotency-Key header to de-duplicate network retries. Any request with the same key and identical body within 24 hours returns the cached response:

curl -X POST 'https://api.example.com/v1/validate' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Idempotency-Key: my-system-txn-id-12345' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

What's next

• Browse your full validation history: GET /v1/validations (filter by status, date range, account type).
• Validate from a receipt image instead of manual fields: see Validate via OCR.
• Export results to CSV for reconciliation: GET /v1/validations/export.