> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nowramp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions API
> Create and manage secure checkout sessions for the Stripe-like integration model.
# Sessions API
The Sessions API provides a Stripe-like checkout model: create a session server-side with a secret key, then redirect users to complete payment using a public key and client secret.
See the [Session-Based Checkout guide](/guides/session-checkout) for integration walkthroughs and examples.
## Base URL
```
POST|GET /v1/sessions/*
```
***
## Create Session
Creates a new checkout session. Returns a `clientSecret` that authorizes frontend operations.
```
POST /v1/sessions
```
**Authentication:** Secret key (`sk_`) required via `Authorization: Bearer sk_...`
### Request Body
| Parameter | Type | Required | Description |
| --------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalCustomerId` | string | Yes\* | Your user/player ID (max 255 chars) |
| `customerId` | string (UUID) | Yes\* | NowRamp customer UUID. *At least one of `externalCustomerId` or `customerId` is required.* |
| `type` | string | No | `"onramp"` (default) or `"offramp"` |
| `sourceAmount` | string or number | No | Fiat amount (e.g., `"100"`) |
| `sourceCurrency` | string | No | Fiat currency code (e.g., `"USD"`) |
| `destinationCurrency` | string | No | Crypto currency code (e.g., `"ETH"`) |
| `network` | string | No | Blockchain network (e.g., `"ethereum"`) |
| `destinationAddress` | string | No | Wallet address (max 255 chars) |
| `redirectUrl` | string (URL) | No | Redirect URL after payment completes |
| `country` | string | No | ISO 3166-1 alpha-2 country code (auto-detected from IP if omitted) |
| `expiresInSeconds` | number | No | Session TTL. Default: `1800` (30 min). Max: `86400` (24 hours). |
| `metadata` | object | No | Partner data attached to the session. When an order is created from the session, this is persisted as `order.metadata.partnerMetadata` and included in webhook payloads. Max 20 keys, 4KB, 2 levels of nesting. |
| `fieldLocks` | object | No | Explicit field lock configuration |
### Field Locks
Fields provided in the session are automatically locked. Use `fieldLocks` to override:
```json theme={null}
{
"destinationAddress": "0x742d...",
"fieldLocks": {
"destinationAddress": { "locked": true },
"sourceAmount": { "locked": true, "min": 10, "max": 1000 }
}
}
```
| Lock Field | Description |
| --------------------- | ---------------------------------------- |
| `destinationAddress` | Wallet address |
| `network` | Blockchain network |
| `destinationCurrency` | Crypto currency |
| `sourceAmount` | Fiat amount (supports `min`/`max` range) |
| `sourceCurrency` | Fiat currency |
### Request Example
```bash theme={null}
curl -X POST https://api.nowramp.com/v1/sessions \
-H "Authorization: Bearer sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"externalCustomerId": "player_12345",
"sourceAmount": "100",
"sourceCurrency": "USD",
"destinationCurrency": "ETH",
"network": "ethereum",
"destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21",
"redirectUrl": "https://yoursite.com/success",
"type": "onramp"
}'
```
### Response (201 Created)
```json theme={null}
{
"type": "session",
"id": "sess_abc123",
"attributes": {
"sessionId": "sess_abc123",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"clientSecret": "sess_secret_xyz789",
"type": "onramp",
"status": "pending",
"customerId": "cust_uuid",
"externalCustomerId": "player_12345",
"sourceAmount": "100",
"sourceCurrency": "USD",
"destinationCurrency": "ETH",
"destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21",
"network": "ethereum",
"redirectUrl": "https://yoursite.com/success",
"fieldLocks": {
"sourceAmount": { "locked": true },
"sourceCurrency": { "locked": true },
"destinationCurrency": { "locked": true },
"destinationAddress": { "locked": true },
"network": { "locked": true }
},
"expiresAt": "2026-02-17T15:30:00Z",
"createdAt": "2026-02-17T15:00:00Z"
}
}
```
The `clientSecret` is **only returned on creation**. Store it immediately — it cannot be retrieved later.
***
## Get Session
Retrieve session details and current status.
```
GET /v1/sessions/:sessionId
```
**Authentication:** Public key (`pk_`) or secret key (`sk_`) via `Authorization: Bearer ...`
### Response
Same structure as creation response, but **without `clientSecret`**.
***
## Confirm Session
Optionally confirm a session and update the wallet address or network before creating an order.
```
POST /v1/sessions/:sessionId/confirm
```
**Authentication:** Public key (`pk_`) via `Authorization: Bearer pk_...`
### Request Body
| Parameter | Type | Required | Description |
| -------------------- | ------ | -------- | ----------------------------------- |
| `clientSecret` | string | Yes | Client secret from session creation |
| `destinationAddress` | string | No | Updated wallet address |
| `network` | string | No | Updated network |
Confirm is optional. You can go directly from session creation to order creation.
***
## Create Order from Session
Creates an order from the session, returning a checkout URL for the chosen payment gateway.
```
POST /v1/sessions/:sessionId/order
```
**Authentication:** Public key (`pk_`) via `Authorization: Bearer pk_...`
### Request Body
| Parameter | Type | Required | Description |
| ---------------- | ---------------- | -------- | ----------------------------------------------------------- |
| `clientSecret` | string | Yes | Client secret from session creation |
| `fiatAmount` | string or number | Yes | Fiat amount |
| `cryptoCurrency` | string | Yes | Crypto currency code |
| `network` | string | Yes | Blockchain network |
| `fiatCurrency` | string | No | Fiat currency (defaults to session's `sourceCurrency`) |
| `walletAddress` | string | No | Wallet address (defaults to session's `destinationAddress`) |
| `gateway` | string | No | Gateway ID (falls back to project default) |
| `email` | string | No | Customer email |
### Request Example
```bash theme={null}
curl -X POST https://api.nowramp.com/v1/sessions/sess_abc123/order \
-H "Authorization: Bearer pk_live_xyz..." \
-H "Content-Type: application/json" \
-d '{
"clientSecret": "sess_secret_xyz789",
"fiatAmount": "100",
"fiatCurrency": "USD",
"cryptoCurrency": "ETH",
"network": "ethereum",
"walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21",
"gateway": "gateway_a",
"email": "user@example.com"
}'
```
### Response (201 Created)
```json theme={null}
{
"type": "order",
"id": "ord_xyz",
"attributes": {
"orderId": "ord_xyz",
"status": "created",
"sessionId": "sess_abc123",
"checkout": {
"method": "redirect",
"url": "https://checkout.gateway-a.com/...",
"expiresAt": 1800
}
}
}
```
Redirect the user to `checkout.url` to complete payment.
***
## Cancel Session
Cancel a pending session. Only available from the backend.
```
POST /v1/sessions/:sessionId/cancel
```
**Authentication:** Secret key (`sk_`) via `Authorization: Bearer sk_...`
***
## List Sessions
List sessions for the current project with filtering and pagination.
```
GET /v1/sessions
```
**Authentication:** Secret key (`sk_`) via `Authorization: Bearer sk_...`
### Query Parameters
| Parameter | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------------------------------- |
| `page` | number | Page number (default: 1) |
| `pageSize` | number | Results per page (default: 25, max: 100) |
| `status` | string | Filter by status: `pending`, `confirmed`, `processing`, `completed`, `expired`, `cancelled` |
| `customerId` | string | Filter by customer UUID |
| `externalCustomerId` | string | Filter by external customer ID |
***
## Error Codes
| Code | HTTP | Description |
| ---------------------- | ---- | --------------------------------------------------- |
| `SESSION_EXPIRED` | 409 | Session TTL exceeded. Create a new session. |
| `SESSION_ALREADY_USED` | 409 | An order was already created from this session. |
| `FORBIDDEN` | 403 | Invalid `clientSecret` or insufficient permissions. |
| `VALIDATION_ERROR` | 400 | Missing or invalid request fields. |
| `NOT_FOUND` | 404 | Session not found. |