Overview
The GET /api/balance endpoint returns the authenticated account’s balance in MXN centavos (integers). There are two fields:
availableCentavos — balance available to send SPEI cash-outpendingCentavos — blocked balance (cash-out in processing, cash-in confirming)
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.
Response Structure
Available balance in MXN centavos. Use this value to validate before a cash-out.
Pending balance in MXN centavos. Includes cash-out in processing and cash-in waiting for final settlement confirmation.
Always MXN in the México scope.
Node.js Example
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;
}
Validation Before 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}` },
});
}
Even validating the balance beforehand, the cash-out may fail with 400 if another concurrent cash-out consumes the balance. Treat the 400 error as “insufficient balance” at the call time.
Response Codes
| Code | Meaning |
|---|
200 | Balance queried |
401 | Invalid or missing token |
502 | account-ms unavailable |
Next Steps
SPEI Cash-Out
Send a SPEI transfer using the available balance
