Skip to content

Payments ​

Endpoint : POST https://pay.nexera.africa/v1/payments — création d'un paiement C2B (client → marchand).

Base URL unique

Même URL pour sandbox et production — les clés nex_test_* vs nex_live_* discriminent l'environnement. Voir Authentication → Base URL.

⚠️ Convention amount — unité entière, PAS cents

Contrairement à Stripe / Fincra, le champ amount est en unité entière de la devise, pas en cents.

  • Pour 100 USD : envoyer amount: 100 (pas amount: 10000)
  • Pour 5000 CDF : envoyer amount: 5000 (pas amount: 500000)

Si vous migrez depuis Stripe, retirez tout * 100 / helper toCents() dans votre code avant d'envoyer.

Mobile Money ​

Nexera Pay accepte le Mobile Money dans 11 pays d'Afrique :

PaysISOOpérateursDevise
RD CongoCODmpesa, airtel, orange, africellCDF, USD
BéninBENmtn, moovXOF
Côte d'IvoireCIVmtn, orangeXOF
CamerounCMRmtnXAF
Congo-BrazzavilleCOGmtn, airtelXAF
GabonGABairtel, moovXAF
KenyaKENmpesaKES
RwandaRWAmtn, airtelRWF
SénégalSENorange, freeXOF
Sierra LeoneSLEorangeSLE
OugandaUGAmtn, airtelUGX
ZambieZMBmtn, zamtelZMW

Champ country

Le champ country (ISO 3166-1 alpha-3) est facultatif pour un MSISDN RDC (préfixe 243, inféré automatiquement). Il est requis pour les 10 autres pays.

Exemple RDC (aucun country à envoyer) :

typescript
const p = await nexera.payments.create({
  amount: 100,             // 100 USD — unité entière de la devise (int)
  currency: "USD",         // USD ou CDF pour RDC
  method: "mobile_money",
  operator: "mpesa",       // "mpesa" | "airtel" | "orange" | "africell"
  phone: "243812345001",
  reference: "INV-001",    // unique par marchand
  description: "Facture #INV-001",
  metadata: { invoice_id: "abc", customer_id: "def" },
});

Exemple Kenya M-Pesa (country requis) :

typescript
const p = await nexera.payments.create({
  amount: 1000,            // 1000 KES
  currency: "KES",
  method: "mobile_money",
  country: "KEN",          // ISO 3166-1 alpha-3
  operator: "mpesa",
  phone: "254722000000",
  reference: "INV-002",
});

Exemple Ouganda MTN :

typescript
const p = await nexera.payments.create({
  amount: 5000,            // 5000 UGX
  currency: "UGX",
  method: "mobile_money",
  country: "UGA",
  operator: "mtn",         // ou "airtel"
  phone: "256772000000",
  reference: "INV-003",
});

Réponse :

json
{
  "id": "pay_a1b2c3d4-...",
  "object": "payment",
  "status": "processing",
  "method": "mobile_money",
  "environment": "test",
  "currency": "USD",
  "amount_charged": 10000,
  "amount_net": 9600,
  "fee": 400,
  "fee_bearer": "merchant",
  "reference": "INV-001",
  "provider": "moko",
  "provider_ref": "PDxxxx",
  "created": 1786200000,
  "completed": null,
  "metadata": {"invoice_id": "abc", "customer_id": "def"}
}

Un STK Push est envoyé sur le téléphone du client. Il tape son PIN. Nexera Pay reçoit le callback Moko et t'envoie le webhook payment.succeeded (ou payment.failed).

Carte (checkout Nexera-branded) ​

typescript
const p = await nexera.payments.create({
  amount: 500,
  currency: "USD",
  method: "card",
  reference: "INV-002",
  customer_email: "client@example.com",
  customer_name: "Jean Kabala",
  return_url: "https://ton-app.com/facture/002",   // client redirigé ici après paiement
});

// Rediriger le client vers le checkout Nexera-branded
window.location.href = p.checkout_url;

Important : récupère l'URL de checkout dans le champ checkout_url de la réponse — ne la construis pas manuellement. L'URL est générée côté serveur et inclut l'ID interne de la transaction.

Exemple de réponse pour un paiement carte :

json
{
  "id": "pay_6f23c8d9...",
  "object": "payment",
  "status": "processing",
  "method": "card",
  "environment": "test",
  "currency": "USD",
  "amount_charged": 50000,
  "amount_net": 48000,
  "fee": 2000,
  "fee_bearer": "merchant",
  "reference": "INV-002",
  "provider": "cybersource",
  "checkout_url": "https://pay.nexera.africa/checkout/6f23c8d9-...",
  "created": 1786200000,
  "completed": null
}

La page checkout est hébergée par Nexera sur pay.nexera.africa/checkout/{payment_id}, propulsée par Cybersource Microform pour la tokenisation carte (PCI DSS SAQ-A — le PAN ne touche jamais nos serveurs, il est saisi directement dans des iframes contrôlés par Cybersource). Le client reste sur l'univers Nexera du début à la fin, sauf pendant le challenge 3-D Secure de sa banque (page issuer standard). Après paiement, il revient sur ton return_url et un webhook payment.succeeded te confirme.

Testable en sandbox : l'URL checkout_url est renvoyée aussi bien en environnement test qu'en live. En test, la page charge Microform Cybersource SBX — tu peux valider tout le flow carte (incluant le challenge 3-D Secure) avec les cartes de test documentées avant d'activer ton environnement live.

Fee bearer ​

Deux modes configurables au niveau marchand (default) ou par transaction (override) :

ModeComportementClient tapeMarchand reçoit
fee_bearer=merchant (défaut)Commission déduite du montant100 USD96 USD
fee_bearer=customerCommission ajoutée (surcharge)104 USD100 USD
typescript
// Le client absorbe le fee — marchand reçoit pile 10000 USD net
await nexera.payments.create({
  amount: 100,   // ← montant NET en USD souhaité par le marchand
  fee_bearer: "customer",
  ...
});

Statuts ​

StatutDescription
pendingCréé, en attente d'envoi provider
processingEnvoyé provider, en attente confirmation client (STK/3DS)
succeededConfirmé — marchand crédité
failedÉchec définitif (client refuse, solde insuffisant, timeout...)
cancelledAnnulé par le client ou timeout
refundedRemboursé partiellement ou totalement

Consultation ​

typescript
const p = await nexera.payments.get("pay_xxx");

Liste ​

typescript
const list = await nexera.payments.list({
  reference: "INV-001",   // filtre par reference marchand
  status: "succeeded",
  limit: 50,
  cursor: "1786200000",   // cursor de la page précédente
});
console.log(list.data, list.has_more, list.next_cursor);

Pagination cursor-based (pas offset). next_cursor = timestamp Unix pour continuer.

Limites ​

  • Body max : 100 KB
  • metadata : max 20 clés, valeurs stringifiées max 500 chars
  • Amount max par tx : configurable par marchand (per_tx_limit_usd / per_tx_limit_cdf)
  • Rate limit : 100 req/min par API key

Nexera Pay · Fais-le tourner.