Documentation de l'API de paiement en cryptomonnaies.

Bienvenue sur la documentation de l'API de paiement en cryptomonnaies de CiExchange.
Cette API permet aux e-commerçants, développeurs d'applications web/mobile, prestataires de services, créateurs de contenu, freelancers ...etc d'accepter des paiements en cryptomonnaies.

Clés API

Les clés API servent à authentifier les requêtes adressées à l'API.

Types de Clés API

Clé API Publique (Public Key)

Utilisation : Authentification côté client (frontend).

Création de paiements
Obtenir les détails/informations d'un paiement
Vérification du statut des paiements
Opérations non sensibles

Sécurité : Peut être exposée publiquement dans le code client.

Clé API Secrète (Secret Key)

Utilisation : Authentification côté serveur (backend) uniquement.

Régénération des clés API
Modification des paiements
Opérations sensibles et administratives

Sécurité : Ne doit JAMAIS être exposée publiquement. Stockez-la de manière sécurisée sur votre serveur.

Environnements

Deux ensembles de clés sont disponibles :

Test : Pour les tests en utilisant des cryptomonnaies fictives (test tokens).
Production : Pour les transactions réelles avec de vrais cryptomonnaies.

Obtention de la Clé d'API

Pour obtenir vos clés d'API, suivez ces étapes :

Connectez-vous à votre compte CiExchange.
Cliquer sur le bouton BUSINESS en bas dans le menu latéral gauche.
Cliquer sur le bouton COMPTES MARCHANDS.
Cliquer sur un compte marchand si vous en avez un ou créez-en un si vous n'en avez pas encore.
Cliquez sur "Développeur" dans le menu latéral gauche pour trouver vos clés d'API ou en créer de nouvelles.

Authentification

Toutes les requêtes à l'API doivent être authentifiées à l'aide d'une clé d'API. La clé d'API doit être incluse dans l'en-tête authorization de chaque requête.

"Authorization": "Bearer VOTRE_CLE_API"

Créer un Paiement

Ce point de terminaison permet de créer un paiement. En retour, vous obtiendrez l'URL de la page de paiement vers laquelle rediriger votre utilisateur ou votre client pour effectuer le paiement.

Clé API recommandée : Clé Publique (Public Key)

Requête

POST/api/v1/payments/

Corps de la requête (JSON)

{
  "isTest": false,
  "fiatAmount": 50000,
  "fiatCurrency": "XOF",
  "merchantId": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
  "redirectUrlOnPaymentSuccess": "https://monsite-web.com",
  "redirectUrlOnPaymentFailure": "https://monsite-web.com",
  "acceptedCryptoType": "stablecoins",
  "paymentDetails": [
    {
      "key": "order_id",
      "value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
    },
    {
      "key": "customer_email",
      "value": "prenoms@gmail.com"
    }
  ],
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
  "webhookUrl": "https://monsite-web.com/api/webhooks/payments"
}

Exemple de requête

HTTP

POST /api/v1/payments HTTP/1.1
Content-Type: application/json
Authorization: Bearer test_public_key__80cfb706c4f69d265c2477e4097b144460ef0a49dc229ac4a710b90cf67367fd
Host: https://ciexchange.xyz
Content-Length: 611
{
  "isTest": false,
  "fiatAmount": 50000,
  "fiatCurrency": "XOF",
  "merchantId": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
  "redirectUrlOnPaymentSuccess": "https://monsite-web.com",
  "redirectUrlOnPaymentFailure": "https://monsite-web.com",
  "acceptedCryptoType": "stablecoins",
  "paymentDetails": [
    {
      "key": "order_id",
      "value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
    },
    {
      "key": "customer_email",
      "value": "prenoms@gmail.com"
    }
  ],
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
  "webhookUrl": "https://monsite-web.com/api/webhooks/payments"
}

Réponse en cas de succès

La réponse contiendra l'ID du paiement et l'URL de la page de paiement.

{
  "data": {
    "payment": {
      "id": "9617ee4d-fb82-4281-9293-d79df20684d4"
    },
    "payment_page_url": "https://ciexchange.xyz/pay/9617ee4d-fb82-4281-9293-d79df20684d4"
  },
  "message": "Page de paiement crée avec succès."
}

Réponse en cas d'échec

La réponse contiendra le message ci-dessous.

{
  "error": {
    "message": "Message d'erreur"
  }
}

Modifier un Paiement

Ce point de terminaison permet de modifier les détails d'un paiement existant. Utile pour mettre à jour les informations de commande ou corriger des erreurs.

Clé API requise : Clé Secrète (Secret Key) - Opération sensible

Requête

PUT/api/payments/:paymentId

Paramètres d'URL

paymentId (string, requis) - L'ID du paiement.

Corps de la requête (JSON)

{
  "isTest": false,
  "fiatAmount": 100000,
  "fiatCurrency": "XOF",
  "merchantId": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
  "redirectUrlOnPaymentSuccess": "https://monsite-web.com",
  "redirectUrlOnPaymentFailure": "https://monsite-web.com",
  "acceptedCryptoType": "stablecoins",
  "paymentDetails": [
    {
      "key": "order_id",
      "value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
    },
    {
      "key": "customer_email",
      "value": "prenoms@gmail.com"
    }
  ],
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
  "webhookUrl": "https://monsite-web.com/api/webhooks/payments"
}

Exemple de requête

HTTP

PUT /api/v1/payments/9617ee4d-fb82-4281-9293-d79df20684d4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer test_secret_key__80cfb706c4f69d265c2477e4097b144460ef0a49dc229ac4a710b90cf67367fd
Host: https://ciexchange.xyz
Content-Length: 612
{
  "isTest": false,
  "fiatAmount": 100000,
  "fiatCurrency": "XOF",
  "merchantId": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
  "redirectUrlOnPaymentSuccess": "https://monsite-web.com",
  "redirectUrlOnPaymentFailure": "https://monsite-web.com",
  "acceptedCryptoType": "stablecoins",
  "paymentDetails": [
    {
      "key": "order_id",
      "value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
    },
    {
      "key": "customer_email",
      "value": "prenoms@gmail.com"
    }
  ],
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
  "webhookUrl": "https://monsite-web.com/api/webhooks/payments"
}

Réponse en cas de succès

La réponse contiendra les détails mis à jour du paiement.

{
  "data": {
    "payment": {
      "id": "9617ee4d-fb82-4281-9293-d79df20684d4"
    },
    "payment_page_url": "https://ciexchange.xyz/pay/9617ee4d-fb82-4281-9293-d79df20684d4"
  },
  "message": "Informations de paiement modifié avec succès."
}

Réponse en cas d'échec

La réponse contiendra le message d'erreur.

{
  "error": {
    "message": "Message d'erreur"
  }
}

Restrictions

Un paiement ne peut être modifié que s'il est en statut "PENDING" (en attente de paiement).
Les paiements "COMPLETED" (paiement terminé) ne peuvent pas être modifiés.

Obtenir les détails d'un Paiement

Ce point de terminaison permet de récupérer tous les détails d'un paiement spécifique, y compris les informations de transaction et les métadonnées.

Clé API recommandée : Clé Publique (Public Key)

Requête

GET/api/payments/:paymentId

Paramètres d'URL

paymentId (string, requis) - L'ID du paiement.

Exemple de requête

GET /api/v1/payments/9617ee4d-fb82-4281-9293-d79df20684d4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer test_public_key__80cfb706c4f69d265c2477e4097b144460ef0a49dc229ac4a710b90cf67367fd
Host: https://ciexchange.xyz

Réponse en cas de succès

La réponse contiendra tous les détails du paiement.

{
  "data": {
    "paymentData": {
      "id": "f34394b6-63dc-435e-a5cf-4a7f448b112c",
      "merchant_id": "73e1f22a-521f-4ffb-a3c8-cce2faf60481",
      "fiat_amount": 50000,
      "fiat_currency": "XOF",
      "redirect_url_on_payment_success": "https://monsite-web.com",
      "redirect_url_on_payment_failure": "https://monsite-web.com",
      "payment_details": [
        {
          "key": "order_id",
          "value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
        },
        {
          "key": "customer_email",
          "value": "prenoms@gmail.com"
        }
      ],
      "status": "PENDING",
      "expires_at": null,
      "type_of_crypto_accepted": "stablecoins",
      "payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
      "created_at": "2025-11-20T12:01:38.881Z",
      "webhook_url": null,
      "is_test": true,
      "preferred_asset_id_for_payment": null
    },
    "payment_page_url": "https://ciexchange.com/pay/PAYMENT_ID"
  },
  "success": {
    "message": "détails du paiement."
  }
}

Champs de la Réponse

id: Identifiant unique du paiement
merchant_id: ID du compte marchand
fiat_amount: Montant en devise fiduciaire
fiat_currency: Devise fiduciaire (code alphabétique de trois lettres ISO 4217), exemple : XOF, XAF, USD, EUR, GBP, CAD, CHF ...etc.
redirect_url_on_payment_success: URL de redirection après succès
redirect_url_on_payment_failure: URL de redirection après échec
payment_details: Métadonnées du paiement
order_id: Identifiant unique de la commande dans votre système
payout_address: Adresse Ethereum (0x...) sur laquelle vous souhaitez recevoir le paiement en cryptomonnaie
type_of_crypto_accepted: Type de cryptomonnaie accepté (stablecoins, native_cryptos)
preferred_asset_id_for_payment: ID de l'actif préféré pour le paiement (si vous avez choisir une cryptomonnaie spécifique dans lequel recevoir le paiement)
status: Statut actuel du paiement
webhook_url: URL à laquelle les notifications seront envoyées
created_at: Date de création
updated_at: Dernière mise à jour
expires_at: Date d'expiration
payment_page_url: URL de la page de paiement

Réponse en cas d'échec

La réponse contiendra le message d'erreur.

{
  "error": {
    "message": "Not found."
  }
}

Statuts possibles des paiements

PENDING - Paiement en attente.
COMPLETED - Paiement effectué.

Obtenir les détails d'un transaction de paiement

Ce point de terminaison permet de récupérer les détails d'une transaction lorsque le paiement est effectué.

Clé API recommandée : Clé Publique (Public Key)

Requête

GET/api/v1/paiement-transactions/:transactionHash

Paramètres d'URL

transactionHash (string, requis) - Le hash de la transaction de paiement.

Exemple de requête

GET /api/v1/payment-transactions/0xd3d23557a930fa511c0b821d75fa83f3a70e98cdef4a426ec929f9829ff5cec2 HTTP/1.1
Content-Type: application/json
Authorization: Bearer test_secret_key__80cfb706c4f69d265c2477e4097b144460ef0a49dc229ac4a710b90cf67367fd
Host: https://ciexchange.xyz

Réponse en cas de succès

La réponse contiendra tous les détails de la transaction.

{
  "id": "4b09a85b-d74b-4147-b497-47e621277130",
  "payment_id": "a98086aa-c744-4eeb-a25f-bef0af7f20c3",
  "merchant_id": "31e128e8-db6b-46a5-aff5-5bf5438eda71",
  "asset_id": "5a9387e6-745b-4786-a01b-eeb0ed9306c1",
  "amount_paid": "100",
  "platform_fee_percentage": 100,
  "platform_fee_amount": "1.00",
  "amount_to_transfer_to_merchant": "99.00",
  "blockchain_txn_hash": "0xd3d23557a930fa511c0b821d75fa83f3a70e98cdef4a426ec929f9829ff5cec2",
  "created_at": "2024-01-15T10:05:00Z"
}

Champs de la Réponse

id: Identifiant unique de la transaction
payment_id: ID du paiement associé
merchant_id: ID du compte marchand associé
asset_id: ID de cryptomonnaie utilisée pour le paiement
amount_paid: Montant total payé en cryptomonnaie
platform_fee_percentage: Pourcentage de CiExchange, (200 pour 2%)
platform_fee_amount: Frais de service CiExchange
amount_to_transfer_to_merchant: Montant net transférer au marchand
blockchain_txn_hash: Hash de la transaction blockchain
created_at: Date de création

Réponse en cas d'échec

La réponse contiendra le message d'erreur.

{
  "error": {
    "message": "Transaction non trouvée"
  }
}

Webhooks de Notification

Le système de webhooks permet de recevoir des notifications en temps réel sur le statut des paiements.

Configuration

Pour activer les webhooks, incluez le champwebhookUrl dans vos requêtes de création ou modification de paiement.

Payload du Webhook

{
  "event": "payment.completed",
  "data": {
    "paymentId": "9617ee4d-fb82-4281-9293-d79df20684d4",
    "status": "COMPLETED",
    "transactionHash": "0x1234567890abcdef...",
    "amountPaid": "0.1",
    "merchantAmount": "0.095",
    "platformFee": "0.005",
    "asset": "ETH",
    "chainId": 1,
    "timestamp": "2024-01-15T10:30:00Z",
    "paymentDetails": {
      "order_id": "73b87b0b-9415-4df3-b0dc-9a8047343350",
      "customer_email": "prenoms@gmail.com"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Événements Supportés

payment.completed - Paiement réussi
payment.failed - Paiement échoué

Bonnes Pratiques

Votre endpoint webhook doit répondre avec un statut HTTP 200 dans les 5 secondes
Logguez toutes les notifications reçues
Testez votre webhook avec notre environnement sandbox
Implémentez un mécanisme de retry côté client pour plus de robustesse

Exemple de Réponse Attendue

// Votre endpoint doit retourner HTTP/1.1 200 OK Content-Type: application/json
{
  "success": true,
  "message": "Webhook received successfully"
}

Bonnes Pratiques de Sécurité

⚠️ Important : Sécurité des Clés API

Clé Publique : Peut être utilisée dans le code frontend
Clé Secrète : JAMAIS dans le code frontend. Utilisez-la uniquement dans votre backend sécurisé
Ne commitez jamais vos clés secrètes dans des dépôts Git
Utilisez des variables d'environnement pour stocker les clés
Régénérez vos clés immédiatement en cas de suspicion de compromission

Codes d'État HTTP

200 - Succès
201 - Créé avec succès
400 - requête invalide
401 - Non autorisé
404 - Ressource non trouvée
422 - Entité non traitable
500 - Erreur interne du serveur

URL du serveur

https://ciexchange.xyz/api/v1/

Swagger

Documnentation Swagger de l'API

SDK JS/TS

https://www.npmjs.com/package/ciexchange-pay

Utilisable en backend Node/Bun/Deno et aussi en frontend React/Vue/Angular...

Support

Pour toute question technique ou assistance, contactez notre équipe de support :

Email : support@ciexchange.xyz
Statut des services : https://ciexchange.xyz/api/v1/status