SPEI Cash-In

Visão Geral

O cash-in SPEI gera uma CLABE descartável que o pagador usa para fazer uma transferência SPEI pelo app do banco. Quando a NTX Pay recebe a liquidação, você é notificado no webhook cash_in com o evento transaction.cash_in.settled. Características:

CLABE válida para uma única transferência (uso único)
Confirmação assíncrona (segundos a minutos)
Expira em ~24 horas se não for paga (você recebe o webhook transaction.cash_in.expired)

Endpoint

POST /api/spei/cash-in

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request

curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCentavos": 50000,
    "externalId": "order-abc-123",
    "description": "Order #123",
    "customerName": "Juan Perez",
    "customerEmail": "juan@example.com",
    "customerTaxId": "PEPJ800101ABC"
  }'

Response (201)

{
  "transactionId": "3f2a1c34-9d1e-4c7b-8a5e-2b6f0d9c4e71",
  "status": "PENDING",
  "destinationClabe": "012180001234567890",
  "beneficiary": {
    "name": "NTX Pay MX",
    "taxId": "NTX800101ABC"
  },
  "referenceNumerical": "1234567",
  "checkoutUrl": "https://pay.ntxpay.com/checkout/xyz",
  "expiresAt": "2026-05-14T23:59:59.000Z",
  "amountCentavos": 50000
}

Exiba a destinationClabe (e/ou a checkoutUrl) ao pagador final. O transactionId (UUID) é o identificador único da transação — é o mesmo valor entregue nos webhooks; use-o para correlacionar eventos e consultar a transação.

Campos do Response

string

obrigatório

Identificador único da transação (UUID). Mesmo valor entregue nos webhooks.

string

obrigatório

Status da transação: PENDING, CONFIRMED, FAILED ou EXPIRED.

string

obrigatório

CLABE de destino que o pagador deve usar na transferência SPEI.

object

obrigatório

Beneficiário exibido ao pagador (name e, quando disponível, taxId).

string

Referência numérica SPEI, quando disponível.

string

URL de checkout hospedado (alternativa à transferência manual), quando disponível.

string

obrigatório

Expiração da cobrança (ISO 8601).

integer

obrigatório

Valor em centavos MXN.

Campos do Request

integer

obrigatório

Valor em centavos MXN. **Mínimo: 1000 centavos (

10,00 MXN)** — piso do banco parceiro; abaixo disso a API retorna `400` com code `CASHIN_MIN_AMOUNT`. Ex.: `50000` =

500,00 MXN.

string

Identificador externo único (até 100 caracteres). Use para correlacionar com o seu sistema. Recomendado para idempotência.

string

Descrição da cobrança (até 255 caracteres).

string

obrigatório

Nome do pagador (1–255 caracteres), exibido no checkout SPEI.

string

obrigatório

E-mail do pagador (formato de e-mail válido).

string

RFC/CURP do pagador (10–20 caracteres).

Fluxo de Pagamento

Estados da Transação

Status	Significado
`PENDING`	CLABE emitida, aguardando transferência
`CONFIRMED`	Transferência recebida e liquidada
`FAILED`	Erro de processamento
`EXPIRED`	CLABE expirou sem receber transferência

No webhook, a liquidação chega como transaction.cash_in.settled com status: LIQUIDATED — veja o payload completo.

Idempotência

Reenvie a mesma requisição com o mesmo externalId para garantir que uma falha de rede não gere duas cobranças. Em caso de duplicação, a NTX Pay retorna a cobrança existente.

Testar no Sandbox

No sandbox, a liquidação é simulada em segundos — sem depender de um banco emissor. Controle o desfecho com o header X-Sandbox-Scenario:

curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: rejected" \
  ...

Veja o catálogo de cenários para forçar rejeição, devolução e atraso.

Próximos Passos

Webhook cash_in

Payload do webhook de confirmação

SPEI Cash-Out

Envie transferências SPEI

Guia

Sandbox

Webhooks

Autenticação

SPEI

Webhooks Config

Visão Geral

Endpoint

POST /api/spei/cash-in

Headers

Request

Response (201)

Campos do Response

Campos do Request

Fluxo de Pagamento

Estados da Transação

Idempotência

Testar no Sandbox

Próximos Passos

Webhook cash_in

SPEI Cash-Out

​Visão Geral

​Endpoint

​POST /api/spei/cash-in

​Headers

​Request

​Response (201)

​Campos do Response

​Campos do Request

​Fluxo de Pagamento

​Estados da Transação

​Idempotência

​Testar no Sandbox

​Próximos Passos

Webhook cash_in

SPEI Cash-Out

Visão Geral

Endpoint

POST /api/spei/cash-in

Headers

Request

Response (201)

Campos do Response

Campos do Request

Fluxo de Pagamento

Estados da Transação

Idempotência

Testar no Sandbox

Próximos Passos