Journal des changements
Ce qui change dans l’API et les webhooks, daté. Les changements de /v1 restent additifs : une rupture ouvrirait /v2.
Le paiement direct
- POST /v1/payments accepte « payer » : la demande part aussitôt sur le téléphone du payeur, sans page de Payiz. Il faut le geste « Paiements · lancer » et un en-tête Idempotency-Key.
- POST /v1/payments/{id}/attempts lance ou relance la demande après un échec ; GET sur le même chemin liste les demandes. Une seule à la fois : sinon attempt_in_progress.
- Chaque paiement porte latest_attempt, un objet payment_attempt (préfixe tnt_) : qui l’a lancée (source), la raison d’un échec (failure_code) et la phrase à montrer au payeur (payer_message).
- GET /v1/payment_methods donne les opérateurs ouverts pour un montant : leur code, leur logo servi par Payiz, leurs bornes et les frais.
- En réel, le direct s’ouvre avec le palier de l’espace ; sinon l’appel répond direct_not_enabled.
- Les SDK passent en 0.2.0 : payments.attempts, paymentMethods, disputes, conversions ; une erreur porte details et requestId ; un appel qui touche un téléphone exige sa clé d’idempotence. En PHP, le code de l’erreur se lit dans $e->errorCode.
Les erreurs et l’idempotence
- Un registre de codes stables, sur la page « Les erreurs » et dans l’OpenAPI : un code ne se retire plus sans passer par ici.
- Chaque erreur porte request_id (aussi dans l’en-tête Request-Id), et details quand le code en a — les opérateurs possibles, les bornes d’un montant.
- Le message suit Accept-Language : français ou anglais.
- Idempotency-Key devient obligatoire quand l’appel touche un téléphone (idempotency_key_required). Passé le point de non-retour, plus jamais de 5xx : l’objet se rend tel qu’il est.
- Trop d’appels d’une clé dans la minute : 429 rate_limited, avec Retry-After.
Webhooks et lectures
- data.object porte l’objet public, le même qu’une lecture de l’API au même instant.
- Trois événements : dispute.created, dispute.closed et conversion.completed. Le catalogue vit dans le contrat, et dans la section webhooks de l’OpenAPI.
- GET /v1/disputes et GET /v1/conversions, en lecture.
- operator vaut un code court et public, propre au pays : mtn, moov, orange.
La fin de la clé publique
- Les clés pk_ n’existent plus. Une page sans serveur ouvre un lien de paiement dans le widget, sans aucune clé : le prix vit dans l’espace.
Le widget et les SDK
- Le widget ouvre la page de paiement dans un voile, sur le site du marchand : <script src="https://pay.payiz.app/payiz.js"></script>, puis Payiz.ouvrir(…).
- Chaque paiement porte un client_secret, rendu à sa création : de quoi laisser une page sans serveur suivre ce paiement-là, et rien d’autre.
- GET /v1/widget/payments/{id}?client_secret=… donne l’état d’un paiement sans clé secrète, en lecture seule et réduit.
- Les SDK Node (npm : payiz) et PHP (composer : payiz/payiz-php) parlent les mêmes noms que l’API, posent l’idempotence d’office et reprennent les pannes passagères.
- Une page de Payiz ne s’encadre plus, sauf celle d’un paiement en mode widget.
Les ressources de /v1
- Les paiements, les remboursements, les liens de paiement, le solde, les bénéficiaires et les retraits s’appellent maintenant par l’API.
- Chaque liste se pagine par curseur : limit (100 au plus) et starting_after, avec data et has_more.
- L’en-tête Idempotency-Key est honoré sur chaque POST : rejouée, la même clé rend la première réponse, avec Idempotent-Replayed: true. Gardée 24 h ; la même clé avec un autre corps répond 409.
- Les dates sortent en secondes depuis 1970, et les montants restent des entiers dans l’unité mineure de la devise.
- GET /v1/refund_reasons donne les motifs de remboursement acceptés : ils se règlent, ne les écrivez pas en dur.
- Un geste fait par une clé apparaît au journal d’audit comme tel, et non au nom de quelqu’un.
Journaux des requêtes
- Chaque appel fait avec une clé s’inscrit dans Développeurs › Journaux, avec son corps, sa réponse et sa durée, gardé 30 jours.
- Les numéros des payeurs et les secrets y sont masqués avant d’être écrits.
Webhooks
- Les destinations se déclarent dans Développeurs › Webhooks, avec les événements voulus et un secret de signature.
- Chaque envoi porte l’en-tête Payiz-Signature (t et v1), sur le corps brut.
- Un échec se retente : 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, puis toutes les 24 h.
- Huit événements : payment.succeeded, payment.attempt_failed, payment.expired, payment.canceled, refund.succeeded, refund.failed, payout.paid, payout.failed.
Clés d’API
- Les clés secrètes et publiques se créent dans Développeurs › Clés API, avec leurs droits et, au besoin, les adresses IP autorisées.
- L’API s’authentifie par « Authorization: Bearer sk_… » ; GET /v1/account dit qui parle.
- Un renouvellement laisse l’ancienne clé valable 24 h ; une révocation la ferme tout de suite.
© 2026 PayizUne question ? L’aide est dans le rond, en bas à droite.