LabPay documentationAPI V2 · V1

Get started

Quickstart

A first Mobile Money test collection with API V2, in a few minutes and with no real money.

The steps#

  1. Create a LabPay merchant account and confirm your e-mail address.
  2. In My API keys, generate your token: you get a live token and a test key (test_…).
  3. Install the SDK for your language (or stay with plain HTTP), then call POST /V2/deposits with the test key and a test number.
  4. Receive the final status on your callback_url, or read the payment with GET /V2/payments/{id}.
  5. When everything works, swap the test key for the live token: same endpoints, same formats.
Server-side only

The token and the test key are secrets: keep them server-side (environment variables), never in a mobile app or the browser.

Collect from a customer#

Every V2 request starts from https://api.labyrinthe-rdc.com/api/V2. The customer gets a PIN prompt on their phone; with the test key, the sandbox simulates their answer based on the number used.

Create a test deposit

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","callback_url":"https://boutique.example/webhooks/labpay","metadata":{"orderId":"42"}}'

The PHP, Laravel, Node.js, Python, Java and C# tabs use the LabPay SDKs (automatic reference, safe retries, typed errors); the "HTTP" tabs make the same call without an SDK. Your choice is remembered across the documentation.

201 response: the payment is accepted and awaits its final status. Keep its id and your reference.

201 response
{
  "data": {
    "id": "DEP-01JCX8Q3T6Y0V5W1Z2A3B4C5D6",
    "reference": "ORDER-42",
    "operation": "deposit",
    "livemode": false,
    "status": "pending",
    "gateway_status": "ACCEPTED",
    "amount": "1000.00",
    "fee": "35.00",
    "total_amount": "1035.00",
    "currency": "CDF",
    "country": "COD",
    "phone": "0813456789",
    "provider": "VODACOM_MPESA_COD",
    "provider_transaction_id": null,
    "failure": null,
    "metadata": {
      "orderId": "42"
    },
    "created_at": "2026-11-11T10:00:00+00:00",
    "completed_at": null,
    "refunded_amount": "0.00"
  }
}

Get the final status#

status moves from pending to completed or failed. The simplest way is to pass a callback_url: LabPay sends a signed notification to it as soon as the status is final. Without a callback_url, read the payment:

Read a payment

curl "https://api.labyrinthe-rdc.com/api/V2/payments/DEP-01JCX8Q3T6Y0V5W1Z2A3B4C5D6" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Next steps#

  1. Verify the signature of each notification (with an SDK: constructEvent).
  2. Always send a unique reference (the SDKs generate one): a resend after a network failure returns the same payment (idempotency).
  3. Handle error codes and limits.