---
title: "Create Onramp Session"
method: POST
path: "/onramp/intents/{intent_id}/session"
tags: ["onramp"]
---

# Create Onramp Session

`POST /onramp/intents/{intent_id}/session`

## Request

- Base URL: `https://api.coinvoyage.io/v3`
- URL: `https://api.coinvoyage.io/v3/onramp/intents/{intent_id}/session`
- Auth: API key in header `X-API-KEY`
- TypeScript: <https://skmtc.dev/coinvoyage/apis/coinvoyage-api-v3/docs/onramp/intents/:intent_id/session/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a headless Stripe embedded onramp session from a server-held onramp intent using the server-held Link OAuth access token. If Stripe identity or KYC action is required, this endpoint returns 422 with action fields in error.details, including status, reason, kyc_next_step, kyc_status, kyc_required, identity_verification_required, and identity_verification_status.

## Path parameters

- `intent_id` string, required

## Headers

- `X-API-KEY` string, required

## Request body

- OnrampSessionRequest
  - `auth_intent_id` string, required: Stripe Link auth intent ID returned by /onramp/auth/intent
  - `crypto_customer_id` string, required: Crypto customer ID returned by the Stripe embedded component after Link authentication
  - `payment_token` string, required: cryptoPaymentToken returned by the Stripe embedded component payment method collection step

## Response `201`

Headless onramp session created

- OnrampSessionResponse
  - `id` string, required
  - `quote_expires_at` integer, nullable
  - `quote` OnrampSessionQuote
    - `source_currency` string, required
    - `source_amount` string, required: Fiat amount converted to crypto, excluding fees.
    - `transaction_fee_amount` string, required: Stripe processing fee for the selected payment method.
    - `network_fee_amount` string, required
    - `source_total_amount` string, required: Total charged to the customer, including fees.

## Other responses

- `401`: Unauthorized
- `404`: Onramp intent not found
- `422`: Invalid request body, unsupported onramp destination, or Stripe identity/KYC action required
- `500`: Failed to create onramp session

## Changes

- **2026-11-10** `3535f46f4c27`: 1 info
  - added the optional property `quote` to the response with the `201` status

[Operation history](https://skmtc.dev/coinvoyage/apis/coinvoyage-api-v3/changes/onramp/intents/:intent_id/session/post.md)

---

[API](https://skmtc.dev/coinvoyage/apis/coinvoyage-api-v3.md) - [All operations](https://skmtc.dev/coinvoyage/apis/coinvoyage-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/coinvoyage/apis/coinvoyage-api-v3/revisions/3535f46f4c27?raw)