Visão Geral
O cash-out SPEI envia uma transferência interbancária para uma CLABE de destino. O saldo da conta é debitado e a NTX Pay processa a transferência na rede SPEI. A confirmação chega via webhook cash_out.
Endpoint
POST /api/spei/cash-out
Authorization: Bearer {token}
Content-Type: application/json
Request
curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-out \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amountCentavos": 50000,
"destinationClabe": "012180001234567890",
"beneficiaryName": "Maria Lopez",
"beneficiaryTaxId": "LOMA850101ABC",
"concept": "Invoice 123 payment"
}'
Response (201)
{
"id": 56789,
"status": "PENDING",
"destinationClabe": "012180001234567890",
"amountCentavos": 50000,
"referenceNumerical": "9876543",
"createdAt": "2026-05-13T12:00:00.000Z"
}
Campos do Request
Valor em centavos MXN (mínimo 1). Ex.: 50000 = $500,00 MXN.
CLABE de destino — exatamente 18 dígitos numéricos (regex: ^\d{18}$).
Nome do beneficiário (3–255 caracteres).
RFC/CURP do beneficiário (10–20 caracteres). Recomendado para reconciliação.
Conceito exibido no extrato do beneficiário (até 255 caracteres).
Validação de Saldo
Antes de enviar, valide o saldo:
const balance = await getBalance(token);
if (balance.availableCentavos < amountCentavos) {
throw new Error('Insufficient balance');
}
Saldo insuficiente retorna 400 — a transação não é criada. Aplique idempotência no lado do cliente (não reprocesse o mesmo pedido após um 400 sem revalidar o saldo).
Estados
| Status | Significado |
|---|
PENDING | Cash-out aceito, aguardando liquidação SPEI |
CONFIRMED | Liquidado no Banxico |
FAILED | Rejeitado pela rede SPEI |
Códigos de Erro
| Código | Causa |
|---|
400 | Saldo insuficiente, CLABE inválida, payload inválido |
401 | Token inválido |
502 | Falha temporária no processamento — não tente novamente sem verificar o status via GET /api/transactions |
async function speiCashOut(token: string, dto: any) {
try {
const { data } = await axios.post(
'https://sandbox.mx.ntxpay.com/api/spei/cash-out',
dto,
{ headers: { Authorization: `Bearer ${token}` } },
);
return data; // status: PENDING
} catch (err) {
if (err.response?.status === 502) {
// Não sabemos se a transação foi criada. Consulte /api/transactions filtrando por externalId
// antes de tentar novamente.
}
throw err;
}
}
Próximos Passos
Webhook cash_out
Detalhes do payload do webhook de liquidação
