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 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:

{
  "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

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)

{
  "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

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)

{
  "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.

Overview

Sessions

Onramp

Sessions API

Sessions API

Base URL

Create Session

Request Body

Field Locks

Request Example

Response (201 Created)

Get Session

Response

Confirm Session

Request Body

Create Order from Session

Request Body

Request Example

Response (201 Created)

Cancel Session

List Sessions

Query Parameters

Error Codes

​Sessions API

​Base URL

​Create Session

​Request Body

​Field Locks

​Request Example

​Response (201 Created)

​Get Session

​Response

​Confirm Session

​Request Body

​Create Order from Session

​Request Body

​Request Example

​Response (201 Created)

​Cancel Session

​List Sessions

​Query Parameters

​Error Codes

Sessions API

Base URL

Create Session

Request Body

Field Locks

Request Example

Response (201 Created)

Get Session

Response

Confirm Session

Request Body

Create Order from Session

Request Body

Request Example

Response (201 Created)

Cancel Session

List Sessions

Query Parameters

Error Codes