4 endpoints
Sessions de paiement
Une commande e-commerce devient une session : vous redirigez l'acheteur vers le checkout hébergé et vous récupérez le résultat.
Les intitulés et descriptions d'endpoints viennent du contrat OpenAPI, en anglais — ils ne peuvent pas diverger de l'API.
En clair
Le paiement intégré à votre site : une commande, une session.
Quand l'utiliser
Pour un site marchand ou une application où le paiement s'inscrit dans un tunnel de commande, avec une URL de retour et une URL d'annulation qui vous appartiennent. Une session expire par défaut 72 heures après sa création — `expiresAt` pour la raccourcir.
Comment l'intégrer
- 1Créez la session avec le montant et votre référence de commande — vos URL de retour sont optionnelles : sans elles, les valeurs par défaut de votre compte s'appliquent.
- 2Redirigez l'acheteur vers l'URL de checkout renvoyée.
- 3À son retour, affichez un état d'attente — la redirection dit que l'acheteur est revenu, pas que le paiement est acquis.
- 4Confirmez la commande sur réception du webhook, jamais sur la seule redirection.
Carte de test sandbox
La sandbox tourne sur de vrais rails, contre un environnement de test : les parcours sont réels, l'argent non. Une seule carte y est acceptée.
Seul ce PAN est accepté. Tout autre numéro — y compris les 4242… d'autres plateformes — est rejeté en amont — en général avec un 502 — et le code stable BAAS_CHARI_ERROR. Si vous rencontrez cette erreur en test, vérifiez d'abord la carte saisie.
- POST
/v1/payment-sessions/{sessionId}/cancelAnnuler une session de paiement - GET
/v1/payment-sessionsLister les sessions de paiement - POST
/v1/payment-sessionsCréer une session de paiement - GET
/v1/payment-sessions/{sessionId}Récupérer une session de paiement
Annuler une session de paiement
Fait expirer la session afin qu'elle ne puisse plus être payée. Renvoie le statut mis à jour de la session.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
sessionId | string | path | Requis |
Lister les sessions de paiement
Renvoie les sessions de paiement de l'appelant pour l'environnement de la clé, les plus récentes en premier. Filtrez éventuellement par origine de création avec ?origin=API ou ?origin=DASHBOARD.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
origin | enum | query | Optionnel | Filtrer par origine de création (API ou DASHBOARD).Valeurs APIDASHBOARD |
pageable | Pageable | query | Requis |
Créer une session de paiement
Crée une session de paiement à usage unique pour une commande et renvoie son checkoutUrl hébergé. Fournissez un externalId facultatif, défini par vos soins (unique par marchand), pour rendre la création idempotente : un externalId en doublon renvoie la session existante avec 200 OK. Passez un en-tête Idempotency-Key facultatif pour sécuriser les nouvelles tentatives.
Schéma · CreateCheckoutSessionRequest
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
Idempotency-Key | string | header | Optionnel | Clé d'idempotence facultative ; rejouer la même valeur renvoie le premier résultat. |
amount | number | body | Requis | Montant à encaisser, en MAD (unité principale). |
orderId | string | body | Requis | Votre référence de commande ou référence métier pour ce checkout. |
singleUse | boolean | body | Optionnel | Session à usage unique (recommandé). Vaut true par défaut. |
externalId | string | body | Optionnel | Identifiant facultatif fourni par vos soins, unique par marchand ; une valeur en doublon rejoue la session existante. Distinct de orderId/externalReference, dont l'unicité n'est pas imposée. |
config | CheckoutSessionConfig | body | Requis | Acheteur, URL de redirection et options du checkout. |
config.customer | CheckoutSessionCustomer | body | Requis | L'acheteur débité. |
config.urls | CheckoutSessionUrls | body | Optionnel | URL de redirection / de notification facultatives. Tout champ non renseigné reprend la valeur par défaut configurée par le marchand, puis celle de la plateforme. |
config.keepAlive | boolean | body | Optionnel | Maintient la session active après une tentative échouée afin que l'acheteur puisse réessayer. Vaut false par défaut. |
config.frontend | CheckoutSessionFrontend | body | Optionnel | Personnalisation visuelle facultative de la page de checkout hébergé. |
config.settlement | CheckoutSessionSettlement | body | Optionnel | Répartition facultative — wallet du sous-marchand à créditer. |
metadata | object | body | Optionnel | Objet de métadonnées libre (≤ 4 Ko) renvoyé tel quel dans le webhook de paiement. |
expiresAt | string (date-time) | body | Optionnel | Expiration de la session (ISO-8601 UTC). Doit être dans le futur ; par défaut 72 h après la création. |
notifyOnFailure | boolean | body | Optionnel | Envoyer aussi un webhook payment.failed en cas d'échec du paiement. Vaut false par défaut. |
Récupérer une session de paiement
Récupère le statut actuel, le montant et l'expiration d'une session à partir de son identifiant.
| Champ | Type | Emplacement | Requis | Description |
|---|---|---|---|---|
sessionId | string | path | Requis | Identifiant de session. |
Une question sur l'intégration ?
Notre équipe technique répond aux intégrateurs, du premier appel en sandbox jusqu'à la mise en production.