---
title: "Initiate a Transaction (V2)"
method: POST
path: "/checkout/v2/intent"
tags: ["Transactions"]
---

# Initiate a Transaction (V2)

`POST /checkout/v2/intent`

## Request

- Base URL: `https://api.onramper.com`
- URL: `https://api.onramper.com/checkout/v2/intent`
- Auth: none declared. Required headers: `x-onramper-signature`, `x-onramper-timestamp`, `x-onramper-nonce`
- TypeScript: <https://skmtc.dev/onramper/apis/onramper-api-collection-v2/docs/checkout/v2/intent/post.ts> (a function with typed inputs; its response is checked against the schema)

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)](https://docs.onramper.com/docs/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](https://docs.onramper.com/docs/checkout-v2). Widget integrations do not call this endpoint. They pass `endUserIpHash` as a signed URL parameter instead: [Widget: Sign a URL (V2)](https://docs.onramper.com/docs/widget-sign-a-url-v2#bind-the-session-to-the-end-users-ip).

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/](https://api-stg.onramper.com/) For Test Environments

## Headers

- `Authorization` string
- `x-onramper-signature` string, required
- `x-onramper-timestamp` string, required
- `x-onramper-nonce` string, required

## Request body

- object
  - `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` 'buy' | 'sell', required: Transaction direction.
  - `paymentMethod` string, required: Payment method identifier from the quote.
  - `network` string: Crypto network for the destination asset. Required for a buy.
  - `endUserIpHash` string, 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.
  - `clientIpHash` string: 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.
  - `wallet` object: End user's wallet. Required for a buy.
    - `address` string, required: Destination wallet address.
    - `memo` string: Memo or tag, for chains that need one.
  - `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).
  - `email` string, email: 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.

## Response `200`

OK

- object
  - `redirectUrl` string, required: Send the end user's browser here, unmodified. Carries the session id and a one-time resume token.
  - `sessionId` string, required: Checkout session id. Single-use, expires 10 minutes after intent.
  - `resumeToken` string: Capability token for resuming the session. Already embedded in `redirectUrl`; treat it as a credential.

## Other responses

- `400`: `endUserIpHash` is missing or is not a 64-character hex SHA256 hash
- `401`: Signature missing, expired, replayed or invalid

## Changes

- **2026-11-03** `dd0decee5ab4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/onramper/apis/onramper-api-collection-v2/changes/checkout/v2/intent/post.md)

---

[API](https://skmtc.dev/onramper/apis/onramper-api-collection-v2.md) - [All operations](https://skmtc.dev/onramper/apis/onramper-api-collection-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/onramper/apis/onramper-api-collection-v2/revisions/dd0decee5ab4?raw)