Documentation API v1.0

MANAGEZ VOS
PAIEMENTS

Nkapsmart fournit une interface unifiée pour accepter les paiements locaux et internationaux en une seule intégration.

Endpoint de Base

https://api.nkapsmart.cm

Gestion des Clés API

Pour interagir avec l'infrastructure Nkapsmart, vous manipulez trois types d'identifiants. Il est crucial de comprendre leur rôle pour sécuriser votre intégration.

Application Key (Public)

C'est l'identifiant unique de votre application. Il peut être exposé dans vos requêtes sans risque.

Usage :Utilisé pour identifier l'entité lors de l'authentification et dans certains Webhooks.

Secret Key (Privé / Signature)

C'est votre clé de signature HMAC. Elle ne doit JAMAIS transiter sur le réseau.

Usage :Sert exclusivement à générer le hash (signature) nécessaire pour obtenir un Access Token. Si elle est compromise, révoquez-la immédiatement.

Access Token (JWT Temporaire)

Il s'agit du jeton dynamique obtenu après une authentification réussie.

Usage :Doit être inclus dans le header 'Authorization' de TOUTES vos appels API vers nos services.

Note Importante sur la récupération

L'Application Key est toujours visible dans votre dashboard. Cependant, la Secret Key n'est affichée qu'une seule fois (à sa création). Si vous la perdez, vous devrez générer une nouvelle paire de clés.

Authentification & Sécurité

Sécurisez vos appels API en utilisant une signature HMAC-SHA256 générée à partir de vos clés applicatives.

Besoin d'aide sur les clés ?

Avant de commencer, familiarisez-vous avec la différence entre Application Key, Secret Key et AccessToken dans notre guide de Gestion des clés.

Génération de la Signature

stringToSign = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + Base64(SHA256(body))
signature = Base64( HMAC-SHA256(secret, stringToSign) )

Le timestamp doit être dans une fenêtre de ±5 minutes par rapport à l'heure du serveur.

La signature est calculée ainsi :

METHODPOST

PATH/api/auth/authenticate

TIMESTAMPTimestamp Unix UTC en secondes (ex: 1745055000)

BODYChaîne vide "" pour cet endpoint

SECRETLa valeur plainTextSecret reçue lors de la création de la clé API

Paramètres de Requête

Champ	Type	Obligatoire
apiKey	string (Votre API Key)	OUI
signature	string (HMAC-SHA256)	OUI
timestamp	number (Unix UTC)	OUI

Réponse de Succès (200 OK)

Retourne le jeton d'accès JWT et les détails de l'utilisateur.

JSON Response

{
  "accessToken": "eyJh... (JWT Token)",
  "tokenType": "Bearer",
  "expiresAt": 1745058600,
  "userId": "3fa85f64..."
}

accessToken:Le jeton JWT à utiliser pour authentifier vos futurs appels API.

tokenType:Le type de jeton (Bearer).

expiresAt:Le timestamp UTC de l'expiration du jeton.

userId:L'identifiant unique de votre compte utilisateur.

Utilisation du Jeton (Bearer Auth)

Le accessToken est crucial pour la sécurité. Une fois obtenu, vous devez l'inclure dans le Header de TOUS vos appels suivants (paiements, retraits, etc.).

Authorization: Bearer [votre_access_token]

Ce mécanisme permet de prouver votre identité de manière sécurisée sans avoir à re-signer ou re-transmettre vos clés secrètes pour chaque action.

POST/api/auth/authenticate

NODEJS IMPLEMENTATION

const crypto = require('crypto');

const secret = 'votre_plain_text_secret';
const method = 'POST';
const path = '/api/auth/authenticate';
const body = '';
const timestamp = Math.floor(Date.now() / 1000).toString();

const bodyHash = crypto.createHash('sha256').update(body).digest('base64');
const stringToSign = `${method}\n${path}\n${timestamp}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('base64');

// Envoyez { apiKey, signature, timestamp: parseInt(timestamp) }

Protection des Clés

Ne partagez jamais votre Secret Key. Si vos clés sont compromises, révoquez-les immédiatement depuis la page KeysPage.

Paiement Mobile

Initiez des paiements mobiles (MTN/Orange) au Cameroun via cet endpoint. Le système gère automatiquement le push USSD vers le téléphone du client.

Comment fonctionnent les paiements Mobile Money

Lorsqu'un client choisit Mobile Money comme mode de paiement, une notification push est envoyée à son appareil mobile enregistré. Pour compléter la transaction, le client doit :

•Ouvrir la notification sur son appareil mobile.
•Autoriser le paiement en saisissant son code PIN ou en suivant le processus d'authentification du fournisseur.

Une fois autorisé, le paiement est traité, et à la fois le client et le commerçant reçoivent une confirmation. Le portefeuille Mobile Money du client est débité et une notification webhook réussie est envoyée à votre serveur.

Workflow de Paiement

Client

Saisit le numéro et le montant.

Système

Vérifie l'identité du bénéficiaire (user_name).

Backend

Valide le solde business et initie la requête.

Opérateur

Envoie le Push USSD sur le mobile du client.

Client

Confirme avec son code PIN.

Système

Reçoit le Webhook et confirme la transaction.

Champ	Type	Obligatoire
phoneNumber	string	OUI
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	NON
productName	string	NON

POST/api/v2/TransactionSecond/mobile

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "...",
  "productName": "..."
}

Note : Assurez-vous que votre serveur écoute le webhook charge.completed pour délivrer la valeur.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Paiement Bancaire

Initiez des paiements via virement bancaire. Cet endpoint génère une session de paiement sécurisée permettant au client de finaliser la transaction via son interface bancaire.

Processus de Paiement Bancaire

Le flux bancaire repose sur une redirection ou une instruction de virement. Une fois la requête envoyée, le système traite l'autorisation avec la banque partenaire.

Le client est redirigé vers l'interface de sa banque si nécessaire.
En cas de succès, il est renvoyé vers votre SuccessUrl.
En cas d'annulation, il retourne sur votre CancelUrl.

Workflow Bancaire

Client

Saisit ses informations et le montant du virement.

Système

Valide la clé d'application et enregistre l'intention de paiement.

Backend

Génère les liens de redirection (Success/Cancel).

Banque

Vérifie la disponibilité des fonds et autorise le transfert.

Client

Est redirigé vers l'URL de succès après confirmation.

Système

Notifie votre serveur via Webhook (charge.completed).

Champ	Type	Obligatoire
phoneNumber	string	NON
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
productName	string	NON
Description	string	NON
SuccessUrl	string	NON
CancelUrl	string	NON

POST/api/Transaction/bank

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "productName": "....",
  "Description": "....",
  "SuccessUrl": "....",
  "CancelUrl": "...."
}

Note de sécurité : Assurez-vous que les URLs de redirection sont accessibles publiquement pour permettre le retour client.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Paiement Crypto (USDT)

Acceptez des paiements en USDT . Ce flux nécessite une adresse de paiement valide pour la réception des fonds.

Fonctionnement du flux Crypto

Le paiement crypto repose sur la vérification de la transaction sur la blockchain.

Le système génère une intention de paiement pour le montant en payCurrency spécifié.
L'utilisateur doit envoyer les fonds exactement à l'adresse fournie dans paymentAddress.
La confirmation est automatique dès que le nombre requis de blocs est atteint sur le réseau.

Workflow Web3 / Crypto

Client

Sélectionne la monnaie.

Système

Valide l'adresse de réception et le montant.

Backend

Verrouille le taux de change et attend le dépôt.

Blockchain

Vérifie la transaction sur le réseau sélectionné.

Système

Détecte le transfert entrant via l'adresse de paiement.

Marchand

Reçoit la notification de succès après confirmation.

Champ	Type	Obligatoire
phoneNumber	string	NON
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	NON
payCurrency	string	OUI
productName	string	NON
paymentAddress	string	OUI

POST/api/v2/TransactionSecond/crypto

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "....",
  "payCurrency": "....",
  "productName": "....",
  "paymentAddress": "...."
}

Sécurité Blockchain : Attention : Toute erreur d'adresse de paiement (`paymentAddress`) ou de réseau (`payCurrency`) peut entraîner une perte définitive des fonds.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Retrait Mobile

Utilisez cet endpoint pour envoyer des fonds depuis votre compte business vers le portefeuille Mobile Money d'un bénéficiaire au Cameroun.

Fonctionnement du retrait

Contrairement au paiement, le Withdraw est une opération sortante. L'argent est débité de votre solde pour créditer un tiers.

Le système vérifie que votre Application Key dispose d'un solde suffisant.
Le bénéficiaire reçoit les fonds directement sur son compte MTN ou Orange.
Il est crucial de fournir le recieverName pour assurer la traçabilité comptable.

Workflow de Retrait

Système

Reçoit la demande de retrait avec les infos du bénéficiaire.

Backend

Vérifie l'éligibilité du compte et le solde disponible.

Opérateur

Exécute le transfert vers le numéro de téléphone indiqué.

Système

Met à jour le statut de la transaction et votre solde.

Champ	Type	Obligatoire
phoneNumber	string	OUI
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	NON
recieverName	string	NON
operator	int	OUI

POST/api/v2/TransactionSecond/mobile/widraw

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "....",
  "recieverName": "....",
  "operator": 0
}

Important : Note : Le retrait est traité immédiatement par le provider. Assurez-vous d'avoir un solde suffisant pour éviter les erreurs 403/400.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Retraits (Crypto & USDT)

Transférez des jetons vers un portefeuille externe. Ce réseau offre des transactions quasi instantanées avec des frais minimes.

Spécificités

Le retrait s'effectue directement sur la Mainnet. Assurez-vous que l'adresse de destination est compatible.

Temps moyen : ~2 minutes

Field	Type	Required
phoneNumber	string	OUI
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	OUI
payCurrency	string	OUI
payeeAddress	string	OUI

POST/api/v2/TransactionSecond/crypto/widraw

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "....",
  "payCurrency": "....",
  "payeeAddress": "...."
}

Endpoint: Crypto Withdraw (Matic)

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Retrait Groupé (Bulk Withdraw)

Envoyez de l'argent à plusieurs bénéficiaires simultanément. Idéal pour automatiser vos paies ou vos campagnes de récompenses.

Fonctionnement du mode Bulk

Au lieu d'appeler l'API pour chaque personne, vous envoyez un tableau transactions.

Le système valide d'abord que votre solde couvre le montant total du lot.
Chaque transaction est traitée de manière asynchrone.
L'API vous retourne un bulkOperationId pour suivre l'avancement global.

Champ	Structure	Obligatoire
applicationKey	string	OUI
transactions	Array<Object>	OUI

Champs de l'objet Transaction

Champ	Type	Obligatoire	Description
phoneNumber	string	OUI	Numéro de téléphone du bénéficiaire
amount	double	OUI	Montant à transférer
email	string	NON	Email du bénéficiaire
description	string	NON	Description de la transaction
recieverName	string	NON	Nom complet du bénéficiaire

POST/api/v2/TransactionSecond/mobile/withdraw/bulk

{
  "applicationKey": "VOTRE_CLE",
  "transactions": [
    {
      "phoneNumber": "6XXXXXXXX",
      "amount": 0,
      "email": "client1@example.com",
      "description": "....",
      "recieverName": "...."
    }
  ]
}

Limitation : Pour des raisons de performance, nous recommandons de ne pas dépasser 100 transactions par lot (Bulk).

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Statut du Retrait Groupé

Utilisez cet endpoint pour suivre l'état d'avancement d'une opération de masse. Vous obtiendrez un récapitulatif global ainsi que le statut individuel de chaque transaction.

Comprendre les Statuts

PENDING : Le lot est en cours de traitement par les opérateurs (MTN/Orange).

COMPLETED : Toutes les transactions du lot ont été finalisées (Succès ou Échec).

PARTIAL : Une partie des transactions a échoué (ex: solde insuffisant ou numéro invalide).

Paramètres d'URL

Paramètre URL	Type	Obligatoire	Description
bulkOperationId	string	OUI	L'identifiant renvoyé lors de la création de l'opération groupée.

Champs de la Réponse

Field	Type	Obligatoire	Description
bulkOperationId	string	OUI	Identifiant unique du lot
totalCount	int	OUI	Nombre total de transactions
successCount	int	OUI	Nombre de succès
failedCount	int	OUI	Nombre d'échecs
pendingCount	int	OUI	Nombre de transactions en cours
status	string	OUI	Statut global (Pending, Completed, Partial)
createdAt	datetime	OUI	Date de création
updatedAt	datetime	OUI	Date de mise à jour

Détails des Transactions

Field	Type	Obligatoire	Description
id	string	OUI	Identifiant unique de transaction
phoneNumber	string	OUI	Numéro du destinataire
amount	double	OUI	Montant
email	string	OUI	Email du destinataire
description	string	OUI	Description interne
status	string	OUI	Statut de la transaction individuelle
transactionKey	string	OUI	Clé de référence externe
errorMessage	string	OUI	Détails de l'erreur si échec
createdAt	datetime	OUI	Date et heure

GET/api/v2/TransactionSecond/mobile/widraw/bulk/{bulkOperationId}

Exemple de Réponse JSON

{
  "bulkOperationId": "BK-2026-X99",
  "totalCount": 2,
  "successCount": 1,
  "failedCount": 1,
  "pendingCount": 0,
  "status": "Completed",
  "createdAt": "2026-06-05T09:59:22.660Z",
  "updatedAt": "2026-06-05T09:59:22.660Z",
  "transactions": [
    {
      "id": "uuid-123",
      "phoneNumber": "6XXXXXXXX",
      "amount": 5000,
      "email": "utilisateur@example.com",
      "description": "Paiement",
      "status": "Success",
      "transactionKey": "KEY123",
      "errorMessage": "",
      "createdAt": "2026-06-05T09:59:22.660Z"
    }
  ]
}

Astuce : Ne bouclez pas trop vite sur cet endpoint. Nous recommandons un intervalle de 5 à 10 secondes entre chaque vérification de statut pour optimiser vos performances.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Vérification Standard

Vérifiez l'état d'un paiement Mobile Money ou Bancaire. Cet endpoint interroge directement le statut final auprès de l'opérateur concerné.

Quand appeler cet endpoint ?

Si vous n'avez pas reçu le Webhook de confirmation.
Lorsqu'un client revient sur votre SuccessUrl pour valider son achat.
Pour lever un doute sur une transaction restée en attente.

Paramètres d'URL

Paramètre URL	Type	Requis
transactionkey	string	OUI

Champs de la Réponse

Field	Type	Requis	Description
transactionReference	string	OUI	Référence unique de la transaction
transactionAmount	double	OUI	Montant à payer
transactionDescription	string	OUI	Résumé court de l'achat
walletToken	string	OUI	Token interne de référence du portefeuille
transactionType	string	OUI	Type de transaction (Paiement, etc.)
transactionCategory	string	OUI	Catégorie de la transaction
successUrl	string	OUI	URL de redirection en cas de succès
cancelUrl	string	OUI	URL de redirection en cas d'annulation
transactionKey	string	OUI	Identifiant technique unique
productName	string	NON	Nom du produit acheté
transactionStatus	string	OUI	Statut actuel (SUCCESS, FAILED, PENDING)
paymentUrl	string	OUI	Lien vers la passerelle de paiement
raison	string	NON	Raison détaillée en cas d'échec
cryptoPayAmount	double	NON	Montant en cryptomonnaie (si applicable)
paymentAddress	string	NON	Adresse crypto de l'expéditeur
payeeAddress	string	NON	Adresse crypto du destinataire
ash	string	NON	Hash de la transaction sur la blockchain
createdAt	datetime	OUI	Date de création de la transaction

Détails du Client (Contact)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique du contact
phoneNumber	string	OUI	Numéro de téléphone du client
email	string	OUI	Adresse email du client
address	string	NON	Adresse physique
city	string	NON	Ville du client
state	string	NON	État ou région
country	string	NON	Pays du client
zipCode	string	NON	Code postal

Historique (Transactions Internes)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique de la transaction
transactionType	string	OUI	Type de transaction
transactionStatus	string	OUI	Statut de la transaction individuelle
operator	string	OUI	Opérateur utilisé (MTN, Orange, etc.)
transactionAmount	double	OUI	Montant total
transactionWithOutFees	double	OUI	Montant net sans frais
transactionReference	string	OUI	Référence marchande
transactionKey	string	OUI	Clé technique
transactionDescription	string	OUI	Description
paymentUrl	string	NON	Lien de paiement
faildRaison	string	NON	Détails de l'échec
ash	string	NON	Hash blockchain
createdAt	datetime	OUI	Date et heure

GET/api/v2/TransactionSecond/verify/{transactionkey}/{ash}

Response Body

{
  "transactionReference": "string",
  "transactionAmount": 0,
  "transactionDescription": "string",
  "walletToken": "string",
  "transactionType": "string",
  "transactionCategory": "string",
  "successUrl": "string",
  "cancelUrl": "string",
  "transactionKey": "string",
  "productName": "string",
  "transactionContact": {
    "id": "string",
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zipCode": "string",
    "phoneNumber": "string",
    "email": "string",
    "transactions": [
      {
        "id": "string",
        "transactionType": 0,
        "transactionStatus": 0,
        "operator": 0,
        "transactionAmount": 0,
        "transactionWithOutFees": 0,
        "transactionReference": "string",
        "transactionKey": "string",
        "walletToken": "string",
        "transactionDescription": "string",
        "successUrl": "string",
        "cancelUrl": "string",
        "productName": "string",
        "paymentUrl": "string",
        "faildRaison": "string",
        "description": "string",
        "payCurrency": "string",
        "payAmount": 0,
        "ash": "string",
        "transactionContactId": "string",
        "transactionCategory": 0,
        "transactionContact": "string",
        "paymentAddress": "string",
        "realAmount": 0,
        "payeeAddress": "string",
        "businnesId": "string",
        "business": {
          "id": "string",
          "name": "string",
          "description": "string",
          "returnUrl": "string",
          "callbackUrl": "string",
          "logoUrl": "string",
          "allowIp": "string",
          "balance": 0,
          "activateEmail": true,
          "prevWidrawAmount": 0,
          "transactionFees": 0,
          "userId": "string",
          "user": {
            "id": "string",
            "userName": "string",
            "normalizedUserName": "string",
            "email": "string",
            "normalizedEmail": "string",
            "emailConfirmed": true,
            "passwordHash": "string",
            "securityStamp": "string",
            "concurrencyStamp": "string",
            "phoneNumber": "string",
            "phoneNumberConfirmed": true,
            "twoFactorEnabled": true,
            "lockoutEnd": "2026-06-05T10:17:07.235Z",
            "lockoutEnabled": true,
            "accessFailedCount": 0,
            "fullName": "string",
            "enterpriseName": "string",
            "websiteUrl": "string",
            "status": 0,
            "logoName": "string",
            "nuiValue": "string",
            "type": 0,
            "cardId": "string",
            "card": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "niuId": "string",
            "niu": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "commercialRegisterId": "string",
            "commercialRegister": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "taxSheetId": "string",
            "taxSheet": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "ribId": "string",
            "rib": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "widrawCountTransaction": 0,
            "createdAt": "2026-06-05T10:17:07.236Z",
            "updatedAt": "2026-06-05T10:17:07.236Z"
          },
          "businessOperatorBalance": [
            {
              "id": "string",
              "businessId": "string",
              "operator": 0,
              "amount": 0,
              "createdAt": "2026-06-05T10:17:07.236Z",
              "updatedAt": "2026-06-05T10:17:07.236Z"
            }
          ],
          "createdAt": "2026-06-05T10:17:07.236Z",
          "updatedAt": "2026-06-05T10:17:07.236Z"
        },
        "createdAt": "2026-06-05T10:17:07.236Z",
        "updatedAt": "2026-06-05T10:17:07.236Z",
        "bulkOperationId": "string"
      }
    ]
  },
  "transactionStatus": "string",
  "paymentUrl": "string",
  "raison": "string",
  "cryptoPayAmount": 0,
  "paymentAddress": "string",
  "payeeAddress": "string",
  "ash": "string",
  "createdAt": "2026-06-05T10:17:07.236Z"
}

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Vérification Crypto

Confirmez le statut d'une transaction sur la blockchain en utilisant la clé de transaction et le Hash (ash) fourni par le réseau.

Note sur le Hash (ash)

Le paramètre ash correspond au Transaction hash associé au transfert.

Paramètres d'URL

Paramètre URL	Type	Requis
transactionkey	string	OUI
ash	string	OUI

Champs de la Réponse

Field	Type	Requis	Description
transactionReference	string	OUI	Référence unique de la transaction
transactionAmount	double	OUI	Montant à payer
transactionDescription	string	OUI	Résumé court de l'achat
walletToken	string	OUI	Token interne de référence du portefeuille
transactionType	string	OUI	Type de transaction
transactionCategory	string	OUI	Catégorie de la transaction
successUrl	string	OUI	URL de redirection en cas de succès
cancelUrl	string	OUI	URL de redirection en cas d'annulation
transactionKey	string	OUI	Identifiant technique unique
productName	string	NON	Nom du produit acheté
transactionStatus	string	OUI	Statut actuel (SUCCESS, FAILED, PENDING)
paymentUrl	string	OUI	Lien vers la passerelle de paiement
raison	string	NON	Raison détaillée en cas d'échec
cryptoPayAmount	double	NON	Montant en cryptomonnaie
paymentAddress	string	NON	Adresse crypto de l'expéditeur
payeeAddress	string	NON	Adresse crypto du destinataire
ash	string	NON	Hash de la transaction sur la blockchain
createdAt	datetime	OUI	Date de création de la transaction

Détails du Client (Contact)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique du contact
phoneNumber	string	OUI	Numéro de téléphone du client
email	string	OUI	Adresse email du client
address	string	NON	Adresse physique
city	string	NON	Ville du client
state	string	NON	État ou région
country	string	NON	Pays du client
zipCode	string	NON	Code postal

Historique (Transactions Internes)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique de la transaction
transactionType	string	OUI	Type de transaction
transactionStatus	string	OUI	Statut de la transaction individuelle
operator	string	OUI	Opérateur utilisé (MTN, Orange, etc.)
transactionAmount	double	OUI	Montant total
transactionWithOutFees	double	OUI	Montant net sans frais
transactionReference	string	OUI	Référence marchande
transactionKey	string	OUI	Clé technique
transactionDescription	string	OUI	Description
paymentUrl	string	NON	Lien de paiement
faildRaison	string	NON	Détails de l'échec
ash	string	NON	Hash blockchain
createdAt	datetime	OUI	Date et heure

GET/api/v2/TransactionSecond/verify/{transactionkey}/{ash}

Response Body

{
  "transactionReference": "string",
  "transactionAmount": 0,
  "transactionDescription": "string",
  "walletToken": "string",
  "transactionType": "string",
  "transactionCategory": "string",
  "successUrl": "string",
  "cancelUrl": "string",
  "transactionKey": "string",
  "productName": "string",
  "transactionContact": {
    "id": "string",
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zipCode": "string",
    "phoneNumber": "string",
    "email": "string",
    "transactions": [
      {
        "id": "string",
        "transactionType": 0,
        "transactionStatus": 0,
        "operator": 0,
        "transactionAmount": 0,
        "transactionWithOutFees": 0,
        "transactionReference": "string",
        "transactionKey": "string",
        "walletToken": "string",
        "transactionDescription": "string",
        "successUrl": "string",
        "cancelUrl": "string",
        "productName": "string",
        "paymentUrl": "string",
        "faildRaison": "string",
        "description": "string",
        "payCurrency": "string",
        "payAmount": 0,
        "ash": "string",
        "transactionContactId": "string",
        "transactionCategory": 0,
        "transactionContact": "string",
        "paymentAddress": "string",
        "realAmount": 0,
        "payeeAddress": "string",
        "businnesId": "string",
        "business": {
          "id": "string",
          "name": "string",
          "description": "string",
          "returnUrl": "string",
          "callbackUrl": "string",
          "logoUrl": "string",
          "allowIp": "string",
          "balance": 0,
          "activateEmail": true,
          "prevWidrawAmount": 0,
          "transactionFees": 0,
          "userId": "string",
          "user": {
            "id": "string",
            "userName": "string",
            "normalizedUserName": "string",
            "email": "string",
            "normalizedEmail": "string",
            "emailConfirmed": true,
            "passwordHash": "string",
            "securityStamp": "string",
            "concurrencyStamp": "string",
            "phoneNumber": "string",
            "phoneNumberConfirmed": true,
            "twoFactorEnabled": true,
            "lockoutEnd": "2026-06-05T10:29:52.518Z",
            "lockoutEnabled": true,
            "accessFailedCount": 0,
            "fullName": "string",
            "enterpriseName": "string",
            "websiteUrl": "string",
            "status": 0,
            "logoName": "string",
            "nuiValue": "string",
            "type": 0,
            "cardId": "string",
            "card": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "niuId": "string",
            "niu": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "commercialRegisterId": "string",
            "commercialRegister": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "taxSheetId": "string",
            "taxSheet": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "ribId": "string",
            "rib": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "widrawCountTransaction": 0,
            "createdAt": "2026-06-05T10:29:52.518Z",
            "updatedAt": "2026-06-05T10:29:52.518Z"
          },
          "businessOperatorBalance": [
            {
              "id": "string",
              "businessId": "string",
              "operator": 0,
              "amount": 0,
              "createdAt": "2026-06-05T10:29:52.518Z",
              "updatedAt": "2026-06-05T10:29:52.518Z"
            }
          ],
          "createdAt": "2026-06-05T10:29:52.518Z",
          "updatedAt": "2026-06-05T10:29:52.518Z"
        },
        "createdAt": "2026-06-05T10:29:52.518Z",
        "updatedAt": "2026-06-05T10:29:52.518Z",
        "bulkOperationId": "string"
      }
    ]
  },
  "transactionStatus": "string",
  "paymentUrl": "string",
  "raison": "string",
  "cryptoPayAmount": 0,
  "paymentAddress": "string",
  "payeeAddress": "string",
  "ash": "string",
  "createdAt": "2026-06-05T10:29:52.518Z"
}

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Nkapsmart is warming up...

Documentation API v1.0

MANAGEZ VOS
PAIEMENTS

Nkapsmart fournit une interface unifiée pour accepter les paiements locaux et internationaux en une seule intégration.

Endpoint de Base

https://api.nkapsmart.cm

Gestion des Clés API

Pour interagir avec l'infrastructure Nkapsmart, vous manipulez trois types d'identifiants. Il est crucial de comprendre leur rôle pour sécuriser votre intégration.

Application Key (Public)

C'est l'identifiant unique de votre application. Il peut être exposé dans vos requêtes sans risque.

Usage :Utilisé pour identifier l'entité lors de l'authentification et dans certains Webhooks.

Secret Key (Privé / Signature)

C'est votre clé de signature HMAC. Elle ne doit JAMAIS transiter sur le réseau.

Usage :Sert exclusivement à générer le hash (signature) nécessaire pour obtenir un Access Token. Si elle est compromise, révoquez-la immédiatement.

Access Token (JWT Temporaire)

Il s'agit du jeton dynamique obtenu après une authentification réussie.

Usage :Doit être inclus dans le header 'Authorization' de TOUTES vos appels API vers nos services.

Note Importante sur la récupération

Authentification & Sécurité

Sécurisez vos appels API en utilisant une signature HMAC-SHA256 générée à partir de vos clés applicatives.

Besoin d'aide sur les clés ?

Avant de commencer, familiarisez-vous avec la différence entre Application Key, Secret Key et AccessToken dans notre guide de Gestion des clés.

Génération de la Signature

stringToSign = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + Base64(SHA256(body))
signature = Base64( HMAC-SHA256(secret, stringToSign) )

Le timestamp doit être dans une fenêtre de ±5 minutes par rapport à l'heure du serveur.

La signature est calculée ainsi :

METHODPOST

PATH/api/auth/authenticate

TIMESTAMPTimestamp Unix UTC en secondes (ex: 1745055000)

BODYChaîne vide "" pour cet endpoint

SECRETLa valeur plainTextSecret reçue lors de la création de la clé API

Paramètres de Requête

Champ	Type	Obligatoire
apiKey	string (Votre API Key)	OUI
signature	string (HMAC-SHA256)	OUI
timestamp	number (Unix UTC)	OUI

Réponse de Succès (200 OK)

Retourne le jeton d'accès JWT et les détails de l'utilisateur.

JSON Response

{
  "accessToken": "eyJh... (JWT Token)",
  "tokenType": "Bearer",
  "expiresAt": 1745058600,
  "userId": "3fa85f64..."
}

accessToken:Le jeton JWT à utiliser pour authentifier vos futurs appels API.

tokenType:Le type de jeton (Bearer).

expiresAt:Le timestamp UTC de l'expiration du jeton.

userId:L'identifiant unique de votre compte utilisateur.

Utilisation du Jeton (Bearer Auth)

Le accessToken est crucial pour la sécurité. Une fois obtenu, vous devez l'inclure dans le Header de TOUS vos appels suivants (paiements, retraits, etc.).

Authorization: Bearer [votre_access_token]

Ce mécanisme permet de prouver votre identité de manière sécurisée sans avoir à re-signer ou re-transmettre vos clés secrètes pour chaque action.

POST/api/auth/authenticate

NODEJS IMPLEMENTATION

const crypto = require('crypto');

const secret = 'votre_plain_text_secret';
const method = 'POST';
const path = '/api/auth/authenticate';
const body = '';
const timestamp = Math.floor(Date.now() / 1000).toString();

const bodyHash = crypto.createHash('sha256').update(body).digest('base64');
const stringToSign = `${method}\n${path}\n${timestamp}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('base64');

// Envoyez { apiKey, signature, timestamp: parseInt(timestamp) }

Protection des Clés

Ne partagez jamais votre Secret Key. Si vos clés sont compromises, révoquez-les immédiatement depuis la page KeysPage.

Paiement Mobile

Initiez des paiements mobiles (MTN/Orange) au Cameroun via cet endpoint. Le système gère automatiquement le push USSD vers le téléphone du client.

Comment fonctionnent les paiements Mobile Money

Lorsqu'un client choisit Mobile Money comme mode de paiement, une notification push est envoyée à son appareil mobile enregistré. Pour compléter la transaction, le client doit :

•Ouvrir la notification sur son appareil mobile.
•Autoriser le paiement en saisissant son code PIN ou en suivant le processus d'authentification du fournisseur.

Workflow de Paiement

Client

Saisit le numéro et le montant.

Système

Vérifie l'identité du bénéficiaire (user_name).

Backend

Valide le solde business et initie la requête.

Opérateur

Envoie le Push USSD sur le mobile du client.

Client

Confirme avec son code PIN.

Système

Reçoit le Webhook et confirme la transaction.

Champ	Type	Obligatoire
phoneNumber	string	OUI
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	NON
productName	string	NON

POST/api/v2/TransactionSecond/mobile

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "...",
  "productName": "..."
}

Note : Assurez-vous que votre serveur écoute le webhook charge.completed pour délivrer la valeur.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Paiement Bancaire

Initiez des paiements via virement bancaire. Cet endpoint génère une session de paiement sécurisée permettant au client de finaliser la transaction via son interface bancaire.

Processus de Paiement Bancaire

Le flux bancaire repose sur une redirection ou une instruction de virement. Une fois la requête envoyée, le système traite l'autorisation avec la banque partenaire.

Le client est redirigé vers l'interface de sa banque si nécessaire.
En cas de succès, il est renvoyé vers votre SuccessUrl.
En cas d'annulation, il retourne sur votre CancelUrl.

Workflow Bancaire

Client

Saisit ses informations et le montant du virement.

Système

Valide la clé d'application et enregistre l'intention de paiement.

Backend

Génère les liens de redirection (Success/Cancel).

Banque

Vérifie la disponibilité des fonds et autorise le transfert.

Client

Est redirigé vers l'URL de succès après confirmation.

Système

Notifie votre serveur via Webhook (charge.completed).

Champ	Type	Obligatoire
phoneNumber	string	NON
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
productName	string	NON
Description	string	NON
SuccessUrl	string	NON
CancelUrl	string	NON

POST/api/Transaction/bank

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "productName": "....",
  "Description": "....",
  "SuccessUrl": "....",
  "CancelUrl": "...."
}

Note de sécurité : Assurez-vous que les URLs de redirection sont accessibles publiquement pour permettre le retour client.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Paiement Crypto (USDT)

Acceptez des paiements en USDT . Ce flux nécessite une adresse de paiement valide pour la réception des fonds.

Fonctionnement du flux Crypto

Le paiement crypto repose sur la vérification de la transaction sur la blockchain.

Le système génère une intention de paiement pour le montant en payCurrency spécifié.
L'utilisateur doit envoyer les fonds exactement à l'adresse fournie dans paymentAddress.
La confirmation est automatique dès que le nombre requis de blocs est atteint sur le réseau.

Workflow Web3 / Crypto

Client

Sélectionne la monnaie.

Système

Valide l'adresse de réception et le montant.

Backend

Verrouille le taux de change et attend le dépôt.

Blockchain

Vérifie la transaction sur le réseau sélectionné.

Système

Détecte le transfert entrant via l'adresse de paiement.

Marchand

Reçoit la notification de succès après confirmation.

Champ	Type	Obligatoire
phoneNumber	string	NON
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	NON
payCurrency	string	OUI
productName	string	NON
paymentAddress	string	OUI

POST/api/v2/TransactionSecond/crypto

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "....",
  "payCurrency": "....",
  "productName": "....",
  "paymentAddress": "...."
}

Sécurité Blockchain : Attention : Toute erreur d'adresse de paiement (`paymentAddress`) ou de réseau (`payCurrency`) peut entraîner une perte définitive des fonds.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Retrait Mobile

Utilisez cet endpoint pour envoyer des fonds depuis votre compte business vers le portefeuille Mobile Money d'un bénéficiaire au Cameroun.

Fonctionnement du retrait

Contrairement au paiement, le Withdraw est une opération sortante. L'argent est débité de votre solde pour créditer un tiers.

Le système vérifie que votre Application Key dispose d'un solde suffisant.
Le bénéficiaire reçoit les fonds directement sur son compte MTN ou Orange.
Il est crucial de fournir le recieverName pour assurer la traçabilité comptable.

Workflow de Retrait

Système

Reçoit la demande de retrait avec les infos du bénéficiaire.

Backend

Vérifie l'éligibilité du compte et le solde disponible.

Opérateur

Exécute le transfert vers le numéro de téléphone indiqué.

Système

Met à jour le statut de la transaction et votre solde.

Champ	Type	Obligatoire
phoneNumber	string	OUI
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	NON
recieverName	string	NON
operator	int	OUI

POST/api/v2/TransactionSecond/mobile/widraw

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "....",
  "recieverName": "....",
  "operator": 0
}

Important : Note : Le retrait est traité immédiatement par le provider. Assurez-vous d'avoir un solde suffisant pour éviter les erreurs 403/400.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Retraits (Crypto & USDT)

Transférez des jetons vers un portefeuille externe. Ce réseau offre des transactions quasi instantanées avec des frais minimes.

Spécificités

Le retrait s'effectue directement sur la Mainnet. Assurez-vous que l'adresse de destination est compatible.

Temps moyen : ~2 minutes

Field	Type	Required
phoneNumber	string	OUI
amount	double	OUI
email	string	OUI
applicationKey	string	OUI
description	string	OUI
payCurrency	string	OUI
payeeAddress	string	OUI

POST/api/v2/TransactionSecond/crypto/widraw

{
  "phoneNumber": "6XXXXXXXX",
  "amount": 0,
  "email": "utilisateur@mail.com",
  "applicationKey": "VOTRE_CLE",
  "description": "....",
  "payCurrency": "....",
  "payeeAddress": "...."
}

Endpoint: Crypto Withdraw (Matic)

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Retrait Groupé (Bulk Withdraw)

Envoyez de l'argent à plusieurs bénéficiaires simultanément. Idéal pour automatiser vos paies ou vos campagnes de récompenses.

Fonctionnement du mode Bulk

Au lieu d'appeler l'API pour chaque personne, vous envoyez un tableau transactions.

Le système valide d'abord que votre solde couvre le montant total du lot.
Chaque transaction est traitée de manière asynchrone.
L'API vous retourne un bulkOperationId pour suivre l'avancement global.

Champ	Structure	Obligatoire
applicationKey	string	OUI
transactions	Array<Object>	OUI

Champs de l'objet Transaction

Champ	Type	Obligatoire	Description
phoneNumber	string	OUI	Numéro de téléphone du bénéficiaire
amount	double	OUI	Montant à transférer
email	string	NON	Email du bénéficiaire
description	string	NON	Description de la transaction
recieverName	string	NON	Nom complet du bénéficiaire

POST/api/v2/TransactionSecond/mobile/withdraw/bulk

{
  "applicationKey": "VOTRE_CLE",
  "transactions": [
    {
      "phoneNumber": "6XXXXXXXX",
      "amount": 0,
      "email": "client1@example.com",
      "description": "....",
      "recieverName": "...."
    }
  ]
}

Limitation : Pour des raisons de performance, nous recommandons de ne pas dépasser 100 transactions par lot (Bulk).

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Statut du Retrait Groupé

Utilisez cet endpoint pour suivre l'état d'avancement d'une opération de masse. Vous obtiendrez un récapitulatif global ainsi que le statut individuel de chaque transaction.

Comprendre les Statuts

PENDING : Le lot est en cours de traitement par les opérateurs (MTN/Orange).

COMPLETED : Toutes les transactions du lot ont été finalisées (Succès ou Échec).

PARTIAL : Une partie des transactions a échoué (ex: solde insuffisant ou numéro invalide).

Paramètres d'URL

Paramètre URL	Type	Obligatoire	Description
bulkOperationId	string	OUI	L'identifiant renvoyé lors de la création de l'opération groupée.

Champs de la Réponse

Field	Type	Obligatoire	Description
bulkOperationId	string	OUI	Identifiant unique du lot
totalCount	int	OUI	Nombre total de transactions
successCount	int	OUI	Nombre de succès
failedCount	int	OUI	Nombre d'échecs
pendingCount	int	OUI	Nombre de transactions en cours
status	string	OUI	Statut global (Pending, Completed, Partial)
createdAt	datetime	OUI	Date de création
updatedAt	datetime	OUI	Date de mise à jour

Détails des Transactions

Field	Type	Obligatoire	Description
id	string	OUI	Identifiant unique de transaction
phoneNumber	string	OUI	Numéro du destinataire
amount	double	OUI	Montant
email	string	OUI	Email du destinataire
description	string	OUI	Description interne
status	string	OUI	Statut de la transaction individuelle
transactionKey	string	OUI	Clé de référence externe
errorMessage	string	OUI	Détails de l'erreur si échec
createdAt	datetime	OUI	Date et heure

GET/api/v2/TransactionSecond/mobile/widraw/bulk/{bulkOperationId}

Exemple de Réponse JSON

{
  "bulkOperationId": "BK-2026-X99",
  "totalCount": 2,
  "successCount": 1,
  "failedCount": 1,
  "pendingCount": 0,
  "status": "Completed",
  "createdAt": "2026-06-05T09:59:22.660Z",
  "updatedAt": "2026-06-05T09:59:22.660Z",
  "transactions": [
    {
      "id": "uuid-123",
      "phoneNumber": "6XXXXXXXX",
      "amount": 5000,
      "email": "utilisateur@example.com",
      "description": "Paiement",
      "status": "Success",
      "transactionKey": "KEY123",
      "errorMessage": "",
      "createdAt": "2026-06-05T09:59:22.660Z"
    }
  ]
}

Astuce : Ne bouclez pas trop vite sur cet endpoint. Nous recommandons un intervalle de 5 à 10 secondes entre chaque vérification de statut pour optimiser vos performances.

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Vérification Standard

Vérifiez l'état d'un paiement Mobile Money ou Bancaire. Cet endpoint interroge directement le statut final auprès de l'opérateur concerné.

Quand appeler cet endpoint ?

Si vous n'avez pas reçu le Webhook de confirmation.
Lorsqu'un client revient sur votre SuccessUrl pour valider son achat.
Pour lever un doute sur une transaction restée en attente.

Paramètres d'URL

Paramètre URL	Type	Requis
transactionkey	string	OUI

Champs de la Réponse

Field	Type	Requis	Description
transactionReference	string	OUI	Référence unique de la transaction
transactionAmount	double	OUI	Montant à payer
transactionDescription	string	OUI	Résumé court de l'achat
walletToken	string	OUI	Token interne de référence du portefeuille
transactionType	string	OUI	Type de transaction (Paiement, etc.)
transactionCategory	string	OUI	Catégorie de la transaction
successUrl	string	OUI	URL de redirection en cas de succès
cancelUrl	string	OUI	URL de redirection en cas d'annulation
transactionKey	string	OUI	Identifiant technique unique
productName	string	NON	Nom du produit acheté
transactionStatus	string	OUI	Statut actuel (SUCCESS, FAILED, PENDING)
paymentUrl	string	OUI	Lien vers la passerelle de paiement
raison	string	NON	Raison détaillée en cas d'échec
cryptoPayAmount	double	NON	Montant en cryptomonnaie (si applicable)
paymentAddress	string	NON	Adresse crypto de l'expéditeur
payeeAddress	string	NON	Adresse crypto du destinataire
ash	string	NON	Hash de la transaction sur la blockchain
createdAt	datetime	OUI	Date de création de la transaction

Détails du Client (Contact)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique du contact
phoneNumber	string	OUI	Numéro de téléphone du client
email	string	OUI	Adresse email du client
address	string	NON	Adresse physique
city	string	NON	Ville du client
state	string	NON	État ou région
country	string	NON	Pays du client
zipCode	string	NON	Code postal

Historique (Transactions Internes)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique de la transaction
transactionType	string	OUI	Type de transaction
transactionStatus	string	OUI	Statut de la transaction individuelle
operator	string	OUI	Opérateur utilisé (MTN, Orange, etc.)
transactionAmount	double	OUI	Montant total
transactionWithOutFees	double	OUI	Montant net sans frais
transactionReference	string	OUI	Référence marchande
transactionKey	string	OUI	Clé technique
transactionDescription	string	OUI	Description
paymentUrl	string	NON	Lien de paiement
faildRaison	string	NON	Détails de l'échec
ash	string	NON	Hash blockchain
createdAt	datetime	OUI	Date et heure

GET/api/v2/TransactionSecond/verify/{transactionkey}/{ash}

Response Body

{
  "transactionReference": "string",
  "transactionAmount": 0,
  "transactionDescription": "string",
  "walletToken": "string",
  "transactionType": "string",
  "transactionCategory": "string",
  "successUrl": "string",
  "cancelUrl": "string",
  "transactionKey": "string",
  "productName": "string",
  "transactionContact": {
    "id": "string",
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zipCode": "string",
    "phoneNumber": "string",
    "email": "string",
    "transactions": [
      {
        "id": "string",
        "transactionType": 0,
        "transactionStatus": 0,
        "operator": 0,
        "transactionAmount": 0,
        "transactionWithOutFees": 0,
        "transactionReference": "string",
        "transactionKey": "string",
        "walletToken": "string",
        "transactionDescription": "string",
        "successUrl": "string",
        "cancelUrl": "string",
        "productName": "string",
        "paymentUrl": "string",
        "faildRaison": "string",
        "description": "string",
        "payCurrency": "string",
        "payAmount": 0,
        "ash": "string",
        "transactionContactId": "string",
        "transactionCategory": 0,
        "transactionContact": "string",
        "paymentAddress": "string",
        "realAmount": 0,
        "payeeAddress": "string",
        "businnesId": "string",
        "business": {
          "id": "string",
          "name": "string",
          "description": "string",
          "returnUrl": "string",
          "callbackUrl": "string",
          "logoUrl": "string",
          "allowIp": "string",
          "balance": 0,
          "activateEmail": true,
          "prevWidrawAmount": 0,
          "transactionFees": 0,
          "userId": "string",
          "user": {
            "id": "string",
            "userName": "string",
            "normalizedUserName": "string",
            "email": "string",
            "normalizedEmail": "string",
            "emailConfirmed": true,
            "passwordHash": "string",
            "securityStamp": "string",
            "concurrencyStamp": "string",
            "phoneNumber": "string",
            "phoneNumberConfirmed": true,
            "twoFactorEnabled": true,
            "lockoutEnd": "2026-06-05T10:17:07.235Z",
            "lockoutEnabled": true,
            "accessFailedCount": 0,
            "fullName": "string",
            "enterpriseName": "string",
            "websiteUrl": "string",
            "status": 0,
            "logoName": "string",
            "nuiValue": "string",
            "type": 0,
            "cardId": "string",
            "card": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "niuId": "string",
            "niu": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "commercialRegisterId": "string",
            "commercialRegister": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "taxSheetId": "string",
            "taxSheet": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "ribId": "string",
            "rib": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "widrawCountTransaction": 0,
            "createdAt": "2026-06-05T10:17:07.236Z",
            "updatedAt": "2026-06-05T10:17:07.236Z"
          },
          "businessOperatorBalance": [
            {
              "id": "string",
              "businessId": "string",
              "operator": 0,
              "amount": 0,
              "createdAt": "2026-06-05T10:17:07.236Z",
              "updatedAt": "2026-06-05T10:17:07.236Z"
            }
          ],
          "createdAt": "2026-06-05T10:17:07.236Z",
          "updatedAt": "2026-06-05T10:17:07.236Z"
        },
        "createdAt": "2026-06-05T10:17:07.236Z",
        "updatedAt": "2026-06-05T10:17:07.236Z",
        "bulkOperationId": "string"
      }
    ]
  },
  "transactionStatus": "string",
  "paymentUrl": "string",
  "raison": "string",
  "cryptoPayAmount": 0,
  "paymentAddress": "string",
  "payeeAddress": "string",
  "ash": "string",
  "createdAt": "2026-06-05T10:17:07.236Z"
}

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

Vérification Crypto

Confirmez le statut d'une transaction sur la blockchain en utilisant la clé de transaction et le Hash (ash) fourni par le réseau.

Note sur le Hash (ash)

Le paramètre ash correspond au Transaction hash associé au transfert.

Paramètres d'URL

Paramètre URL	Type	Requis
transactionkey	string	OUI
ash	string	OUI

Champs de la Réponse

Field	Type	Requis	Description
transactionReference	string	OUI	Référence unique de la transaction
transactionAmount	double	OUI	Montant à payer
transactionDescription	string	OUI	Résumé court de l'achat
walletToken	string	OUI	Token interne de référence du portefeuille
transactionType	string	OUI	Type de transaction
transactionCategory	string	OUI	Catégorie de la transaction
successUrl	string	OUI	URL de redirection en cas de succès
cancelUrl	string	OUI	URL de redirection en cas d'annulation
transactionKey	string	OUI	Identifiant technique unique
productName	string	NON	Nom du produit acheté
transactionStatus	string	OUI	Statut actuel (SUCCESS, FAILED, PENDING)
paymentUrl	string	OUI	Lien vers la passerelle de paiement
raison	string	NON	Raison détaillée en cas d'échec
cryptoPayAmount	double	NON	Montant en cryptomonnaie
paymentAddress	string	NON	Adresse crypto de l'expéditeur
payeeAddress	string	NON	Adresse crypto du destinataire
ash	string	NON	Hash de la transaction sur la blockchain
createdAt	datetime	OUI	Date de création de la transaction

Détails du Client (Contact)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique du contact
phoneNumber	string	OUI	Numéro de téléphone du client
email	string	OUI	Adresse email du client
address	string	NON	Adresse physique
city	string	NON	Ville du client
state	string	NON	État ou région
country	string	NON	Pays du client
zipCode	string	NON	Code postal

Historique (Transactions Internes)

Field	Type	Requis	Description
id	string	OUI	Identifiant unique de la transaction
transactionType	string	OUI	Type de transaction
transactionStatus	string	OUI	Statut de la transaction individuelle
operator	string	OUI	Opérateur utilisé (MTN, Orange, etc.)
transactionAmount	double	OUI	Montant total
transactionWithOutFees	double	OUI	Montant net sans frais
transactionReference	string	OUI	Référence marchande
transactionKey	string	OUI	Clé technique
transactionDescription	string	OUI	Description
paymentUrl	string	NON	Lien de paiement
faildRaison	string	NON	Détails de l'échec
ash	string	NON	Hash blockchain
createdAt	datetime	OUI	Date et heure

GET/api/v2/TransactionSecond/verify/{transactionkey}/{ash}

Response Body

{
  "transactionReference": "string",
  "transactionAmount": 0,
  "transactionDescription": "string",
  "walletToken": "string",
  "transactionType": "string",
  "transactionCategory": "string",
  "successUrl": "string",
  "cancelUrl": "string",
  "transactionKey": "string",
  "productName": "string",
  "transactionContact": {
    "id": "string",
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zipCode": "string",
    "phoneNumber": "string",
    "email": "string",
    "transactions": [
      {
        "id": "string",
        "transactionType": 0,
        "transactionStatus": 0,
        "operator": 0,
        "transactionAmount": 0,
        "transactionWithOutFees": 0,
        "transactionReference": "string",
        "transactionKey": "string",
        "walletToken": "string",
        "transactionDescription": "string",
        "successUrl": "string",
        "cancelUrl": "string",
        "productName": "string",
        "paymentUrl": "string",
        "faildRaison": "string",
        "description": "string",
        "payCurrency": "string",
        "payAmount": 0,
        "ash": "string",
        "transactionContactId": "string",
        "transactionCategory": 0,
        "transactionContact": "string",
        "paymentAddress": "string",
        "realAmount": 0,
        "payeeAddress": "string",
        "businnesId": "string",
        "business": {
          "id": "string",
          "name": "string",
          "description": "string",
          "returnUrl": "string",
          "callbackUrl": "string",
          "logoUrl": "string",
          "allowIp": "string",
          "balance": 0,
          "activateEmail": true,
          "prevWidrawAmount": 0,
          "transactionFees": 0,
          "userId": "string",
          "user": {
            "id": "string",
            "userName": "string",
            "normalizedUserName": "string",
            "email": "string",
            "normalizedEmail": "string",
            "emailConfirmed": true,
            "passwordHash": "string",
            "securityStamp": "string",
            "concurrencyStamp": "string",
            "phoneNumber": "string",
            "phoneNumberConfirmed": true,
            "twoFactorEnabled": true,
            "lockoutEnd": "2026-06-05T10:29:52.518Z",
            "lockoutEnabled": true,
            "accessFailedCount": 0,
            "fullName": "string",
            "enterpriseName": "string",
            "websiteUrl": "string",
            "status": 0,
            "logoName": "string",
            "nuiValue": "string",
            "type": 0,
            "cardId": "string",
            "card": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "niuId": "string",
            "niu": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "commercialRegisterId": "string",
            "commercialRegister": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "taxSheetId": "string",
            "taxSheet": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "ribId": "string",
            "rib": {
              "id": "string",
              "fileName": "string",
              "custumFileName": "string"
            },
            "widrawCountTransaction": 0,
            "createdAt": "2026-06-05T10:29:52.518Z",
            "updatedAt": "2026-06-05T10:29:52.518Z"
          },
          "businessOperatorBalance": [
            {
              "id": "string",
              "businessId": "string",
              "operator": 0,
              "amount": 0,
              "createdAt": "2026-06-05T10:29:52.518Z",
              "updatedAt": "2026-06-05T10:29:52.518Z"
            }
          ],
          "createdAt": "2026-06-05T10:29:52.518Z",
          "updatedAt": "2026-06-05T10:29:52.518Z"
        },
        "createdAt": "2026-06-05T10:29:52.518Z",
        "updatedAt": "2026-06-05T10:29:52.518Z",
        "bulkOperationId": "string"
      }
    ]
  },
  "transactionStatus": "string",
  "paymentUrl": "string",
  "raison": "string",
  "cryptoPayAmount": 0,
  "paymentAddress": "string",
  "payeeAddress": "string",
  "ash": "string",
  "createdAt": "2026-06-05T10:29:52.518Z"
}

N'oubliez pas d'inclure votre accessToken dans le Header de cette requête (Authorization: Bearer [token]). C'est indispensable pour la sécurité.

MANAGEZ VOS PAIEMENTS

Gestion des Clés API

Application Key (Public)

Secret Key (Privé / Signature)

Access Token (JWT Temporaire)

Note Importante sur la récupération

Authentification & Sécurité

La signature est calculée ainsi :

Réponse de Succès (200 OK)

Utilisation du Jeton (Bearer Auth)

Protection des Clés

Paiement Mobile

Comment fonctionnent les paiements Mobile Money

Workflow de Paiement

Paiement Bancaire

Processus de Paiement Bancaire

Workflow Bancaire

Paiement Crypto (USDT)

Fonctionnement du flux Crypto

Workflow Web3 / Crypto

Retrait Mobile

Fonctionnement du retrait

Workflow de Retrait

Retraits (Crypto & USDT)

Spécificités

Retrait Groupé (Bulk Withdraw)

Fonctionnement du mode Bulk

Statut du Retrait Groupé

Comprendre les Statuts

Vérification Standard

Quand appeler cet endpoint ?

Vérification Crypto

Note sur le Hash (ash)

MANAGEZ VOS PAIEMENTS

Gestion des Clés API

Application Key (Public)

Secret Key (Privé / Signature)

Access Token (JWT Temporaire)

Note Importante sur la récupération

Authentification & Sécurité

La signature est calculée ainsi :

Réponse de Succès (200 OK)

Utilisation du Jeton (Bearer Auth)

Protection des Clés

Paiement Mobile

Comment fonctionnent les paiements Mobile Money

Workflow de Paiement

Paiement Bancaire

Processus de Paiement Bancaire

Workflow Bancaire

Paiement Crypto (USDT)

Fonctionnement du flux Crypto

Workflow Web3 / Crypto

Retrait Mobile

Fonctionnement du retrait

Workflow de Retrait

Retraits (Crypto & USDT)

Spécificités

Retrait Groupé (Bulk Withdraw)

Fonctionnement du mode Bulk

Statut du Retrait Groupé

Comprendre les Statuts

Vérification Standard

Quand appeler cet endpoint ?

Vérification Crypto

Note sur le Hash (ash)

MANAGEZ VOS
PAIEMENTS

MANAGEZ VOS
PAIEMENTS