Package Exports

pretium
pretium/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (pretium) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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": "dev@acme.io",
    "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