Checkout V2

Checkout V2 is the same checkout call with two extra fields:

• clientIpHash: SHA256 of the end user's IP, hashed on your backend. We check the IP of the browser that opens the session against it, so a leaked session link is useless from another machine. Required.
• platform: where your integration runs. Providers that only serve whitelisted platforms are dropped when you leave it out.

The flow

1. The user starts a purchase in your app.
2. Your backend takes the user's IP, hashes it with SHA256, and calls POST /checkout/v2/intent with a V2 signature.
3. Onramper returns redirectUrl and sessionId.
4. You send the user's browser to redirectUrl.
5. Onramper checks the IP behind that browser against clientIpHash, then takes the user to the provider. A mismatch returns 403.

Step 1: add platform to your quotes call

GET /quotes/usd/btc?amount=100&paymentMethod=creditcard&platform=mobile-ios

Pick the value that describes where the user actually is. A React Native WebView on iOS is webview-ios, not web.

Leaving platform out is not neutral: providers that require whitelisting disappear from quotes and cannot be used at checkout. Use the same value in the checkout body.

Step 2: call POST /checkout/v2/intent

Same body as POST /checkout/intent, plus:

Both fields sit inside the signed body, so build them before you sign.

Response:

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

Step 3: send the user to redirectUrl

Redirect the browser to redirectUrl exactly as returned. It carries a one-time resume token, so treat it as a credential: do not log it, store it, or share it anywhere else. Each session is single-use and expires 10 minutes after intent.

Errors

At intent, on your backend:

After the redirect, when the user's browser opens the session:

Example

Signing uses the signApiRequestV2 helper from API: Sign requests (V2).

const API_BASE = 'https://api.onramper.com';
const PLATFORM = 'mobile-ios'; // match your integration type

function sha256(data: string): string {
  return createHash('sha256').update(data).digest('hex');
}

async function createCheckout(userIp: string, onramp: string) {
  const body = {
    onramp,
    source: 'eur',
    destination: 'btc',
    amount: 300,
    type: 'buy',
    country: 'de',
    paymentMethod: 'creditcard',
    network: 'bitcoin',
    wallet: { address: 'bc1q...' },
    clientIpHash: sha256(userIp),
    platform: PLATFORM,
  };

  const resp = await fetch(`${API_BASE}/checkout/v2/intent`, {
    method: 'POST',
    headers: {
      ...signApiRequestV2({
        method: 'POST',
        path: '/checkout/v2/intent',
        body,
        contentType: 'application/json',
      }),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  const { redirectUrl } = await resp.json();
  return redirectUrl; // send the user's browser here
}

Hash the end user's IP, not your server's. Read it from the connection your frontend makes to your backend.

Migrating from V1

If you already sign with V2, the signing format does not change. Only the path, the two new fields and the response shape differ.