Additional resources

Utilities

Utility endpoints: identify an operator, check service availability and view your balance.

Sandbox mode. Use your kpay_test_... keys and the test numbers below. KPay routes your requests to its test environment — no real money is moved.

Application information

GET/api/v1/payments/me

Returns the ID and name of the application and company associated with the API keys used. Useful to verify your identifiers, retrieve theapplicationId (required for inter-wallet transfers) or the companyId.

Request example

Node.js

const res = await fetch("https://admin.kpay.site/api/v1/payments/me", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
  },
});
const data = await res.json();

Response (200)

200 OK

{
  "application": {
    "id": "b8aefadd-88b4-561a-8a90-2f9814207bfb",
    "name": "Mon Application"
  },
  "company": {
    "id": "e7c3b4f5-8d9e-4a1b-9c2d-3e4f5a6b7c8d",
    "name": "My Startup Inc"
  },
  "environment": "TEST"
}

Response properties

application.idstring

Application UUID. Use it in the applicationId field of inter-wallet transfers.

application.namestring

Application name as configured in the dashboard.

company.idstring

UUID of the company that owns the application.

company.namestring

Company name.

environmentstring

Environment of the keys used: TEST or PRODUCTION.

Obtain a JWT token

POST/api/v1/payments/token

Exchanges your API keys for a Bearer JWT token (lifetime: 30 minutes). This token is required for JWT-authenticated endpoints such as the inter-wallet transfer (POST /api/wallets/transfer).

Why a JWT token?

Some sensitive endpoints (inter-wallet transfers) use the dashboard's JWT authentication for enhanced security. This endpoint lets you obtain a JWT token without going through the login form — your API keys are sufficient.

Automatic environment

The JWT token automatically inherits the environment of your API keys:

Key kpay_test_... → sandbox token → operations on test wallets.
Key kpay_live_... → production token → operations on real wallets.

You don't need to specify anything in the transfer body — the correct environment is deduced from the key used.

Request example

Node.js

const res = await fetch("https://admin.kpay.site/api/v1/payments/token", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await res.json();

Response (201)

201 Created

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "30m",
  "environment": "TEST"
}

Response properties

accessTokenstring

JWT token to use in the Authorization: Bearer <token> header. The environment (TEST/PRODUCTION) is encoded in the token.

expiresInstring

Token validity duration (30 minutes). After expiration, call this endpoint again.

environmentstring

Token environment: TEST (key kpay_test_...) or PRODUCTION (key kpay_live_...). Confirms the environment in which operations will be performed.

Using the token

Exemple avec cURL

# 1. Obtenir le token
TOKEN=$(curl -s -X POST https://admin.kpay.site/api/v1/payments/token \
  -H "X-API-Key: kpay_test_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_test_xxxxxxxxxxxxxxxx" \
  | jq -r '.accessToken')

# 2. Utiliser le token pour un transfert inter-wallet
curl -X POST https://admin.kpay.site/api/wallets/transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "votre-application-id",
    "sourceCountry": "CMR",
    "destinationCountry": "GAB",
    "amount": 50000
  }'

Exchange rate

GET/api/v1/payments/exchange-rate?from=XAF&to=XOF

Returns the real-time exchange rate between two currencies. The rate is cached for 1 hour server-side. Useful before a cross-currency inter-wallet transfer to show the estimated amount to the user.

Query parameters

fromstringrequis

Source currency (e.g. XAF, XOF, GHS, KES, NGN).

tostringrequis

Target currency.

Request example

Node.js

const res = await fetch("https://admin.kpay.site/api/v1/payments/exchange-rate?from=XAF&to=XOF", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
  },
});
const data = await res.json();

Response (200)

200 OK

{
  "from": "XAF",
  "to": "XOF",
  "rate": 1.0153
}

Response properties

fromstring

Source currency.

tostring

Target currency.

ratenumber

Exchange rate: 1 unit of `from` = `rate` units of `to`. To convert: amount × rate.

Monetary zones

Currencies within the same zone (CEMAC: XAF, UEMOA: XOF) return a rate of 1 for intra-zone transfers. Cross-zone transfers use the real rate.

Guess the operator of a number

POST/api/v1/payments/predict-provider

Identifies the Mobile Money (MMO) provider associated with a phone number, along with the country. Useful to pre-fill the provider field before initiating a payment or withdrawal.

Helper endpoint (lookup)

The result is a suggestion. You remain responsible for the provider passed to the init. In sandbox, only test numbers are recognized.

Request body

phoneNumberstringrequis

Mobile Money number (national or international format, e.g. 237670000001, 260763456789).

Request example

Node.js

const res = await fetch("https://admin.kpay.site/api/v1/payments/predict-provider", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "phoneNumber": "237653456789"
}),
});
const data = await res.json();

Response (201)

201 Created

{
  "country": "CMR",
  "provider": "MTN_MOMO_CMR",
  "phoneNumber": "237653456789"
}

Response properties

countrystring

Operator country, ISO 3166-1 alpha-3 (e.g. CMR, ZMB, GHA).

providerstring

pawaPay provider code (e.g. MTN_MOMO_CMR, ORANGE_CMR). Use this value in the provider field of the init.

phoneNumberstring

Normalized number (digits only, without + or leading 0).

Common errors

400 — Number not recognized, invalid format or unsupported operator.
401 — API keys missing or invalid.
429 — Rate limit exceeded.

Operator availability

GET/api/v1/payments/availability

Returns the operational status of each Mobile Money provider, by country and operation type (DEPOSIT, PAYOUT, REMITTANCE). Data is cached for 1 minute on KPay's side.

Possible statuses

Status	Meaning
`OPERATIONAL`	Service fully operational
`DELAYED`	Service operational but with abnormal delays
`CLOSED`	Service temporarily unavailable

Request example

Node.js

const res = await fetch("https://admin.kpay.site/api/v1/payments/availability", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
  },
});
const data = await res.json();

Response (200)

200 OK

[
  {
    "country": "CMR",
    "providers": [
      {
        "provider": "MTN_MOMO_CMR",
        "operationTypes": [
          { "operationType": "DEPOSIT", "status": "OPERATIONAL" },
          { "operationType": "PAYOUT", "status": "OPERATIONAL" }
        ]
      },
      {
        "provider": "ORANGE_CMR",
        "operationTypes": [
          { "operationType": "DEPOSIT", "status": "OPERATIONAL" },
          { "operationType": "PAYOUT", "status": "DELAYED" }
        ]
      }
    ]
  },
  {
    "country": "GHA",
    "providers": [
      {
        "provider": "MTN_MOMO_GHA",
        "operationTypes": [
          { "operationType": "DEPOSIT", "status": "OPERATIONAL" },
          { "operationType": "PAYOUT", "status": "OPERATIONAL" }
        ]
      },
      {
        "provider": "VODAFONE_GHA",
        "operationTypes": [
          { "operationType": "DEPOSIT", "status": "OPERATIONAL" },
          { "operationType": "PAYOUT", "status": "DELAYED" }
        ]
      }
    ]
  }
]

Use case

Query this endpoint to build a monitoring dashboard, display service status to your users, or dynamically disable an unavailable operator in your interface.

Check wallet balance

GET/api/v1/payments/balance

Returns the balance of your KPay wallet for the application identified by your API keys. In sandbox, the returned balance is that of the test wallet.

Request example

Node.js

const res = await fetch("https://admin.kpay.site/api/v1/payments/balance", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
  },
});
const data = await res.json();

Response (200)

200 OK

[
  {
    "currency": "XAF",
    "balance": 150000,
    "reservedBalance": 25000,
    "availableBalance": 125000
  }
]

Response properties

currencystring

Wallet currency (e.g. XAF).

balancenumber

Total wallet balance.

reservedBalancenumber

Amount reserved for withdrawals currently being processed.

availableBalancenumber

Available balance (balance - reservedBalance). This is the amount you can actually use for withdrawals.

Related resources

ProvidersOperator catalogue (provider codes)

PaymentsCreate and track payments

WithdrawalsSend funds to Mobile Money

WebhooksStatus change notifications

PrecedentVirtual numbers Suivant Webhooks

Was this page helpful?