CiExchange - Documentation de l'API de Paiement en cryptomonnaie.

Bienvenue sur la documentation de l'API de paiement en cryptomonnaies de ciexchange. Cette API permet aux propriétaires de site sites e-commerce, d'applications web/mobile, prestataires de services, créateurs de contenu, freelancers ...etc d'accepter des paiements en cryptomonnaies sur leur site web ou leur application.

Clés API

Les clés API servent à authentifier les requêtes adressées à l'API de paiement en cryptomonnaies de CiExchange.

Types de Clés API

Environnements

Obtention de la Clé d'API

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.

Créer un Paiement

Ce point de terminaison permet de créer un paiement. En retour, vous obtiendrez une URL de paiement vers laquelle rediriger votre utilisateur ou votre client.

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

Requête

POST /api/v1/payments/

Corps de la Requête (JSON)

				
{
	"fiat_amount": "number, (le montant a payer), ex: 50000",

	"fiat_currency": "string, (la devise du montant a payer), ex: XOF ou XAF",

	"merchant_id": "string, (l'ID du compte marchand), ex: '09f27837-cee5-4a6b-96fc-71773f9c3f3c'",

	"redirect_url_on_payment_success": "string, (l'URL vers laquel sera rediriger l'utilisateur ou le client si paiement confirmé/réussir), ex: 'https://monsite-web.com'",

	"redirect_url_on_payment_failure": "string, (l'URL vers laquel sera rediriger l'utilisateur ou le client si paiement échoué/non finalisé), ex: 'https://monsite-web.com'",

	"accepted_crypto_type": "string, (les types de cryptomonnaies a affiché a l'utilisateur ou à votre client sur la page de paiement), ex: 'stablecoins', 'native_cryptos', 'stablecoins_and_native_cryptos'",

	"payment_details": "tableau d'object, (données supplémentaires sur le paiement ou la facture), ex: [
		{'key': 'order_id', 'value': '73b87b0b-9415-4df3-b0dc-9a8047343350'},
		{'key': 'customer_email', 'value': 'prenoms@gmail.com'}
	]",

	"payout_address": "string, (l'adresse Ethereum ou compatible Ethereum sur laquel vous souhaitez reçevoir instantanément le paiement), ex: '0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06'",

	"webhook_url": "string, (l'URL pour recevoir les notifications de statut du paiement), ex: 'https://monsite-web.com/api/webhooks/payments'"
}

Exemple de Requête

CURL

                
curl --request POST \
--url https://api.ciexchange.xyz/api/v1/payments \
--header 'authorization: Bearer prod_secret_key__e57e08ea556c4cf9f2965636d6c920ed2c3272dcdefebe6d55b7a1ed713a0eff' \
--header 'content-type: application/json' \
--data '{
"fiat_amount": 50000,
"fiat_currency": "XOF",
"merchant_id": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
"redirect_url_on_payment_success": "https://monsite-web.com",
"redirect_url_on_payment_failure": "https://monsite-web.com",
"accepted_crypto_type": "stablecoins",
"payment_details": [
{
"key": "order_id",
"value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
},
{
"key": "customer_email",
"value": "prenoms@gmail.com"
}
],
"payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
"webhook_url": "https://monsite-web.com/api/webhooks/payments"
}'

HTTP

			
POST /api/payments HTTP/1.1
Content-Type: application/json
Authorization: Bearer prod_secret_key__e57e08ea556c4cf9f2965636d6c920ed2c3272dcdefebe6d55b7a1ed713a0eff
Host: https://ciexchange.xyz
Content-Length: 542

{
"fiat_amount": 50000,
"fiat_currency": "XOF",
"merchant_id": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
"redirect_url_on_payment_success": "https://monsite-web.com",
"redirect_url_on_payment_failure": "https://monsite-web.com",
"accepted_crypto_type": "stablecoins",
"payment_details": [
{
"key": "order_id",
"value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
},
{
"key": "customer_email",
"value": "prenoms@gmail.com"
}
],
"payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
"webhook_url": "https://monsite-web.com/api/webhooks/payments"
}

FETCH

				
const url = 'https://api.ciexchange.xyz/api/v1/payments';
const options = {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: 'Bearer prod_secret_key__e57e08ea556c4cf9f2965636d6c920ed2c3272dcdefebe6d55b7a1ed713a0eff'
},
body:
'{"fiat_amount":50000,"fiat_currency":"XOF","merchant_id":"09f27837-cee5-4a6b-96fc-71773f9c3f3c","redirect_url_on_payment_success":"https://monsite-web.com","redirect_url_on_payment_failure":"https://monsite-web.com","accepted_crypto_type":"stablecoins","payment_details":[{"key":"order_id","value":"73b87b0b-9415-4df3-b0dc-9a8047343350"},{"key":"customer_email","value":"prenoms@gmail.com"}],"payout_address":"0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06","webhook_url":"https://monsite-web.com/api/webhooks/payments"}'
};

try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

Réponse en cas de succès

La réponse contiendra l'URL 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)

				
{
    "fiat_amount": 100000,
    "fiat_currency": "XOF",
    "merchant_id": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
    "redirect_url_on_payment_success": "https://monsite-web.com",
    "redirect_url_on_payment_failure": "https://monsite-web.com",
    "accepted_crypto_type": "stablecoins",
    "payment_details": [
    {
    "key": "order_id",
    "value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
    },
    {
    "key": "customer_email",
    "value": "prenoms@gmail.com"
    }
    ],
    "payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
    "webhook_url": "https://monsite-web.com/api/webhooks/payments"
}

Exemple de Requête

CURL

			
curl --request PUT \
--url https://api.ciexchange.xyz/api/v1/payments/9617ee4d-fb82-4281-9293-d79df20684d4 \
--header 'authorization: Bearer prod_secret_key__e57e08ea556c4cf9f2965636d6c920ed2c3272dcdefebe6d55b7a1ed713a0eff' \
--header 'content-type: application/json' \
--data '{
"fiat_amount": 100000,
"fiat_currency": "XOF",
"merchant_id": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
"redirect_url_on_payment_success": "https://monsite-web.com",
"redirect_url_on_payment_failure": "https://monsite-web.com",
"accepted_crypto_type": "stablecoins",
"payment_details": [
{
"key": "order_id",
"value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
},
{
"key": "customer_email",
"value": "prenoms@gmail.com"
}
],
"payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
"webhook_url": "https://monsite-web.com/api/webhooks/payments"
}'

HTTP

			
PUT /api/payments/9617ee4d-fb82-4281-9293-d79df20684d4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer prod_secret_key__e57e08ea556c4cf9f2965636d6c920ed2c3272dcdefebe6d55b7a1ed713a0eff
Host: https://ciexchange.xyz
Content-Length: 543

{
"fiat_amount": 100000,
"fiat_currency": "XOF",
"merchant_id": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
"redirect_url_on_payment_success": "https://monsite-web.com",
"redirect_url_on_payment_failure": "https://monsite-web.com",
"accepted_crypto_type": "stablecoins",
"payment_details": [
{
"key": "order_id",
"value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
},
{
"key": "customer_email",
"value": "prenoms@gmail.com"
}
],
"payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
"webhook_url": "https://monsite-web.com/api/webhooks/payments"
}

FETCH

		
const url = 'https://api.ciexchange.xyz/api/v1/payments/9617ee4d-fb82-4281-9293-d79df20684d4';
const options = {
method: 'PUT',
headers: {
'content-type': 'application/json',
authorization: 'Bearer prod_secret_key__e57e08ea556c4cf9f2965636d6c920ed2c3272dcdefebe6d55b7a1ed713a0eff'
},
body:
'{"fiat_amount":100000,"fiat_currency":"XOF","merchant_id":"09f27837-cee5-4a6b-96fc-71773f9c3f3c","redirect_url_on_payment_success":"https://monsite-web.com","redirect_url_on_payment_failure":"https://monsite-web.com","accepted_crypto_type":"stablecoins","payment_details":[{"key":"order_id","value":"73b87b0b-9415-4df3-b0dc-9a8047343350"},{"key":"customer_email","value":"prenoms@gmail.com"}],"payout_address":"0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06","webhook_url":"https://monsite-web.com/api/webhooks/payments"}'
};

try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

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"
Les paiements "COMPLETED", "FAILED" ou "EXPIRED" 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

                
curl --request GET \
--url https://api.ciexchange.xyz/api/v1/payments/PAYMENT_ID \
--header 'authorization: Bearer VOTRE_CLE_PUBLIQUE'

Réponse en cas de succès

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


{
    data: {
		paymentData: {
			"id": "PAYMENT_ID",
			"fiat_amount": 50000,
			"fiat_currency": "XOF",
			"status": "PENDING",
			"merchant_id": "09f27837-cee5-4a6b-96fc-71773f9c3f3c",
			"redirect_url_on_payment_success": "https://monsite-web.com",
			"redirect_url_on_payment_failure": "https://monsite-web.com",
			"accepted_crypto_type": "stablecoins",
			"payout_address": "0x39E60373b7A1BE5bf9F4288D58e65C8d9c314F06",
			"payment_details": [
			{
			"key": "order_id",
			"value": "73b87b0b-9415-4df3-b0dc-9a8047343350"
			},
			{
			"key": "customer_email",
			"value": "prenoms@gmail.com"
			}
			],
			"created_at": "2024-01-15T10:00:00Z",
			"updated_at": "2024-01-15T10:00:00Z",
			"expires_at": "2024-01-15T11:00:00Z",
		},
		"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 fiat
fiat_currency: Devise fiat (XOF ou XAF)
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 sur laquelle le paiement sera effectué
type_of_crypto_accepted: Type de crypto accepté
status: Statut actuel du paiement
webhook_url: URL à laquelle les notifications seront envoyées
payment_page_url: URL de la page de paiement
created_at: Date de création
updated_at: Dernière mise à jour
expires_at: Date d'expiration

Devise fiduciaire possibles

XOF - Franc CFA de l'Afrique de l'Ouest
XAF - Franc CFA de l'Afrique centrale

Statuts possibles des paiements

PENDING - En attente de paiement
COMPLETED - Paiement effectué

Réponse en cas d'échec

La réponse contiendra le message d'erreur.

	{
	    "error": {
	        "message": "Paiement non trouvé"
	    }
	}

Obtenir les Détails d'une Transaction

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/{transactionId}

Paramètres d'URL

transactionId (string, requis) - L'ID de la transaction de paiement.

Exemple de Requête

                
curl --request GET \
--url https://api.ciexchange.xyz/api/v1/paiement-transactions/TRANSACTION_ID \
--header 'authorization: Bearer VOTRE_CLE_PUBLIQUE'

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": 200,
	"platform_fee_amount": "2.00",
	"amount_to_transfer_to_merchant": "98.00",
	"blockchain_txn_hash": "0xa1b2c3d4e5f6789012345678901234567890123456789012345678901234567890",
	"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 champ webhookUrl dans vos requêtes de création ou modification de paiement.

Payload du Webhook

			{
			"event": "payment.completed", // ou "payment.failed"
			"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é

Codes d'État HTTP

Environnements et URLs

Support

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

Documentation de l'API de paiement en cryptomonnaies.

Clés API

Types de Clés API

Clé API Publique (Public Key)

Clé API Secrète (Secret Key)

Environnements

Obtention de la Clé d'API

Authentification

Créer un Paiement

Requête

Corps de la Requête (JSON)

Exemple de Requête

CURL

HTTP

FETCH

Réponse en cas de succès

Réponse en cas d'échec

Modifier un Paiement

Requête

Paramètres d'URL

Corps de la Requête (JSON)

Exemple de Requête

CURL

HTTP

FETCH

Réponse en cas de succès

Réponse en cas d'échec

Restrictions

Obtenir les Détails d'un Paiement

Requête

Paramètres d'URL

Exemple de Requête

Réponse en cas de succès

Champs de la Réponse

Devise fiduciaire possibles

Statuts possibles des paiements

Réponse en cas d'échec

Obtenir les Détails d'une Transaction

Requête

Paramètres d'URL

Exemple de Requête

Réponse en cas de succès

Champs de la Réponse

Réponse en cas d'échec

Webhooks de Notification

Configuration

Payload du Webhook

Événements Supportés

Bonnes Pratiques

Exemple de Réponse Attendue

Bonnes Pratiques de Sécurité

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

Codes d'État HTTP

Environnements et URLs

Support