Onramp Widget

The onramp widget lets you send users to a Partna-managed checkout where they can pay in local currency and receive crypto in their wallet. Use this flow when you want a faster integration without building your own payment UI.

Base URLs

Environment	URL
`staging`	`https://staging-pay.getpartna.com/v4/pay/onramp`
`production`	`https://pay.getpartna.com/v4/pay/onramp`

Required query parameters

Parameter	Required	Description
`amount`	Yes	Amount the user will pay in local currency
`from_currency`	Yes	Local currency the user is paying with, such as `NGN`, `KES`, or `GHS`
`to_currency`	Yes	Crypto the user should receive, such as `USDT`, `USDC`, `BTC`, or `ETH`
`to_network`	Yes	Network to deliver the crypto on, such as `tron`, `celo`, or `ethereum`
`address`	Yes	Wallet address that will receive the crypto
`merchant`	Yes	Your Partna merchant username
`reference`	No	A hex string transaction reference

Registration modes

The widget supports two merchant-controlled registration modes:

Mode	Behavior
`open`	Users can begin registration through the widget flow and complete onboarding later
`closed`	Only users you have already created can continue in the widget flow

You can manage this setting through Update Settings and inspect the current value with Get Settings. If your registration mode is open, you can use Register Account to create a pending registration. If your registration mode is closed, create the user up front with Create Account.

How it works

Generate the redirect URL

Build a URL using the correct environment URL and the required query parameters.

Redirect the user

Send the user to the hosted Partna checkout from your app or website.

User completes payment

The user follows the payment instructions in the hosted flow and pays the local currency amount.

Receive webhook updates

Partna sends Onramp webhook events as the transaction moves through each state. See Webhooks for signature verification and endpoint setup.

Handle completion

Once the transaction reaches completed, the crypto has been sent to the destination wallet address.

Build the redirect URL

const redirectURL =
  environment === "staging"
    ? "https://staging-pay.getpartna.com/v4/pay/onramp"
    : "https://pay.getpartna.com/v4/pay/onramp";

const params = new URLSearchParams();
params.append("from_currency", fromCurrency);
params.append("to_currency", toCurrency);
params.append("to_network", toNetwork);
params.append("amount", amount);
params.append("address", walletAddress);
params.append("merchant", merchant);

if (reference) {
  params.append("reference", reference);
}

const url = `${redirectURL}?${params.toString()}`;
window.location.href = url;

const redirectURL =
  environment === "staging"
    ? "https://staging-pay.getpartna.com/v4/pay/onramp"
    : "https://pay.getpartna.com/v4/pay/onramp";

const params = new URLSearchParams({
  from_currency: fromCurrency,
  to_currency: toCurrency,
  to_network: toNetwork,
  amount,
  address: walletAddress,
  merchant,
});

if (reference) {
  params.append("reference", reference);
}

window.location.href = `${redirectURL}?${params.toString()}`;

Example redirect URL

https://pay.getpartna.com/v4/pay/onramp?amount=1000&from_currency=KES&to_currency=CUSD&to_network=celo&address=0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d&merchant=your-merchant-username&reference=a152225b9ccd6d28c2b58f8828a81125

For staging, use https://staging-pay.getpartna.com/v4/pay/onramp instead.

Transaction lifecycle

Partna emits Onramp webhooks with these statuses:

Status	Meaning
`pending`	The onramp request has been created and is awaiting user payment
`received`	Partna has received the user’s payment
`processing`	Conversion or transfer is currently being processed
`completed`	The crypto delivery is complete

Sample webhook payloads

`pending`

{
  "event": "Onramp",
  "data": {
    "transactionReference": "a152225b9ccd6d28c2b58f8828a81125",
    "status": "pending",
    "timestamp": 1773760151,
    "fromAmount": 14.2,
    "toAmount": 0.0954,
    "fromCurrency": "KES",
    "toCurrency": "CUSD",
    "fromNetwork": "kenyanshilling",
    "toNetwork": "celo",
    "totalFeesInFromCurrency": 1.8,
    "totalFeesInToCurrency": 0.0138,
    "expireAt": 1773763751,
    "toExternalAccount": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d"
  },
  "signature": "BASE64_SIGNATURE"
}

`received`

{
  "event": "Onramp",
  "data": {
    "transactionReference": "a152225b9ccd6d28c2b58f8828a81125",
    "status": "received",
    "timestamp": 1773760193,
    "fromAmount": 14.2,
    "toAmount": 0.095407692303476,
    "fromCurrency": "KES",
    "toCurrency": "CUSD",
    "totalFeesInFromCurrency": 1.797000000052,
    "totalFeesInToCurrency": 0.013823076922924,
    "toExternalAccount": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d"
  },
  "signature": "BASE64_SIGNATURE"
}

`processing`

{
  "event": "Onramp",
  "data": {
    "transactionReference": "a152225b9ccd6d28c2b58f8828a81125",
    "status": "processing",
    "timestamp": 1773760502,
    "transactionHash": "0xc41e313cfb60826d8ccb1803f55fdaaa8d72c269b35fc1a273f7fe3bd7b86831",
    "fromAmount": 14.2,
    "toAmount": 0.0954,
    "fromCurrency": "KES",
    "toCurrency": "CUSD",
    "fromNetwork": "kenyanshilling",
    "toNetwork": "celo",
    "expireAt": 1773763751,
    "toExternalAccount": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d"
  },
  "signature": "BASE64_SIGNATURE"
}

`completed`

{
  "event": "Onramp",
  "data": {
    "transactionReference": "a152225b9ccd6d28c2b58f8828a81125",
    "status": "completed",
    "timestamp": 1773760502,
    "transactionHash": "0xc41e313cfb60826d8ccb1803f55fdaaa8d72c269b35fc1a273f7fe3bd7b86831",
    "fromAmount": 14.2,
    "toAmount": 0.0954,
    "fromCurrency": "KES",
    "toCurrency": "CUSD",
    "fromNetwork": "kenyanshilling",
    "toNetwork": "celo",
    "toExternalAccount": "0x00B6845c6F47C770cE630B96df9BD4A6dA91C65d"
  },
  "signature": "BASE64_SIGNATURE"
}

Use the hosted widget when you want:

A faster integration with less frontend work
Partna to handle the payment instructions UI
A simple redirect-based flow from your product

Use the API-based Onramp Guide when you need full control over the user experience and payment orchestration.

Getting Started

Core Concepts

Guides

Base URLs

Required query parameters

Registration modes

How it works

Build the redirect URL

Example redirect URL

Transaction lifecycle

Sample webhook payloads

`pending`

`received`

`processing`

`completed`

When to use the hosted widget

​Base URLs

​Required query parameters

​Registration modes

​How it works

​Build the redirect URL

​Example redirect URL

​Transaction lifecycle

​Sample webhook payloads

​pending

​received

​processing

​completed

​When to use the hosted widget

Base URLs

Required query parameters

Registration modes

How it works

Build the redirect URL

Example redirect URL

Transaction lifecycle

Sample webhook payloads

`pending`

`received`

`processing`

`completed`

When to use the hosted widget