Documentation API

L'API ZAFEW vous permet d'accepter des paiements MonCash en HTG depuis votre site ou application. Toutes les requêtes sont en JSON sur HTTPS. Les réponses utilisent les codes HTTP standards.

Authentification

Chaque requête doit inclure votre clé API secrète dans l'en-tête Authorization. Les clés sk_test_ opèrent en sandbox, les clés sk_live_ en production.

Authorization: Bearer sk_test_votre_cle_api

Votre clé API n'est affichée qu'une seule fois à sa création. Stockez-la dans un gestionnaire de secrets, jamais dans votre code source.

Environnements

La sandbox simule tout le cycle de paiement sans argent réel. Les soldes sandbox et production sont strictement séparés. Le passage en production se fait en changeant simplement de clé API, aucun changement de code n'est nécessaire.

En sandbox, la payment_url renvoyée par pay-create ouvre un simulateur de paiement : votre client (ou vous-même) peut y confirmer ou annuler le paiement, exactement comme sur la vraie page MonCash : crédit du solde, webhooks et redirections returnUrl/cancelUrl compris.

Créer un paiement

POST /v1/pay-create

Crée un paiement MonCash et retourne l'URL de la page de paiement hébergée vers laquelle rediriger votre client.

Paramètres

curl https://api.zafew.ht/v1/pay-create \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cmd-1042" \
  -d '{
    "amount": "1500.00",
    "referenceId": "cmd-1042",
    "returnUrl": "https://maboutik.ht/merci"
  }'

Réponse 201 :

{
  "transaction_id": 87,
  "payment_url": "https://.../pay/...",
  "status": "pending"
}

Statut d'un paiement

GET /v1/payments/:transaction_id

Vérifie le statut auprès de MonCash et crédite votre solde si le paiement est confirmé. Ne vous fiez jamais au seul retour navigateur, appelez toujours cet endpoint (ou attendez le webhook) avant de livrer une commande.

{
  "transaction_id": 87,
  "status": "succeeded",
  "amount": "1500.00",
  "commission_amount": "37.50",
  "net_amount": "1462.50"
}

Statuts possibles : pending, succeeded, failed, cancelled

Solde

GET /v1/merchant/balance

Retourne le solde de l'environnement correspondant à votre clé API.

{
  "environment": "sandbox",
  "solde_disponible": "1462.50",
  "solde_en_attente": "0.00",
  "updated_at": "2026-07-10T21:03:33Z"
}

Historique des transactions

GET /v1/merchant/transactions

Liste paginée (25 par page, paramètre ?page=) des transactions de l'environnement de votre clé.

Demander un retrait

POST /v1/merchant/withdraw

Transfère une partie de votre solde disponible vers le numéro MonCash configuré sur votre compte. Le montant est réservé immédiatement puis transféré ; en cas d'échec, il est automatiquement recrédité. Des frais de retrait de 10% sont déduits : vous recevez le montant net (net_amount dans la réponse). Minimum 100 HTG, maximum 75 000 HTG par retrait.

curl https://api.zafew.ht/v1/merchant/withdraw \
  -H "Authorization: Bearer sk_test_..." \
  -d '{"amount": "1000.00"}'

Webhooks

Configurez une URL de webhook dans votre dashboard pour être notifié en temps réel. Chaque livraison est signée : l'en-tête X-Zafew-Signature contient le HMAC-SHA256 (hex) du corps brut, calculé avec votre secret de signature whsec_....

Événements

• payment.succeeded : paiement confirmé, solde crédité
• payment.failed : paiement échoué
• withdrawal.completed : retrait transféré
• withdrawal.failed : retrait échoué, montant recrédité

Vérifier la signature (Python)

import hashlib, hmac

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Répondez 2xx rapidement. Sans réponse, nous retentons avec backoff exponentiel (jusqu'à 6 tentatives).

Idempotence

Passez un en-tête Idempotency-Key unique sur pay-create : en cas de retry réseau, la même transaction est retournée au lieu d'en créer une seconde.

Limites

Qui paie les frais ?

Rien ne vous oblige à absorber la commission sur votre marge. La plupart des marchands qui utilisent ZAFEW intègrent les 6% de commission et les 10% de frais de retrait directement dans leur prix de vente, exactement comme une TVA ou des frais de service affichés au client final.