# Introduction

Pretium Checkout is a lightweight, no code e-commerce widget that enables businesses across Africa to instantly accept crypto payments and settle in local fiat with minimal fees.

#### 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 **Merchant admin credentials**.


# Why merchants choose us

Crypto payments without complexity

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Instant crypto-to-fiat checkout</strong></td><td>Seamlessly accept crypto payments at checkout and receive local currency instantly.</td><td><a href="https://images.unsplash.com/photo-1616077168712-fc6c788db4af?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwxfHxzZW5kJTIwbW9uZXl8ZW58MHx8fHwxNzYzNTU2MjM1fDA&#x26;ixlib=rb-4.1.0&#x26;q=85">https://images.unsplash.com/photo-1616077168712-fc6c788db4af?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwxfHxzZW5kJTIwbW9uZXl8ZW58MHx8fHwxNzYzNTU2MjM1fDA&#x26;ixlib=rb-4.1.0&#x26;q=85</a></td></tr><tr><td><strong>Low fees</strong></td><td>Save money on every transaction with ultra-low fees.</td><td><a href="https://images.unsplash.com/photo-1596248675029-bd9b0c7dc479?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwyfHxsb3clMjBmZWVzfGVufDB8fHx8MTc2MzU1NjMwOHww&#x26;ixlib=rb-4.1.0&#x26;q=85">https://images.unsplash.com/photo-1596248675029-bd9b0c7dc479?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwyfHxsb3clMjBmZWVzfGVufDB8fHx8MTc2MzU1NjMwOHww&#x26;ixlib=rb-4.1.0&#x26;q=85</a></td></tr><tr><td><strong>No code integration</strong></td><td>Plug in few lines og code and you are live.</td><td><a href="https://images.unsplash.com/photo-1615752865424-62638daceeae?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwxfHxlYXN5fGVufDB8fHx8MTc2MzU1NjQwMXww&#x26;ixlib=rb-4.1.0&#x26;q=85">https://images.unsplash.com/photo-1615752865424-62638daceeae?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwxfHxlYXN5fGVufDB8fHx8MTc2MzU1NjQwMXww&#x26;ixlib=rb-4.1.0&#x26;q=85</a></td></tr></tbody></table>


# Payment types

Brief overview of the payment methods

| Option         | How it works                                                                                                                                                                                                                                                                                                                                                                           | Best for                                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Connect Wallet | <ol><li>The customer will connect their preferred wallet (MetaMask, Trust Wallet, Rainbow, etc.). </li><li>The customer will review the exact amount and confirm the correct network. </li><li>The customer will then tap <strong>Pay</strong> to securely sign and send the transaction directly from their connected wallet.</li></ol>                                               | Users who already have a wallet open and want the fastest, one-tap experience.                           |
| Direct Pay     | <ol><li>The customer will receive a unique deposit address and QR code for their order. </li><li>The customer will scan the QR code (or copy the address) and send the exact amount from any wallet or exchange they prefer (Coinbase, Binance, Trust Wallet, Phantom, etc.). </li><li>The customer will have their payment automatically detected on-chain once it is sent.</li></ol> | Users who want to pay from a different wallet/exchange, mobile app, or simply prefer scanning a QR code. |


# Connect wallet flow

One-Click-Payment

{% stepper %}
{% step %}
**Customer selects “Connect Wallet” option**

The wallet connection widget opens.

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FiRLmzKhJnBbhFfSWbeLJ%2FScreenshot%202025-11-25%20at%2010.39.13.png?alt=media\&token=8600ca94-0dd4-483d-9cbf-955914b2e393)
{% endstep %}

{% step %}
**Wallet connection**

Customer connects and signs (if required by the wallet). The widget automatically detects  the following:

* Connected address
* Current blockchain networks
* Token balances on all supported chains

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FFi6wQM6SOcJTd1xnNigx%2FScreenshot%202025-11-25%20at%2010.45.05.png?alt=media\&token=f4ea55ff-352a-4b86-b448-0742bf9ad290)
{% endstep %}

{% step %}
**Network selection**

The customer selects the desired network (e.g., Celo, Base) and the asset they wish to pay with. Balances are shown in real time.

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FWKSxainnBg1pDpKqLHsX%2FScreenshot%202025-11-25%20at%2010.46.32.png?alt=media\&token=8f7fec2b-a739-4615-8f77-49ec1560d62a)
{% endstep %}

{% step %}
**Payment details confirmation**

Upon selecting an asset, the system instantly calls the settlement endpoint and retrieves the following :

* Exact crypto amount to send
* Destination address
* Current exchange rate

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FX0jWhk0L3DdGfl9k2fVH%2FScreenshot%202025-11-25%20at%2010.47.24.png?alt=media\&token=233029e5-de4f-42ca-845e-a3fb3d08d446)![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2Fwuvxt1rpFa5bYzjIlM6a%2FScreenshot%202025-11-25%20at%2010.47.34.png?alt=media\&token=8e7e2bcf-9a0e-4a61-81fc-ec10db53889d)

{% endstep %}

{% step %}
**Payment processing**

After the customer has reviewed the payment details and taps Pay, the wallet prompts the customer to confirm the transaction. Once confirmed, the transaction is broadcast and the widget shows “Processing…”.

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2F5z2WoFyzcIKd0T8rGrhA%2Fcropped.png?alt=media\&token=ef6ed4a6-48da-438e-83a5-0554ae88b25e)

{% endstep %}

{% step %}
**Payment confirmation**

As soon as the transaction is confirmed on-chain, the customer sees “Payment Successful” and is redirected to the merchant’s success/callback URL.

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FR5ueM5nNkMn5uK4vT2pJ%2FScreenshot%202025-11-25%20at%2010.48.05.png?alt=media\&token=89667f97-3a5d-42d6-a544-8cbc7a94bc1e)
{% endstep %}

{% step %}
**Disbursement of funds to the merchant**

Clients pay using stablecoins, while merchants receive their funds in local currency. On the merchant dashboard, they can choose to enable **automatic settlements**, allowing funds to be disbursed automatically to their respective mobile money or bank accounts.&#x20;

<figure><img src="https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FfS2uRP1EbXJiM29qNhUe%2Fauto_settlement.png?alt=media&amp;token=b962d069-45a4-4799-99e9-d2ce0cd859b2" alt=""><figcaption></figcaption></figure>

Alternatively, merchants may opt for **manual settlements**, where they can manually withdraw funds to their respective mobile money or bank accounts.

<figure><img src="https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FcFyCz0Q1azyfln9ms20G%2Fmanual.png?alt=media&amp;token=975e500b-01eb-4677-a4e3-d8f6f937070a" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}


# Direct pay flow

Manual transfer

{% stepper %}
{% step %}
**Customer selects “Direct Pay” option**

The wallet connection widget opens.

&#x20;![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FiRLmzKhJnBbhFfSWbeLJ%2FScreenshot%202025-11-25%20at%2010.39.13.png?alt=media\&token=8600ca94-0dd4-483d-9cbf-955914b2e393)

{% endstep %}

{% step %}
**Network selection**

The customer selects the desired network (e.g., Celo, Base) and the asset they wish to pay with.

![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FiRLmzKhJnBbhFfSWbeLJ%2FScreenshot%202025-11-25%20at%2010.39.13.png?alt=media\&token=8600ca94-0dd4-483d-9cbf-955914b2e393) ![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FCdWfFiiwZ5EYJGE6ZMIa%2FScreenshot%202025-11-25%20at%2010.38.07.png?alt=media\&token=7cc21f2b-3e26-4993-91fd-b4b2110a8add)
{% endstep %}

{% step %}
**Payment details confirmation**

Upon selecting an asset, the system instantly calls the settlement endpoint and retrieves the following:

* Exact crypto amount to send
* Destination address
* Current exchange rate
* Payment expiry timer&#x20;

The customer either scans the QR code with any mobile wallet or exchange app, or copies the address and manually sends the exact amount&#x20;

&#x20; ![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FjfncLbGd0xLpyY1e1XIg%2FScreenshot%202025-11-25%20at%2010.40.33.png?alt=media\&token=17aced99-aaaa-4b20-8e87-cbee936aaaba)![](https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FPG06gbLLdWReDAD9kYQ1%2FScreenshot%202025-11-25%20at%2010.42.35.png?alt=media\&token=17fe4f78-dd10-4a2d-9417-3269858175b5)
{% endstep %}

{% step %}
**Payment confirmation**

The widget starts polling the order status every 30 seconds (and offers a manual “Confirm” button) for the customer to manually confirm in case they have already paid.

Once the customer pays, the payment will be confirmed on-chain, and the customer sees “Payment Complete” and is redirected to the merchant’s success/callback URL
{% endstep %}

{% step %}
**Disbursement of funds to the merchant**

Clients pay using stablecoins, while merchants receive their funds in local currency. On the merchant dashboard, they can choose to enable **automatic settlements**, allowing funds to be disbursed automatically to their respective mobile money or bank accounts.&#x20;

<figure><img src="https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FfS2uRP1EbXJiM29qNhUe%2Fauto_settlement.png?alt=media&amp;token=b962d069-45a4-4799-99e9-d2ce0cd859b2" alt=""><figcaption></figcaption></figure>

Alternatively, merchants may opt for **manual settlements**, where they can manually withdraw funds to their respective mobile money or bank accounts.

<figure><img src="https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FcFyCz0Q1azyfln9ms20G%2Fmanual.png?alt=media&amp;token=975e500b-01eb-4677-a4e3-d8f6f937070a" alt=""><figcaption></figcaption></figure>

{% endstep %}
{% endstepper %}


# How to integrate

Use these query parameters to pre-fill and customize the Pretium Checkout when using the iframe.

**Required parameters**

| Parameter      | Type   | Description                                          | Example       |
| -------------- | ------ | ---------------------------------------------------- | ------------- |
| amount         | Number | Amount in fiat/local currency                        | 1000          |
| currency\_code | String | 3-letter ISO 4217 fiat currency code                 | KES, MWK, GHS |
| checkout\_ref  | String | Your unique checkout reference                       | chk\_01hxyz   |
| order\_id      | String | Your internal order ID (will be returned in webhook) | ORD-2025-123  |

**Quick Start (Copy-Paste Integration)**

Retrieve the checkout key from your merchant dashboard and pass it as your checkout\_ref.

<figure><img src="https://3637480436-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3TsE4w3mKKZa9SsK3biR%2Fuploads%2FYXt9vaz4ndCWNZr6XbzB%2Fconsumer.png?alt=media&amp;token=a81fc57f-0687-47c5-bbe8-00c66226276b" alt=""><figcaption></figcaption></figure>

Add this single tag to your checkout or payment page:

```html
<iframe
  src="https://checkout.pretium.africa?amount=30&currency_code=KES&checkout_ref=jdhdyeere&order_id=123"
  width="100%"
  height="600px"
  frameborder="0"
  >
</iframe>
```

Full Example URL:

```

  https://checkout.pretium.africa?amount=30&currency_code=KES&checkout_ref=kwe2213w&order_id=123

```

**Webhook / Callback (Recommended)**

```*
callback-url?order_id=your_order_id
```

Use this to:

* Mark the order as paid
* Send receipt email


# Payloads

When a transaction is completed, Pretium sends two webhook notifications

#### Payment notification

When a transaction is completed by the user, our API automatically sends a webhook to the webhook URL configured on the merchant portal.

```
{
   "status": "COMPLETE",
   "order_id":"701cc1d3-01e",
   "message": "Success, payment received successfully!"
}

```

#### Merchant settlement

If the merchant has enabled automatic settlements, the payment will be automatically disbursed to their set mobile money or bank account, and our API will send a webhook to the webhook URL configured on the merchant portal.

```
{
   "status": "COMPLETE",
   "transaction_code":"7dced6e3-53bf-4dca-9fde-49b7e6121ec5",
   "receipt_number":"TL1QRBRFUD",
   "public_name":" Joe Doe",
   "message": "Transaction processed successfully."
}

```


# Supported networks & assets

| Network | Assets           |
| ------- | ---------------- |
| CELO    | USDT, CUSD, USDC |
| BASE    | USDC             |


# Supported countries

| Country  | Currency Code |
| -------- | ------------- |
| Kenya    | KES           |
| Nigeria  | NGN           |
| Malawi   | MWK           |
| Uganda   | UGX           |
| Ghana    | GHS           |
| DR Congo | CDF           |
| Ethiopia | ETB           |