API V2 (recommended)

Send money

POST /V2/payouts: send money from your LabPay balance to a Mobile Money wallet, and cancel a payout left in the queue.

POST `/V2/payouts`#

Sends amount to the given number. Same fields and country rules as a collection (Countries and numbers):

Field	Type	Required	Description
`amount`	string \| number	Yes	Net amount, > 0, at most 2 decimals (e.g. `"1500"`, `"12.50"`).
`currency`	string	Yes	Currency of an open country (e.g. `CDF`, `USD`), then checked against the phone number's country. Each country's currencies: Countries and providers.
`phone`	string	Yes	Local number of the default country (`0812345678`) or international, with the country's dial code (`+243812345678`). At most 20 characters. See Countries and numbers.
`country`	string	No	Phone number's country, 3-letter code (e.g. `COD`). Without it: local number = the platform's default country (currently DR Congo, `COD`), international number = country of the dial code.
`provider`	string	No	Provider code (e.g. `VODACOM_MPESA_COD`, see Countries and providers). Inferred from the number when absent.
`reference`	string	No	Your reference, unique per token, at most 100 characters (letters, digits, `. _ : -`). See idempotency.
`callback_url`	string	No	Public HTTPS address that will receive the final status notification.
`customer_message`	string	No	Text shown to the customer (SMS, history), depending on the provider: 4 to 22 characters, letters, digits and spaces.
`metadata`	object	No	Up to 20 key / value pairs (strings of at most 255 characters), returned as is.

Send 5,000 CDF

curl -X POST "https://api.labyrinthe-rdc.com/api/V2/payouts" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount":"5000","currency":"CDF","phone":"0813456789","reference":"PAYOUT-17","callback_url":"https://boutique.example/webhooks/labpay","metadata":{"payoutId":"17"}}'

201 response

{
  "data": {
    "id": "PAY-01JCX9A1B2C3D4E5F6G7H8J9K0",
    "reference": "PAYOUT-17",
    "operation": "payout",
    "livemode": false,
    "status": "pending",
    "gateway_status": "ACCEPTED",
    "amount": "5000.00",
    "fee": "175.00",
    "total_amount": "5175.00",
    "currency": "CDF",
    "country": "COD",
    "phone": "0813456789",
    "provider": "VODACOM_MPESA_COD",
    "provider_transaction_id": null,
    "failure": null,
    "metadata": {
      "payoutId": "17"
    },
    "created_at": "2026-11-11T10:00:00+00:00",
    "completed_at": null
  }
}

Balance debit#

The recipient receives amount; your balance in that currency is debited immediately with amount + payout fees (total_amount).
The debit happens under a lock: two simultaneous payouts cannot exceed the balance. Insufficient balance: 422 INSUFFICIENT_BALANCE, nothing is sent.
If the payout fails, your balance is credited back in full (amount and fees).
If the provider does not accept decimals in the currency (e.g. Vodacom in CDF), a decimal amount is refused (INVALID_AMOUNT) rather than rounded.

Live, payouts require a verified (KYC) account when the platform enforces it (KYC_REQUIRED). In test mode, they use the test balance, funded by your test deposits.

Cancel a queued payout#

When the provider is struggling, the payout may be queued: it stays pending with gateway_status: "ENQUEUED". It can then be cancelled.

POST `/V2/payouts/{id}/cancel`#

The status is re-read before deciding. Cancellation is asynchronous: the response returns the payment, which then moves to failed; your balance is then credited back.

Cancel a payout

curl -X POST "https://api.labyrinthe-rdc.com/api/V2/payouts/PAY-01JCX9A1B2C3D4E5F6G7H8J9K0/cancel" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

The SDKs expose isQueued() (or is_queued, IsQueued) to tell whether a payout can be cancelled. A cancellation is never retried automatically after a network error: read the payment before trying again.

Code	Case
`NOT_A_PAYOUT` (409)	The payment is not a payout.
`NOT_CANCELLABLE` (409)	The payout is not (or no longer) `ENQUEUED`, or the cancellation was refused.
`GATEWAY_UNAVAILABLE` (503)	The cancellation could not be processed: retry.
`PAYMENT_NOT_FOUND` (404)	Unknown identifier for this token and mode.
`FEATURE_DISABLED` (503)	Payout cancellation suspended from the LabPay console.

Provider availability (OPERATIONAL, DELAYED = payouts queued, CLOSED) is read on GET /V2/availability.