Migrer de la v2 à la v3

Rien ne vous oblige à migrer maintenant

Les routes v2 (init-payment, GET /payments/{paymentId}) restent servies telles quelles : même URL, même en-tête x-api-key, mêmes champs, mêmes codes d'erreur. Quand votre organisation passe sur la nouvelle plateforme, la v2 est servie directement par elle ; avant, elle est relayée vers la plateforme actuelle. Vous n'avez rien à faire, et les plugins ne demandent aucune mise à jour.

Ce que la v3 apporte

Sujet	v2	v3 (prévu)
Authentification	x-api-key: <organisationId>:<secret>	même en-tête x-api-key, nouvelles clés kpk_<prefix>:<secret> ; les clés actuelles restent valides
Destinataire	receiverWalletId	paymentAccountId : un compte d'encaissement de l'organisation
Moyens de paiement	acceptedPaymentMethods (bank_card, e-DINAR, flouci)	codes de prestataire du catalogue (clictopay, flouci, izi, mpgs_poste, pluxee)
Devise	token	currency
Statut	pending, completed, ...	pending, succeeded, failed, expired, canceled, refunded
Tentatives	transactions[]	attempts[] avec le prestataire et sa référence
Webhook	GET non signé avec payment_ref	POST JSON signé en HMAC (voir Webhooks)
Rejeu	non	Idempotency-Key
Erreurs	{ errors } ou { message }	{ error, message } avec un code stable
Client Node	fetch	@konnect/sdk, typé depuis l'OpenAPI

Dans quel ordre migrer

1. Webhooks d'abord. Déclarez une URL v3, vérifiez la signature, et gardez votre webhook v2 en parallèle. Les deux peuvent coexister.
2. Lecture ensuite. Lisez vos paiements en v3 ; la référence d'un paiement créé en v2 reste lisible en v2.
3. Création en dernier. Basculez init-payment vers la création v3 avec une Idempotency-Key, compte d'encaissement par compte d'encaissement.
4. Retirez la v2 de votre code quand plus aucun paiement v2 n'est en cours (après la durée de vie maximale, 60 minutes).

Correspondance des statuts

v2	v3
pending	pending
completed	succeeded
failed	failed
expired	expired
canceled	canceled
refunded	refunded
partial	pending avec un montant restant dû