API V2 (recommended)

Refund a deposit

POST /V2/refunds: refund all or part of a completed V2 deposit, to the wallet that paid.

POST `/V2/refunds`#

Field	Type	Required	Description
`payment_id`	string	Yes	`id` of the deposit to refund (`DEP-…`).
`amount`	string \| number	No	Amount to refund, at most 2 decimals. Default: everything left to refund.
`reference`	string	No	Your reference, unique per token (see idempotency).
`callback_url`	string	No	Public HTTPS address that will receive the final status notification.
`metadata`	object	No	Up to 20 key / value pairs, returned as is.

Refund 300 CDF

curl -X POST "https://api.labyrinthe-rdc.com/api/V2/refunds" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"payment_id":"DEP-01JCX8Q3T6Y0V5W1Z2A3B4C5D6","amount":"300","reference":"REFUND-42-1"}'

201 response

{
  "data": {
    "id": "RFD-01JCXB7M8N9P0Q1R2S3T4V5W6X",
    "reference": "REFUND-42-1",
    "operation": "refund",
    "livemode": false,
    "status": "pending",
    "gateway_status": "ACCEPTED",
    "amount": "300.00",
    "fee": "0.00",
    "total_amount": "300.00",
    "currency": "CDF",
    "country": "COD",
    "phone": "0813456789",
    "provider": "VODACOM_MPESA_COD",
    "provider_transaction_id": null,
    "failure": null,
    "metadata": null,
    "created_at": "2026-11-11T10:00:00+00:00",
    "completed_at": null,
    "refunded_payment_id": "DEP-01JCX8Q3T6Y0V5W1Z2A3B4C5D6"
  }
}

Rules#

Only for a completed V2 deposit of this token.
The refundable amount is the net amount credited to the merchant (the deposit's amount): fees are not refunded. The deposit shows what was already refunded in refunded_amount.
Only one refund in progress at a time per deposit (REFUND_IN_PROGRESS).
No fee on a refund. Your balance is debited with the refunded amount at initiation, and credited back if the refund fails.
The refund follows the same status lifecycle as a payment and can have its own callback_url.

Specific errors#

Code	Case
`DEPOSIT_NOT_FOUND` (404)	`payment_id` matches no V2 deposit of this token.
`DEPOSIT_NOT_COMPLETED` (409)	The deposit is not completed.
`REFUND_IN_PROGRESS` (409)	A refund of this deposit is already in progress.
`DEPOSIT_ALREADY_REFUNDED` (409)	The deposit is fully refunded.
`AMOUNT_TOO_LARGE` (422)	Amount above what is left to refund (the message gives the maximum).
`INSUFFICIENT_BALANCE` (422)	Your balance does not cover the refund.
`WITHDRAWALS_DISABLED` (503)	Payouts and refunds temporarily disabled.
`FEATURE_DISABLED` (503)	Refunds suspended from the LabPay console (`feature: "operations.refunds"`).

Refund a deposit

POST /V2/refunds#

Rules#

Specific errors#

POST `/V2/refunds`#