Le fonctionnement des paiements

Chaque paiement, par carte ou en espèces, est une intention de paiement (payment intent) : un objet pour un montant à encaisser, de sa création jusqu’à l’argent reçu. Vous la créez vous-même, ou une session de paiement ou un lien de paiement la crée pour vous. Son status dit où elle en est ; votre code le lit au lieu de le deviner.

Intentions de paiement et tentativesCopier le lien de la section

Une intention de paiement peut être tentée plusieurs fois. Chaque essai est une tentative, aussi appelée charge (ch_…) : une page de paiement par carte ouverte, ou un code espèces émis. Une carte refusée ou un code expiré termine la tentative, pas l’intention de paiement : votre client peut réessayer, avec le même moyen ou un autre.

• Le latest_charge de l’intention nomme sa tentative la plus récente.
• Une intention de paiement réussit une seule fois. Même si une confirmation nous parvient plusieurs fois, il y a un seul succès, un seul événement payment_intent.succeeded et une seule écriture dans votre solde.
• amount_received est fixé quand le paiement réussit ; amount_refunded augmente à chaque remboursement.

Le cycle de vieCopier le lien de la section

Un paiement par carte confirmé tout de suite peut aussi passer directement de requires_action à succeeded.

Chaque statut, et que faireCopier le lien de la section

Quand quelque chose ne colle pasCopier le lien de la section

Si un paiement est confirmé pour un autre montant que celui demandé, ou si de l’argent arrive après l’annulation du paiement ou l’expiration de son code, rien n’est crédité automatiquement. L’intention de paiement reste en processing et reçoit un objet review, avec reason à amount_mismatch ou paid_after_end, et vous recevez review.opened. Une personne de notre équipe l’examine. Dans le bac à sable, les scénarios espèces permettent de déclencher les deux.

TentativesCopier le lien de la section

Le status d’une tentative vaut pending, succeeded, failed, canceled ou expired. Une tentative échouée porte failure_code et failure_message, et l’intention les recopie dans last_payment_error :

Une tentative a une durée de vie limitée : environ 30 minutes pour une page de paiement par carte, et l’échéance du code pour les espèces (environ trois jours). Une tentative arrivée à son terme finit expired.

Actions suivantesCopier le lien de la section

Tant qu’une intention de paiement est en requires_action, son next_action dit ce que votre client doit faire. Avec la page hébergée ou un lien de paiement, vous ne le lisez jamais : nos pages s’en chargent. Avec votre propre page :

• form_post, pour une carte : une adresse et des champs que le navigateur de votre client envoie pour atteindre la page de paiement par carte.
• display_voucher, pour les espèces : le code, l’amount_to_pay (votre montant plus un petit droit de timbre payé par votre client), expires_at, un slip_url imprimable, et hosted_voucher_url, notre page du bon.

Montants et deviseCopier le lien de la section

• Chaque montant est un entier en centimes : 25000 vaut 250,00 MAD. N’envoyez jamais de décimales.
• currency vaut toujours mad, en minuscules.
• Un paiement en espèces vaut au moins 100,00 MAD (10000) ; un paiement par carte au moins 1,00 MAD (100). Un montant inférieur est refusé avec amount_too_small, en mode test comme en production.

Redirections et webhooks : auquel se fierCopier le lien de la section

Votre client revient sur votre success_url après avoir payé, mais ce retour ne prouve rien : il peut fermer l’onglet avant, un paiement en espèces se fait des jours plus tard chez un agent, et n’importe qui peut taper l’adresse.

Livrez sur l’un de ces deux signaux seulement :

1. le webhook payment_intent.succeeded, avec une signature vérifiée ;
2. l’intention de paiement lue dans l’API, avec votre clé secrète, qui montre status: "succeeded".

Servez-vous du retour pour remercier votre client et afficher « Nous confirmons votre paiement » ; laissez ensuite le webhook faire le reste.

RemboursementsCopier le lien de la section

Un paiement par carte réussi peut être remboursé, en totalité ou en partie, tant que le total remboursé ne dépasse pas le montant reçu. Un remboursement est pending, puis succeeded, failed ou canceled. Un paiement en espèces ne peut pas être remboursé par AdProMaxPay : l’argent a été remis en espèces, et il n’y a pas de carte sur laquelle le rendre. Réglez-le directement avec votre client. Voir Remboursements.

Les événements que vous recevezCopier le lien de la section

La liste complète est dans Webhooks.