Checkout direct : construire un formulaire de carte personnalisé en quatre appels

Le checkout direct, c'est l'option qui vous laisse construire votre propre formulaire de carte au lieu de rediriger l'acheteur vers la page de paiement hébergée. Il tient en quatre appels — vérifier la session, soumettre la carte, confirmer le retour 3-D Secure, lire l'état du paiement —, authentifiés par la session et sa clé de vérification à usage unique, jamais par votre clé d'API. Il a un prix qu'il faut regarder en face : vos systèmes voient passer des données de carte et entrent dans le périmètre de conformité PCI DSS. Ce guide détaille quand il se justifie, comment l'intégrer pas à pas, et ce qu'il change pour vous.

Le checkout direct, en une définition

ChariPay est une plateforme de paiement marocaine, un PSP opéré par Chari Money, établissement de paiement agréé par Bank Al-Maghrib. Son API propose deux façons d'encaisser une carte à partir d'une session de paiement.

Le checkout direct vous laisse construire votre propre formulaire de carte : vérification de la session, envoi des données de carte, retour 3-D Secure, état du paiement. Ces appels ne sont pas authentifiés par votre clé d'API mais par la session et sa clé de vérification à usage unique (vk) — n'y envoyez jamais votre clé d'API — et ils vous placent dans le périmètre de conformité des données de carte.

La différence avec le checkout hébergé tient en deux phrases. Avec la page hébergée, vous redirigez l'acheteur vers une page tenue par ChariPay, où il saisit sa carte et passe 3-D Secure ; vous ne voyez jamais le numéro. Avec le checkout direct, c'est votre formulaire qui recueille la carte, et votre serveur qui exécute, de serveur à serveur, les quatre appels décrits plus bas.

Formulaire de carte personnalisé ou page hébergée : la grille de décision

Le checkout direct n'a de sens que si vous avez une raison précise de ne pas utiliser la page hébergée. Avant d'écrire une ligne de code, comparez point par point.

Si votre besoin est seulement d'afficher vos couleurs et votre logo, la page hébergée y répond déjà : la session de checkout reprend vos couleurs et votre logo. Les raisons qui justifient le checkout direct sont plus rares : un parcours de paiement entièrement intégré à votre produit, par exemple, et une équipe prête à porter la conformité qui va avec. Si vous hésitez encore entre lien de paiement et session, la comparaison est dans lien de paiement ou checkout ; pour une application iOS ou Android, l'architecture recommandée est décrite dans paiement dans une application mobile.

Vous gardez une raison précise ? Déroulez les quatre appels en sandbox avant de décider, et comparez avec la page hébergée dans le même compte : Commencer en mode test. Trois champs (nom, e-mail professionnel, entreprise), un lien d'activation reçu par e-mail pour choisir votre mot de passe, puis le portail, où vous créez vous-même votre clé de test après une ré-authentification ; la clé complète ne s'affiche qu'une seule fois. Payez avec la carte de test 4918 9141 0719 5005, CVV 123, n'importe quelle date d'expiration future, code 3-D Secure 555 : seule cette carte est acceptée, et aucun argent réel ne circule. C'est gratuit, sans limite de durée, sans validation à attendre.

Avant tout : une session créée par votre serveur

Le checkout direct ne remplace pas la session de paiement : il la consomme. Une commande devient une session : vous créez la session côté serveur, avec votre clé d'API, par POST /v1/payment-sessions — montant, orderId, coordonnées du client, URL de retour et de notification, metadata. La réponse (201, ou 200 au rejeu sur externalId) porte cinq champs, et rien d'autre :

{
  "sessionId": "ps_5Kd0Rn",
  "sessionToken": "st_…",
  "verifyKey": "vk_5Kd0Rn",
  "expiresAt": "2026-10-05T10:15:00Z",
  "checkoutUrl": "https://…/checkout/ps_5Kd0Rn"
}

Pour la page hébergée, vous redirigeriez l'acheteur vers checkoutUrl. Pour le checkout direct, vous en retenez deux valeurs : sessionId et verifyKey, que POST /checkout/verify attend sous le nom vk. Votre clé d'API reste sur votre serveur, et c'est lui aussi qui exécute les appels /checkout/*, de serveur à serveur : votre formulaire recueille la carte et la transmet à votre serveur. Chaque session a une durée de vie limitée — 72 heures par défaut, expiresAt pour la raccourcir — et n'est consommée qu'une seule fois, sauf si vous l'avez créée réutilisable (singleUse: false).

Les quatre appels, dans l'ordre

Le module « Checkout direct » de la documentation détaille chaque appel. Voici l'enchaînement, sur la base unique https://api-psp.charipay.ma.

1. 1Vérifier la session — POST /checkout/verify, avec sessionId et vk dans le corps. La réponse donne le contexte d'affichage : montant, devise, éléments de marque, expiration. Cet appel est obligatoire avant tout envoi de carte ; sur une session à usage unique, la vk est consommée par cette première vérification.
2. 2Soumettre la carte — POST /checkout/submit, avec sessionId et les données de carte. La réponse porte un operationId, une reference et un status : un statut final, ou PENDING_3DS accompagné d'une redirectionUrl.
3. 3Confirmer le retour 3-D Secure — POST /checkout/return, avec sessionId et l'operationId reçu à l'étape 2, une fois que l'acheteur a terminé l'authentification. La réponse donne le statut final et la redirectUrl d'acceptation ou de refus de votre session.
4. 4Lire l'état du paiement — GET /checkout/payments/{reference}, pour l'affichage. La réponse indique le status, paid, le montant et la devise, sans aucune donnée personnelle.

La vérification, en curl :

# No X-CHARI-PAY-API-KEY header: the session and its vk authenticate this call.
curl -X POST 'https://api-psp.charipay.ma/checkout/verify' \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId": "ps_5Kd0Rn",
    "vk": "vk_5Kd0Rn"
  }'

Nous ne publions volontairement aucun exemple d'appel submit : c'est celui qui transporte un numéro de carte, et il n'a sa place que dans un code dont vous maîtrisez la conformité.

Authentification : la session et la clé vk, jamais votre clé d'API

En checkout direct, c'est votre serveur qui exécute les appels /checkout/*, de serveur à serveur ; sur le checkout hébergé, c'est la page de paiement de ChariPay qui les exécute. Dans les deux cas, ils sont authentifiés par la session et sa vk, jamais par votre clé d'API : ils sont l'exception à la règle de l'en-tête X-CHARI-PAY-API-KEY. Une clé est un secret : jamais dans le navigateur, une application mobile, un dépôt git ou une capture d'écran.

Quand l'authentification de la session échoue, l'API répond 401 INVALID_TOKEN : vk invalide ou déjà consommée sur verify, ou envoi de carte sur une session qui n'a pas été vérifiée d'abord. Trois autres réponses relèvent du cycle de vie de la session :

• 410 SESSION_EXPIRED : la session a dépassé son expiresAt ; créez-en une nouvelle côté serveur.
• 409 SESSION_ALREADY_CONSUMED : la session a déjà été payée — ne la soumettez plus ; pour un nouveau paiement, créez une nouvelle session, et pour rendre l'argent, remboursez.
• 409 SESSION_NOT_ACTIVE : la session a été annulée — créez-en une nouvelle si la commande doit encore être payée.

Ce qui produit ces états — durée de vie, retour de l'acheteur, annulation — est expliqué dans expiration et retour d'une session de paiement.

Le retour 3-D Secure et la confirmation par webhook

Les paiements par carte passent par l'authentification 3-D Secure : le porteur confirme auprès de sa banque, ce qui protège le commerçant contre l'essentiel des impayés et des contestations. Avec le checkout direct, c'est à vous d'orchestrer ce moment.

1. 1submit répond PENDING_3DS avec une redirectionUrl : l'acheteur doit l'ouvrir pour s'authentifier auprès de sa banque.
2. 2Au retour de l'acheteur, votre serveur appelle POST /checkout/return avec le sessionId et l'operationId : il obtient le statut final et la redirectUrl à suivre.
3. 3Pour afficher le résultat, lisez GET /checkout/payments/{reference}.

Ce que voit le navigateur ne suffit pas à confirmer une commande. Confirmez la commande sur réception du webhook, jamais sur la seule redirection : la redirection dit que l'acheteur est revenu, pas que le paiement est acquis. Le webhook signé arrive sur votre endpoint de webhooks — et à l'URL de notification de la session si vous en avez déclaré une —, exactement comme pour la page hébergée. Retrouvez votre commande par votre metadata, renvoyé tel quel dans l'événement ; pour une session, l'événement porte aussi votre orderId.

Idempotence : ne jamais soumettre deux fois

Un double clic sur « Payer », une connexion qui coupe au mauvais moment, un utilisateur qui recharge la page : le checkout direct doit encaisser une seule fois quoi qu'il arrive. L'en-tête Idempotency-Key est requis sur POST /checkout/submit d'une session réutilisable (singleUse: false) et recommandé sur une session à usage unique. Rejouer la même valeur renvoie le premier résultat ; la même clé avec un corps différent répond 409 IDEMPOTENCY_CONFLICT. Sur une session réutilisable, une clé absente ou trop longue répond 400 INVALID_IDEMPOTENCY_KEY.

Trois règles pratiques :

• Une clé par tentative de paiement, générée quand l'acheteur valide le formulaire et conservée jusqu'à la réponse, pour être rejouée telle quelle après une coupure réseau.
• Un bouton désactivé dès le premier clic, jusqu'à la réponse de submit.
• Un rejeu, pas un nouvel envoi : après un 5xx, rejouez avec la même clé ; les 5xx sont de notre côté.

Toutes les erreurs suivent la même enveloppe :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount: must be greater than 0"
  },
  "correlationId": "b0c1e2d3-4f56-7890-abcd-ef0123456789"
}

Testez le code, jamais le message : le premier est stable, le second peut évoluer. Gardez le correlationId dans vos journaux, il permet de retrouver une requête précise avec l'équipe.

Ce que le checkout direct change pour PCI DSS

PCI DSS est le standard de sécurité des données de cartes publié par le PCI Security Standards Council, conçu, tel que le Conseil le décrit, pour renforcer la sécurité des données des comptes de cartes de paiement et favoriser une large adoption de mesures de sécurité des données cohérentes dans le monde entier. Le niveau 1 est le plus exigeant.

La plateforme est certifiée PCI DSS niveau 1, une certification renouvelée chaque année ; elle qualifie la plateforme, pas votre site. Avec la page hébergée, votre client saisit sa carte sur le checkout hébergé, dans un périmètre certifié PCI DSS niveau 1 : vous ne voyez jamais de numéro de carte, et votre questionnaire d'auto-évaluation s'en trouve réduit — à confirmer avec votre conseil ou votre acquéreur. Avec le checkout direct, la situation s'inverse : votre formulaire recueille la carte, vos systèmes la transmettent, et vous entrez dans le périmètre de conformité des données de carte. Les obligations qui en découlent sont les vôtres, à évaluer avec votre conseil avant la production.

Le détail de ce périmètre côté marchand est traité dans PCI DSS pour les commerçants.

Questions fréquentes

Qu'est-ce que le checkout direct ?

C'est la façon d'encaisser une carte avec votre propre formulaire, au lieu de rediriger l'acheteur vers la page hébergée. Quatre appels s'enchaînent : vérification de la session, envoi des données de carte, retour 3-D Secure, état du paiement. Ils sont authentifiés par la session et sa clé de vérification à usage unique, et ils vous placent dans le périmètre de conformité des données de carte.

Quelle différence entre le checkout direct et le checkout hébergé ?

Avec le checkout hébergé, l'acheteur saisit sa carte sur une page tenue par ChariPay, à vos couleurs, et vous ne voyez jamais le numéro. Avec le checkout direct, c'est votre formulaire qui recueille la carte et votre serveur qui exécute les quatre appels, de serveur à serveur, avec le retour 3-D Secure et les erreurs. Dans les deux cas, la commande se confirme sur le webhook signé.

Faut-il envoyer sa clé d'API aux appels du checkout direct ?

Non, jamais. Les endpoints /checkout/* sont authentifiés par la session et sa clé de vérification à usage unique, la vk, renvoyée sous le nom verifyKey à la création de la session. Dans ce parcours, votre clé d'API ne sert qu'à créer la session, côté serveur. Elle ne doit jamais apparaître dans un navigateur, une application mobile, un dépôt git ou une capture d'écran.

Le checkout direct supprime-t-il l'étape 3-D Secure ?

Non. Les paiements par carte passent par l'authentification 3-D Secure, que le formulaire soit le vôtre ou celui de la page hébergée. Quand la banque l'exige, submit répond PENDING_3DS avec une redirectionUrl que l'acheteur doit ouvrir ; à son retour, votre serveur appelle POST /checkout/return pour obtenir le statut final. Votre interface doit prévoir ce passage par la banque.

Le checkout direct change-t-il mes obligations PCI DSS ?

Oui. Votre formulaire recueille les données de carte et vos systèmes les transmettent : vous entrez dans le périmètre de conformité des données de carte. La certification PCI DSS niveau 1 qualifie la plateforme, pas votre site. Avec la page hébergée, votre questionnaire d'auto-évaluation est réduit ; avec le checkout direct, faites évaluer vos obligations par votre conseil avant la production.

Que se passe-t-il si le client clique deux fois sur « Payer » ?

Avec un Idempotency-Key sur POST /checkout/submit, le second envoi rejoue le premier résultat au lieu de payer deux fois ; la même clé avec un corps différent répond 409 IDEMPOTENCY_CONFLICT. L'en-tête est requis sur une session réutilisable et recommandé sinon. Une session déjà payée répond 409 SESSION_ALREADY_CONSUMED. Désactivez aussi le bouton dès le premier clic.

Que signifie l'erreur 401 INVALID_TOKEN sur le checkout direct ?

Que la session n'a pas pu être authentifiée. Sur POST /checkout/verify, la vk est invalide ou déjà consommée — sur une session à usage unique, elle ne sert qu'une fois. Sur POST /checkout/submit, la session n'a pas été vérifiée au préalable. Vérifiez l'ordre des appels et la valeur transmise, ou créez une nouvelle session côté serveur.

Prochaine étape

Essayez d'abord la page hébergée, qui reprend déjà vos couleurs et votre logo, puis le checkout direct en sandbox avec la carte de test : Commencer en mode test. Si vous retenez le checkout direct, faites valider votre périmètre PCI DSS par votre conseil avant la production. Le module « Checkout direct » de la documentation et PCI DSS pour les commerçants vous accompagnent pour la suite.

Sources

• PCI Security Standards Council — PCI DSS — lu le 2026-10-02