Xenos Pay
Documentation

Intégrez le paiement en quelques minutes.

Tout ce qu'il faut pour créer un paiement, rediriger le client vers la page hébergée et recevoir la confirmation sur votre serveur.

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.

  1. Créer un paiementVotre serveur appelle l'API avec le montant et reçoit une adresse checkout_url.
  2. Rediriger le clientLe client saisit sa carte sur la page hébergée.
  3. Confirmer la commandeVotre serveur reçoit l'événement payment.succeeded et valide la commande.
La plateforme fonctionne aujourd'hui en environnement de test : les transactions sont simulées et seules les cartes de test sont acceptées.

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.

HTTP
Authorization: Bearer sk_test_votre_cle

Adresse 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
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
<?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

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_url

Python

Python
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

HTML
<a href="https://srv2176870.hstgr.cloud/l/lnk_votre_lien">Payer 49,90 €</a>

Bouton prêt à l'emploi

HTML
<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

JSON
{
  "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
// 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 // 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.

ChampTypeDescription
amountentier, obligatoireMontant en centimes.
currencytexte, obligatoireEUR, USD, GBP, CHF ou CAD.
descriptiontexteAffichée au client sur la page de paiement.
order_reftexteVotre numéro de commande.
customer_emailtextePréremplit l'email du client.
success_urlURLRetour après paiement réussi.
cancel_urlURLLien « annuler » de la page de paiement.
metadataobjetDonné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éroRéseauRésultat
4242 4242 4242 4242VisaPaiement accepté (risque faible) visa_ok
5555 5555 5555 4444MastercardPaiement accepté (risque faible) mc_ok
4000 0000 0000 3220VisaAuthentification 3D Secure demandée par la banque visa_3ds
4000 0000 0000 0077VisaPaiement en attente, confirmé ensuite visa_async
4000 0000 0000 4954VisaRisque modéré : contrôle 3D Secure imposé visa_elevated
4000 0007 6000 0002VisaRisque élevé : mise en attente pour examen visa_br_elevated
4100 0000 0000 0019VisaFraude signalée : blocage immédiat visa_fraud
4000 0000 0000 9979VisaCarte volée : blocage immédiat visa_stolen
4000 0000 0000 0002VisaCarte refusée visa_declined
4000 0000 0000 9995VisaFonds insuffisants visa_nsf
4000 0000 0000 0069VisaCarte expirée visa_expired
4000 0000 0000 0119VisaErreur 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.

JSON
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "amount",
    "message": "amount doit être un entier en centimes, entre 50 et 99999999."
  }
}