Commandes, paiements et remboursements

De la réservation à la commande payée

1. L'acheteur réserve des places sur le site, puis donne un nom et un e-mail, choisit un moyen de paiement et accepte les conditions. Aucun compte n'est nécessaire.
2. L'API transforme la réservation en commande (une référence comme TKT-1042) en Awaiting payment, avec les montants de la réservation. Le navigateur n'envoie jamais de prix.
3. L'acheteur paie sur la page propre du fournisseur. Les données de carte ne sont jamais saisies sur votre site.
4. Le fournisseur confirme, et l'API émet un billet par place, marque la commande Paid, envoie les billets par e-mail et prévient l'équipe. Chaque e-mail concernant la commande est dans la langue de la page du site sur laquelle l'acheteur a payé, anglais ou arabe, avec le titre de l'événement dans cette langue.

Le site ne décide jamais qu'une commande est payée. Pendant que l'acheteur attend sur « Confirming your payment », l'API interroge elle-même le fournisseur : un paiement devient donc des billets même sur un ordinateur portable que le webhook du fournisseur ne peut pas joindre. Un paiement annulé garde la réservation pour un nouvel essai ; un paiement échoué garde les informations de l'acheteur.

Moyens de paiement

• Chaque fournisseur est proposé dès que ses clés sont définies. Utilisez d'abord des clés de test (sk_test_..., le bac à sable PayPal) : elles ne déplacent aucun argent.
• Avec PAYMENTS_SIMULATOR=auto, Test payment est proposé tant qu'aucune clé de production n'est définie : une installation neuve peut donc vendre un billet aussitôt, et une boutique en production ne l'affiche jamais.
• Paramètres, Paiements dans le tableau de bord affiche chaque fournisseur comme connecté, en mode test ou non configuré, avec les variables à définir et l'adresse de son webhook. Les clés ne sont jamais saisies dans le tableau de bord.

Webhooks

Avant la mise en ligne, enregistrez le webhook chez chaque fournisseur avec l'adresse publique de votre API :

Chaque appel est vérifié avec la signature du fournisseur avant toute autre chose, et chaque événement n'est traité qu'une fois, quel que soit le nombre de fois où il arrive. Définissez STOREFRONT_URL avec l'adresse du site, où les pages de paiement renvoient les acheteurs, et PUBLIC_API_URL avec celle de l'API, pour le retour de PayPal.

• Liste de contrôle du déploiement

Billets gratuits

Un type de billet à 0 ne porte aucun frais. Quand une commande ne coûte rien, le paiement n'affiche aucun moyen de paiement, le total indique Free, et Get tickets confirme aussitôt la commande, avec ses billets, son e-mail et la notification de l'équipe, avec ou sans clés de paiement. Aucun fournisseur n'est sollicité, pas même le paiement de test.

Une commande gratuite affiche « Free » comme fournisseur. Elle n'a rien à rembourser : ses billets sont annulés à la place. Creative Mornings, dans les données d'exemple, est un événement gratuit, et Meadow Days vend des billets gratuits pour les enfants de moins de 12 ans.

Les frais de réservation et la taxe

• Les frais de réservation sont un pourcentage du prix de chaque billet, arrondi une fois par billet et ajouté au total du participant au paiement : le participant les paie toujours. Ils se règlent dans Paramètres, Général, de 0 à 20 % (fee_bps, 300 ou 3 % dans les données d'exemple : deux places à 20,00 $ font 41,20 $).
• La devise est celle de l'espace de travail (USD dans les données d'exemple), choisie dans le même onglet parmi USD, EUR, GBP, SAR et AED, et elle se verrouille dès que le premier billet est payé.
• Ticketory ne prélève aucune taxe. Configurez la fiscalité de votre pays avant d'encaisser de vrais paiements. Les frais des fournisseurs de paiement sont distincts.

Statuts de commande

La page des commandes

• Des tuiles Payées, En attente, Remboursées et Échouées avec leurs nombres, une recherche par référence de commande, nom ou e-mail, et des filtres par événement, statut de paiement (Payée, Gratuite, En attente, Remboursée, Échouée, En vérification) et période. Les plus récentes d'abord, dix par page, avec Export CSV.
• La page d'une commande affiche ses détails, la chronologie du paiement avec un lien vers le tableau de bord propre de Stripe ou de PayPal, ses billets avec Reissue, Void et Refund, et ses remboursements.

Remboursements

1. Les remboursements portent sur des billets entiers. Sélectionnez les billets sur la page de la commande et appuyez sur Refund : le montant (le prix de chaque billet et ses frais) est calculé par l'API, jamais saisi. Choisissez un motif et cochez que le remboursement révoque l'entrée.
2. Les billets sont suspendus aussitôt, personne n'est donc admis avec eux, et le remboursement est pending tant que le fournisseur ne l'a pas confirmé.
3. Une fois confirmé, les billets sont annulés, leurs places repartent en vente (sauf si le titulaire était déjà entré), la commande devient partiellement remboursée ou remboursée, et l'acheteur reçoit un e-mail dans la langue de la commande.

Si le fournisseur refuse ou ne répond jamais, le remboursement est failed et les billets restent suspendus jusqu'à ce que quelqu'un décide : Retry refund le renvoie avec la même clé fournisseur, il ne peut donc jamais payer deux fois, et Restore admission rend aux billets leur droit d'entrée sans aucun mouvement d'argent. Une commande payée avec le paiement de test est remboursée de la même façon, sans argent déplacé ; les remboursements des commandes d'exemple se règlent quelques secondes après leur demande.

Un événement annulé envoie un e-mail à ses acheteurs mais ne déplace aucun argent : remboursez chacune de ses commandes depuis sa page.

Qui peut faire quoi

Les routes derrière tout cela

• GET /api/checkout/methods liste ce qui est proposé à l'instant ; POST /api/checkout exige le X-Hold-Token de la réservation et un Idempotency-Key et répond avec la référence de commande, la page du fournisseur et un jeton d'accès à la commande, envoyé ensuite comme X-Order-Token.
• Une référence de commande seule n'ouvre rien : l'acheteur lit une commande avec ce jeton ou avec le jeton bearer du participant.
• POST /api/admin/orders/:reference/refunds exige un Idempotency-Key et la version de la commande ; une version plus ancienne donne un 409 VERSION_CONFLICT. Une commande gratuite répond refund_nothing_left.

• Référence de l'API