Démarrage
Xenos Pay permet à un site d'encaisser par carte sans jamais manipuler de numéro de carte. Votre site crée un paiement, redirige le client vers la page de paiement hébergée, puis reçoit la confirmation par webhook.
- Créer un paiementVotre serveur appelle l'API avec le montant et reçoit une adresse
checkout_url. - Rediriger le clientLe client saisit sa carte sur la page hébergée.
- Confirmer la commandeVotre serveur reçoit l'événement
payment.succeededet valide la commande.
Authentification
Chaque commerçant crée ses clés dans Clés API. La clé secrète commence par sk_test_ et s'envoie dans l'en-tête Authorization. Elle ne doit jamais apparaître dans le code d'une page web ni dans une application mobile.
Authorization: Bearer sk_test_votre_cleAdresse de base de l'API : https://srv2176870.hstgr.cloud/v1. Les montants sont des entiers en centimes (4990 pour 49,90 €).
Créer un paiement
cURL
curl https://srv2176870.hstgr.cloud/v1/payments \
-H "Authorization: Bearer sk_test_votre_cle" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commande-1042" \
-d '{
"amount": 4990,
"currency": "EUR",
"description": "Commande 1042",
"order_ref": "1042",
"customer_email": "client@exemple.com",
"success_url": "https://votresite.com/merci",
"cancel_url": "https://votresite.com/panier",
"metadata": { "panier": "A17" }
}'PHP
<?php
$ch = curl_init('https://srv2176870.hstgr.cloud/v1/payments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XENOS_SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 4990,
'currency' => 'EUR',
'description' => 'Commande 1042',
'success_url' => 'https://votresite.com/merci',
]),
]);
$payment = json_decode(curl_exec($ch), true);
header('Location: ' . $payment['checkout_url']);Node.js
const res = await fetch('https://srv2176870.hstgr.cloud/v1/payments', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.XENOS_SECRET_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount: 4990, currency: 'EUR', description: 'Commande 1042', success_url: 'https://votresite.com/merci' }),
});
const payment = await res.json();
// Redirigez ensuite le client vers payment.checkout_urlPython
import os, requests
r = requests.post('https://srv2176870.hstgr.cloud/v1/payments',
headers={'Authorization': 'Bearer ' + os.environ['XENOS_SECRET_KEY']},
json={'amount': 4990, 'currency': 'EUR', 'description': 'Commande 1042',
'success_url': 'https://votresite.com/merci'})
checkout_url = r.json()['checkout_url']Site HTML sans serveur
Pour un site statique, créez un lien de paiement à montant fixe dans votre espace, puis collez l'un de ces deux codes dans la page.
Lien simple
<a href="https://srv2176870.hstgr.cloud/l/lnk_votre_lien">Payer 49,90 €</a>Bouton prêt à l'emploi
<script src="https://srv2176870.hstgr.cloud/static/bouton.js"
data-lien="lnk_votre_lien"
data-texte="Payer 49,90 €"></script>Le montant est fixé côté plateforme : il ne peut pas être modifié depuis la page du site.
Retour du client
Après un paiement réussi, le client est renvoyé vers success_url avec deux paramètres : payment_id et status. Cette redirection sert à afficher une page de remerciement. Pour valider une commande, fiez-vous au webhook ou relisez le paiement par l'API, jamais aux seuls paramètres de l'adresse.
Webhooks
Déclarez l'adresse de votre serveur dans Webhooks. À chaque événement, la plateforme envoie une requête POST en JSON. Répondez avec un code 2xx en moins de 10 secondes. En cas d'échec, l'envoi est retenté 5 fois (10 s, 1 min, 5 min, 30 min, 2 h).
Événements
payment.created payment.succeeded payment.failed payment.refunded payment.canceled payment.expired
Corps de la requête
{
"id": "evt_5f2c...",
"type": "payment.succeeded",
"created_at": 1767225600,
"test": true,
"data": { "payment": { "id": "pay_9a1b...", "amount": 4990, "currency": "EUR", "status": "succeeded", "order_ref": "1042" } }
}Vérifier la signature
L'en-tête X-Webhook-Signature vaut t=horodatage,v1=signature. La signature est le HMAC SHA256, avec le secret du point de terminaison, de la chaîne horodatage.corps_brut. Refusez les requêtes dont l'horodatage a plus de 5 minutes.
// Node.js
const crypto = require('crypto');
function verifier(corpsBrut, entete, secret) {
const parts = Object.fromEntries(entete.split(',').map((p) => p.split('=')));
const attendu = crypto.createHmac('sha256', secret).update(parts.t + '.' + corpsBrut).digest('hex');
const recent = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return recent && attendu.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(parts.v1));
}<?php // PHP
$corps = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE']), $s);
$attendu = hash_hmac('sha256', $s['t'] . '.' . $corps, getenv('XENOS_WEBHOOK_SECRET'));
if (abs(time() - (int) $s['t']) > 300 || !hash_equals($attendu, $s['v1'])) { http_response_code(400); exit; }
$evenement = json_decode($corps, true);
http_response_code(200);Référence API
POST/v1/payments Crée un paiement.
| Champ | Type | Description |
|---|---|---|
amount | entier, obligatoire | Montant en centimes. |
currency | texte, obligatoire | EUR, USD, GBP, CHF ou CAD. |
description | texte | Affichée au client sur la page de paiement. |
order_ref | texte | Votre numéro de commande. |
customer_email | texte | Préremplit l'email du client. |
success_url | URL | Retour après paiement réussi. |
cancel_url | URL | Lien « annuler » de la page de paiement. |
metadata | objet | Données libres, renvoyées telles quelles. |
L'en-tête facultatif Idempotency-Key évite de créer deux paiements si la même requête est rejouée.
GET/v1/payments/:id Relit un paiement.
GET/v1/payments Liste les paiements. Paramètres : limit, status, order_ref, starting_after.
POST/v1/payments/:id/refund Rembourse en totalité, ou en partie avec amount.
POST/v1/payments/:id/cancel Annule un paiement non réglé.
Statuts d'un paiement
pending en attente · succeeded réussi · failed dernière tentative refusée, nouvel essai possible · refunded remboursé en totalité · canceled annulé · expired non réglé après 24 heures.
Cartes de test
Utilisez une date d'expiration future et un cryptogramme quelconque.
| Numéro | Réseau | Résultat |
|---|---|---|
| 4242 4242 4242 4242 | Visa | Paiement accepté (risque faible) visa_ok |
| 5555 5555 5555 4444 | Mastercard | Paiement accepté (risque faible) mc_ok |
| 4000 0000 0000 3220 | Visa | Authentification 3D Secure demandée par la banque visa_3ds |
| 4000 0000 0000 0077 | Visa | Paiement en attente, confirmé ensuite visa_async |
| 4000 0000 0000 4954 | Visa | Risque modéré : contrôle 3D Secure imposé visa_elevated |
| 4000 0007 6000 0002 | Visa | Risque élevé : mise en attente pour examen visa_br_elevated |
| 4100 0000 0000 0019 | Visa | Fraude signalée : blocage immédiat visa_fraud |
| 4000 0000 0000 9979 | Visa | Carte volée : blocage immédiat visa_stolen |
| 4000 0000 0000 0002 | Visa | Carte refusée visa_declined |
| 4000 0000 0000 9995 | Visa | Fonds insuffisants visa_nsf |
| 4000 0000 0000 0069 | Visa | Carte expirée visa_expired |
| 4000 0000 0000 0119 | Visa | Erreur de traitement visa_error |
Erreurs
L'API répond avec les codes HTTP usuels : 400 requête invalide, 401 clé absente ou invalide, 403 compte suspendu, 404 ressource introuvable, 429 trop de requêtes.
{
"error": {
"type": "invalid_request_error",
"code": "invalid_parameter",
"param": "amount",
"message": "amount doit être un entier en centimes, entre 50 et 99999999."
}
}