Pretium SDK

A Node.js/TypeScript client library for the Pretium API — enabling off-ramp, on-ramp, and fiat disbursement operations across Africa.

Installation

npm install pretium

Initialization

const { Pretium, PretiumError } = require('pretium');

const pretium = new Pretium({ apiKey: 'YOUR_API_KEY' });

Response Envelope

All API responses follow a consistent wrapper format:

{
  "code": 200,
  "message": "Human-readable description",
  "data": { }
}

| Field | Type | Description | |-----------|--------------------|-------------------------------------------------| | code | number | HTTP status code (200 for success) | | message | string | Human-readable description of the result | | data | object \| array | The response payload (object, array, or null) |

Error Handling

All methods throw a PretiumError on failure.

try {
  const account = await pretium.getAccount();
} catch (err) {
  if (err instanceof PretiumError) {
    console.error(`[${err.code}]: ${err.message}`);
  }
}

PretiumError shape:

| Field | Type | Description | |-----------|----------|----------------------------| | code | number | HTTP or API error code | | message | string | Human-readable description |

Error response example:

{
  "code": 400,
  "message": "Invalid account number",
  "data": null
}

API Reference

getAccount()

Returns the authenticated account's profile, wallets, and connected networks.

const account = await pretium.getAccount();

Expected Response:

{
  "code": 200,
  "message": "Account details retrieved successfully",
  "data": {
    "id": 42,
    "name": "Acme Corp",
    "email": "[email protected]",
    "status": "ACTIVE",
    "checkoutKey": "ck_live_xxxxxxxxxxxxxxxx",
    "wallets": [
      {
        "currency": "KES",
        "balance": "1500.00",
        "countryName": "Kenya"
      },
      {
        "currency": "NGN",
        "balance": "50000.00",
        "countryName": "Nigeria"
      }
    ],
    "networks": [
      {
        "name": "CELO",
        "icon": "https://cdn.pretium.africa/icons/celo.png",
        "settlementWalletAddress": "0x3Eaab84B42F9fCf2A9B3f2FDB83572B4153eE958",
        "checkoutStatus": true,
        "assets": [
          { "name": "USDT", "contractAddress": "0x617f3112bf5397D0467D315cC709EF968D9ba546" },
          { "name": "USDC", "contractAddress": "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B" }
        ]
      }
    ],
    "createdAt": "2024-03-15T08:00:00.000Z"
  }
}

getCountries()

Returns a list of all supported countries.

const countries = await pretium.getCountries();

Expected Response:

{
  "code": 200,
  "message": "List of countries",
  "data": [
    {
      "id": 1,
      "name": "Kenya",
      "currencyCode": "KES",
      "phoneCode": "+254"
    },
    {
      "id": 2,
      "name": "Nigeria",
      "currencyCode": "NGN",
      "phoneCode": "+234"
    },
    {
      "id": 3,
      "name": "Ghana",
      "currencyCode": "GHS",
      "phoneCode": "+233"
    }
  ]
}

getExchangeRates(params)

Returns the current exchange rate from USD to a target currency.

const rate = await pretium.getExchangeRates({ to: 'KES', buyingRate: true });

Parameters:

| Param | Type | Description | |--------------|-----------|---------------------------------------------| | to | string | Target currency code (e.g. "KES") | | buyingRate | boolean | true for buying rate, false for selling |

Expected Response:

{
  "code": 200,
  "message": "Exchange rate retrieved successfully",
  "data": {
    "from": "USD",
    "to": "KES",
    "rate": 129.50
  }
}

getNetworks()

Returns all supported blockchain networks and their available assets.

const networks = await pretium.getNetworks();

Expected Response:

{
  "code": 200,
  "message": "List of networks",
  "data": [
    {
      "name": "CELO",
      "icon": "https://cdn.pretium.africa/icons/celo.png",
      "settlementWalletAddress": "0x3Eaab84B42F9fCf2A9B3f2FDB83572B4153eE958",
      "checkoutStatus": true,
      "assets": [
        { "name": "USDT", "contractAddress": "0x617f3112bf5397D0467D315cC709EF968D9ba546" },
        { "name": "USDC", "contractAddress": "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B" }
      ]
    },
    {
      "name": "POLYGON",
      "icon": "https://cdn.pretium.africa/icons/polygon.png",
      "settlementWalletAddress": "0xABCDEF1234567890ABCDEF1234567890ABCDEF12",
      "checkoutStatus": true,
      "assets": [
        { "name": "USDT", "contractAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F" }
      ]
    }
  ]
}

getWallets(params)

Returns the wallet balance for a specific country.

const wallet = await pretium.getWallets({ countryId: 1 }); // 1 = Kenya

Parameters:

| Param | Type | Description | |-------------|----------|----------------------------------------| | countryId | number | ID of the country (e.g. 1 for Kenya) |

Expected Response:

{
  "code": 200,
  "message": "Wallet retrieved successfully",
  "data": {
    "currency": "KES",
    "balance": "1500.00",
    "countryName": "Kenya"
  }
}

getSupportedBanks(params)

Returns a list of banks supported for transfers in a given country.

const banks = await pretium.getSupportedBanks({ countryCode: 'KE' });

Parameters:

| Param | Type | Description | |---------------|----------|----------------------------------| | countryCode | string | ISO 3166-1 alpha-2 country code |

Expected Response:

{
  "code": 200,
  "message": "List of banks",
  "data": [
    { "Code": "000019", "Name": "Equity Bank" },
    { "Code": "000011", "Name": "KCB Bank" },
    { "Code": "000012", "Name": "Co-operative Bank" },
    { "Code": "000013", "Name": "Absa Bank Kenya" }
  ]
}

validatePhoneNumber(params)

Validates a mobile money phone number before initiating a disbursement.

const result = await pretium.validatePhoneNumber({
  currencyCode: 'KES',
  type: 'MOBILE',
  shortCode: '0704333650',
  mobileNetwork: 'Safaricom',
});

Parameters:

| Param | Type | Description | |-----------------|----------|----------------------------------------------| | currencyCode | string | Currency of the transaction (e.g. "KES") | | type | string | Payment type (e.g. "MOBILE") | | shortCode | string | Phone number in local format | | mobileNetwork | string | Mobile network operator (e.g. "Safaricom") |

Expected Response:

{
  "code": 200,
  "message": "Phone number validated successfully",
  "data": {
    "valid": true,
    "name": "John Doe",
    "shortCode": "0704333650",
    "mobileNetwork": "Safaricom",
    "currencyCode": "KES"
  }
}

validateAccountNigeria(params)

Validates a Nigerian bank account number before initiating a transfer.

const result = await pretium.validateAccountNigeria({
  accountNumber: '8536409',
  bankCode: '100033',
});

Parameters:

| Param | Type | Description | |-----------------|----------|---------------------| | accountNumber | string | Bank account number | | bankCode | string | Bank code |

Expected Response:

{
  "code": 200,
  "message": "Account validated successfully",
  "data": {
    "accountNumber": "8536409",
    "accountName": "Jane Smith",
    "bankCode": "100033",
    "bankName": "Zenith Bank"
  }
}

initiateDisburse(params)

Initiates a mobile money disbursement (send money, paybill, or till).

Mobile (Send Money)

const result = await pretium.initiateDisburse({
  type: 'MOBILE',
  shortCode: '0704333650',
  mobileNetwork: 'Safaricom',
  amount: '20',
  fee: '0',
  chain: 'CELO',
  transactionHash: '0x55a572efe...',
  callbackUrl: 'https://your-server.com/callback',
  currencyCode: 'KES',
});

Paybill

const result = await pretium.initiateDisburse({
  type: 'PAYBILL',
  shortCode: '247247',
  accountNumber: '011001100',
  mobileNetwork: 'Safaricom',
  amount: '20',
  fee: '0',
  chain: 'CELO',
  transactionHash: '0x55a572efe...',
  callbackUrl: 'https://your-server.com/callback',
  currencyCode: 'KES',
});

Parameters:

| Param | Type | Description | |-------------------|-----------------------------------|---------------------------------------------------| | type | 'MOBILE' \| 'PAYBILL' \| 'TILL' | Payment type | | shortCode | string | Phone number, paybill, or till number | | mobileNetwork | string | Mobile network operator | | amount | string | Amount to disburse in local currency | | fee | string | Transaction fee (use "0" if none) | | chain | string | Blockchain network (e.g. "CELO") | | transactionHash | string | On-chain transaction hash of the crypto payment | | callbackUrl | string | Webhook URL to receive transaction status updates | | currencyCode | string | Local currency code (e.g. "KES") | | accountNumber | string (optional) | Required for PAYBILL type |

Expected Response:

{
  "code": 200,
  "message": "Disbursement initiated successfully",
  "data": {
    "transactionCode": "ebb8ee20-4e24-4360-bcd3-e4291b8d1cad",
    "status": "PENDING"
  }
}

initiateBankTransfer(params)

Initiates a bank transfer in Kenya or Nigeria.

Kenya

const result = await pretium.initiateBankTransfer({
  currencyCode: 'KES',
  type: 'BANK_TRANSFER',
  accountNumber: '011001100',
  bankCode: '247247',
  amount: '20',
  chain: 'CELO',
  transactionHash: '0x55a572efe...',
  callbackUrl: 'https://your-server.com/callback',
});

Nigeria

const result = await pretium.initiateBankTransfer({
  currencyCode: 'NGN',
  type: 'BANK_TRANSFER',
  accountNumber: '001918181',
  bankCode: '123455',
  amount: '500',
  chain: 'CELO',
  transactionHash: '0x55a572efe...',
  callbackUrl: 'https://your-server.com/callback',
  accountName: 'John Doe',
  bankName: 'Sterling Bank',
  fee: '10',
});

Parameters:

| Param | Type | Description | |-------------------|-----------------------|-------------------------------------------------| | currencyCode | string | Currency code (e.g. "KES", "NGN") | | type | string | Must be "BANK_TRANSFER" | | accountNumber | string | Recipient bank account number | | bankCode | string | Bank code | | amount | string | Amount in local currency | | chain | string | Blockchain network (e.g. "CELO") | | transactionHash | string | On-chain transaction hash of the crypto payment | | callbackUrl | string | Webhook URL for status updates | | accountName | string (optional) | Required for NGN transfers | | bankName | string (optional) | Required for NGN transfers | | fee | string (optional) | Transaction fee |

Expected Response:

{
  "code": 200,
  "message": "Bank transfer initiated successfully",
  "data": {
    "transactionCode": "c3d2e1f0-89ab-4567-bcde-f01234567890",
    "status": "PENDING"
  }
}

initiateOnramp(params)

Initiates an on-ramp — collects fiat from a mobile money number and delivers crypto to a wallet address.

const result = await pretium.initiateOnramp({
  shortCode: '0707023542',
  mobileNetwork: 'Safaricom',
  amount: '20',
  fee: '0',
  chain: 'CELO',
  asset: 'USDT',
  walletAddress: '0x3Eaab84B42F9fCf2A9B3f2FDB83572B4153eE958',
  callbackUrl: 'https://your-server.com/callback',
  currencyCode: 'KES',
});

Parameters:

| Param | Type | Description | |-----------------|----------|----------------------------------------------------| | shortCode | string | Customer's mobile money phone number | | mobileNetwork | string | Mobile network operator | | amount | string | Fiat amount to collect | | fee | string | Transaction fee | | chain | string | Target blockchain network | | asset | string | Crypto asset to deliver (e.g. "USDT", "USDC") | | walletAddress | string | Recipient crypto wallet address | | callbackUrl | string | Webhook URL for status updates | | currencyCode | string | Source fiat currency (e.g. "KES") |

Expected Response:

{
  "code": 200,
  "message": "On-ramp initiated. STK push sent to 0707023542",
  "data": {
    "transactionCode": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING"
  }
}

getTransactions(params)

Returns a list of transactions within a date range.

const txns = await pretium.getTransactions({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  currencyCode: 'KES',
});

Parameters:

| Param | Type | Description | |----------------|----------|------------------------------------| | startDate | string | Start of date range (YYYY-MM-DD) | | endDate | string | End of date range (YYYY-MM-DD) | | currencyCode | string | Filter by currency (e.g. "KES") |

Expected Response:

{
  "code": 200,
  "message": "List of transactions",
  "data": [
    {
      "id": 1001,
      "transactionCode": "ebb8ee20-4e24-4360-bcd3-e4291b8d1cad",
      "status": "COMPLETE",
      "amount": "20.00",
      "amountInUsd": "0.15",
      "type": "DISBURSEMENT",
      "shortcode": "0704333650",
      "category": "MOBILE",
      "chain": "CELO",
      "message": "Transaction completed successfully",
      "currencyCode": "KES",
      "isReleased": true,
      "createdAt": "2024-06-15T14:23:00.000Z",
      "receiptNumber": "RCP123456789",
      "asset": "USDT",
      "transactionHash": "0x55a572efe1234567890abcdef1234567890abcdef1234567890abcdef12345678"
    },
    {
      "id": 1002,
      "transactionCode": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "status": "FAILED",
      "amount": "500.00",
      "amountInUsd": "3.86",
      "type": "BANK_TRANSFER",
      "shortcode": "011001100",
      "category": "BANK_TRANSFER",
      "chain": "CELO",
      "message": "Invalid account number",
      "currencyCode": "KES",
      "isReleased": false,
      "createdAt": "2024-07-01T09:10:00.000Z",
      "accountNumber": "011001100",
      "publicName": "John Doe"
    }
  ]
}

getTransactionStatus(params)

Returns the current status of a single transaction.

const status = await pretium.getTransactionStatus({
  transactionCode: 'ebb8ee20-4e24-4360-bcd3-e4291b8d1cad',
  currencyCode: 'kes',
});

Parameters:

| Param | Type | Description | |-------------------|----------|------------------------------------------------------------| | transactionCode | string | UUID of the transaction | | currencyCode | string | Currency code (case-insensitive, e.g. "kes" or "KES") |

Expected Response:

{
  "code": 200,
  "message": "Transaction status retrieved successfully",
  "data": {
    "id": 1001,
    "transactionCode": "ebb8ee20-4e24-4360-bcd3-e4291b8d1cad",
    "status": "COMPLETE",
    "amount": "20.00",
    "amountInUsd": "0.15",
    "type": "DISBURSEMENT",
    "shortcode": "0704333650",
    "category": "MOBILE",
    "chain": "CELO",
    "message": "Transaction completed successfully",
    "currencyCode": "KES",
    "isReleased": true,
    "createdAt": "2024-06-15T14:23:00.000Z",
    "receiptNumber": "RCP123456789",
    "asset": "USDT",
    "transactionHash": "0x55a572efe1234567890abcdef1234567890abcdef1234567890abcdef12345678"
  }
}

Possible status values:

| Value | Description | |------------|------------------------------------| | COMPLETE | Transaction processed successfully | | PENDING | Transaction is being processed | | FAILED | Transaction failed |

Callback / Webhook Payload

When a transaction is completed or fails, Pretium POSTs to your callbackUrl with the following payload:

{
  "code": 200,
  "message": "Transaction completed successfully",
  "data": {
    "transactionCode": "ebb8ee20-4e24-4360-bcd3-e4291b8d1cad",
    "status": "COMPLETE",
    "amount": "20.00",
    "currencyCode": "KES",
    "receiptNumber": "RCP123456789"
  }
}

TypeScript Support

The SDK ships with full TypeScript type definitions. All method parameters and return types are exported:

import { Pretium, PretiumError } from 'pretium';
import type { AccountInfo, TransactionStatus, Disburse } from 'pretium';

License

MIT