Collection & disbursement

Collection and disbursement work the same way as off-ramp and on-ramp transactions. They use the same request body structure, except transaction_hash and chain are not included. See Offramp and Onramp for crypto settlement flows. Base URL: {{base_url}} · Auth: consumer x-api-key Replace {currency_code} with a market prefix such as kes, ugx, ngn, ghs, mwk, cdf, or etb.

Disbursement

Calls Pretium to release fiat from your partner wallet to the recipient (mobile money, paybill, till, etc.).

POST /{currency_code}/disburse

string

required

MOBILE, BUY_GOODS, or PAYBILL

string

required

Recipient mobile, till, or paybill number

string

Required if type is PAYBILL

number

required

Amount to disburse

string

e.g. Safaricom — required when type is MOBILE

string

Optional URL for payment notification

number

Optional partner fee — see Fee

{
  "shortcode": "0700123456",
  "amount": 50,
  "type": "MOBILE",
  "mobile_network": "Safaricom",
  "callback_url": "https://example.com/hooks/pretium"
}

{
  "code": 200,
  "message": "Message",
  "data": {
    "status": "PENDING",
    "transaction_code": "DDM6D",
    "message": "Success! Processing payment..."
  }
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

curl -X POST "{{base_url}}/kes/disburse" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcode": "0700123456",
    "amount": 50,
    "type": "MOBILE",
    "mobile_network": "Safaricom"
  }'

Collection

Initiates cash collection from the user (mobile money prompt / similar).

POST /{currency_code}/collect

string

required

Customer mobile number

number

required

Amount to collect

string

required

e.g. Safaricom, Airtel

string

Optional notification URL

number

Optional partner fee — see Fee

{
  "shortcode": "0743312265",
  "amount": 20,
  "mobile_network": "Safaricom",
  "callback_url": "https://example.com/hooks/pretium"
}

{
  "code": 200,
  "message": "Disburse initiated",
  "data": {
    "status": "PENDING",
    "transaction_code": "TSALX",
    "message": "Success! Processing payment."
  }
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

Banks

Three endpoints cover bank payouts: list the supported banks, resolve an account name, then transfer to the account.

Supported banks

List banks supported for the currency. Use the returned Code as bank_code in the bank info and bank transfer requests.

POST /{currency_code}/banks

No request body is required.

{
  "code": 200,
  "message": "Supported banks",
  "data": [
    {
      "Code": "247247",
      "Name": "Equity Bank"
    }
  ]
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

curl -X POST "{{base_url}}/kes/banks" \
  -H "x-api-key: YOUR_CONSUMER_KEY"

Bank info

Resolves a bank account number and returns the registered account name. Available for kes and ngn.

POST /{currency_code}/bank-infor

string

required

Bank account number to look up

string

required

Bank code from POST /{currency_code}/banks

{
  "account_number": "001918181",
  "bank_code": "247247"
}

{
  "code": 200,
  "message": "Bank Information",
  "data": {
    "account_name": "JOHN DOE",
    "account_number": "001918181",
    "bank_name": "Equity Bank",
    "bank_code": "247247"
  }
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

curl -X POST "{{base_url}}/kes/bank-infor" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "001918181",
    "bank_code": "247247"
  }'

Bank transfer

Settle a disbursement to a recipient bank account (wallet-funded). Track it afterwards with POST /{currency_code}/status using the returned transaction_code.

POST /{currency_code}/bank-transfer

number

required

Amount to transfer. For kes the allowed range is 100 – 250,000.

string

required

Recipient bank account number

string

required

Bank code from POST /{currency_code}/banks

string

Optional URL for payment notification

string

Optional unique reference used as the transaction_code. Auto-generated if omitted.

{
  "amount": 500,
  "account_number": "001918181",
  "bank_code": "247247",
  "callback_url": "https://example.com/hooks/pretium"
}

{
  "code": 200,
  "message": "Message",
  "data": {
    "status": "PENDING",
    "transaction_code": "045c1753-4e5b-4fa8-997b-ee52b78a96fa",
    "message": "Success! Processing payment..."
  }
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

curl -X POST "{{base_url}}/kes/bank-transfer" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "account_number": "001918181",
    "bank_code": "247247"
  }'

Validation

Validates a phone number / shortcode and returns the registered public name from the MNO where available. Reliability varies by country — avoid heavy dependence on this endpoint alone.

POST /{currency_code}/validation

string

required

Phone or shortcode to validate

string

required

e.g. MOBILE

string

e.g. Safaricom

{
  "shortcode": "0700123456",
  "type": "MOBILE",
  "network": "Safaricom"
}

{
  "code": 200,
  "message": "Validation results",
  "data": {
    "status": "COMPLETE",
    "shortcode": "0700123456",
    "public_name": "JOHN DOE"
  }
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

Status

Fetch a transaction by transaction_code.

POST /{currency_code}/status

string

required

Transaction reference returned from disburse, collect, or bank transfer

{
  "transaction_code": "fg464gggshshkkk"
}

{
  "code": 200,
  "message": "Transaction",
  "data": {
    "id": 51215,
    "transaction_code": "045c1753-4e5b-4fa8-997b-ee52b78a96fa",
    "status": "COMPLETE",
    "amount": "20",
    "type": "MOBILE",
    "shortcode": "0700123456",
    "account_number": null,
    "public_name": "JOHN DOE",
    "receipt_number": "TIMCW5AK69",
    "category": "DISBURSEMENT",
    "message": "Transaction processed successfully.",
    "currency_code": "KES",
    "created_at": "2025-09-22T08:08:18.000000Z"
  }
}

{
  "code": 400,
  "message": "Failed - Bad Request"
}

Currency codes

Use the lowercase currency prefix as {currency_code}, for example kes, ugx, ngn, ghs, mwk, cdf, etb, tzs, or zmw. Endpoint availability and amount limits differ by market.

Overview

Account

Rates

Payments (v1)

Banks

Checkout