Skip to main content
POST
cURL

Authorizations

​
Authorization
string
header
required

Query Parameters

​
accountId
string
required

The ID of the account to work with.

Example:

"F50091"

Body

application/json

Body

​
type
enum<string>
required
Available options:
SHOPPING
​
checkoutId
string<uuid>
required

The checkout to take the session on. Its configured type must match type.

Maximum string length: 36
Example:

"6f1c2d0e-7a4b-4e2f-9c1d-3b5a7e9f0a12"

​
idempotencyKey
string
required

Caller-supplied key that makes creation safe to retry: a repeat with the same key on the same account returns the original checkout session instead of creating a second one. Use one key per payment journey.

Required string length: 1 - 255
Example:

"3f9a1c2e-7b4d-4e8a-9c6f-0d2b5a8e1f47"

​
merchantReference
string
required

The merchant's own reference for this checkout session, such as its order or basket ID. Shown to the merchant, never to the payer's bank.

Required string length: 1 - 128
Example:

"ORDER-10421"

​
amount
object
required

The total the payer pays, including any shipping. Must be in the checkout's currency.

​
bankReference
string

The reference shown on the payer's and merchant's bank statements. Faster Payments allows 18 characters; letters, digits, spaces and hyphens, not starting or ending with a space or hyphen. Omit to let Roqqett generate one (RQ + 16 characters).

Required string length: 1 - 18
Pattern: ^[A-Za-z0-9]([A-Za-z0-9 -]{0,16}[A-Za-z0-9])?$
Example:

"ORDER-10421"

​
description
string

What the payment is for, as shown to the payer.

Required string length: 1 - 140
Example:

"Order ORDER-10421"

​
returnUrl
string<uri>

Where the payer is sent once the session ends. Defaults to the checkout's return URL.

Maximum string length: 2048
Example:

"https://shop.example.com/checkout/complete"

​
locale
string

BCP 47 language tag for the payer-facing checkout. Matches the locale set held against a person and account in CIS, so a value forwarded from Equals Money always validates. A locale Roqqett has no translations for yet renders in en-GB.

Pattern: ^[a-zA-Z]{2,3}(-[a-zA-Z]{4})?(-([a-zA-Z]{2}|\d{3}))?$
Example:

"en-GB"

​
expiresAt
string<date-time>

When the session expires if not paid, as an ISO 8601 date-time with a Z or ±hh:mm offset. Must be a real calendar date and time, in the future, and within the checkout's maximum expiry window, which is also the default.

Maximum string length: 64
Example:

"2026-10-02T13:00:00Z"

​
basket
object
​
shipping
object

Response

OK

​
id
string<uuid>
required

The ID of a checkout session: one payment journey.

Maximum string length: 36
Example:

"0b8e5c3a-2f1d-4c6b-8a9e-7d4f2c1b0a93"

​
type
enum<string>
required

SHOPPING pays for a basket into the merchant's settlement account. TOP_UP pays into a payee the merchant supplies.

Available options:
SHOPPING,
TOP_UP
Example:

"SHOPPING"

​
status
enum<string>
required

OPEN until the payer authorises at their bank, PROCESSING while the payment settles, then exactly one terminal status.

Available options:
OPEN,
PROCESSING,
COMPLETED,
CANCELLED,
ABANDONED,
EXPIRED
Example:

"OPEN"

​
checkoutId
string<uuid>
required

The ID of a checkout: the configured payment page a checkout session is taken on.

Maximum string length: 36
Example:

"6f1c2d0e-7a4b-4e2f-9c1d-3b5a7e9f0a12"

​
merchantReference
string
required

The merchant's own reference for this checkout session, such as its order or basket ID. Shown to the merchant, never to the payer's bank.

Required string length: 1 - 128
Example:

"ORDER-10421"

​
description
string | null
required

What the payment is for, as shown to the payer.

Maximum string length: 140
Example:

"Order ORDER-10421"

​
amount
object
required

The total the payer pays, including any shipping.

​
payeeId
string<uuid> | null
required

The payee a TOP_UP session pays into. null for SHOPPING.

Maximum string length: 36
Example:

"d2a7c9e1-5b3f-4a8d-9e6c-1f0b2a4c8e57"

​
basket
object | null
required
​
shipping
object | null
required
​
locale
string | null
required

The locale the checkout is presented in. null when neither the request nor the checkout set one, in which case the payer's browser preference decides and en-GB is the final fallback.

Pattern: ^[a-zA-Z]{2,3}(-[a-zA-Z]{4})?(-([a-zA-Z]{2}|\d{3}))?$
Example:

"en-GB"

​
checkoutUrl
string<uri>
required

Where to send the payer to pay. Valid until expiresAt.

Maximum string length: 2048
Example:

"https://pay.roqqett.com/ch/pay/s/0b8e5c3a-2f1d-4c6b-8a9e-7d4f2c1b0a93"

​
returnUrl
string<uri> | null
required

Where the payer is sent once the session ends.

Maximum string length: 2048
Example:

"https://shop.example.com/checkout/complete"

​
paymentId
string<uuid> | null
required

The payment, once the payer has authorised one.

Maximum string length: 36
Example:

"9c4e1a7b-3d2f-4b6a-8e5c-0f7d2a9b1c34"

​
orderId
string<uuid> | null
required

The order a completed SHOPPING session produced. Always null for TOP_UP.

Maximum string length: 36
Example:

"7e2b9d4a-6c1f-4a5e-8b3d-2f9c0a1e6b78"

​
expiresAt
string<date-time>
required

When an OPEN session expires.

Example:

"2026-10-02T13:00:00Z"

​
createdAt
string<date-time>
required

The date the Resource was initially created. ISO 8601 format without milliseconds.

​
updatedAt
string<date-time>
required

The date the Resource was last modified. ISO 8601 format without milliseconds.

​
bankReference
string | null

The reference shown on the payer's and merchant's bank statements. Faster Payments allows 18 characters; letters, digits, spaces and hyphens, not starting or ending with a space or hyphen. Omit to let Roqqett generate one (RQ + 16 characters).

Required string length: 1 - 18
Pattern: ^[A-Za-z0-9]([A-Za-z0-9 -]{0,16}[A-Za-z0-9])?$
Example:

"ORDER-10421"