Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getpartna.com/llms.txt

Use this file to discover all available pages before exploring further.

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

EnvironmentURL
staginghttps://staging-pay.getpartna.com/v4/pay/onramp
productionhttps://pay.getpartna.com/v4/pay/onramp

​
Required query parameters

ParameterRequiredDescription
amountYesAmount the user will pay in local currency
from_currencyYesLocal currency the user is paying with, such as NGN, KES, or GHS
to_currencyYesCrypto the user should receive, such as USDT, USDC, BTC, or ETH
to_networkYesNetwork to deliver the crypto on, such as tron, celo, or ethereum
addressYesWallet address that will receive the crypto
merchantYesYour Partna merchant username
referenceNoA hex string transaction reference

​
Registration modes

The widget supports two merchant-controlled registration modes:
ModeBehavior
openUsers can begin registration through the widget flow and complete onboarding later
closedOnly 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

1

Generate the redirect URL

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

Redirect the user

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

User completes payment

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

Receive webhook updates

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

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;

​
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:
StatusMeaning
pendingThe onramp request has been created and is awaiting user payment
receivedPartna has received the user’s payment
processingConversion or transfer is currently being processed
completedThe 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"
}

​
When to use the hosted widget

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.