Migrating from v2 to v3

Nothing forces you to migrate now

The v2 routes (init-payment, GET /payments/{paymentId}) keep being served as they are: same URL, same x-api-key header, same fields, same error codes. When your organisation moves to the new platform, v2 is served by it directly; before that, it is relayed to the current platform. You have nothing to do, and the plugins need no update.

What v3 brings

Topic	v2	v3 (planned)
Authentication	x-api-key: <organisationId>:<secret>	same x-api-key header, new keys kpk_<prefix>:<secret>; current keys keep working
Recipient	receiverWalletId	paymentAccountId: one payment account of the organisation
Payment methods	acceptedPaymentMethods (bank_card, e-DINAR, flouci)	provider codes of the catalogue (clictopay, flouci, izi, mpgs_poste, pluxee)
Currency	token	currency
Status	pending, completed, ...	pending, succeeded, failed, expired, canceled, refunded
Attempts	transactions[]	attempts[] with the provider and its reference
Webhook	unsigned GET with payment_ref	JSON POST signed with HMAC (see Webhooks)
Replay	no	Idempotency-Key
Errors	{ errors } or { message }	{ error, message } with a stable code
Node client	fetch	@konnect/sdk, typed from the OpenAPI

In which order to migrate

1. Webhooks first. Declare a v3 URL, verify the signature, and keep your v2 webhook alongside. Both can coexist.
2. Reads next. Read your payments in v3; the reference of a payment created in v2 stays readable in v2.
3. Creation last. Switch init-payment to the v3 creation with an Idempotency-Key, one payment account at a time.
4. Remove v2 from your code once no v2 payment is in flight (after the maximum lifespan, 60 minutes).

Status mapping

v2	v3
pending	pending
completed	succeeded
failed	failed
expired	expired
canceled	canceled
refunded	refunded
partial	pending with an amount still due