SPEI
Quick Reference
O que é SPEI
O SPEI (Sistema de Pagos Electrónicos Interbancarios) é o sistema de transferência interbancária em tempo real do México, operado pelo Banco de México. Ele permite transferências instantâneas 24/7 entre qualquer conta bancária no México usando um número CLABE (Clave Bancaria Estandarizada) como referência de pagamento.
| Característica | Detalhe |
|---|---|
| Mercado | México |
| Moeda | MXN |
| Liquidação | Quase em tempo real (mesmo dia) |
| Disponibilidade | 24/7/365 |
| Chargebacks | Nenhum — pagamento push irrevogável |
| Validade padrão | 24 horas (configurável) |
Como funciona
Comerciante cria a cobrança
Seu servidor chama POST /api/v1/bank/wallet/charge/ com type_charge: "spei" e currency: "MXN".
A55 gera a referência CLABE
A API retorna um número CLABE e uma referência de pagamento para o cliente utilizar.
Cliente transfere via SPEI
O cliente inicia uma transferência SPEI a partir do seu app bancário para o CLABE fornecido.
Confirmação em tempo real
O Banco de México processa a transferência. A A55 recebe a confirmação e envia um webhook com status: "paid".
Fluxo de pagamento
Ciclo de vida do SPEI
| Status | Descrição |
|---|---|
| issued | CLABE gerado; aguardando transferência |
| pending | Registrado; aguardando transferência SPEI |
| paid | Transferência SPEI confirmada |
| expired | Nenhuma transferência recebida antes do prazo |
| error | Erro na geração ou processamento |
Criar uma cobrança SPEI
/api/v1/bank/wallet/charge/Bearer TokenCriar um pagamento SPEI- cURL
- Python
curl -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"wallet_uuid": "00000000-0000-0000-0000-000000000000",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "Carlos García",
"payer_email": "carlos.garcia@example.com",
"payer_tax_id": "GARC850101HDFRRL09",
"payer_cell_phone": "+5215512345678",
"installment_value": 1500,
"installment_count": 1,
"items": [{"name":"Premium Plan","quantity":1,"total_amount":1500,"unit_amount":1500,"sku":"PLAN-MX-001","code":"PM001"}],
"payer_address": {"street":"Av. Reforma","address_number":"222","complement":"Piso 5","neighborhood":"Juárez","city":"Ciudad de México","state":"CDMX","postal_code":"06600","country":"MX"},
"currency": "MXN",
"due_date": "2026-12-31T23:59:59Z",
"description": "Premium subscription",
"type_charge": "spei",
"webhook_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/confirmation"
}'
import requests
charge = requests.post(
"https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
json={
"wallet_uuid": "00000000-0000-0000-0000-000000000000",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "Carlos García",
"payer_email": "carlos.garcia@example.com",
"payer_tax_id": "GARC850101HDFRRL09",
"payer_cell_phone": "+5215512345678",
"installment_value": 1500,
"installment_count": 1,
"items": [{"name": "Premium Plan", "quantity": 1, "total_amount": 1500, "unit_amount": 1500, "sku": "PLAN-MX-001", "code": "PM001"}],
"payer_address": {"street": "Av. Reforma", "address_number": "222", "complement": "Piso 5", "neighborhood": "Juárez", "city": "Ciudad de México", "state": "CDMX", "postal_code": "06600", "country": "MX"},
"currency": "MXN",
"due_date": "2026-12-31T23:59:59Z",
"description": "Premium subscription",
"type_charge": "spei",
"webhook_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/confirmation",
},
)
data = charge.json()
clabe = data["clabe"]
reference = data["payment_reference"]
Exemplo de resposta
{
"charge_uuid": "b4c2d5e6-7890-abcd-ef12-3456789abcde",
"currency": "MXN",
"type": "spei",
"status": "issued",
"clabe": "646180157042875632",
"payment_reference": "A55-SPE-20261231-001",
"beneficiary_name": "A55 Pagamentos",
"due_date": "2026-12-31T23:59:59Z",
"charge_payment_url": "https://pay.a55.tech/charge/b4c2d5e6-7890-abcd-ef12-3456789abcde"
}
| Campo | Descrição |
|---|---|
clabe | CLABE de 18 dígitos para o destino da transferência SPEI |
payment_reference | Código de referência que o cliente deve incluir na transferência |
beneficiary_name | Nome a ser exibido como destinatário da transferência |
due_date | Prazo após o qual a cobrança expira |
Vencimento
O vencimento padrão do SPEI é de 24 horas. Configure via due_date. Após o vencimento, a cobrança é marcada como expired e um webhook é enviado.
Exiba o CLABE, nome do beneficiário, valor e referência de forma destacada. A maioria dos apps bancários mexicanos exige os quatro campos para concluir uma transferência SPEI.
Prazo de liquidação
A liquidação do SPEI é quase em tempo real. Assim que o Banco de México confirma a transferência, os fundos ficam disponíveis no mesmo dia.
| Cenário | Liquidação |
|---|---|
| Horário comercial (6:00–17:30 CST) | Minutos |
| Fora do horário / fins de semana | Próximo ciclo do Banxico (geralmente no mesmo dia) |
Ciclos de processamento do SPEI
O Banxico processa transferências SPEI em ciclos quase em tempo real ao longo do dia. Embora o sistema opere 24/7, transferências fora do horário comercial podem ter tempos de confirmação ligeiramente maiores, pois entram em fila para o próximo ciclo de processamento. A A55 monitora as notificações de liquidação continuamente e dispara webhooks assim que a confirmação chega.
Erros comuns
| Erro | Causa | Solução |
|---|---|---|
invalid_currency | A moeda não é MXN | SPEI aceita apenas Pesos Mexicanos |
invalid_tax_id | Formato RFC/CURP inválido | Verifique o documento fiscal mexicano do pagador |
amount_below_minimum | Valor abaixo do mínimo do provedor | Verifique o valor mínimo do SPEI |
spei_generation_failed | Falha na geração do CLABE | Tente novamente; se persistir, entre em contato com o suporte |