Initiate a Transaction (V2)

post

https://api.onramper.com/checkout/v2/intent

Creates a checkout session bound to the end user's IP and returns the URL to redirect them to.

This endpoint requires a Signature V2 request. Sign every call with your Ed25519 key and send x-onramper-signature, x-onramper-timestamp and x-onramper-nonce. There is no API-key-only mode: an unsigned or invalid request returns 401. See API: Sign requests (V2).

The body is the same as POST /checkout/intent, plus clientIpHash (required) and platform. Both are covered by the signature, so build them before you sign.

Redirect the browser to redirectUrl exactly as returned. It carries a one-time resume token, so treat it as a credential. Each session is single-use and expires 10 minutes after intent.

🛠️ Please Use https://api-stg.onramper.com/ For Test Environments

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

onramp

string

required

Provider to transact with, as returned by the quote you selected.

source

string

required

Source currency. Fiat for a buy, crypto for a sell.

destination

string

required

Destination currency. Crypto for a buy, fiat for a sell.

amount

number

required

Amount in the source currency. Must be greater than 0.

type

string

enum

required

Transaction direction.

Allowed:

paymentMethod

string

required

Payment method identifier from the quote.

network

string

Crypto network for the destination asset. Required for a buy.

clientIpHash

string

required

length between 64 and 64

^[a-f0-9]{64}$

Lowercase hex SHA256 of the end user's IP address, hashed on your backend. Onramper matches the IP of the browser that opens the session against this value and rejects a mismatch with 403. Uppercase hex is rejected.

platform

string

enum

Where your integration runs. Send the same value you used on the quotes call. Providers that require platform whitelisting are unavailable when this is absent.

Allowed:

wallet

object

End user's wallet. Required for a buy.

country

string

ISO 3166-1 alpha-2 country of the end user. Derived from the request when omitted.

subdivision

string

ISO 3166-2 subdivision, where the provider requires it (for example US states).

string

End user's email, prefilled at the provider.

partnerContext

string

Opaque value echoed back on webhooks and transaction reads. Use it to correlate with your own order id.

externalCustomerId

string

Your identifier for the end user.

uuid

string

Client-generated request id, useful for tracing.

originatingHost

string

Host the flow originates from. Overridden with the verified request origin when one is present.

allowOnrampPmSelection

boolean

Let the provider offer its own payment-method picker.

targetContractAddress

string

Contract address for token purchases that are not a listed asset.

supportedParams

object

Provider-facing extras, including theme for widget styling and partnerData.redirectUrl.success for the post-purchase return URL.

metaData

object

Free-form key/value pairs stored with the session.

Headers

Authorization

string

x-onramper-signature

string

required

Ed25519 signature over the canonical request, prefixed with v2:.

x-onramper-timestamp

string

required

ISO 8601 timestamp used in the signature.

x-onramper-nonce

string

required

UUID v4, unique per request. A reused nonce is rejected.

Responses

200OK

400clientIpHash is missing or is not a 64-character hex SHA256 hash

401Signature missing, expired, replayed or invalid