Saltar al contenido
LevaPay

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

  1. Cree su cuenta gratis y genere en el panel un usuario API y una PRIVATE_KEY de modo TEST.
  2. Use la URL base TEST: https://api.levapay.dev/test/v1
  3. Consulte el saldo, cotice, envíe con una idempotency_key única y consulte el estado.
  4. 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 queda completed al instante.
  • MonCash: en TEST los envíos quedan en pending y 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_KEY

Todas 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

HTTPSignificado
401Usuario o clave inválidos, o clave de otro modo
402Saldo prepago insuficiente
403Cuenta aún no aprobada para producción (solo PROD)
404Transferencia o endpoint inexistente
409Cotización ya usada, o idempotency_key repetida con otro cuerpo
422Datos inválidos o cotización vencida
429Más de 60 peticiones por minuto con la misma clave
503Servicio 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.