Idempotency (reference)

How it works#

On POST /V2/deposits, POST /V2/payouts and POST /V2/refunds, the optional reference field is unique per token (and per mode). If you resend a request with an already used reference — after a network failure, a timeout, a restart —, the API returns the existing payment instead of creating a second one.

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":"0813456789","reference":"ORDER-42"}'

With the SDKs: automatic reference#

The SDKs apply this principle for you. Without a reference, they generate one (sdk_<uuid>) before the first attempt, then reuse it on every retry: a deposit, payout or refund can be retried after a network error or a 5xx with no risk of double payment. A reference you provide always takes precedence.

<?php
use Labyrinthe\LabPay\Client;

$labpay = new Client('test_xxxxxxxxxxxxxxxx'); // ou Client::fromEnv() (LABPAY_API_KEY)

// Sans reference : le SDK envoie sdk_<uuid> et peut relancer sans risque de double paiement.
$payment = $labpay->deposits->create(amount: '1000', currency: 'CDF', phone: '0813456789');
echo $payment->reference; // sdk_…

// Désactiver : new Client('test_xxxxxxxxxxxxxxxx', autoReference: false)

• Can be disabled: autoReference: false (PHP, Node.js, Java), auto_reference=False (Python), AutoReference = false (.NET); a payment without reference is then never retried after a network error or a 5xx.
• Keep the generated reference (payment.reference): it lets you find the payment with findByReference if the response was lost.
• A network error (ConnectionException, ConnectionError, APIConnectionError) on a payment does not mean failure: resend the same reference.

Response to a resend#

• The returned payment is the original one, in its current state: the new request's fields (amount, number…) are ignored.
• A reference applies across all the token's operations: do not reuse it for a deposit and a payout.
• Two simultaneous requests with the same reference also result in a single payment.

Over plain HTTP, without a reference, every request creates a new payment: a resend after a timeout may then charge the customer twice. The reference also lets you find a payment: GET /V2/payments?reference=ORDER-42.