Documentation de l’API MonCash et NatCash

Tout ce qu’il faut pour intégrer les transferts vers les portefeuilles MonCash et NatCash depuis votre plateforme : authentification, endpoints, statuts, erreurs et exemples prêts à copier.

Démarrage rapide

Créez un compte gratuit et générez dans le panneau un utilisateur API et une PRIVATE_KEY de mode TEST.
Utilisez l’URL de base TEST : https://api.levapay.dev/test/v1
Consultez le solde, demandez un devis, envoyez avec une idempotency_key unique et consultez le statut.
Une fois votre entreprise vérifiée, recommencez avec vos clés PROD et l’URL de base PROD : https://api.levapay.dev/prod/v1

Une clé TEST ne fonctionne pas en PROD et inversement. Les transferts sont effectués par votre plateforme via l’API.

Mode TEST

Le solde TEST n’est pas de l’argent réel et il est attribué par LevaPay. Si votre solde TEST est à 0, les transferts répondent 402 : demandez du solde TEST à votre contact LevaPay.
NatCash : utilisez le portefeuille de test 50940885084. Le transfert est completed immédiatement.
MonCash : en TEST, les transferts restent pending et le montant est réservé sur votre solde TEST. Utile pour tester la gestion des statuts.

Authentification

Envoyez ces en-têtes à chaque requête :

Content-Type: application/json
X-Api-User: VOTRE_UTILISATEUR
X-Api-Key: VOTRE_PRIVATE_KEY

Toutes les réponses sont en JSON avec ok. Si ok vaut false, le champ message en donne la raison.

Solde

GEThttps://api.levapay.dev/test/v1/balance

Renvoie le solde prépayé disponible en HTG pour le mode de l’URL.

{ "ok": true, "data": { "mode": "test", "balance_htg": 2000.00, "currency": "HTG" } }

Devis

POSThttps://api.levapay.dev/test/v1/transfers/quote

{
  "network": "natcash",
  "wallet": "50940885084",
  "amount_htg": 100,
  "note": "Paiement commande 123"
}

network : natcash ou moncash. wallet : 8 chiffres ou 509 + 8. amount_htg : entier supérieur ou égal à 1. Le devis dure environ 120 secondes et total_htg est le montant débité de votre solde si vous confirmez.

note (facultatif, 64 caractères maximum) : texte que le bénéficiaire verra sur son dépôt. Sans note, LEVAPAY est utilisé.

Réponse :

{
  "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": "Compte de test"
  }
}

fee_htg est la commission et total_htg = amount_htg + fee_htg. beneficiary (nom du titulaire) n’est renvoyé que pour NatCash.

Envoi

POSThttps://api.levapay.dev/test/v1/transfers

{ "quote_id": "qt_...", "idempotency_key": "commande-123" }

Vous pouvez aussi omettre quote_id et envoyer network, wallet et amount_htg avec idempotency_key.

Idempotence : répéter la requête avec la même idempotency_key et le même corps renvoie le même transfert sans second débit ; la même clé avec un autre corps renvoie 409. Un devis ne peut être envoyé qu’une fois.

Réponse :

{
  "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
  }
}

Les dates sont au format ISO 8601 avec fuseau horaire. message indique la raison lorsqu’un transfert est failed.

Historique et statut

GEThttps://api.levapay.dev/test/v1/transfers

Paramètres facultatifs : page, per_page (100 maximum), status et network. Du plus récent au plus ancien.

{
  "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}

Renvoie le même objet que l’envoi. Si le statut est pending (MonCash), consultez à nouveau jusqu’à completed ou failed.

Titulaire NatCash

GEThttps://api.levapay.dev/test/v1/wallets/50940885084?network=natcash

Renvoie le nom du titulaire d’un portefeuille NatCash et crée un devis de vérification de 100 HTG : confirmez-le avec POST /transfers seulement si vous voulez l’envoyer. Non disponible pour MonCash.

{
  "ok": true,
  "data": {
    "network": "natcash",
    "wallet_masked": "509****5084",
    "beneficiary": "Compte de test",
    "quote_id": "qt_028c3443d910b8ed7db3",
    "note": "Cotización de verificación (100 HTG). Confirme con POST /transfers si desea enviarla."
  }
}

Erreurs et statuts

HTTP	Signification
401	Utilisateur ou clé invalide, ou clé de l’autre mode
402	Solde prépayé insuffisant
403	Compte pas encore approuvé pour la production (PROD uniquement)
404	Transfert ou endpoint introuvable
409	Devis déjà utilisé, ou idempotency_key réutilisée avec un autre corps
422	Données invalides ou devis expiré
429	Plus de 60 requêtes par minute avec la même clé
503	Service de transfert temporairement indisponible

{ "ok": false, "message": "Saldo prepago insuficiente." }

Statuts d’un transfert : pending, completed et failed. Le débit n’a lieu que si le transfert est accepté ; s’il échoue ensuite, le montant revient sur votre solde.

Les messages d’erreur de l’API sont renvoyés en espagnol.

Exemples

cURL : devis pour un transfert NatCash (TEST)

curl -s -X POST https://api.levapay.dev/test/v1/transfers/quote \
  -H "Content-Type: application/json" \
  -H "X-Api-User: VOTRE_UTILISATEUR" \
  -H "X-Api-Key: VOTRE_PRIVATE_KEY" \
  -d '{"network":"natcash","wallet":"50940885084","amount_htg":100}'

cURL : confirmer le transfert

curl -s -X POST https://api.levapay.dev/test/v1/transfers \
  -H "Content-Type: application/json" \
  -H "X-Api-User: VOTRE_UTILISATEUR" \
  -H "X-Api-Key: VOTRE_PRIVATE_KEY" \
  -d '{"quote_id":"qt_...","idempotency_key":"envoi-001"}'

PHP

<?php
$base = 'https://api.levapay.dev/test/v1';
$headers = [
    'Content-Type: application/json',
    'X-Api-User: VOTRE_UTILISATEUR',
    'X-Api-Key: VOTRE_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', // ou moncash
    'wallet' => '50940885084',
    'amount_htg' => 100,
], $headers);

$transfer = post("$base/transfers", [
    'quote_id' => $quote['data']['quote_id'] ?? '',
    'idempotency_key' => 'envoi-' . 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': 'VOTRE_UTILISATEUR',
  'X-Api-Key': process.env.LEVAPAY_KEY, // VOTRE_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', // ou moncash
  wallet: '50940885084',
  amount_htg: 100,
});

const transfer = await post('/transfers', {
  quote_id: quote.data.quote_id,
  idempotency_key: `envoi-${Date.now()}`,
});
console.log(transfer.data?.status ?? transfer.message);

Prêt à intégrer ?

Créez un compte gratuit et obtenez vos clés TEST en quelques minutes.

Créer un compte gratuit API NatCash