Visão Geral
O endpoint GET /api/balance retorna o saldo da conta autenticada em centavos MXN (inteiros). Há dois campos:
availableCentavos — saldo disponível para enviar cash-out SPEIpendingCentavos — saldo bloqueado (cash-out em processamento, cash-in confirmando)
Endpoint
GET /api/balance
Authorization: Bearer {token}
Request
curl -X GET https://sandbox.mx.ntxpay.com/api/balance \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response (200)
{
"availableCentavos": 4873490,
"pendingCentavos": 0,
"currency": "MXN"
}
4873490 centavos = $48.734,90 MXN.
Estrutura da Resposta
Saldo disponível em centavos MXN. Use este valor para validar antes de um cash-out.
Saldo pendente em centavos MXN. Inclui cash-out em processamento e cash-in aguardando a confirmação final da liquidação.
Sempre MXN no escopo México.
Exemplo em Node.js
import axios from 'axios';
async function getBalance(token: string) {
const { data } = await axios.get('https://sandbox.mx.ntxpay.com/api/balance', {
headers: { Authorization: `Bearer ${token}` },
});
const availableMXN = (data.availableCentavos / 100).toFixed(2);
const pendingMXN = (data.pendingCentavos / 100).toFixed(2);
console.log(`Available: $${availableMXN} MXN`);
console.log(`Pending: $${pendingMXN} MXN`);
return data;
}
Validação Antes do Cash-Out
async function safeSpeiCashOut(amountCentavos: number, token: string, dto: any) {
const balance = await getBalance(token);
if (balance.availableCentavos < amountCentavos) {
throw new Error(
`Insufficient balance: available ${balance.availableCentavos}, ` +
`requested ${amountCentavos} (in centavos)`,
);
}
return axios.post('https://sandbox.mx.ntxpay.com/api/spei/cash-out', dto, {
headers: { Authorization: `Bearer ${token}` },
});
}
Mesmo validando o saldo antes, o cash-out pode falhar com 400 se outro cash-out concorrente consumir o saldo. Trate o erro 400 como “saldo insuficiente” no momento da chamada.
Códigos de Resposta
| Código | Significado |
|---|
200 | Saldo consultado |
401 | Token inválido ou ausente |
502 | account-ms indisponível |
Próximos Passos
SPEI Cash-Out
Envie uma transferência SPEI usando o saldo disponível
