API SankiPay

Encaissez depuis votre boutique en ligne en trois appels : votre serveur crée le paiement, le client paie sur la page SankiPay, votre serveur est prévenu.

Principe

Votre serveur appelle spy_api_creer avec le montant et la référence de la commande.
Il reçoit une adresse url : vous y envoyez le client. Il choisit son pays, son moyen de paiement, et paie dans sa devise.
SankiPay prévient votre serveur par un webhook signé. Vous pouvez aussi demander le statut avec spy_api_statut.

Pas de site ? Les liens de paiement de votre espace marchand font la même chose sans une ligne de code.

Clés

Chaque appel porte deux clés :

La clé publique de la plateforme, dans l'en-tête apikey. Elle est la même pour tous et peut être vue de tous :
Votre clé secrète sk_…, dans le corps de la requête (p_cle). Générez-la dans Développeurs. Elle n'est montrée qu'une fois : gardez-la dans une variable d'environnement de votre serveur, jamais dans une page web ni une application mobile.

Créer un paiement

POST /rest/v1/rpc/spy_api_creer

Paramètre	Obligatoire	Description
`p_cle`	oui	Votre clé secrète.
`p_montant`	oui	Montant à encaisser, dans la devise indiquée.
`p_devise`	non	Code ISO (`XOF`, `XAF`, `EUR`…). Par défaut : la devise de votre compte.
`p_reference`	non	Votre numéro de commande. Il revient dans le statut et le webhook.
`p_description`	non	Texte affiché au client sur la page de paiement.
`p_retour_url`	non	Adresse `https://` où renvoyer le client après un paiement réussi.
`p_client_nom`, `p_client_email`, `p_client_tel`	non	Pré-remplissent la page de paiement.

Réponse :

La session reste ouverte 24 heures. Le client peut réessayer autant de fois que nécessaire jusqu'au premier paiement réussi.

Rediriger le client

Envoyez le client vers url. Après un paiement réussi, s'il y a une p_retour_url, il y est renvoyé avec deux paramètres : ?sankipay_ref=SPY-…&statut=reussi.

Ne livrez jamais sur la seule foi de ce retour : n'importe qui peut taper cette adresse. Confirmez toujours par le webhook ou par spy_api_statut.

Vérifier un paiement

POST /rest/v1/rpc/spy_api_statut avec p_cle et p_id : l'identifiant de session, la référence SPY-… ou votre propre référence de commande.

La réponse contient session, paiement (montant, frais, net, moyen, pays, statut) et paye, qui vaut true dès que la commande est payée.

Webhooks

Indiquez l'adresse de votre webhook dans Développeurs. À chaque paiement réussi ou échoué, SankiPay y envoie un POST JSON :

Événements : paiement.reussi, paiement.echoue, et test (bouton « Envoyer un test »). L'en-tête X-SankiPay-Signature contient le HMAC-SHA256, en hexadécimal, du corps brut reçu, calculé avec votre secret de signature whsec_…. Vérifiez-le avant toute action, puis répondez par un code 2xx.

Mode test

Tant que la plateforme est en mode test, les appels sont identiques mais aucun argent ne circule : sur la page de paiement, le client choisit lui-même « réussite » ou « refus ». Les données de test restent séparées des données réelles.

Erreurs

Une erreur renvoie un code HTTP 400 avec un message de la forme {"code":"P0001","message":"SPY_CLE_INVALIDE"}.

Message	Signification
`SPY_CLE_INVALIDE`	Clé secrète absente, fausse ou remplacée.
`SPY_MONTANT_INVALIDE`	Montant nul, négatif ou trop grand.
`SPY_DEVISE_INCONNUE`	Devise non gérée par la plateforme.
`SPY_URL_INVALIDE`	L'adresse de retour doit commencer par https:// ou http://.
`SPY_MARCHAND_SUSPENDU`	Votre compte est suspendu : contactez le support.
`SPY_MARCHAND_NON_VERIFIE`	En mode réel, votre compte doit être vérifié (KYC).
`SPY_TROP_DE_TENTATIVES`	Plus de 120 créations par minute : ralentissez.
`SPY_PAIEMENT_INTROUVABLE`	Aucun paiement ni session avec cet identifiant sur votre compte.

SankiPay API

Collect payments from your online shop in three calls: your server creates the payment, the customer pays on the SankiPay page, your server is notified.

How it works

Your server calls spy_api_creer with the amount and the order reference.
It receives a url: send the customer there. They choose their country and payment method, and pay in their currency.
SankiPay notifies your server with a signed webhook. You can also ask for the status with spy_api_statut.

No website? The payment links in your merchant account do the same without a single line of code.

Keys

Every call carries two keys:

The platform's public key, in the apikey header. It is the same for everyone and can be seen by anyone:
Your secret key sk_…, in the request body (p_cle). Generate it in Developers. It is shown only once: keep it in an environment variable on your server, never in a web page or a mobile app.

Create a payment

POST /rest/v1/rpc/spy_api_creer

Parameter	Required	Description
`p_cle`	yes	Your secret key.
`p_montant`	yes	Amount to collect, in the given currency.
`p_devise`	no	ISO code (`XOF`, `XAF`, `EUR`…). Default: your account's currency.
`p_reference`	no	Your order number. It comes back in the status and the webhook.
`p_description`	no	Text shown to the customer on the payment page.
`p_retour_url`	no	`https://` address to send the customer back to after a successful payment.
`p_client_nom`, `p_client_email`, `p_client_tel`	no	Pre-fill the payment page.

Response:

The session stays open for 24 hours. The customer can try again as many times as needed until the first successful payment.

Redirect the customer

Send the customer to url. After a successful payment, if there is a p_retour_url, they are sent back to it with two parameters: ?sankipay_ref=SPY-…&statut=reussi.

Never deliver based on this return alone: anyone can type that address. Always confirm with the webhook or with spy_api_statut.

Check a payment

POST /rest/v1/rpc/spy_api_statut with p_cle and p_id: the session id, the SPY-… reference, or your own order reference.

The response contains session, paiement (amount, fee, net, method, country, status) and paye, which is true as soon as the order is paid.

Webhooks

Enter your webhook URL in Developers. For every successful or failed payment, SankiPay sends it a JSON POST:

Events: paiement.reussi, paiement.echoue, and test ("Send a test" button). The X-SankiPay-Signature header holds the hex HMAC-SHA256 of the raw body received, computed with your whsec_… signing secret. Check it before doing anything, then reply with a 2xx code.

Test mode

While the platform is in test mode, calls are identical but no money moves: on the payment page, the customer picks "success" or "decline" themselves. Test data stays separate from live data.

Errors

An error returns HTTP 400 with a message like {"code":"P0001","message":"SPY_CLE_INVALIDE"}.

Message	Meaning
`SPY_CLE_INVALIDE`	Secret key missing, wrong or replaced.
`SPY_MONTANT_INVALIDE`	Amount zero, negative or too large.
`SPY_DEVISE_INCONNUE`	Currency not handled by the platform.
`SPY_URL_INVALIDE`	The return address must start with https:// or http://.
`SPY_MARCHAND_SUSPENDU`	Your account is suspended: contact support.
`SPY_MARCHAND_NON_VERIFIE`	In live mode, your account must be verified (KYC).
`SPY_TROP_DE_TENTATIVES`	More than 120 creations per minute: slow down.
`SPY_PAIEMENT_INTROUVABLE`	No payment or session with this id on your account.