# Countries
Source: https://docs.pretium.africa/api-reference/account/countries

POST /account/countries
List countries available to the partner.

Returns `id`, `name`, `currency_code`, and `phone_code` for each country.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/countries" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>


# Account detail
Source: https://docs.pretium.africa/api-reference/account/detail

POST /account/detail
Partner profile, wallets, networks, and checkout key.

No body required.

<ResponseField name="data.id" type="number">
  Partner id.
</ResponseField>

<ResponseField name="data.name" type="string">
  Partner name.
</ResponseField>

<ResponseField name="data.email" type="string">
  Partner email.
</ResponseField>

<ResponseField name="data.status" type="string">
  `ACTIVE` or `DEACTIVATED`.
</ResponseField>

<ResponseField name="data.checkout_key" type="string">
  Key for `/v1/checkout` routes.
</ResponseField>

<ResponseField name="data.wallets" type="array">
  Fiat account balances by country.
</ResponseField>

<ResponseField name="data.networks" type="array">
  Supported settlement networks and assets.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/detail" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>


# Account FX convert
Source: https://docs.pretium.africa/api-reference/account/exchange-rate

POST /account/exchange-rate
Convert an amount using selling or buying rate direction.

Provide either a selling-rate conversion or a buying-rate conversion.

### Selling (`from` fiat → quote)

<ParamField type="number">
  Amount in the `from` currency.
</ParamField>

<ParamField type="string">
  Source currency code.
</ParamField>

### Buying (`to` fiat ← quote)

<ParamField type="number">
  Amount toward the `to` currency.
</ParamField>

<ParamField type="string">
  Destination currency code.
</ParamField>

Response includes `from`, `to`, and computed `rate`.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/exchange-rate" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"selling_rate":100,"from":"KES"}'
  ```
</RequestExample>


# Fund wallet
Source: https://docs.pretium.africa/api-reference/account/fund

POST /account/fund
Get FX rate and settlement wallets for topping up a fiat wallet with crypto.

First step of wallet funding. Returns the current FX rate and Pretium settlement addresses per network. Send stablecoin to one of those addresses, then call [Fund confirm](/api-reference/account/fund-confirm).

<ParamField type="string">
  Fiat wallet currency such as `KES` or `UGX` (case-insensitive).
</ParamField>

<ResponseField name="data.currency_code" type="string">
  Currency code of the wallet being funded.
</ResponseField>

<ResponseField name="data.selling_rate" type="number">
  Current FX rate for the market. Confirm credits use the rate at confirmation time.
</ResponseField>

<ResponseField name="data.networks" type="array">
  Settlement options. Each item has `network`, `settlement_wallet_address`, and `assets`.
</ResponseField>

### Supported networks & assets

| Network    | Assets         |
| ---------- | -------------- |
| `BASE`     | `USDC`         |
| `ETHEREUM` | `USDT`, `USDC` |
| `SOLANA`   | `USDT`, `USDC` |
| `CELO`     | `USDT`, `USDC` |

### Errors

| Status | Message                  | When                                |
| ------ | ------------------------ | ----------------------------------- |
| `400`  | Validation message       | Missing `currency_code`             |
| `400`  | `Country not supported.` | Unknown currency                    |
| `404`  | `Wallet not found!`      | No partner wallet for that currency |

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/fund" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"currency_code":"KES"}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": 200,
    "message": "Fund wallet details",
    "data": {
      "currency_code": "KES",
      "selling_rate": 131.2,
      "networks": [
        {
          "network": "BASE",
          "settlement_wallet_address": "0x...",
          "assets": ["USDC"]
        },
        {
          "network": "CELO",
          "settlement_wallet_address": "0x...",
          "assets": ["USDT", "USDC"]
        }
      ]
    }
  }
  ```
</ResponseExample>


# Fund confirm
Source: https://docs.pretium.africa/api-reference/account/fund-confirm

POST /account/fund/confirm
Verify an on-chain deposit and credit the partner fiat wallet.

Second step of wallet funding. After transferring USDC or USDT to a settlement address from [Fund wallet](/api-reference/account/fund), submit the transaction hash. Pretium verifies the transfer on-chain, converts at the current FX rate, and credits your fiat balance.

Amount and asset are read from the chain — do not send them in the body.

<ParamField type="string">
  Fiat wallet currency such as `KES` or `UGX` (case-insensitive).
</ParamField>

<ParamField type="string">
  Chain of the deposit: `BASE`, `CELO`, `SOLANA` (`sol`), or `ETHEREUM` (`eth`). Case-insensitive.
</ParamField>

<ParamField type="string">
  On-chain transaction hash. Must not have been processed before.
</ParamField>

<ResponseField name="data.currency_code" type="string">
  Credited wallet currency.
</ResponseField>

<ResponseField name="data.amount" type="number">
  Fiat amount credited (`amount_in_usd × rate`).
</ResponseField>

<ResponseField name="data.amount_in_usd" type="number">
  Stablecoin amount detected on-chain.
</ResponseField>

<ResponseField name="data.buying_rate" type="number">
  FX rate used for the conversion.
</ResponseField>

<ResponseField name="data.asset" type="string">
  Token received (`USDC` or `USDT`).
</ResponseField>

<ResponseField name="data.network" type="string">
  Normalized chain name.
</ResponseField>

<ResponseField name="data.transaction_hash" type="string">
  Confirmed transaction hash.
</ResponseField>

<ResponseField name="data.balance" type="number">
  Fiat wallet balance after the credit.
</ResponseField>

### Supported networks & assets

| Network    | Assets         |
| ---------- | -------------- |
| `BASE`     | `USDC`         |
| `ETHEREUM` | `USDT`, `USDC` |
| `SOLANA`   | `USDT`, `USDC` |
| `CELO`     | `USDT`, `USDC` |

### Errors

| Status | Message                                                               | When                                |
| ------ | --------------------------------------------------------------------- | ----------------------------------- |
| `400`  | Validation message                                                    | Missing required fields             |
| `400`  | `Country not supported.`                                              | Unknown currency                    |
| `400`  | `Unsupported network. Allowed networks: Base, Celo, Solana, Ethereum` | Invalid network                     |
| `400`  | `Settlement wallet not configured for this network.`                  | No funding wallet for chain         |
| `400`  | `This transaction hash has already been processed.`                   | Hash already used                   |
| `400`  | `Transaction not complete on-chain. Try again.`                       | On-chain status is not success      |
| `400`  | `This transaction was not done to Pretium wallet address.`            | Transfer not to settlement wallet   |
| `400`  | `{CHAIN} {TOKEN} token not supported at the moment.`                  | Unsupported asset on that chain     |
| `400`  | `Wallet not found!`                                                   | No partner wallet for that currency |

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/fund/confirm" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "currency_code": "KES",
      "network": "BASE",
      "transaction_hash": "0xabc123..."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": 200,
    "message": "FIAT wallet credited successfully.",
    "data": {
      "currency_code": "KES",
      "amount": 12950.0,
      "amount_in_usd": 100.0,
      "buying_rate": 129.5,
      "asset": "USDC",
      "network": "BASE",
      "transaction_hash": "0xabc123...",
      "balance": 50000.0
    }
  }
  ```
</ResponseExample>


# Networks
Source: https://docs.pretium.africa/api-reference/account/networks

POST /account/networks
Supported blockchain networks and assets.

Each network includes name, icon, settlement wallet address, checkout status, and assets.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/networks" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>


# Get transaction
Source: https://docs.pretium.africa/api-reference/account/transaction

POST /account/{country_code}/transaction
Fetch one transaction by code under a country namespace.

<ParamField type="string">
  e.g. `kes`, `ugx`, `ngn`, `zmw`, `mwk`, `cdf` (others fall back to KES store).
</ParamField>

<ParamField type="string">
  Transaction code to look up.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/kes/transaction" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"transaction_code":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
  ```
</RequestExample>


# List account transactions
Source: https://docs.pretium.africa/api-reference/account/transactions

POST /account/{country_code}/transactions
List transactions for a country with optional date filters.

<ParamField type="string">
  Country code segment, e.g. `kes`.
</ParamField>

<ParamField type="string">
  Optional start date.
</ParamField>

<ParamField type="string">
  Optional end date.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/kes/transactions" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>


# Wallet balance
Source: https://docs.pretium.africa/api-reference/account/wallet

POST /account/wallet/{country_id}
Fiat wallet balance for a country.

<ParamField type="integer">
  Country id `1`–`10` (see [API overview](/api-reference/overview#country-ids-account-wallet)).
</ParamField>

Returns balance, currency code, and country name for that wallet.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/account/wallet/1" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>


# Bank info
Source: https://docs.pretium.africa/api-reference/banks/bank-info

POST /{currency_code}/bank-infor
Resolve a bank account number to the registered account name.

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

<ParamField type="string">
  Lowercase market prefix, e.g. `kes`.
</ParamField>

<ParamField type="string">
  Bank account number to look up.
</ParamField>

<ParamField type="string">
  Bank code from [List banks](/api-reference/banks/banks).
</ParamField>

<RequestExample>
  ```bash theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Bank Information",
    "data": {
      "account_name": "JOHN DOE",
      "account_number": "001918181",
      "bank_name": "Equity Bank",
      "bank_code": "247247"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</ResponseExample>


# Bank transfer
Source: https://docs.pretium.africa/api-reference/banks/bank-transfer

POST /{currency_code}/bank-transfer
Settle a wallet-funded disbursement to a recipient bank account.

Settles a disbursement to a recipient bank account from your Pretium wallet balance. Track it afterwards with [`POST /{currency_code}/status`](/api-reference/countries/collection-and-disbursement#status) using the returned `transaction_code`.

<ParamField type="string">
  Lowercase market prefix, e.g. `kes`.
</ParamField>

<ParamField type="number">
  Amount to transfer. For `kes` the allowed range is **100 – 250,000**.
</ParamField>

<ParamField type="string">
  Recipient bank account number.
</ParamField>

<ParamField type="string">
  Bank code from [List banks](/api-reference/banks/banks).
</ParamField>

<ParamField type="string">
  Optional URL for payment notification.
</ParamField>

<ParamField type="string">
  Optional unique reference used as the `transaction_code`. Auto-generated if omitted.
</ParamField>

<RequestExample>
  ```bash theme={null}
  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",
      "callback_url": "https://example.com/hooks/pretium"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Message",
    "data": {
      "status": "PENDING",
      "transaction_code": "045c1753-4e5b-4fa8-997b-ee52b78a96fa",
      "message": "Success! Processing payment..."
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</ResponseExample>


# List banks
Source: https://docs.pretium.africa/api-reference/banks/banks

POST /{currency_code}/banks
List banks supported for a currency.

<ParamField type="string">
  Lowercase market prefix, e.g. `kes`.
</ParamField>

No request body is required. Use the returned `Code` as `bank_code` in [Bank info](/api-reference/banks/bank-info) and [Bank transfer](/api-reference/banks/bank-transfer) requests.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/kes/banks" \
    -H "x-api-key: YOUR_CONSUMER_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Supported banks",
    "data": [
      {
        "Code": "247247",
        "Name": "Equity Bank"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</ResponseExample>


# Create checkout
Source: https://docs.pretium.africa/api-reference/checkout/create

POST /v1/checkout/
Create a short-lived settlement order.

Uses the partner **checkout key** as `x-api-key`. Parameters are passed as **query params**.

Orders expire in about **7 minutes**.

<ParamField type="string">
  Settlement network name.
</ParamField>

<ParamField type="string">
  Asset symbol (e.g. `USDC`, `USDT`).
</ParamField>

<ParamField type="string">
  Fiat currency context, e.g. `KES`.
</ParamField>

<ParamField type="number">
  Order amount.
</ParamField>

<ParamField type="string">
  Your unique order identifier.
</ParamField>

Response includes settlement `address`, `rate`, USD `amount`, and `expires_in`.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/checkout/?network=CELO&asset=USDT&currency_code=KES&amount=1000&order_id=order_123" \
    -H "x-api-key: YOUR_CHECKOUT_KEY"
  ```
</RequestExample>


# Checkout networks
Source: https://docs.pretium.africa/api-reference/checkout/networks

POST /v1/checkout/networks
List networks available for checkout settlement.

Auth: **checkout key**. No parameters required.

Returns a networks resource (names, assets, settlement details).

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/checkout/networks" \
    -H "x-api-key: YOUR_CHECKOUT_KEY"
  ```
</RequestExample>


# Confirm checkout payment
Source: https://docs.pretium.africa/api-reference/checkout/pay

POST /v1/checkout/pay
Submit the on-chain hash that settles a checkout order.

Auth: **checkout key**.

<ParamField type="string">
  Checkout order id.
</ParamField>

<ParamField type="string">
  Hash of the settlement transfer.
</ParamField>

Verifies the transfer on-chain and may trigger auto-settlement (e.g. KES) plus a webhook.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/checkout/pay?order_id=order_123&transaction_hash=0xabc" \
    -H "x-api-key: YOUR_CHECKOUT_KEY"
  ```
</RequestExample>


# Checkout status
Source: https://docs.pretium.africa/api-reference/checkout/status

POST /v1/checkout/status
Get checkout order status by order_id.

Auth: **checkout key**. Query parameter:

<ParamField type="string">
  Order id from create checkout.
</ParamField>

Statuses: `PENDING`, `EXPIRED`, `CANCELLED`, `FAILED`, `COMPLETE`.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/checkout/status?order_id=order_123" \
    -H "x-api-key: YOUR_CHECKOUT_KEY"
  ```
</RequestExample>


# Collection & disbursement
Source: https://docs.pretium.africa/api-reference/countries/collection-and-disbursement

Wallet-funded collect and disburse under a currency prefix — same shape as offramp/onramp without transaction_hash.

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](/guides/offramp) and [Onramp](/guides/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
```

<ParamField type="string">
  `MOBILE`, `BUY_GOODS`, or `PAYBILL`
</ParamField>

<ParamField type="string">
  Recipient mobile, till, or paybill number
</ParamField>

<ParamField type="string">
  Required if `type` is `PAYBILL`
</ParamField>

<ParamField type="number">
  Amount to disburse
</ParamField>

<ParamField type="string">
  e.g. `Safaricom` — required when `type` is `MOBILE`
</ParamField>

<ParamField type="string">
  Optional URL for payment notification
</ParamField>

<ParamField type="number">
  Optional partner fee — see [Fee](/fee)
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "shortcode": "0700123456",
    "amount": 50,
    "type": "MOBILE",
    "mobile_network": "Safaricom",
    "callback_url": "https://example.com/hooks/pretium"
  }
  ```

  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Message",
    "data": {
      "status": "PENDING",
      "transaction_code": "DDM6D",
      "message": "Success! Processing payment..."
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

```bash theme={null}
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
```

<ParamField type="string">
  Customer mobile number
</ParamField>

<ParamField type="number">
  Amount to collect
</ParamField>

<ParamField type="string">
  e.g. `Safaricom`, `Airtel`
</ParamField>

<ParamField type="string">
  Optional notification URL
</ParamField>

<ParamField type="number">
  Optional partner fee — see [Fee](/fee)
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "shortcode": "0743312265",
    "amount": 20,
    "mobile_network": "Safaricom",
    "callback_url": "https://example.com/hooks/pretium"
  }
  ```

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

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

***

## 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.

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Supported banks",
    "data": [
      {
        "Code": "247247",
        "Name": "Equity Bank"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

```bash theme={null}
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
```

<ParamField type="string">
  Bank account number to look up
</ParamField>

<ParamField type="string">
  Bank code from [`POST /{currency_code}/banks`](#supported-banks)
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "account_number": "001918181",
    "bank_code": "247247"
  }
  ```

  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Bank Information",
    "data": {
      "account_name": "JOHN DOE",
      "account_number": "001918181",
      "bank_name": "Equity Bank",
      "bank_code": "247247"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

```bash theme={null}
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`](#status) using the returned `transaction_code`.

```
POST /{currency_code}/bank-transfer
```

<ParamField type="number">
  Amount to transfer. For `kes` the allowed range is **100 – 250,000**.
</ParamField>

<ParamField type="string">
  Recipient bank account number
</ParamField>

<ParamField type="string">
  Bank code from [`POST /{currency_code}/banks`](#supported-banks)
</ParamField>

<ParamField type="string">
  Optional URL for payment notification
</ParamField>

<ParamField type="string">
  Optional unique reference used as the `transaction_code`. Auto-generated if omitted.
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "amount": 500,
    "account_number": "001918181",
    "bank_code": "247247",
    "callback_url": "https://example.com/hooks/pretium"
  }
  ```

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

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

```bash theme={null}
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
```

<ParamField type="string">
  Phone or shortcode to validate
</ParamField>

<ParamField type="string">
  e.g. `MOBILE`
</ParamField>

<ParamField type="string">
  e.g. `Safaricom`
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "shortcode": "0700123456",
    "type": "MOBILE",
    "network": "Safaricom"
  }
  ```

  ```json 200 Success theme={null}
  {
    "code": 200,
    "message": "Validation results",
    "data": {
      "status": "COMPLETE",
      "shortcode": "0700123456",
      "public_name": "JOHN DOE"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

***

## Status

Fetch a transaction by `transaction_code`.

```
POST /{currency_code}/status
```

<ParamField type="string">
  Transaction reference returned from disburse, collect, or bank transfer
</ParamField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "transaction_code": "fg464gggshshkkk"
  }
  ```

  ```json 200 Success theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": 400,
    "message": "Failed - Bad Request"
  }
  ```
</CodeGroup>

***

## 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.


# API overview
Source: https://docs.pretium.africa/api-reference/overview

Conventions shared across Pretium endpoints.

## Base URL

Examples use `{{base_url}}` as the API host placeholder. The interactive playground is configured with the live Pretium API server.

```
{{base_url}}
```

## Authentication

Send `x-api-key` on every request. See [Authentication](/authentication).

## Content type

```
Content-Type: application/json
```

Checkout endpoints primarily accept **query parameters** even on `POST`.

## Transaction object

Status and list endpoints return resources similar to:

```json theme={null}
{
  "id": 1,
  "transaction_code": "uuid-or-reference",
  "status": "COMPLETE",
  "amount": 1000,
  "amount_in_usd": 7.5,
  "type": "MOBILE",
  "shortcode": "2547...",
  "account_number": null,
  "public_name": "JOHN DOE",
  "receipt_number": "...",
  "category": "DISBURSEMENT",
  "chain": "CELO",
  "asset": "USDT",
  "transaction_hash": "0x...",
  "message": "...",
  "currency_code": "KES",
  "is_released": false,
  "created_at": "2026-07-31T10:00:00.000000Z"
}
```

Country-specific resources may add `mobile_network`, bank fields, etc.

## Statuses

| Domain       | Values                                                               |
| ------------ | -------------------------------------------------------------------- |
| Transactions | `PENDING`, `COMPLETE`, `FAILED`, `REFUNDED`                          |
| Checkout     | `PENDING`, `EXPIRED`, `CANCELLED`, `FAILED`, `COMPLETE`              |
| MCP orders   | `processing`, `pending`, `complete`, `failed`, `expired`, `refunded` |


# Supported banks
Source: https://docs.pretium.africa/api-reference/payments/banks

POST /v1/banks/{currency_code}
List supported banks for a currency (defaults to NGN).

<ParamField type="string">
  Defaults to `NGN` when omitted.
</ParamField>

Returns a list of banks (codes and names) usable with validation and payout fields.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/banks/NGN" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</RequestExample>


# Onramp
Source: https://docs.pretium.africa/api-reference/payments/onramp

POST /v1/onramp/{currency_code}
Collect fiat via mobile money and release stablecoins to an address. Amount limits are per transaction.

Starts a local collection and, after success, releases crypto to the destination wallet.

<ParamField type="string">
  e.g. `KES`, `UGX`, `GHS`, `MWK`, `CDF`.
</ParamField>

<ParamField type="string">
  Customer phone / mobile money number (10 digits for KES/UGX).
</ParamField>

<ParamField type="number">
  Fiat amount to collect. Limits are per transaction — see [Limits](/limits).
</ParamField>

<ParamField type="string">
  Network operator for the market (e.g. `Safaricom`, `Airtel`, `MTN`).
</ParamField>

<ParamField type="string">
  Destination wallet address for released assets.
</ParamField>

<ParamField type="string">
  `BASE` or `CELO`.
</ParamField>

<ParamField type="string">
  `USDC` on BASE; `USDT` on CELO.
</ParamField>

<ParamField type="string">
  Optional webhook URL.
</ParamField>

<ParamField type="string">
  Optional client reference.
</ParamField>

## Amount limits

Per-transaction min/max by currency: [Limits](/limits).

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/onramp/KES" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "shortcode": "254712345678",
      "amount": 500,
      "mobile_network": "Safaricom",
      "address": "0xYourWallet",
      "chain": "BASE",
      "asset": "USDC"
    }'
  ```
</RequestExample>


# Pay (offramp)
Source: https://docs.pretium.africa/api-reference/payments/pay

POST /v1/pay/{currency_code}
Verify an on-chain transfer and disburse local fiat. Amount limits are per transaction.

Offramp endpoint. Provide a `transaction_hash` for a confirmed stablecoin transfer, plus destination details for the target currency.

<ParamField type="string">
  Destination currency. Defaults to Kenya rules when omitted.
</ParamField>

## Common fields

<ParamField type="string">
  On-chain transaction hash. Must not have been processed before.
</ParamField>

<ParamField type="string">
  `BASE`, `CELO` (default), `STELLAR`, `POLYGON`, `SOLANA`, `ETHEREUM`, or `BNB`.
</ParamField>

<ParamField type="number">
  Fiat amount to disburse. Limits are per transaction — see [Limits](/limits).
</ParamField>

<ParamField type="string">
  Optional webhook URL for this transaction.
</ParamField>

<ParamField type="string">
  Optional client reference; a UUID is generated if omitted.
</ParamField>

## Currency-specific fields

### KES

| Field            | Rules                                             |
| ---------------- | ------------------------------------------------- |
| `type`           | `MOBILE`, `PAYBILL`, `BUY_GOODS`, `BANK_TRANSFER` |
| `shortcode`      | Required for mobile / paybill / buy goods         |
| `account_number` | Required for paybill / bank transfer              |
| `mobile_network` | `Safaricom` or `Airtel` when `type=MOBILE`        |
| `amount`         | See [Limits](/limits)                             |

### UGX

| Field            | Rules                 |
| ---------------- | --------------------- |
| `shortcode`      | 10 digits             |
| `mobile_network` | `Airtel` or `MTN`     |
| `amount`         | See [Limits](/limits) |

### NGN

| Field                                                      | Rules                 |
| ---------------------------------------------------------- | --------------------- |
| `account_name`, `account_number`, `bank_name`, `bank_code` | Required              |
| `amount`                                                   | See [Limits](/limits) |

### GHS

| Field            | Rules                          |
| ---------------- | ------------------------------ |
| `shortcode`      | Required                       |
| `mobile_network` | `AirtelTigo`, `MTN`, `Telecel` |
| `amount`         | See [Limits](/limits)          |

### MWK

| Field                                                      | Rules                                             |
| ---------------------------------------------------------- | ------------------------------------------------- |
| `type`                                                     | `MOBILE` or `BANK_TRANSFER`                       |
| `shortcode`                                                | Phone number for `MOBILE`                         |
| `mobile_network`                                           | `Airtel Money` or `TNM Mpamba` when `type=MOBILE` |
| `account_name`, `account_number`, `bank_name`, `bank_code` | For `BANK_TRANSFER`                               |
| `amount`                                                   | See [Limits](/limits)                             |

### CDF

| Field            | Rules                              |
| ---------------- | ---------------------------------- |
| `shortcode`      | Required                           |
| `mobile_network` | `Airtel Money` or `Mpesa`          |
| `amount`         | See [Limits](/limits)              |
| `currency`       | Optional: `CDF` (default) or `USD` |

### ETB

| Field            | Rules                              |
| ---------------- | ---------------------------------- |
| `shortcode`      | Required                           |
| `mobile_network` | `Telebirr`, `Cbe Birr`, or `MPESA` |
| `amount`         | See [Limits](/limits)              |

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/pay/KES" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "transaction_hash": "0xabc123",
      "chain": "CELO",
      "type": "MOBILE",
      "shortcode": "254712345678",
      "amount": 1000,
      "mobile_network": "Safaricom"
    }'
  ```
</RequestExample>


# Refund
Source: https://docs.pretium.africa/api-reference/payments/refund

POST /v1/refund
Initiate a refund/credit flow against a verified on-chain hash.

<ParamField type="string">
  Original on-chain transaction hash.
</ParamField>

<ParamField type="string">
  Chain of the original transfer.
</ParamField>

Verifies the hash and runs the partner refund/credit path when eligible.

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/refund" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "transaction_hash": "0xabc123",
      "chain": "CELO"
    }'
  ```
</RequestExample>


# Transaction status
Source: https://docs.pretium.africa/api-reference/payments/status

POST /v1/status/{currency_code}
Look up a single transaction by transaction_code.

<ParamField type="string">
  Currency namespace for the transaction store (e.g. `KES`, `UGX`).
</ParamField>

<ParamField type="string">
  Transaction code returned when the payment was created.
</ParamField>

Returns a [transaction resource](/api-reference/overview#transaction-object).

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/status/KES" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"transaction_code":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
  ```
</RequestExample>


# List transactions
Source: https://docs.pretium.africa/api-reference/payments/transactions

POST /v1/transactions/{currency_code}
List recent transactions for a currency (optional date window).

When `start_date` / `end_date` are provided, results are limited to a **3-day** window. No pagination — the full matching set is returned.

<ParamField type="string">
  Currency code, e.g. `KES`.
</ParamField>

<ParamField type="string">
  Optional start date (`YYYY-MM-DD`).
</ParamField>

<ParamField type="string">
  Optional end date (`YYYY-MM-DD`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/transactions/KES" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"start_date":"2026-07-28","end_date":"2026-07-30"}'
  ```
</RequestExample>


# Validation
Source: https://docs.pretium.africa/api-reference/payments/validation

POST /v1/validation/{currency_code}
Validate a mobile money shortcode or bank account before payout.

Resolves account names / validity for the destination currency. Defaults to Kenya (`KES`) rules when the path currency is omitted.

<ParamField type="string">
  `KES`, `UGX`, `NGN`, `GHS`, etc.
</ParamField>

## Body by currency

### KES (default)

<ParamField type="string">
  Phone or till / paybill number.
</ParamField>

<ParamField type="string">
  `MOBILE`, `PAYBILL`, or `BUY_GOODS`.
</ParamField>

<ParamField type="string">
  Required for `MOBILE`: `Safaricom` or `Airtel`.
</ParamField>

### UGX

<ParamField type="string">
  10-digit phone number.
</ParamField>

<ParamField type="string">
  `MTN` or `Airtel`.
</ParamField>

### NGN

<ParamField type="string">
  Bank account number.
</ParamField>

<ParamField type="string">
  Bank code from the banks list.
</ParamField>

### GHS

<ParamField type="string">
  10-digit mobile number.
</ParamField>

<ParamField type="string">
  `MTN`, `AirtelTigo`, or `Telecel`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/validation/KES" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "shortcode": "254712345678",
      "type": "MOBILE",
      "mobile_network": "Safaricom"
    }'
  ```
</RequestExample>


# Exchange rate
Source: https://docs.pretium.africa/api-reference/rates/exchange-rate

POST /v1/exchange-rate
Get buying and selling FX rates for a currency.

Returns partner-category FX rates for a supported currency.

<ParamField type="string">
  ISO-style currency code, e.g. `KES`, `UGX`, `NGN`.
</ParamField>

<ResponseField name="code" type="number">
  `200` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status.
</ResponseField>

<ResponseField name="data.buying_rate" type="number">
  Rate used in buying/offramp contexts.
</ResponseField>

<ResponseField name="data.selling_rate" type="number">
  Rate used in selling/onramp contexts.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v1/exchange-rate" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"currency_code":"KES"}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": 200,
    "message": "Exchange rates",
    "data": {
      "buying_rate": 129.5,
      "selling_rate": 131.2
    }
  }
  ```
</ResponseExample>


# Exchange rate (v2)
Source: https://docs.pretium.africa/api-reference/rates/exchange-rate-v2

POST /v2/exchange-rate
FX rates plus onramp/offramp availability flags.

Same rates as v1, with booleans indicating whether ramps are currently active for the market.

<ParamField type="string">
  Currency code such as `KES` or `UGX` (case-insensitive).
</ParamField>

<ResponseField name="data.buying_rate" type="number">
  Buying rate.
</ResponseField>

<ResponseField name="data.selling_rate" type="number">
  Selling rate.
</ResponseField>

<ResponseField name="data.is_offramp_active" type="boolean">
  `true` when offramp is not payment-locked.
</ResponseField>

<ResponseField name="data.is_onramp_active" type="boolean">
  `true` when onramp is not payment-locked.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "{{base_url}}/v2/exchange-rate" \
    -H "x-api-key: YOUR_CONSUMER_KEY" \
    -H "Content-Type: application/json" \
    -d '{"currency_code":"KES"}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": 200,
    "message": "Exchange rates",
    "data": {
      "buying_rate": 129.5,
      "selling_rate": 131.2,
      "is_offramp_active": true,
      "is_onramp_active": true
    }
  }
  ```
</ResponseExample>


# Authentication
Source: https://docs.pretium.africa/authentication

API keys and checkout keys for Pretium.

All partner HTTP APIs authenticate with an API key header.

## Partner API key

Send your portal **consumer key** as:

```
x-api-key: YOUR_CONSUMER_KEY
```

Used by `/v1`, `/v2`, `/account`, `/{currency}`, and `/utility`.

| Status                | Response                                                  |
| --------------------- | --------------------------------------------------------- |
| Missing / invalid key | `401` `{ "code": 401, "message": "Unauthorized" }`        |
| Partner deactivated   | `403` `{ "code": 403, "message": "Account deactivated" }` |

## Checkout key

Checkout endpoints under `/v1/checkout` use your portal **checkout key** in the same header:

```
x-api-key: YOUR_CHECKOUT_KEY
```

Do not use the consumer key on checkout routes (and vice versa).

## AI agents (MCP)

Cursor, Claude, and ChatGPT do not call these headers directly. Configure the [Pretium MCP server](/guides/agents); it uses your partner API key (and secret key for `register_agent`) on your behalf.

## Request headers

| Header         | Required          | Value                        |
| -------------- | ----------------- | ---------------------------- |
| `x-api-key`    | Yes               | Consumer key or checkout key |
| `Content-Type` | Yes (JSON bodies) | `application/json`           |

## IP allowlisting

You can register allowed IPs in the partner portal. Prefer allowing only your production egress IPs.

## Keys in the portal

From the merchant portal you can:

* View / rotate the consumer key
* View the checkout key
* View the secret key (for MCP `register_agent`)
* Configure webhook URLs and IP allowlists


# Errors
Source: https://docs.pretium.africa/errors

Standard error envelope and common failure modes.

## Envelope

```json theme={null}
{
  "code": 400,
  "message": "The amount field is required."
}
```

Success responses add a `data` field:

```json theme={null}
{
  "code": 200,
  "message": "OK",
  "data": {}
}
```

| HTTP / `code` | Meaning                             |
| ------------- | ----------------------------------- |
| `200`         | Success                             |
| `201`         | Created                             |
| `400`         | Validation or business-rule failure |
| `401`         | Invalid or missing API key          |
| `403`         | Account deactivated or forbidden    |
| `404`         | Resource not found                  |

## Common messages

| Message                                               | Cause                                                            |
| ----------------------------------------------------- | ---------------------------------------------------------------- |
| `Unauthorized`                                        | Bad `x-api-key`                                                  |
| `Account deactivated`                                 | Partner status off                                               |
| `Country not supported.`                              | Unknown `currency_code`                                          |
| `Destination country not defined in payment gateway!` | Unsupported currency on `/v1/pay`                                |
| `Unsupported network. Allowed networks: ...`          | Invalid `chain`                                                  |
| Hash already processed                                | `transaction_hash` reused (idempotent block via `master_hashes`) |
| Payment lock / maintenance messages                   | Country ramp temporarily disabled                                |

Validation failures usually return the first Laravel validator error string as `message`.

## Idempotency

* Optional `reference` — if omitted, a UUID is generated for many money-moving calls.
* `transaction_hash` — cannot be processed twice for offramp / checkout settlement.
* Checkout `order_id` — must be unique per partner order.

There is no general `Idempotency-Key` header.


# Fee
Source: https://docs.pretium.africa/fee

Collect a partner facilitation fee on collection, disbursement, offramp, and onramp requests.

The `fee` field allows Pretium to collect fees on your behalf.

## Example

If your UI charges a **1% facilitation fee** and a user wants to offramp **KES 1,000** (resulting in a **KES 10** fee):

### Steps

1. Deduct the equivalent of **KES 1,010** from the user’s wallet.
2. Submit the following parameters in your API request:

```json theme={null}
{
  "amount": 1010,
  "fee": 10
}
```

Pretium’s payment protocol will send **KES 1,000** to the user and credit **KES 10** to your fiat wallet.

## Onramp

The reverse applies during onramping — if User B wants to onramp **KES 1,000** and you include a fee of **10**, Pretium API will initiate a collection of **KES 1,010** from the user, credit **KES 10** to your fiat wallet upon confirmation, and release assets equivalent to **KES 1,000** to the user’s address.

## Where to send `fee`

Include `fee` (optional number) on money-moving requests such as:

* `POST /v1/pay/{currency}` and `POST /v1/onramp/{currency}` — [Offramp](/guides/offramp) / [Onramp](/guides/onramp)

`amount` is the **gross** amount (recipient + fee). `fee` is the portion credited to your partner fiat wallet.


# AI agents (MCP)
Source: https://docs.pretium.africa/guides/agents

Add Pretium as an MCP server in Cursor, Claude, or ChatGPT so agents can pay across African rails.

Pretium ships a **Model Context Protocol (MCP)** server so AI tools can call payment capabilities as tools — not as a REST API you wire into your app.

Connect it once in **Cursor**, **Claude**, or **ChatGPT**. Your agent can then register a Pretium agent, set spend limits, validate recipients, check balances, and send fiat or stablecoin payouts through normal chat.

Hosted endpoint: [`https://mcp.pretium.africa/mcp`](https://mcp.pretium.africa/mcp)\
Open source: [github.com/derrickbundi/pretium-mcp](https://github.com/derrickbundi/pretium-mcp)

## What agents can do

| Capability          | Tools                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| FX rates            | `get_exchange_rates`                                                                                           |
| Off-ramp orders     | `create_order`, `confirm_order`, `get_order_status`                                                            |
| Validate recipients | `validate_phone_number`, `validate_bank_account`                                                               |
| Agent lifecycle     | `register_agent`, `create_agent_spend_policy`, `get_agent`                                                     |
| Balances & payouts  | `get_agent_balance`, `agent_create_fiat_order`, `get_agent_fiat_order_status`, `agent_create_stablecoin_order` |

Fiat agent payouts today: **KES**, **UGX**, **NGN** (mobile money, paybill, buy goods, bank transfer). Stablecoins: **USDT/USDC** on **Celo**, **Base**, **BNB**.

## Prerequisites

1. A Pretium **partner** account and **API key** (used by the MCP server as `x-api-key`).
2. For agent tools: a partner **secret key** from the portal (used by `register_agent`).
3. An ERC-20 settlement wallet configured in the partner portal (for agent stablecoin flows).

You do **not** call `/mcp/agent/*` HTTP routes from your product. The MCP server wraps those for the AI client.

## Add in Cursor

1. Open **Cursor Settings → MCP** (or edit `~/.cursor/mcp.json` / project `.cursor/mcp.json`).
2. Add the Pretium server:

```json theme={null}
{
  "mcpServers": {
    "pretium": {
      "url": "https://mcp.pretium.africa/mcp"
    }
  }
}
```

For a local [pretium-mcp](https://github.com/derrickbundi/pretium-mcp) instance:

```json theme={null}
{
  "mcpServers": {
    "pretium": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

3. Restart Cursor (or reload MCP). You should see Pretium tools listed under the server.
4. Ask the agent things like: “Register my Pretium agent and check the UGX balance.”

Also listed on [cursor.directory](https://cursor.directory/plugins/pretium-mcp) for discovery.

## Add in Claude

### Claude Desktop

Edit your Claude Desktop MCP config (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "pretium": {
      "url": "https://mcp.pretium.africa/mcp"
    }
  }
}
```

Restart Claude Desktop. Pretium tools appear in the MCP tools list for the conversation.

### Claude Code / CLI

```bash theme={null}
claude mcp add --transport http pretium https://mcp.pretium.africa/mcp
```

If your Claude build only supports stdio MCP, run [pretium-mcp](https://github.com/derrickbundi/pretium-mcp) locally and point the client at its Streamable HTTP or SSE URL (see below).

## Add in ChatGPT

1. Open ChatGPT settings for **Apps / Connectors** (or Custom GPT actions that support MCP, depending on your plan).
2. Add a new MCP connector with URL:

```
https://mcp.pretium.africa/mcp
```

3. Allow the Pretium tools you need (rates, validation, agent payouts).
4. In chat, instruct the model to use Pretium for African payouts — for example: “Validate this Safaricom number, then pay 500 KES from my agent.”

If ChatGPT requires OAuth or a verified connector for remote MCP, use a self-hosted [pretium-mcp](https://github.com/derrickbundi/pretium-mcp) behind your own auth, or contact [hello@pretium.africa](mailto:hello@pretium.africa) for partner MCP access.

## Self-host (optional)

```bash theme={null}
git clone https://github.com/derrickbundi/pretium-mcp
cd pretium-mcp
npm install
# set PRETIUM_API_KEY (and optional PRETIUM_API_BASE_URL) in .env
npm run dev
```

| Transport       | URL                                                | Clients                 |
| --------------- | -------------------------------------------------- | ----------------------- |
| Streamable HTTP | `POST http://localhost:3000/mcp`                   | Cursor, modern Claude   |
| SSE             | `GET http://localhost:3000/sse` + `POST /messages` | Legacy SSE-only clients |

Do not expose a self-hosted MCP publicly without auth — it acts with your partner API key.

## Typical chat workflows

**Register and pay fiat**

```text theme={null}
register_agent → create_agent_spend_policy → validate_phone_number
  → agent_create_fiat_order → get_agent_fiat_order_status
```

**Stablecoin transfer**

```text theme={null}
register_agent → create_agent_spend_policy → get_agent_balance
  → agent_create_stablecoin_order
```

**Off-ramp (crypto → fiat)**

```text theme={null}
create_order → (user pays on-chain) → confirm_order → get_order_status
```

Approvals above auto-approve limits are handled in the [partner portal](https://merchant.xwift.africa).

## Fiat payout field cheat sheet

| `type`          | Required fields                               |
| --------------- | --------------------------------------------- |
| `mobile`        | `shortcode`, `mobile_network`                 |
| `paybill`       | `shortcode`, `account_number`                 |
| `buy_goods`     | `shortcode`                                   |
| `bank_transfer` | `bank_code`, `account_number`, `account_name` |

| Currency | Allowed types                                     |
| -------- | ------------------------------------------------- |
| UGX      | `mobile` only                                     |
| KES      | `mobile`, `paybill`, `buy_goods`, `bank_transfer` |
| NGN      | `bank_transfer` only                              |

## REST Pretium vs MCP

|          | Pretium (this docs site)             | Pretium MCP                                                  |
| -------- | ------------------------------------ | ------------------------------------------------------------ |
| Audience | Your backend / product               | Cursor, Claude, ChatGPT agents                               |
| Auth     | `x-api-key` on each HTTP call        | MCP server holds the key; tools are invoked by the AI client |
| Shape    | REST JSON under `/v1`, `/account`, … | MCP tools (`register_agent`, `create_order`, …)              |

Use the [Pretium API reference](/api-reference/overview) when you are building a product integration. Use **MCP** when you want an AI assistant to operate Pretium for you.


# Checkout
Source: https://docs.pretium.africa/guides/checkout

Hosted settlement flow using your checkout key.

Checkout creates a short-lived order (about **7 minutes**) with a settlement address. The payer sends assets on-chain; you confirm with the transaction hash.

## Auth

Use your **checkout key** as `x-api-key` (not the consumer key).

## Flow

1. [`POST /v1/checkout/`](/api-reference/checkout/create) — create order (`network`, `asset`, `currency_code`, `amount`, `order_id`).
2. Show the returned settlement `address` and amount to the payer.
3. [`POST /v1/checkout/pay`](/api-reference/checkout/pay) — submit `order_id` + `transaction_hash` after on-chain payment.
4. [`POST /v1/checkout/status`](/api-reference/checkout/status) — poll until `COMPLETE`, `EXPIRED`, `FAILED`, or `CANCELLED`.

Query parameters are used on these POST endpoints (not only JSON body).

## Statuses

`PENDING` → `COMPLETE` | `EXPIRED` | `CANCELLED` | `FAILED`

## Networks

List supported settlement networks with [`POST /v1/checkout/networks`](/api-reference/checkout/networks).

## Webhooks

On completion or failure Pretium may POST:

```json theme={null}
{
  "status": "COMPLETE",
  "order_id": "order_123",
  "message": "Settlement complete"
}
```


# Collection & disbursements
Source: https://docs.pretium.africa/guides/collection-and-disbursements

Wallet-funded collection and disbursement under currency prefixes.

Collection and disbursement APIs move fiat from your Pretium wallet balance — **without** an on-chain `transaction_hash`.

They share the same body shape as offramp / onramp, except `transaction_hash` and `chain` are omitted.

Top up that balance with crypto via [`POST /account/fund`](/api-reference/account/fund) then [`POST /account/fund/confirm`](/api-reference/account/fund-confirm).

## Core endpoints

| Action        | Method | Path                             |
| ------------- | ------ | -------------------------------- |
| Disburse      | `POST` | `/{currency_code}/disburse`      |
| Collect       | `POST` | `/{currency_code}/collect`       |
| Banks         | `POST` | `/{currency_code}/banks`         |
| Bank info     | `POST` | `/{currency_code}/bank-infor`    |
| Bank transfer | `POST` | `/{currency_code}/bank-transfer` |
| Status        | `POST` | `/{currency_code}/status`        |

Full request and response examples: **[Collection & disbursement](/api-reference/countries/collection-and-disbursement)**.

## Auth

`x-api-key` = partner consumer key.

## Currency prefixes

| Prefix | Market             |
| ------ | ------------------ |
| `/kes` | Kenya              |
| `/ugx` | Uganda             |
| `/ngn` | Nigeria            |
| `/ghs` | Ghana              |
| `/mwk` | Malawi             |
| `/cdf` | DR Congo           |
| `/etb` | Ethiopia           |
| `/tzs` | Tanzania           |
| `/zmw` | Zambia             |
| `/rwf` | Rwanda (utilities) |

## When to use `/v1` instead

| Use `/v1` pay / onramp              | Use `/{currency_code}` collection & disbursement |
| ----------------------------------- | ------------------------------------------------ |
| Settling with on-chain hashes       | Wallet-funded local rails                        |
| Crypto → fiat or fiat → crypto      | Fiat in / out only                               |
| Single cross-market product surface | Market-specific collect / disburse               |

## Payment locks

Collections and disbursements can be temporarily locked per country (`400` with a maintenance-style message). Check [`POST /v2/exchange-rate`](/api-reference/rates/exchange-rate-v2) for ramp flags on the unified API.


# Offramp
Source: https://docs.pretium.africa/guides/offramp

Convert on-chain stablecoin deposits into local fiat payouts. Amount limits are per transaction.

Offramp uses the unified `/v1` API: verify an on-chain transfer, then disburse to mobile money or bank accounts.

## Flow

```mermaid theme={null}
sequenceDiagram
  participant App as Your backend
  participant Chain as Blockchain
  participant API as Pretium API
  participant Rail as Mobile money / bank

  App->>API: POST /v1/validation/{currency}
  API-->>App: Account name / validity
  Note over App,Chain: Customer sends USDT/USDC
  App->>API: POST /v1/pay/{currency} + transaction_hash
  API->>Chain: Verify hash
  API->>Rail: Disburse fiat
  API-->>App: Status + transaction_code
  API->>App: Webhook (optional)
```

## Steps

1. **Validate** the destination with [`POST /v1/validation/{currency_code}`](/api-reference/payments/validation).
2. **Quote** with [`POST /v1/exchange-rate`](/api-reference/rates/exchange-rate) or v2 for ramp locks.
3. Customer (or your treasury) sends stablecoins to our settlement address on a supported network.
4. Call [`POST /v1/pay/{currency_code}`](/api-reference/payments/pay) with `transaction_hash` and payout fields.
5. Poll [`POST /v1/status/{currency_code}`](/api-reference/payments/status) or handle [webhooks](/webhooks).

## Supported networks (pay)

`BASE`, `CELO` (default), `STELLAR`, `POLYGON`, `SOLANA`, `ETHEREUM`, `BNB`, `AVALANCHE`, `ARBITRUM`

## Amount limits (pay)

Per-transaction min/max by currency and mobile money network: [Limits](/limits).

## Example (KES mobile)

```bash theme={null}
curl -X POST "{{base_url}}/v1/pay/KES" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_hash": "0xabc...",
    "chain": "CELO",
    "type": "MOBILE",
    "shortcode": "254712345678",
    "amount": 1000,
    "mobile_network": "Safaricom",
    "callback_url": "https://example.com/hooks/pretium"
  }'
```

Reuse of the same `transaction_hash` is rejected once it has been processed.


# Onramp
Source: https://docs.pretium.africa/guides/onramp

Collect local fiat and settle stablecoins to a wallet. Amount limits are per transaction.

Onramp collects mobile money (or similar) from a customer, then releases crypto to an address you provide.

## Flow

1. Call [`POST /v1/onramp/{currency_code}`](/api-reference/payments/onramp) with phone/network, amount, destination `address`, `chain`, and `asset`.
2. Customer completes the collection prompt (e.g. STK push).
3. Poll status or wait for a webhook; when collection completes, assets are released on-chain.

## Networks & assets

| Chain  | Asset  |
| ------ | ------ |
| `BASE` | `USDC` |
| `CELO` | `USDT` |

Only `BASE` and `CELO` are accepted for onramp.

## Amount limits

Per-transaction min/max by currency and mobile money network: [Limits](/limits).

## Example (KES)

```bash theme={null}
curl -X POST "{{base_url}}/v1/onramp/KES" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcode": "254712345678",
    "amount": 500,
    "mobile_network": "Safaricom",
    "address": "0xYourWallet",
    "chain": "BASE",
    "asset": "USDC",
    "callback_url": "https://example.com/hooks/pretium"
  }'
```

Check [`POST /v2/exchange-rate`](/api-reference/rates/exchange-rate-v2) for `is_onramp_active` before starting collections.


# Introduction
Source: https://docs.pretium.africa/index

Pretium — move value between stablecoins and African fiat rails.

<img alt="Pretium stablecoin and African payment rails" />

Pretium (served at `{{base_url}}`) lets partners collect and disburse fiat across African markets, settle with stablecoins on-chain, and run hosted checkout. For AI assistants, add Pretium as an [MCP server](/guides/agents) in Cursor, Claude, or ChatGPT — no REST agent integration required.

## Onboarding process

To begin your onboarding journey, complete this quick [form](https://docs.google.com/forms/d/1MWxinUbcGBOYJxaEZMCYJCJhBxrlNozAWYvwctFJtHY/edit) to get started, or book a meeting [here](https://calendly.com/pretium-finance) with our team for a walkthrough or to address any questions you may have.

Once we get your details, our onboarding specialists will guide you through **the setup, verification, and integration of your account and API**.

Once onboarded, you'll receive your **API credentials** and **sandbox access** to test crypto transactions securely.

## What you can build

<CardGroup>
  <Card title="Offramp" icon="arrow-up-from-bracket" href="/guides/offramp">
    Convert on-chain stablecoin payments into mobile money or bank payouts.
  </Card>

  <Card title="Onramp" icon="arrow-down-to-bracket" href="/guides/onramp">
    Collect local fiat and settle stablecoins to a wallet address.
  </Card>

  <Card title="Checkout" icon="cart-shopping" href="/guides/checkout">
    Hosted settlement flow with a checkout key and order lifecycle.
  </Card>

  <Card title="AI agents (MCP)" icon="robot" href="/guides/agents">
    Add Pretium in Cursor, Claude, or ChatGPT and let agents pay via MCP tools.
  </Card>
</CardGroup>

## Supported markets

| Currency | Country  | Prefix                |
| -------- | -------- | --------------------- |
| KES      | Kenya    | `/kes`, `/v1/.../KES` |
| UGX      | Uganda   | `/ugx`                |
| NGN      | Nigeria  | `/ngn`                |
| GHS      | Ghana    | `/ghs`                |
| MWK      | Malawi   | `/mwk`                |
| CDF      | DR Congo | `/cdf`                |
| ETB      | Ethiopia | `/etb`                |
| TZS      | Tanzania | `/tzs`                |
| ZMW      | Zambia   | `/zmw`                |
| RWF      | Rwanda   | `/rwf` (utilities)    |

## API surfaces

| Surface                   | Base path                   | Auth header value                           |
| ------------------------- | --------------------------- | ------------------------------------------- |
| Unified payments          | `/v1`, `/v2`                | Partner `consumer_key`                      |
| Account                   | `/account`                  | Partner `consumer_key`                      |
| Collection & disbursement | `/{currency}`               | Partner `consumer_key`                      |
| Checkout                  | `/v1/checkout`              | Partner `checkout_key`                      |
| AI agents                 | [MCP guide](/guides/agents) | MCP server (`mcp.pretium.africa`), not REST |

Almost all partner Pretium endpoints are **POST** with a JSON body.

## Response envelope

Successful and error responses share a consistent shape:

```json theme={null}
{
  "code": 200,
  "message": "Exchange rates",
  "data": {}
}
```

Errors omit `data` and use `400`, `401`, `403`, or `404` in both the HTTP status and `code` field.

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Make your first authenticated request in under five minutes.
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    How API keys and checkout keys work for Pretium.
  </Card>
</CardGroup>


# Limits
Source: https://docs.pretium.africa/limits

Per-transaction amount limits by country and mobile money for pay (offramp) and onramp.

Amount limits for the unified `/v1` pay (offramp) and onramp APIs. All values are **per transaction**, in local fiat currency.

Limits apply at the country/currency level — every mobile money operator in that market shares the same min and max. See [MNOs](/mnos) for supported networks by country.

## Kenya (KES)

| Flow          | Min | Max     | Networks          |
| ------------- | --- | ------- | ----------------- |
| Pay (offramp) | 20  | 250,000 | Safaricom, Airtel |
| Onramp        | 100 | 250,000 | Safaricom, Airtel |

## Uganda (UGX)

| Flow          | Min | Max       | Networks    |
| ------------- | --- | --------- | ----------- |
| Pay (offramp) | 500 | 5,000,000 | MTN, Airtel |
| Onramp        | 500 | 5,000,000 | MTN, Airtel |

## Ghana (GHS)

| Flow          | Min | Max   | Networks                 |
| ------------- | --- | ----- | ------------------------ |
| Pay (offramp) | 5   | 1,000 | MTN, AirtelTigo, Telecel |
| Onramp        | 10  | 5,000 | MTN, AirtelTigo, Telecel |

## Malawi (MWK)

| Flow          | Min   | Max       | Networks                 |
| ------------- | ----- | --------- | ------------------------ |
| Pay (offramp) | 100   | 5,000,000 | Airtel Money, TNM Mpamba |
| Onramp        | 2,000 | 5,000,000 | Airtel, TNM Mpamba       |

## DR Congo (CDF)

| Flow          | Min   | Max     | Networks            |
| ------------- | ----- | ------- | ------------------- |
| Pay (offramp) | 2,800 | 280,000 | Airtel Money, Mpesa |
| Onramp        | 2,800 | 280,000 | Airtel Money, Mpesa |

## Ethiopia (ETB)

| Flow          | Min | Max   | Networks                  |
| ------------- | --- | ----- | ------------------------- |
| Pay (offramp) | 5   | 5,000 | Telebirr, Cbe Birr, MPESA |

## Nigeria (NGN)

| Flow          | Min | Max       | Networks  |
| ------------- | --- | --------- | --------- |
| Pay (offramp) | 100 | 1,000,000 | All banks |


# MNOs
Source: https://docs.pretium.africa/mnos

Mobile network operators and bank rails supported by Pretium per country.

Supported mobile money operators and bank rails by market. Exact values for API fields (e.g. `mobile_network`) can vary by endpoint — use the currency-specific rules on [Pay](/api-reference/payments/pay) and [Onramp](/api-reference/payments/onramp).

For per-transaction amount limits by country, see [Limits](/limits).

<div>
  <div>
    <div>Kenya</div>

    <div>
      <Badge>Safaricom</Badge>
      <Badge>Airtel</Badge>
      <Badge>All banks</Badge>
    </div>
  </div>

  <div>
    <div>DR Congo</div>

    <div>
      <Badge>Airtel Money</Badge>
      <Badge>Mpesa</Badge>
      <Badge>Orange Money</Badge>
    </div>
  </div>

  <div>
    <div>Uganda</div>

    <div>
      <Badge>MTN</Badge>
      <Badge>Airtel</Badge>
    </div>
  </div>

  <div>
    <div>Malawi</div>

    <div>
      <Badge>Airtel</Badge>
      <Badge>TNM Mpamba</Badge>
    </div>
  </div>

  <div>
    <div>Nigeria</div>

    <div>
      <Badge>All banks</Badge>
    </div>
  </div>

  <div>
    <div>Ghana</div>

    <div>
      <Badge>MTN</Badge>
      <Badge>AirtelTigo</Badge>
      <Badge>Telecel</Badge>
    </div>
  </div>

  <div>
    <div>Ethiopia</div>

    <div>
      <Badge>Telebirr</Badge>
      <Badge>Cbe Birr</Badge>
      <Badge>MPESA</Badge>
    </div>
  </div>
</div>


# Networks
Source: https://docs.pretium.africa/networks

Blockchain networks and stablecoin assets supported by Pretium.

Settle offramp, onramp, and checkout with these chains and assets. Availability can differ by product and partner account — confirm what is enabled for you before going live.

<div>
  <div>
    <div>CELO</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>BASE</div>

    <div>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>STELLAR</div>

    <div>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>SOLANA</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>POLYGON</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>ETHEREUM</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>BNB (BSChain)</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>AVALANCHE</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>

  <div>
    <div>ARBITRUM</div>

    <div>
      <Badge>USDT</Badge>
      <Badge>USDC</Badge>
    </div>
  </div>
</div>

<Note>
  Product surfaces (offramp, onramp, checkout, MCP) may expose a subset of this list. Use [`POST /account/networks`](/api-reference/account/networks) or the [partner portal](https://merchant.xwift.africa) for the networks enabled on your account. Checkout also has [`POST /v1/checkout/networks`](/api-reference/checkout/networks).
</Note>


# Onboarding process
Source: https://docs.pretium.africa/onboarding

Apply for a Pretium partner account and get API credentials.

To begin your onboarding journey, complete this quick [form](https://docs.google.com/forms/d/1MWxinUbcGBOYJxaEZMCYJCJhBxrlNozAWYvwctFJtHY/edit) to get started, or book a meeting [here](https://calendly.com/pretium-finance) with our team for a walkthrough or to address any questions you may have.

Once we get your details, our onboarding specialists will guide you through **the setup, verification, and integration of your account and API**.

Once onboarded, you'll receive your **API credentials** and **sandbox access** to test crypto transactions securely.

## Next steps

After you have credentials:

1. [Quickstart](/quickstart) — make your first authenticated request
2. [Authentication](/authentication) — how API keys and checkout keys work
3. [Networks](/networks) — chains and assets available to your account


# Quickstart
Source: https://docs.pretium.africa/quickstart

Authenticate and fetch an exchange rate in a few minutes.

## 1. Get your API key

Sign in to the [partner portal](https://merchant.xwift.africa) and copy your **consumer key** from API keys. You will send it as the `x-api-key` header on every partner request.

## 2. Fetch an exchange rate

```bash theme={null}
curl -X POST "{{base_url}}/v1/exchange-rate" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency_code":"KES"}'
```

Example response:

```json theme={null}
{
  "code": 200,
  "message": "Exchange rates",
  "data": {
    "buying_rate": 129.5,
    "selling_rate": 131.2
  }
}
```

* **Buying rate** — used when you buy fiat with crypto (offramp pricing context).
* **Selling rate** — used when you sell fiat for crypto (onramp pricing context).

For ramp availability flags, use [`POST /v2/exchange-rate`](/api-reference/rates/exchange-rate-v2).

## 3. Typical offramp flow

1. Validate the destination with [`POST /v1/validation/{currency}`](/api-reference/payments/validation).
2. Receive a stablecoin payment on a supported chain.
3. Call [`POST /v1/pay/{currency}`](/api-reference/payments/pay) with the `transaction_hash` and payout details.
4. Poll [`POST /v1/status/{currency}`](/api-reference/payments/status) or wait for a [webhook](/webhooks).

See the [offramp guide](/guides/offramp) for currency-specific fields and limits.

## 4. Explore further

| Goal                                   | Start here                                                         |
| -------------------------------------- | ------------------------------------------------------------------ |
| Collect fiat → send crypto             | [Onramp guide](/guides/onramp)                                     |
| Hosted settlement UI                   | [Checkout guide](/guides/checkout)                                 |
| AI agents in Cursor / Claude / ChatGPT | [MCP guide](/guides/agents)                                        |
| Direct mobile money / bank rails       | [Collection & disbursements](/guides/collection-and-disbursements) |


# Webhooks
Source: https://docs.pretium.africa/webhooks

Outbound callbacks for transaction and checkout status.

Pretium posts JSON to your callback URL when a payment reaches a terminal or updated state. Configure a default webhook in the partner portal, and/or pass `callback_url` per request.

## Delivery

* Method: `POST`
* Timeout: \~3 seconds connect + read
* Retries: not guaranteed on failure (failed deliveries are logged; you can recall some callbacks from the portal)

Always treat webhooks as **at-least-once** hints and reconcile with the status API.

## Transaction callback

Typical payload for collect / disburse / offramp flows:

```json theme={null}
{
  "status": "COMPLETE",
  "transaction_code": "a1b2c3d4-....",
  "receipt_number": "QJK7...",
  "message": "Payment successful",
  "public_name": "JOHN DOE"
}
```

| Field              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `status`           | e.g. `COMPLETE`, `FAILED`, `PENDING`, `PROCESSING` |
| `transaction_code` | Your reference / Pretium transaction id            |
| `receipt_number`   | Provider receipt when available                    |
| `message`          | Human-readable status detail                       |
| `public_name`      | Resolved account / wallet name when available      |

## Checkout callback

```json theme={null}
{
  "status": "COMPLETE",
  "order_id": "order_123",
  "message": "Settlement complete"
}
```

`status` may be `COMPLETE` or `FAILED` (and related checkout states during the lifecycle).

## Verifying outcomes

Do not trust the webhook alone for money movement. Confirm with:

* [`POST /v1/status/{currency}`](/api-reference/payments/status)
* [`POST /account/{country_code}/transaction`](/api-reference/account/transaction)
* [`POST /v1/checkout/status`](/api-reference/checkout/status)
* For AI agent payouts: use MCP tools such as `get_order_status` / `get_agent_fiat_order_status` ([MCP guide](/guides/agents))