Resources

Versions and V1 → V2 migration

The differences between the legacy V1 and V2, and the steps to migrate an existing integration.

Version status#

Version	Status	Use
V2	Recommended	Any new integration.
V1	Legacy, maintained	Existing integrations; to migrate to V2.

Both versions share merchant accounts, tokens and balances: a V2 payment shows up in get-transactions (V1), a V1 collection credits the balance read by GET /V2/balances. You can therefore migrate endpoint by endpoint.

Differences#

Topic	V1	V2
Token	`token` field in body or query	`Authorization: Bearer` header
Test mode	None	`test_…` key, sandbox, separate balances
Countries	DR Congo (`country: "CD"`)	Countries open in the database (`country: "COD"`, optional)
Phone number	Local, 10 digits	Local or international
Provider	Inferred from the prefix	Inferred from the number, or explicit `provider`
Identifier	UUID (`orderNumber`)	`DEP-…`, `PAY-…`, `RFD-…` + your `reference`
Idempotency	None	`reference` unique per token
Statuses	`processed`, `pending`, `done`, `failed`…	`pending`, `completed`, `failed`
Result	Unsigned callback, sent once	HMAC-signed notification, redelivered, history and resend
Payout	Balance debited on confirmation, no fee	Balance debited at initiation (under lock), credited back on failure, payout fee
Other operations	Cross-network transfer, statistics	Refund, payout cancellation, status refresh, providers, availability, prediction
Errors	`success: false` + message	Stable `code` + message
Official SDKs	None	PHP, Laravel, Node.js, Python, Java, .NET, WooCommerce (SDKs and tools)

Migrate to V2#

Get your test key (GET /V2/account or the merchant area) and your signing secret (webhook_secret, live token).
Move the token from the body to the Authorization: Bearer header.
Replace POST /V1/payment/mobile with POST /V2/deposits and POST /V1/payment/withdrawal with POST /V2/payouts; drop country: "CD" (or pass COD); callback becomes callback_url.
Add a unique reference to each request and store the returned id.
Adapt status reading: done → completed, processed / pending → pending, failed / canceled → failed.
Replace the V1 callback handling with the signature verification of V2 notifications.
Test with the test key and the test numbers, then switch to the live token.
The shortest path: use an SDK (PHP, Laravel, Node.js, Python, Java, .NET) or the WooCommerce plugin: they only speak V2 and already handle the header, the reference, the statuses and the signature.

Before (V1)

curl -X POST "https://api.labyrinthe-rdc.com/api/V1/payment/mobile" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"token":"VOTRE_TOKEN","phone":"0812345678","amount":1000,"currency":"CDF","country":"CD","callback":"https://boutique.example/callback"}'

After (V2)

curl -X POST "https://api.labyrinthe-rdc.com/api/V2/deposits" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount":"1000","currency":"CDF","phone":"0812345678","reference":"ORDER-42","callback_url":"https://boutique.example/webhooks/labpay"}'

Fees differ: in V1, the customer pays the amount plus 7%; in V2, fees follow your account rate (see Limits and fees). Check the amounts shown to your customers before switching.