---
title: Payment Sessions
description: Create and manage payment sessions for orders.
---

# Payment Sessions

Create and manage payment sessions for orders.

## [POST /payment-sessions](/api-reference/payment-sessions#tag/payment-sessions/POST/payment-sessions)

Create payment session

Create a new payment session to collect payment information for an order. For orders with a
positive total, this initiates payment collection. For zero-total orders, consider creating a
payment profile session instead. The order must be complete and ready for submission — an order
that would fail submission validation is rejected before any payment is collected. Once the
payment succeeds, the order is submitted automatically.

Set hosted to false to collect the payment inside your own checkout page. The response then
carries providerContext instead of hostedUrl. Only this call returns providerContext, because
it contains a credential that is not stored. To show the form again, create a new session.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code.

### Request body (required)

Type: `object`

- `orderId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-89abcdef0123) — The unique identifier of the order to create a payment session for.
- `paymentProvider` (`enum<string>`, required, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction.
- `paymentProfileId` (`string`, optional, example e5f6a7b8-c9d0-1234-5678-9abcdef01234) — A previously saved payment method to prefill on the payment page, for returning customers.
- `savePaymentProfile` (`boolean`, optional, example true) — Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
- `setAsDefaultPaymentProfile` (`boolean`, optional, example false) — Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.
- `grantAutopayConsent` (`boolean`, optional, example false) — Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.
- `hosted` (`boolean`, optional, example true) — Whether to collect the payment on a hosted page. A hosted session returns hostedUrl, and you send the customer to it. An embedded session (false) returns providerContext, and you show the payment form inside your own checkout page. Defaults to true.
- `returnUrl` (`string`, required, example https://example.com/order/confirmation) — The URL the customer comes back to after they pay. A hosted page redirects to it. An embedded form redirects to it only for a payment method that leaves the page, such as 3D Secure. Must be provided to create a session.
- `cancelUrl` (`string`, optional, example https://example.com/order/checkout) — The URL the customer is redirected to if they cancel the payment on the hosted page. A hosted session only.
- `branding` (`object`, optional) — The colors and the name that the payment form shows. Every property is optional. A property you leave out keeps the default of the payment provider. Branding does not change the layout or the spacing of the form.
  - `backgroundColor` (`string`, optional, pattern ^#[0-9a-fA-F]{6}$, example #ffffff) — The background color of the payment form, as a hex value with a leading number sign.
  - `buttonColor` (`string`, optional, pattern ^#[0-9a-fA-F]{6}$, example #0cf68c) — The color of the payment button, as a hex value with a leading number sign.
  - `borderStyle` (`enum<string>`, optional, one of PILL, RECTANGULAR, ROUNDED, example PILL) — The shape of the buttons and the input fields of the payment form.
  - `displayName` (`string`, optional, max length 100, example Seamless) — The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms.
- `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
  - `*` (`string`, optional)

### Responses

#### 201

Payment session created successfully

Type: [PaymentSession](/api-reference/models.md#models/PaymentSession)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 412

A precondition for this request was not met.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/payment-sessions \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "paymentProvider": "STRIPE",
  "savePaymentProfile": true,
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "metadata": {
    "source": "web-checkout"
  }
}'
```

## [GET /payment-sessions/{paymentSessionId}](/api-reference/payment-sessions#tag/payment-sessions/GET/payment-sessions/{paymentSessionId})

Get payment session

Retrieve details of a specific payment session by its identifier.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `paymentSessionId` (`string`, required) — The unique identifier of the payment session to retrieve.

### Responses

#### 200

Payment session retrieved successfully

Type: [PaymentSession](/api-reference/models.md#models/PaymentSession)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

## [POST /payment-sessions/{paymentSessionId}/cancel](/api-reference/payment-sessions#tag/payment-sessions/POST/payment-sessions/{paymentSessionId}/cancel)

Cancel payment session

Cancel an active payment session, preventing further payment attempts.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `paymentSessionId` (`string`, required) — The unique identifier of the payment session to cancel.

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code.

### Request body (optional)

Type: `object`

- `reason` (`string`, optional, example Customer changed their mind) — Optional reason for cancelling the payment session.
- `metadata` (`object with string keys`, optional, example {"cancelled_by":"customer_service","ticket_id":"SUPP-12345"}) — Custom key-value pairs for additional cancellation information.
  - `*` (`string`, optional)

### Responses

#### 200

Payment session canceled successfully

Type: [PaymentSession](/api-reference/models.md#models/PaymentSession)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 412

A precondition for this request was not met.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "Customer changed their mind",
  "metadata": {
    "cancelled_by": "customer_service",
    "ticket_id": "SUPP-12345"
  }
}'
```