Documentación de la API de MonCash y NatCash
Todo lo necesario para integrar envíos a billeteras MonCash y NatCash desde su plataforma: autenticación, endpoints, estados, errores y ejemplos listos para copiar.
Inicio rápido
- Cree su cuenta gratis y genere en el panel un usuario API y una
PRIVATE_KEYde modo TEST. - Use la URL base TEST:
https://api.levapay.dev/test/v1 - Consulte el saldo, cotice, envíe con una
idempotency_keyúnica y consulte el estado. - Cuando su empresa esté verificada, repita con sus claves PROD y la URL base PROD:
https://api.levapay.dev/prod/v1
Una clave TEST no funciona en PROD y viceversa. Los envíos los hace su plataforma mediante la API.
Modo TEST
- El saldo TEST no es dinero real y lo asigna LevaPay. Si su saldo TEST es 0, los envíos responden 402: pida saldo TEST a su contacto de LevaPay.
- NatCash: use la billetera de prueba
50940885084. El envío quedacompletedal instante. - MonCash: en TEST los envíos quedan en
pendingy el monto queda reservado de su saldo TEST. Sirve para probar su manejo de estados.
Autenticación
Envíe estas cabeceras en cada petición:
Content-Type: application/json
X-Api-User: SU_USUARIO
X-Api-Key: SU_PRIVATE_KEYTodas las respuestas son JSON con ok. Si ok es false, el campo message explica el motivo.
Saldo
GEThttps://api.levapay.dev/test/v1/balance
Devuelve el saldo prepago disponible en HTG del modo de la URL.
{ "ok": true, "data": { "mode": "test", "balance_htg": 2000.00, "currency": "HTG" } }Cotizar
POSThttps://api.levapay.dev/test/v1/transfers/quote
{
"network": "natcash",
"wallet": "50940885084",
"amount_htg": 100,
"note": "Pago pedido 123"
}network: natcash o moncash. wallet: 8 dígitos o 509 + 8. amount_htg: entero mayor o igual a 1. La cotización dura unos 120 segundos y total_htg es lo que se debitará de su saldo si confirma.
note (opcional, máximo 64 caracteres): texto que verá el beneficiario en su depósito. Si no lo envía se usa LEVAPAY.
Respuesta:
{
"ok": true,
"data": {
"quote_id": "qt_df63eb09ceba25c5be99",
"network": "natcash",
"wallet_masked": "509****5084",
"amount_htg": 100,
"fee_htg": 3.5,
"total_htg": 103.5,
"expires_at": "2026-10-04T12:00:05-04:00",
"beneficiary": "Cuenta de prueba"
}
}fee_htg es la comisión y total_htg = amount_htg + fee_htg. beneficiary (nombre del titular) solo viene en NatCash.
Enviar
POSThttps://api.levapay.dev/test/v1/transfers
{ "quote_id": "qt_...", "idempotency_key": "pedido-123" }También puede omitir quote_id y enviar network, wallet y amount_htg junto con idempotency_key.
Idempotencia: si repite la petición con la misma idempotency_key y el mismo cuerpo recibe la misma transferencia sin un segundo débito; con la misma clave y otro cuerpo recibe 409. Una cotización solo se puede enviar una vez.
Respuesta:
{
"ok": true,
"data": {
"id": "tr_2d3c076092bbff0f59e3",
"status": "completed",
"network": "natcash",
"wallet": "509****5084",
"amount_htg": 100,
"fee_htg": 3.5,
"total_htg": 103.5,
"created_at": "2026-10-04T11:58:05-04:00",
"completed_at": "2026-10-04T11:58:06-04:00",
"message": null
}
}Las fechas usan ISO 8601 con zona horaria. message trae el motivo cuando el envío queda failed.
Historial y estado
GEThttps://api.levapay.dev/test/v1/transfers
Parámetros opcionales: page, per_page (máximo 100), status y network. Del más reciente al más antiguo.
{
"ok": true,
"data": {
"items": [
{
"id": "tr_37092e06026a4f7cc967",
"status": "pending",
"network": "moncash",
"wallet": "509****5084",
"amount_htg": 10,
"fee_htg": 0.35,
"total_htg": 10.35,
"created_at": "2026-10-04T11:58:08-04:00",
"completed_at": null,
"message": null
}
],
"page": 1,
"per_page": 20,
"total": 6
}
}GEThttps://api.levapay.dev/test/v1/transfers/{id}
Devuelve el mismo objeto que el envío. Si el estado es pending (MonCash), vuelva a consultar hasta completed o failed.
Titular NatCash
GEThttps://api.levapay.dev/test/v1/wallets/50940885084?network=natcash
Devuelve el nombre del titular NatCash desde el directorio interno (sin consultar Bencash). Si no hay registro, beneficiary será null: envíe beneficiary_name en la cotización. No disponible para MonCash.
{
"ok": true,
"data": {
"network": "natcash",
"wallet_masked": "509****5084",
"beneficiary": "Jean Pierre",
"quote_id": null,
"note": "Consulta en directorio interno (sin Bencash). Si no hay titular, envíe beneficiary_name en la cotización."
}
}Errores y estados
| HTTP | Significado |
|---|---|
| 401 | Usuario o clave inválidos, o clave de otro modo |
| 402 | Saldo prepago insuficiente |
| 403 | Cuenta aún no aprobada para producción (solo PROD) |
| 404 | Transferencia o endpoint inexistente |
| 409 | Cotización ya usada, o idempotency_key repetida con otro cuerpo |
| 422 | Datos inválidos o cotización vencida |
| 429 | Más de 60 peticiones por minuto con la misma clave |
| 503 | Servicio de envíos no disponible temporalmente |
{ "ok": false, "message": "Saldo prepago insuficiente." }Estados de un envío: pending, completed y failed. El débito ocurre solo si el envío se acepta; si falla después, el monto vuelve a su saldo.
Ejemplos
cURL: cotizar un envío NatCash (TEST)
curl -s -X POST https://api.levapay.dev/test/v1/transfers/quote \
-H "Content-Type: application/json" \
-H "X-Api-User: SU_USUARIO" \
-H "X-Api-Key: SU_PRIVATE_KEY" \
-d '{"network":"natcash","wallet":"50940885084","amount_htg":100}'cURL: confirmar el envío
curl -s -X POST https://api.levapay.dev/test/v1/transfers \
-H "Content-Type: application/json" \
-H "X-Api-User: SU_USUARIO" \
-H "X-Api-Key: SU_PRIVATE_KEY" \
-d '{"quote_id":"qt_...","idempotency_key":"envio-001"}'PHP
<?php
$base = 'https://api.levapay.dev/test/v1';
$headers = [
'Content-Type: application/json',
'X-Api-User: SU_USUARIO',
'X-Api-Key: SU_PRIVATE_KEY',
];
function post(string $url, array $body, array $headers): array {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => json_encode($body),
]);
return json_decode((string) curl_exec($ch), true);
}
$quote = post("$base/transfers/quote", [
'network' => 'natcash', // o moncash
'wallet' => '50940885084',
'amount_htg' => 100,
], $headers);
$transfer = post("$base/transfers", [
'quote_id' => $quote['data']['quote_id'] ?? '',
'idempotency_key' => 'envio-' . uniqid(),
], $headers);
echo $transfer['data']['status'] ?? $transfer['message'];Node.js
const base = 'https://api.levapay.dev/test/v1';
const headers = {
'Content-Type': 'application/json',
'X-Api-User': 'SU_USUARIO',
'X-Api-Key': process.env.LEVAPAY_KEY, // SU_PRIVATE_KEY
};
const post = (path, body) =>
fetch(base + path, { method: 'POST', headers, body: JSON.stringify(body) })
.then((r) => r.json());
const quote = await post('/transfers/quote', {
network: 'natcash', // o moncash
wallet: '50940885084',
amount_htg: 100,
});
const transfer = await post('/transfers', {
quote_id: quote.data.quote_id,
idempotency_key: `envio-${Date.now()}`,
});
console.log(transfer.data?.status ?? transfer.message);¿Listo para integrar?
Cree su cuenta gratis y obtenga sus claves TEST en minutos.