Documentation de l'API de paiement en cryptomonnaies.

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.

Requête

POST/api/v1/payments/

Corps de la requête (JSON)

{
  "fiatAmount": 50000,
  "fiatCurrency": "XOF",
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
  "redirectUrl": "https://monsite-web.com/success",
  "acceptedCryptoType": "stablecoins",
  "orderId": "ORDER_12345",
  "additionalData": [
    {
      "key": "customer_email",
      "value": "customer@example.com"
    }
  ]
}

Champs du corps de la requête

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
{
  "fiatAmount": 50000,
  "fiatCurrency": "XOF",
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
  "redirectUrl": "https://monsite-web.com/success",
  "acceptedCryptoType": "stablecoins",
  "orderId": "ORDER_12345",
  "additionalData": [
    {
      "key": "customer_email",
      "value": "customer@example.com"
    }
  ]
}

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://app.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.

Requête

PUT/api/payments/:paymentId

Paramètres d'URL

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

Corps de la requête (JSON)

{
  "fiatAmount": 100000,
  "fiatCurrency": "XOF",
  "redirectUrl": "https://monsite-web.com/updated-success",
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06"
}

Champs modifiables

Vous pouvez envoyer n'importe lequel des champs utilisés lors de la création pour mettre à jour le paiement. Les règles de caractère obligatoire/facultatif restent les mêmes.

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
{
  "fiatAmount": 100000,
  "fiatCurrency": "XOF",
  "redirectUrl": "https://monsite-web.com/updated-success",
  "payoutAddress": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06"
}

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://app.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.

Supprimer un Paiement

Ce point de terminaison permet de supprimer un paiement existant. Cela est utile pour annuler des demandes de paiement qui ne sont plus nécessaires.

Requête

DELETE/api/payments/{paymentId}

Paramètres d'URL

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

Exemple de requête

HTTP

DELETE /api/v1/payments/9617ee4d-fb82-4281-9293-d79df20684d4 HTTP/1.1
Authorization: Bearer test_secret_key__...
Host: https://ciexchange.xyz

Réponse en cas de succès

{
  "success": {
    "message": "Paiement supprimé avec succès."
  }
}

Réponse en cas d'échec

{
  "error": {
    "message": "Seuls les paiements en attente peuvent être supprimés."
  }
}

Restrictions

• Seuls les paiements avec le statut PENDING peuvent être supprimés.
• Les paiements déjà complétés ne peuvent pas être supprimé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.

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",
      "fiat_amount": 50000,
      "fiat_currency": "XOF",
      "redirect_url": "https://monsite-web.com/success",
      "additional_data": [
        {
          "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",
      "is_test": true,
      "preferred_asset_id_for_payment": null
    },
    "payment_page_url": "https://app.ciexchange.com/pay/PAYMENT_ID"
  },
  "success": {
    "message": "détails du paiement."
  }
}

Champs de la Réponse

• id: Identifiant unique du paiement
• 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: URL de redirection de l'utilisateur après le paiement
• additional_data: Données supplémentaires 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
• 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é.

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",
  "asset_id": "5a9387e6-745b-4786-a01b-eeb0ed9306c1",
  "amount_paid": "1000",
  "platform_fee_percentage": 100,
  "platform_fee_amount": "10",
  "amount_to_transfer_to_merchant": "990",
  "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é
• asset_id: ID de cryptomonnaie utilisée pour le paiement, Ex: "5a9387e6-745b-4786-a01b-eeb0ed9306c1" (USDT)
• amount_paid: Montant total payé en cryptomonnaie (Ex: 1000 USDT)
• platform_fee_percentage: Pourcentage de CiExchange, (100 pour 1%, 100 points de base = 1%).
• platform_fee_amount: Frais de service CiExchange (Ex: 10 USDT)
• amount_to_transfer_to_merchant: Montant net transférer au marchand (Ex: 990 USDT)
• 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"
  }
}

Obtenir les crypto-monnaies supportées pour CiExchange Pay

Ce point de terminaison permet de récupérer la liste des crypto-monnaies spécifiquement supportées pour effectuer des paiements via CiExchange Pay.

Requête

GET/api/v1/cryptocurrencies/supported/for-pay

Réponse en cas de succès

{
  "data": [
    {
      "id": "5a9387e6-745b-4786-a01b-eeb0ed9306c1",
      "name": "Tether",
      "symbol": "USDT",
      "is_stablecoin": true,
      "current_price": 1
    }
  ],
  "message": "Liste des crypto-monnaies supportées pour CiExchange Pay."
}

Webhooks de Notification

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

Configuration

Pour configurer les webhooks, allez dans votre compte marchand CiExchange Pay, puis cliquez sur Développeur dans le menu latéral gauche et puis cliquez sur URLS Webhook. Cliquez ensuite sur Ajouter un URL Webhook et remplissez le formulaire.

Jeton de Sécurité (Webhook Token)

Après avoir ajouté une URL Webhook avec succès, un modal s'affichera contenant un Token Webhook unique.

Réception d'un Webhook

Lorsqu'un Webhook est envoyé à l'url que vous avez configuré, la requête http POST contient un corps en format JSON détaillant l'événement Webhook. Le header X-CiExchange-Pay-Webhook-Token est également présent pour vous permettre de vérifier l'authenticité de la requête.

Exemple de corps de la requête Webhook.

{
  "event": "payment-completed",
  "data": {
    "paymentId": "9617ee4d-fb82-4281-9293-d79df20684d4",
    "status": "COMPLETED",
    "paymentTransactionHash": "0x1234567890abcdef..."
  }
}

É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

Exemple de Réponse Attendue

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