ONonramper
Transactions

Initiate a Transaction (V2)

Changed on

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 endUserIpHash (required) and platform. Both are covered by the signature, so build them before you sign. clientIpHash remains accepted as a deprecated alias.

Step-by-step integration guide: Checkout V2. Widget integrations do not call this endpoint. They pass endUserIpHash as a signed URL parameter instead: Widget: Sign a URL (V2).

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

post/checkout/v2/intent

Request

Headers

Authorizationstring
x-onramper-signaturestring required

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

x-onramper-timestampstring required

ISO 8601 timestamp used in the signature.

x-onramper-noncestring required

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

Request body

onrampstring required

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

sourcestring required

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

destinationstring required

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

amountnumber required

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

type'buy' | 'sell' required

Transaction direction.

paymentMethodstring required

Payment method identifier from the quote.

networkstring

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

endUserIpHashstring required

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.

clientIpHashstring

Deprecated alias for endUserIpHash, still accepted. If both are sent, endUserIpHash is used.

platform'web' | 'mobile-ios' | 'mobile-android' | 'webview-ios' | 'webview-android' | 'browser-extension' | 'desktop'

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.

countrystring

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

subdivisionstring

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

emailstring email

End user's email, prefilled at the provider.

partnerContextstring

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

externalCustomerIdstring

Your identifier for the end user.

uuidstring

Client-generated request id, useful for tracing.

originatingHoststring

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

allowOnrampPmSelectionboolean

Let the provider offer its own payment-method picker.

targetContractAddressstring

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

supportedParamsobject

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

metaDataobject

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

Example request

{
  "onramp": "moonpay",
  "source": "eur",
  "destination": "btc",
  "amount": 100,
  "type": "buy",
  "paymentMethod": "creditcard",
  "network": "bitcoin",
  "uuid": "6756256e-d07f-42f0-a873-4d992eec8a2e",
  "originatingHost": "buy.onramper.com",
  "partnerContext": "123-CLIENT-ORDER-ID-456",
  "email": "satoshi@gmx.com",
  "wallet": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  },
  "supportedParams": {
    "theme": {
      "isDark": false,
      "themeName": "light-theme",
      "primaryColor": "#241D1C",
      "secondaryColor": "#FFFFFF",
      "primaryTextColor": "#141519",
      "secondaryTextColor": "#6B6F80",
      "cardColor": "#F6F7F9"
    },
    "partnerData": {
      "redirectUrl": {
        "success": "http%3A%2F%2Fredirecturl.com%2F"
      }
    }
  },
  "endUserIpHash": "3b7a4f1c8e2d5a9b6c0f3e8d1a4b7c2e5f8a1d4b7c0e3f6a9b2c5d8e1f4a7b0c",
  "platform": "mobile-ios"
}

Response

OK

redirectUrlstring required

Send the end user's browser here, unmodified. Carries the session id and a one-time resume token.

sessionIdstring required

Checkout session id. Single-use, expires 10 minutes after intent.

resumeTokenstring

Capability token for resuming the session. Already embedded in redirectUrl; treat it as a credential.

Example response

{
  "redirectUrl": "https://buy.onramper.com?session=01ABCDEFGHIJKLMNOPQRSTUVWX&resumeToken=8f2c1d5e9a3b7c0f",
  "sessionId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "resumeToken": "8f2c1d5e9a3b7c0f"
}

Changes