Docs
ES

Goal

Let MexCep extract the transfer fields from a SPEI receipt image and validate the transfer against the Banxico CEP — without you manually parsing the comprobante. The resulting validation record is identical to one created with POST /v1/validate; you can download the CEP certificate and enable retries the same way.

Prerequisites

  • An active API key (mxcep_…) with the validations_ocr:create permission.
  • A receipt image in JPEG, PNG, or WebP format, under 20 MB.
  • The image must contain a legible SPEI comprobante (electronic receipt). Masked account numbers are resolved against your registered beneficiaries list when the masked form matches an account on file.

Steps

1. Submit the receipt

Send the image as a base64-encoded string in the image field, or pass a publicly accessible URL in image_url. You can optionally provide cuenta_beneficiaria as a disambiguation hint when the image shows a masked account.

Option A — remote URL:

curl -X POST 'https://api.example.com/v1/validate-ocr' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "https://storage.example.com/receipts/spei-receipt-001.png",
    "playground": false
  }'

Option B — base64 image:

curl -X POST 'https://api.example.com/v1/validate-ocr' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "<base64-encoded-image-bytes>",
    "playground": false
  }'

Synchronous 200 response — OCR extracted the fields and Banxico replied in-band:

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "validation",
    "attributes": {
      "validation_type": "ocr",
      "status": "valid",
      "has_cep": true,
      "ocr_confidence": 0.96,
      "ocr_result": {
        "fecha": "2025-04-10",
        "monto": 12500.00,
        "clave_rastreo": "MXBA20250410003456"
      },
      "image_path": "comprobantes/c3d4e5f6-a7b8-9012-cdef-123456789012.png",
      "processing_time_ms": 2840,
      "created_at": "2025-04-10T11:30:00Z",
      "completed_at": "2025-04-10T11:30:02Z"
    }
  }
}

2. Handle the async path (?async=1)

For high-volume pipelines, add ?async=1 to receive an immediate 202 and let the OCR + CEP query run in the background. The image is sanitized and persisted before the job is enqueued, so you won't lose it if the worker is briefly down.

curl -X POST 'https://api.example.com/v1/validate-ocr?async=1' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "image_url": "https://storage.example.com/receipts/spei-receipt-002.png" }'

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. Honor the Retry-After header when present.

3. Download the CEP certificate

Once status is valid and has_cep is true, download the certificate just as you would for a direct validation:

curl 'https://api.example.com/v1/validations/c3d4e5f6-.../cep?format=pdf' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output cep.pdf

4. Retrieve the stored receipt image

The sanitized image is persisted on the platform and accessible via GET /v1/validations/{id}/image. Use this to display the comprobante in your UI or to archive it alongside the CEP.

curl 'https://api.example.com/v1/validations/c3d4e5f6-.../image' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output comprobante.png

What's next