API V2 (recommended)

Countries, providers and prediction

Read open countries, providers and their rules, their availability in real time, and predict a phone number's provider.

These endpoints require the token (live or test), like the others. The same information, read from the database, is published on the Countries and providers page.

Open countries#

GET `/V2/countries`#

Countries open to payments: code, name, dial code, currencies, limits per currency and default country (the one of a local number without country).

List countries

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

Each data item contains country (e.g. COD), name, dial_code, currencies, limits ({ "<CURRENCY>": { "min_amount", "max_amount" } }, null when undefined) and default (boolean).

Providers and rules#

GET `/V2/providers`#

Field	Type	Required	Description
`operation`	string	No	`deposit` (default), `payout` or `refund`: rules depend on the operation.
`country`	string	No	3-letter country code; all open countries by default.

Payout providers in DR Congo

curl "https://api.labyrinthe-rdc.com/api/V2/providers?operation=payout&country=COD" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Field	Description
`provider`	Provider code, to pass in the `provider` field.
`country`	Provider's country.
`name`, `name_displayed_to_customer`, `logo`	Name, name shown to the customer and logo.
`currencies.<DEVISE>.min_amount`, `max_amount`	Provider limits for this operation.
`currencies.<DEVISE>.decimals`	Decimals accepted in the amount (e.g. `NONE`: whole amount).
`currencies.<DEVISE>.status`	Operation status for this provider.
`currencies.<DEVISE>.pin_prompt`, `pin_prompt_revivable`, `pin_prompt_instructions`	How the PIN prompt works and instructions to show the customer.

The list comes from LabPay's active configuration. If it does not respond: 503 GATEWAY_UNAVAILABLE, retry after a few seconds.

Provider availability#

GET `/V2/availability`#

Optional country parameter. data is an object keyed by provider code; for each one: country and a status per operation type (DEPOSIT, PAYOUT…).

Status	Meaning
`OPERATIONAL`	Working normally.
`DELAYED`	Payouts queued (`gateway_status: "ENQUEUED"`), processed later or cancellable.
`CLOSED`	Closed: a payment to this provider is refused immediately (`503 PROVIDER_TEMPORARILY_UNAVAILABLE`).

Availability in DR Congo

curl "https://api.labyrinthe-rdc.com/api/V2/availability?country=COD" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Predict a number's provider#

POST `/V2/predict-provider`#

Validates a number and predicts its provider, without creating a payment: useful to pre-fill a form or check a number before a payout.

Field	Type	Required	Description
`phone`	string	Yes	Local or international number, at most 20 characters.
`country`	string	No	3-letter country code.

Predict the provider

curl -X POST "https://api.labyrinthe-rdc.com/api/V2/predict-provider" \
  -H "Authorization: Bearer test_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"phone":"0813456789","country":"COD"}'

200 response

{
  "data": {
    "phone": "243813456789",
    "provider": "VODACOM_MPESA_COD",
    "country": "COD"
  }
}

phone is returned in international format, without +. Invalid number: 422 INVALID_PHONE_NUMBER; country not open: UNSUPPORTED_COUNTRY.