Getting started

Introduction

Bienvenue dans la documentation de l'API Nkap Pay. Cette API vous permet d'accepter des paiements Mobile Money (MTN, Orange Money) et par carte bancaire (Visa, Mastercard) en Afrique Centrale.

Base URL

text
https://pay.ltcgroup.site/api/v1

Devises supportées

FieldTypeDescription

XAFFranc CFA (CEMAC)Cameroun, Gabon, Congo, Tchad, RCA, Guinée Équatoriale

XOFFranc CFA (UEMOA)Sénégal, Côte d'Ivoire, Mali, Burkina Faso, etc.

EUREuroPaiements par carte bancaire uniquement

USDUS DollarPaiements par carte bancaire uniquement

Méthodes de paiement

FieldTypeDescription

MOBILE_MONEYDynamicMobile Money via TouchPay (SDK ou Direct API). Les operateurs et limites dependent du pays. Consultez GET /payments/countries.

BANK_CARDVisa, MastercardCarte bancaire via Stripe Payment Intents. Pas de limite de montant.

Flux de paiement

1. Créer un paiement via POST /api/v1/payments

2. Rediriger le client vers payment_url

3. Le client paie sur la page de checkout

4. Nkap Pay envoie un webhook à votre callback_url

5. Vérifier la signature et mettre à jour votre système

Getting started

Introduction

Bienvenue dans la documentation de l'API Nkap Pay. Cette API vous permet d'accepter des paiements Mobile Money (MTN, Orange Money) et par carte bancaire (Visa, Mastercard) en Afrique Centrale.

Base URL

text
https://pay.ltcgroup.site/api/v1

Devises supportées

FieldTypeDescription

XAFFranc CFA (CEMAC)Cameroun, Gabon, Congo, Tchad, RCA, Guinée Équatoriale

XOFFranc CFA (UEMOA)Sénégal, Côte d'Ivoire, Mali, Burkina Faso, etc.

EUREuroPaiements par carte bancaire uniquement

USDUS DollarPaiements par carte bancaire uniquement

Méthodes de paiement

FieldTypeDescription

MOBILE_MONEYDynamicMobile Money via TouchPay (SDK ou Direct API). Les operateurs et limites dependent du pays. Consultez GET /payments/countries.

BANK_CARDVisa, MastercardCarte bancaire via Stripe Payment Intents. Pas de limite de montant.

Flux de paiement

1. Créer un paiement via POST /api/v1/payments

2. Rediriger le client vers payment_url

3. Le client paie sur la page de checkout

4. Nkap Pay envoie un webhook à votre callback_url

5. Vérifier la signature et mettre à jour votre système

Getting started

Authentication

Toutes les requêtes à l'API doivent inclure vos clés API dans les headers HTTP. Vous trouverez vos clés dans le tableau de bord marchand.

Headers

FieldTypeDescription

X-API-KeyREQstringVotre clé API (ltcpay_live_... en production, ltcpay_test_... en test).

X-API-SecretREQstringVotre clé secrète API.

Content-TypeREQstringapplication/json

Exemple

curl
curl -X GET https://pay.ltcgroup.site/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ltcpay_live_abc123..." \
  -H "X-API-Secret: your_api_secret"

Ne partagez jamais votre X-API-Secret. Si vous pensez que votre clé a été compromise, régénérez-la immédiatement depuis le tableau de bord.

Limite de requêtes

L'API est limitée à 60 requêtes par minute par adresse IP. Les réponses incluent les headers X-RateLimit-Limit et X-RateLimit-Remaining.

Payments

Create a payment

Crée un nouveau paiement et retourne une URL de checkout vers laquelle rediriger votre client. La référence retournée est unique et stable.

POSThttps://pay.ltcgroup.site/api/v1/payments

Corps de la requête

FieldTypeDescription

amountREQdecimalMontant en unité entière. 5000 = 5 000 F CFA. Min: 100. Les limites dependent du pays et de l'operateur. Carte bancaire : pas de limite.

currencystringOptionnel. Auto-detecte depuis le pays si omis. XAF, XOF, EUR ou USD.

merchant_referencestringVotre ID de commande interne. Retourné dans les webhooks. Max 255 car.

descriptionstringAffiché au client sur la page de checkout. Max 500 car.

payment_methodstringMOBILE_MONEY ou BANK_CARD. Omettez pour laisser le client choisir.

payment_modestringSDK (défaut), DIRECT_API ou STRIPE. Auto-détecté si operator + customer_phone fournis.

countrystringCode pays ISO 3166-1 alpha-2 (ex: CM, CI). Auto-detecte depuis customer_phone si omis.

operatorstringCode operateur (ex: MTN, ORANGE, WAVE). Requis si payment_mode = DIRECT_API. Consultez GET /payments/countries pour la liste.

customer_phonestringNuméro du client (max 20 car). Requis si payment_mode = DIRECT_API.

customer_info.namestringNom du client. Max 255 car.

customer_info.emailstringEmail du client. Max 255 car.

customer_info.phonestringTéléphone du client (format E.164). Max 20 car.

callback_urlstringURL webhook spécifique à ce paiement (remplace le défaut marchand). Max 500 car.

return_urlstringURL de redirection après paiement. Max 500 car.

metadataobjectDonnées personnalisées JSON (retournées dans les webhooks).

Exemple (mode SDK)

curl
curl -X POST https://pay.ltcgroup.site/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ltcpay_live_..." \
  -H "X-API-Secret: ltcpay_secret_..." \
  -d '{
    "amount": 75000,
    "currency": "XAF",
    "merchant_reference": "ORDER-3041",
    "description": "Pagne + livraison",
    "customer_info": {
      "name": "Jean-Pierre Mbarga",
      "phone": "237670123456"
    },
    "return_url": "https://mamishop.cm/thanks"
  }'

Champs de la réponse

FieldTypeDescription

payment_iduuidIdentifiant unique du paiement.

referencestringRéférence unique (PAY-XXXX). Utilisez-la pour les requêtes GET.

payment_tokenstringToken JWT pour la page de checkout.

amountdecimalMontant final (peut inclure les frais si fee_bearer = CLIENT).

currencystringDevise du paiement.

statusstringPENDING (SDK/Stripe) ou PROCESSING (Direct API).

payment_modestringSDK, DIRECT_API ou STRIPE.

countrystring|nullCode pays ISO 3166-1 alpha-2 (ex: CM).

payment_urlstringURL de checkout (mode SDK/Stripe). Redirigez le client ici.

stripe_client_secretstring|nullClient secret Stripe (mode BANK_CARD uniquement). Null sinon.

created_atdatetimeDate de création ISO 8601.

Exemple de réponse

json
{
  "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "reference": "PAY-A1B2C3D4E5F67890",
  "payment_token": "eyJhbGciOiJIUzI1NiIs...",
  "amount": "75000.00",
  "currency": "XAF",
  "status": "PENDING",
  "payment_mode": "SDK",
  "country": "CM",
  "payment_url": "https://pay.ltcgroup.site/pay/PAY-A1B2C3D4E5F67890",
  "stripe_client_secret": null,
  "created_at": "2026-06-10T14:42:00Z"
}

Redirigez immédiatement le client vers payment_url. La session expire en 30 minutes par défaut.

Frais de transaction

Une commission est calculée sur chaque paiement selon votre taux configuré (défaut : 1.75%). Le porteur des frais dépend de votre configuration :

FieldTypeDescription

MERCHANTdéfautLes frais sont déduits du montant reversé au marchand. Le client paie le montant exact demandé.

CLIENToptionLes frais sont ajoutés au montant payé par le client. Le montant retourné dans la réponse inclut les frais.

Détection automatique du mode

Si vous envoyez operator et customer_phone sans spécifier payment_mode, le mode DIRECT_API est automatiquement sélectionné. Si vous envoyez payment_method: BANK_CARD, le mode STRIPE est automatiquement sélectionné.

Exemple (Direct API — sans redirection)

curl
curl -X POST https://pay.ltcgroup.site/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ltcpay_live_..." \
  -H "X-API-Secret: ltcpay_secret_..." \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "country": "CM",
    "payment_mode": "DIRECT_API",
    "operator": "MTN",
    "customer_phone": "237670000000"
  }'

Le client reçoit une notification push sur son app MTN/Orange. Pollez GET /api/v1/payments/{reference} toutes les 3-5 secondes pour suivre le statut.

Exemple (Carte bancaire)

curl
curl -X POST https://pay.ltcgroup.site/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ltcpay_live_..." \
  -H "X-API-Secret: ltcpay_secret_..." \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "payment_method": "BANK_CARD",
    "description": "Abonnement Premium",
    "customer_info": {
      "email": "client@example.com"
    },
    "return_url": "https://myshop.cm/thanks"
  }'

Le paiement par carte est traité via Stripe. Le client saisit ses informations de carte sur la page de checkout sécurisée.

Payments

Get payment

Récupère les détails d'un paiement par sa référence. Utilisez cet endpoint pour vérifier le statut d'un paiement ou pour le polling en mode Direct API.

GEThttps://pay.ltcgroup.site/api/v1/payments/{reference}

Paramètres

FieldTypeDescription

referenceREQstring (path)Référence du paiement (ex: PAY-A1B2C3D4E5F67890).

Exemple

curl
curl https://pay.ltcgroup.site/api/v1/payments/PAY-A1B2C3D4E5F67890 \
  -H "X-API-Key: ltcpay_live_..." \
  -H "X-API-Secret: ltcpay_secret_..."

Champs de la réponse

FieldTypeDescription

iduuidIdentifiant unique du paiement.

merchant_iduuidIdentifiant du marchand.

referencestringRéférence unique PAY-XXXX.

payment_tokenstringToken JWT de la session.

merchant_referencestring|nullVotre ID de commande interne.

provider_transaction_idstring|nullID de transaction côté fournisseur.

amountdecimalMontant du paiement.

feedecimalFrais de transaction calculés.

currencystringDevise (XAF, XOF, EUR, USD).

methodstring|nullMOBILE_MONEY ou BANK_CARD.

statusstringStatut actuel du paiement.

payment_modestringSDK, DIRECT_API ou STRIPE.

providerstring|nullTOUCHPAY ou STRIPE.

operatorstring|nullCode operateur Mobile Money (ex: MTN, ORANGE, WAVE).

operator_transaction_idstring|nullID de transaction côté opérateur.

stripe_payment_intent_idstring|nullID PaymentIntent Stripe (carte).

customer_infoobject|nullInfos client (name, email, phone).

descriptionstring|nullDescription du paiement.

completed_atdatetime|nullDate de complétion (null si non terminé).

created_atdatetimeDate de création.

updated_atdatetimeDate de dernière mise à jour.

Exemple de réponse

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "merchant_id": "...",
  "reference": "PAY-A1B2C3D4E5F67890",
  "payment_token": "eyJhbGciOiJIUzI1NiIs...",
  "merchant_reference": "ORDER-3041",
  "provider_transaction_id": "1781183068139",
  "amount": "75000.00",
  "fee": "1312.50",
  "currency": "XAF",
  "method": "MOBILE_MONEY",
  "status": "COMPLETED",
  "payment_mode": "SDK",
  "country": "CM",
  "provider": "TOUCHPAY",
  "operator": "MTN",
  "operator_transaction_id": "1781183068139",
  "stripe_payment_intent_id": null,
  "customer_info": {
    "name": "Jean-Pierre Mbarga",
    "phone": "237670123456"
  },
  "description": "Pagne + livraison",
  "completed_at": "2026-06-10T14:45:30Z",
  "created_at": "2026-06-10T14:42:00Z",
  "updated_at": "2026-06-10T14:45:30Z"
}

Vous ne pouvez accéder qu'aux paiements de votre propre compte marchand.

Payments

List payments

Récupère la liste paginée de tous vos paiements, avec filtrage optionnel par statut.

GEThttps://pay.ltcgroup.site/api/v1/payments

Paramètres de requête

FieldTypeDescription

pageintegerNuméro de page (défaut: 1).

page_sizeintegerÉléments par page (1-100, défaut: 20).

statusstringFiltrer par statut: PENDING, PROCESSING, COMPLETED, FAILED, EXPIRED, REFUNDED, CANCELLED.

Exemple

curl
curl "https://pay.ltcgroup.site/api/v1/payments?page=1&page_size=10&status=COMPLETED" \
  -H "X-API-Key: ltcpay_live_..." \
  -H "X-API-Secret: ltcpay_secret_..."

Réponse

json
{
  "payments": [
    {
      "id": "...",
      "reference": "PAY-A1B2C3D4E5F67890",
      "amount": "75000.00",
      "currency": "XAF",
      "status": "COMPLETED",
      "payment_mode": "SDK",
      "provider": "TOUCHPAY",
      "created_at": "2026-06-10T14:42:00Z",
      ...
    }
  ],
  "total_count": 142,
  "page": 1,
  "page_size": 10
}

Payments

Available countries

Liste les pays disponibles avec leurs operateurs, devises, formats de telephone et limites de transaction.

GEThttps://pay.ltcgroup.site/api/v1/payments/countries

Cet endpoint fonctionne avec ou sans authentification. Avec les cles API marchand, il filtre par les pays autorises pour le marchand.

Exemple

curl
curl https://pay.ltcgroup.site/api/v1/payments/countries

Reponse

json
[
  {
    "code": "CM",
    "name": "Cameroun",
    "currency": "XAF",
    "phone_prefix": "237",
    "phone_digits": 9,
    "phone_pattern": "6XX XX XX XX",
    "flag_emoji": "🇨🇲",
    "min_amount": 100,
    "max_amount": 500000,
    "operators": [
      {
        "code": "MTN",
        "name": "MTN MoMo",
        "color": "#ffcc00",
        "logo_url": "",
        "min_amount": null,
        "max_amount": 500000,
        "ussd_code": "*126#"
      },
      {
        "code": "ORANGE",
        "name": "Orange Money",
        "color": "#ff6600",
        "logo_url": "",
        "min_amount": null,
        "max_amount": 500000,
        "ussd_code": "#150*50#"
      }
    ]
  }
]

Champs pays

FieldTypeDescription

codestringCode ISO 3166-1 alpha-2 (ex: CM, CI, SN).

namestringNom du pays.

currencystringDevise par defaut (XAF, XOF, etc.).

phone_prefixstringIndicatif telephonique (ex: 237, 225).

phone_digitsintegerNombre de chiffres apres l'indicatif.

phone_patternstringFormat d'affichage (ex: 6XX XX XX XX).

flag_emojistringEmoji drapeau du pays.

min_amountintegerMontant minimum par transaction.

max_amountintegerMontant maximum par transaction.

operatorsarrayListe des operateurs actifs pour ce pays.

Champs operateur

FieldTypeDescription

codestringCode operateur (ex: MTN, ORANGE, WAVE).

namestringNom complet de l'operateur.

colorstringCouleur CSS hex pour l'affichage.

logo_urlstringURL du logo (peut etre vide).

min_amountinteger|nullLimite min specifique a l'operateur (null = utilise la limite pays).

max_amountinteger|nullLimite max specifique a l'operateur (null = utilise la limite pays).

ussd_codestringCode USSD pour verifier le solde.

Utilisez cet endpoint pour construire dynamiquement l'interface de selection d'operateur dans votre application. Les operateurs et limites peuvent changer sans modification de code.

Payments

Payment modes

Nkap Pay supporte trois modes d'intégration pour s'adapter à tous les cas d'usage.

SDK (Intégration web)

Recommandé pour les sites web

Créez le paiement via l'API
Redirigez le client vers payment_url
Le client choisit MTN, Orange ou Carte sur la page de checkout
Recevez le résultat via webhook

Direct API (Intégration mobile)

Recommandé pour les apps mobiles

Aucune redirection — purement API
Envoyez country, operator et customer_phone
Le client reçoit une notification push sur son app MoMo
Pollez GET /payments/{'{reference}'} pour suivre le statut

Stripe (Carte bancaire)

Paiement par carte Visa/Mastercard

Envoyez payment_method: BANK_CARD dans la requête
Le client est redirigé vers la page de checkout avec formulaire carte sécurisé
3D Secure géré automatiquement
Recevez le résultat via webhook

Webhooks

Webhook signature

Tous les webhooks envoyés à votre callback_url sont signés avec HMAC-SHA256. Vérifiez toujours la signature avant de traiter le payload.

Headers envoyés

FieldTypeDescription

X-LtcPay-SignaturestringSignature HMAC-SHA256 du body JSON, signée avec votre Webhook Secret (visible dans le dashboard).

X-LtcPay-EventstringType d'événement (ex: payment.status_changed).

X-LtcPay-Delivery-IdstringIdentifiant unique de la livraison (pour déduplication).

Content-Typestringapplication/json

User-AgentstringLtcPay-Webhook/1.0

Vérification de la signature

python
import hmac
import hashlib

def verify_signature(payload_body: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Exemple Node.js

javascript
const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Payload webhook

json
{
  "event": "payment.status_changed",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "reference": "PAY-A1B2C3D4E5F67890",
    "merchant_reference": "ORDER-3041",
    "provider_transaction_id": "1781183068139",
    "amount": 75000.0,
    "fee": 1312.5,
    "currency": "XAF",
    "status": "COMPLETED",
    "method": "MOBILE_MONEY",
    "customer_name": "Jean-Pierre Mbarga",
    "customer_email": null,
    "customer_phone": "237670123456",
    "description": "Pagne + livraison",
    "completed_at": "2026-06-10T14:45:30Z",
    "created_at": "2026-06-10T14:42:00Z"
  },
  "timestamp": "2026-06-10T14:45:31Z"
}

Les webhooks sont envoyés avec un mécanisme de retry (5 tentatives max) avec backoff exponentiel (2s, 4s, 8s, 16s, 32s). Votre endpoint doit répondre avec un code HTTP 2xx.

Webhooks

Event types

Liste des événements envoyés à votre webhook endpoint.

FieldTypeDescription

payment.status_changedwebhookEnvoyé chaque fois que le statut d'un paiement change (PENDING → COMPLETED, PENDING → FAILED, etc.).

Transitions de statut

PENDING → PROCESSING (Direct API: paiement initié)

PENDING → COMPLETED (SDK/Stripe: paiement réussi)

PROCESSING → COMPLETED (Direct API: client a validé)

PENDING → FAILED (erreur de paiement)

PROCESSING → FAILED (client a refusé ou timeout)

PENDING → EXPIRED (session expirée, 30 min par défaut)

PENDING → CANCELLED (annulé par le client ou le marchand)

COMPLETED → REFUNDED (remboursement effectué)

Implémentez l'idempotence côté webhook : vous pouvez recevoir le même événement plusieurs fois en cas de retry.

Reference

Payment statuses

Un paiement passe par différents statuts au cours de son cycle de vie.

FieldTypeDescription

PENDINGinitialPaiement créé, en attente de l'action du client.

PROCESSINGtransitionalPaiement en cours de traitement (Direct API uniquement — le client a reçu la notification push).

COMPLETEDterminalPaiement réussi. Les fonds ont été collectés.

FAILEDterminalPaiement échoué (refus opérateur, solde insuffisant, erreur technique).

EXPIREDterminalSession de paiement expirée (30 minutes par défaut).

CANCELLEDterminalPaiement annulé par le client ou le marchand.

REFUNDEDterminalPaiement remboursé.

Les statuts 'terminal' (COMPLETED, FAILED, EXPIRED, CANCELLED, REFUNDED) sont définitifs et ne changent plus.

Reference

Error codes

L'API utilise les codes de statut HTTP standards. Les erreurs incluent un message descriptif dans le corps de la réponse.

Format d'erreur

json
{
  "detail": "Payment not found"
}

Codes HTTP

FieldTypeDescription

200OKRequête réussie.

201CreatedRessource créée (ex: nouveau paiement).

400Bad RequestParamètres invalides (montant < 100, devise non supportée, etc.).

401UnauthorizedClés API manquantes ou invalides.

403ForbiddenAccès refusé (ex: paiement d'un autre marchand).

404Not FoundRessource introuvable (référence de paiement invalide).

422Validation ErrorErreur de validation des données (détails dans le corps).

429Rate LimitedTrop de requêtes. Attendez avant de réessayer.

502Bad GatewayErreur du fournisseur de paiement (TouchPay ou Stripe).

500Server ErrorErreur interne du serveur.

Erreur de validation (422)

json
{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "Le montant minimum est 100",
      "type": "value_error"
    }
  ]
}