Intégrer les paiements TekSafi PayIntegrating TekSafi Pay payments

Démarrage rapideQuickstart

curl -X POST https://api.teksafipay.com/api/v1/auth \
  -H "x-application-id: 8796c6c4-aa02-403f-bd95-3f7254dda8e9" \
  -H "x-api-key: a47f9e21-6c3d-4b8a-9f12-7e4d8c2b91a5"

Sandbox vs LiveSandbox vs Live

Le mode est un attribut de votre compte, pas un paramètre de requête : il n'y a ni en-tête ni flag "test mode" à passer. Tant que votre compte est en Sandbox, chaque appel — collection, décaissement, webhook — passe par un simulateur interne au lieu de l'agrégateur réel ; le contrat de requête/réponse est identique dans les deux modes, seul le traitement change.

Mode is an attribute of your account, not a request parameter : there's no "test mode" header or flag to pass. As long as your account is in Sandbox, every call — collection, disbursement, webhook — runs through an internal simulator instead of the real aggregator; the request/response contract is identical in both modes, only the processing changes.

AuthentificationAuthentication

Toutes les routes de paiement exigent un jeton (JWT) dans l'en-tête Authorization : Bearer <jeton>. Un jeton expire après 1 heure — prévoyez de le renouveler.

Every payment route requires a token (JWT) in the Authorization : Bearer <token> header. A token expires after 1 hour — plan to refresh it.

Obtenir un jetonGetting a token

POST /auth/login-key

{
  "applicationId": "8796c6c4-aa02-403f-bd95-3f7254dda8e9",
  "key": "a47f9e21-6c3d-4b8a-9f12-7e4d8c2b91a5"
}

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Générer vos clésGenerating your keys

Vos clés démarrent à null à la création du compte — générez-les vous-même une fois connecté (nécessite un jeton obtenu via le dashboard, authMethod email).

Your keys start at null when the account is created — generate them yourself once signed in (requires a token obtained via the dashboard, authMethod email).

{
  "success": true,
  "message": "Clé générée avec succès.",
  "data": {
    "oldKey": null,
    "newKey": "a47f9e21-6c3d-4b8a-9f12-7e4d8c2b91a5"
  }
}

Trois types de clé, trois usagesThree key types, three purposes

Découvrir vos marchés & moyens de paiementDiscovering your markets & payment methods

{
  "success": true,
  "data": {
    "appName": "Boutique Malonga",
    "markets": [
      {
        "marketId": "f394448f-65e2-46b4-b213-a1159e74ba58",
        "marketActive": true,
        "country": { "code": "CG", "name": "République du Congo", "callingCode": "+242", "currency": "XAF" },
        "paymentMethods": [
          {
            "code": "MTN_MOMO_COG",
            "name": "MTN Mobile Money",
            "type": "MOBILE_MONEY",
            "regexValidation": "^24206\\d{7}$",
            "validationFormat": "242 06XXXXXXX",
            "rates": { "collection": 6, "disbursement": 1 }
          }
        ]
      }
    ]
  }
}

Collecter un paiement (Collection)Collecting a payment (Collection)

Une Collection encaisse de l'argent depuis le mobile money d'un client vers votre wallet TekSafi. C'est une opération asynchrone : la réponse initiale confirme que la demande a été envoyée à l'opérateur, pas qu'elle a réussi.

A Collection pulls money from a customer's mobile money account into your TekSafi wallet. It's an asynchronous operation : the initial response confirms the request was sent to the operator, not that it succeeded.

POST /transactions/collection
X-Collection-Key: a2f1c9e4-...

{
  "countryCode": "CG",
  "paymentMethodCode": "MTN_MOMO_COG",
  "amount": 5000,
  "currency": "XAF",
  "customerInfo": { "phoneNumber": "242061234567" },
  "reference": "commande-48213"
}

{
  "id": "985f19c3-11bc-422a-b731-c97ccb0e5e20",
  "reference": "commande-48213",
  "status": "PENDING",
  "amount": "5000.00",
  "currency": "XAF",
  "providerReference": "367ea115-37ce-4932-a69a-fbfe0e59384f",
  "createdAt": "2026-08-14T19:37:41.897Z",
  "customerInfo": { "phoneNumber": "242061234567" }
}

Formats de numéro de téléphonePhone number formats

Chaque moyen de paiement mobile money porte sa propre règle de validation (regexValidation), propre à son pays. TekSafi Pay n'est pas limité au Congo : de nouveaux marchés sont activés au fil du temps, chacun avec son propre format. Ne codez jamais un format en dur dans votre intégration — récupérez-le systématiquement via GET /applications/markets-payment-methods, qui reste la seule source à jour pour les marchés auxquels votre compte est relié.

Every mobile money payment method carries its own validation rule (regexValidation), specific to its country. TekSafi Pay isn't limited to Congo : new markets are activated over time, each with its own format. Never hardcode a format in your integration — always fetch it via GET /applications/markets-payment-methods, which remains the only up-to-date source for the markets your account is linked to.

À titre d'illustration du principe général (indicatif pays + préfixe opérateur local conservé, sans +), voici le marché Congo-Brazzaville :

As an illustration of the general pattern (country code + local operator prefix kept, no +), here is the Congo-Brazzaville market :

Vérifier le statut d'une transactionChecking a transaction's status

{
  "id": "985f19c3-11bc-422a-b731-c97ccb0e5e20",
  "reference": "commande-48213",
  "status": "SUCCESS",
  "amount": "5000.00",
  "currency": "XAF",
  "providerReference": "367ea115-37ce-4932-a69a-fbfe0e59384f",
  "completedAt": "2026-08-14T19:39:57.453Z",
  "type": "collection"
}

WebhooksWebhooks

Plutôt que d'interroger GET /transactions/callback/:reference en boucle, enregistrez une URL de webhook : TekSafi vous notifie automatiquement dès qu'une transaction atteint un état définitif.

Instead of polling GET /transactions/callback/:reference in a loop, register a webhook URL : TekSafi notifies you automatically as soon as a transaction reaches a final state.

{
  "webhookUrl": "https://monapp.cg/webhooks/teksafi"
}

{
  "success": true,
  "message": "Webhook enregistré.",
  "data": {
    "webhookUrl": "https://monapp.cg/webhooks/teksafi",
    "webhookSecret": "676e30a4-58ee-4eeb-a5ca-f0c54e582d10"
  }
}

Ce que vous recevezWhat you receive

Une requête POST vers votre webhookUrl, pour chacun des quatre événements :

A POST request to your webhookUrl, for each of the four events :

{
  "event": "collection.success",
  "data": {
    "id": "985f19c3-11bc-422a-b731-c97ccb0e5e20",
    "reference": "commande-48213",
    "status": "SUCCESS",
    "amount": "5000.00",
    "currency": "XAF",
    "providerReference": "367ea115-37ce-4932-a69a-fbfe0e59384f",
    "completedAt": "2026-08-14T19:39:57.453Z",
    "type": "collection"
  },
  "timestamp": "2026-08-14T19:39:57.500Z"
}

Vérifier la signatureVerifying the signature

Chaque requête porte un en-tête X-TekSafi-Signature : un HMAC-SHA256 du corps JSON exact (tel quel, avant tout re-formatage), calculé avec votre webhookSecret. Recalculez-le et comparez avant de traiter la notification.

Every request carries an X-TekSafi-Signature header : an HMAC-SHA256 of the exact JSON body (as sent, before any reformatting), computed with your webhookSecret. Recompute it and compare before acting on the notification.

const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return expected === signatureHeader;
}

Réessais & fiabilitéRetries & reliability

3 tentatives par notification (avec un court délai croissant entre chacune) si votre endpoint ne répond pas ou renvoie une erreur. Passé ce délai, la notification est abandonnée : elle n'est pas conservée en file d'attente pour un envoi ultérieur. Votre endpoint doit répondre 2xx rapidement — traitez la notification de façon asynchrone si besoin plutôt que de faire attendre la réponse.

3 attempts per notification (with a short increasing delay between each) if your endpoint doesn't respond or returns an error. After that, the notification is dropped : it is not queued for later delivery. Your endpoint should respond 2xx quickly — process the notification asynchronously if needed rather than making the response wait.

Décaisser (Disbursement)Payout (Disbursement)

Un Décaissement envoie de l'argent depuis votre wallet TekSafi vers un client (mobile money) ou un compte bancaire. Comme la Collection, c'est une opération asynchrone : fonctionne à l'identique en mode Sandbox (simulateur) et en mode Live (agrégateur réel) — aucun changement de contrat entre les deux.

A Disbursement sends money out from your TekSafi wallet to a customer (mobile money) or bank account. Like Collection, it's an asynchronous operation : it works identically in Sandbox mode (simulator) and Live mode (real aggregator) — no contract change between the two.

POST /transactions/disbursement
X-Disbursement-Key: d9e2b7a1-...

{
  "countryCode": "CG",
  "paymentMethodCode": "ORANGE_MONEY",
  "amount": 3000,
  "currency": "XAF",
  "recipientInfo": { "phoneNumber": "242061234567" },
  "reference": "remboursement-9910"
}

{
  "id": "12ab34cd-56ef-78a9-bc01-d2e3f4a5b6c7",
  "reference": "remboursement-9910",
  "status": "PROCESSING",
  "amount": "3000.00",
  "currency": "XAF",
  "providerReference": "9c1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a",
  "createdAt": "2026-08-14T19:37:41.897Z",
  "recipientInfo": { "phoneNumber": "242061234567" }
}

Historique & statistiquesHistory & statistics

{
  "success": true,
  "data": [ { "id": "...", "status": "SUCCESS", "amount": "5000.00", "..." : "..." } ],
  "meta": { "total": 42, "totalPages": 1, "page": 1, "limite": 50 }
}

{
  "success": true,
  "data": {
    "stat": [ { "date": "2026-08-01", "collection": 3, "disbursement": 0 } ],
    "volume": { "collection": 42, "disbursement": 0 },
    "growth": { "collection": 12.5, "disbursement": 0 }
  }
}

Solde & walletBalance & wallet

[
  {
    "id": "431a6abc-1cf5-44bf-b2b4-32bf85f7283a",
    "balance": "4700.00",
    "country": { "code": "CG" },
    "currency": { "code": "XAF" },
    "paymentMethods": [ { "code": "MTN_MOMO_COG", "rates": { "totalCollection": 6, "totalDisbursement": 1 } } ]
  }
]

Demander un retraitRequesting a withdrawal

{
  "walletId": "431a6abc-1cf5-44bf-b2b4-32bf85f7283a",
  "amount": 4000,
  "paymentDetails": {
    "mobileMoney": { "provider": "MTN_MOMO_COG", "phoneNumber": "242061234567" }
  }
}

{
  "success": true,
  "message": "Demande de retrait créée, wallet débité",
  "data": { "id": "...", "status": "PENDING", "amount": "4000.00" }
}

Référence des erreursError reference

Les erreurs de validation de champ renvoient un tableau de messages, un par règle non respectée :

Field validation errors return an array of messages, one per failed rule :

{
  "statusCode": 400,
  "message": [
    "amount must not be less than 0.01",
    "currency must be a string"
  ],
  "error": "Bad Request"
}

Format des réponsesResponse format

La majorité des routes de lecture/écriture (comptes, transactions, wallet) renvoient une enveloppe standard :

Most read/write routes (accounts, transactions, wallet) return a standard envelope :

{
  "success": true,
  "message": "...",
  "data": { }
}

Sur certaines routes de configuration, la réponse est directement l'objet créé/modifié, sans enveloppe — c'est indiqué à chaque endpoint de cette documentation par l'exemple de réponse fourni. En cas de doute, fiez-vous toujours à l'exemple, pas à une règle générale.

On some configuration routes, the response is directly the created/updated object, with no envelope — this is shown at every endpoint in this documentation via the response example provided. When in doubt, always trust the example, not a general rule.