Onramper - Fiat On/Off-Ramp

The Onramper plugin adds a Buy & sell crypto page to your exchange. Onramper compares offers from many payment providers. Users pick a coin, a network and a currency, see the best quote and finish in Onramper's checkout. Purchases land in the user's exchange wallet, and sales are paid out from the user's exchange balance. Your exchange never handles fiat.

What you need

• The Enterprise plan on HollaEx Cloud.
• An Onramper account with an API key (it starts with pk_prod_, or pk_test_ for testing) and the Onramper secret.
• A signing key pair (Ed25519), which Onramper uses to check that checkout links really come from your exchange. You keep the private key in the plugin and register the public key with Onramper. See Create the signing key.

Set it up

1. Get your API key and secret from Onramper.

2. Create the signing key pair and register the public key with Onramper.

3. Install onramper from Operator Controls → Exchange → Plugins.

4. Open the plugin, enter the settings below and save.

5. Ask Onramper to send webhooks (status updates) to this address, with your exchange's API domain in place of <your-api-domain>:

   https://<your-api-domain>/plugins/onramper/webhook

   See Base URLs to find your API domain. Without webhooks, orders are still updated every minute.

6. Test with your pk_test_ key: buy a small amount and check it arrives in the user's wallet. If you offer selling, also run one test sale before going live (see Troubleshooting).

Setting	What it does
api_key	Your Onramper API key, pk_prod_... or pk_test_.... Required. It isn't secret: it's part of every checkout link.
signing_private_key	Secret. The private half of your signing key, in PEM format. Line breaks can be written as \n. Required.
secret	Secret, from Onramper. Your Onramper secret. The plugin uses it to look up transactions and to check that webhooks come from Onramper. Required.
mode	Which flows to offer: buy, sell or buy,sell. Default buy.
api_url	The public https address of your exchange's API, for example https://api.example.com. Onramper sends sellers back to it. If empty, your exchange's API address is used. Selling stays off without a valid https address.
exchange_url	The public https address of your exchange website, where users return after checkout. If empty, your exchange URL is used.
coins	Optional. The coins to offer, comma separated, for example btc,eth,usdt. If empty, every coin on your exchange that Onramper supports is offered.
fiat_currencies	Optional. The fiat currencies to offer, comma separated, for example usd,eur. If empty, all of Onramper's are offered.
default_fiat	The currency selected when the page opens. Default usd.
default_crypto	Optional. The coin selected when the page opens.
default_amount	The amount filled in for a purchase. Default 100.

Create the signing key

The key pair is created with the free openssl tool, which comes with macOS and Linux. Ask your developer if you're not sure how to run it. The first command creates the private key file, and the second prints the public key to register with Onramper:

openssl genpkey -algorithm ed25519 -out onramper.pem

openssl pkey -in onramper.pem -pubout

Paste the full contents of onramper.pem into signing_private_key. Keep the file somewhere safe and never share it.

What your users see

The Buy & sell crypto page appears in your exchange's navigation. Users must be signed in to use it.

• Buying: the user picks the coin, network, currency and amount, and sees an estimate with the best offer. Onramper's checkout opens locked to that coin and the user's own deposit address on your exchange, so the purchase can only land in their exchange wallet.
• Selling: the user picks the coin and amount and chooses an offer in Onramper's checkout. They then come back to your exchange to approve the transfer. Like any withdrawal, it needs the 6-digit code emailed to the user, and their 2FA code if they've turned 2FA on. The user has one hour to approve a sale.

Users see their Onramper orders and their status on the same page.

How it works

• A sale moves the crypto out of the user's balance as a normal withdrawal from your exchange, to the address of the payment provider Onramper chose. All your usual withdrawal checks apply: limits, verification level, blacklists and the travel rule. The emailed code is always needed, even for addresses the user has whitelisted.
• Before any funds move, the plugin checks the sale with Onramper directly: the transaction must exist, belong to this order and match the coin, amount and payout address. If anything doesn't match, the sale is refused.
• The plugin only accepts webhooks signed with your Onramper secret.
• A payout with an unclear result is held for review. If the plugin can't tell whether the withdrawal went out, or if it went out and the sale then failed at Onramper, the order is marked for review. It's never retried automatically. If a payout went out but couldn't be recorded, the plugin matches it against the user's withdrawals after 5 minutes.
• Users whose account is deactivated or flagged can't use the page.

Troubleshooting

• Every sale is refused with "Onramper did not report a payout address": Onramper's record for your account doesn't include the provider's payout address. Run one test sale before going live, and ask Onramper to fix this if it happens.
• A sale that needs a memo or tag is refused: the plugin only sends it when Onramper's record carries the same memo.
• Selling doesn't appear: check that mode includes sell and that api_url is a valid https address.
• An order is stuck in review: open a ticket with the order details so the team can check what happened before anything is refunded or sent again.

Need help? Open a ticket from your HollaEx dashboard.