Accept payments - Equals Documentation

The hosted checkout is the way to integrate Roqqett. Your server creates a checkout session, you redirect the payer to its checkoutUrl, and Roqqett takes them through paying at their bank.

Before you begin

Complete Set up Roqqett. You need the ID of an active SHOPPING checkout.

Step 1: Create a checkout session

When the payer chooses to pay with Roqqett, your server creates a checkout session. Always create it on your server, with prices from your own records.

POST /v2/roqqett/checkout-sessions

curl -i -X POST \
  'https://api.equalsmoney.com/v2/roqqett/checkout-sessions?accountId=F12345' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "SHOPPING",
    "checkoutId": "6f1c2d0e-7a4b-4e2f-9c1d-3b5a7e9f0a12",
    "idempotencyKey": "order-10421-attempt-1",
    "merchantReference": "ORDER-10421",
    "description": "Order ORDER-10421",
    "amount": { "amount": "54.99", "currencyCode": "GBP" },
    "returnUrl": "https://shop.example.com/orders/ORDER-10421",
    "basket": {
      "items": [
        {
          "name": "Linen shirt",
          "quantity": 1,
          "unitPrice": { "amount": "49.99", "currencyCode": "GBP" }
        }
      ]
    },
    "shipping": {
      "amount": { "amount": "5.00", "currencyCode": "GBP" }
    }
  }'

{
  "id": "0b8e5c3a-2f1d-4c6b-8a9e-7d4f2c1b0a93",
  "type": "SHOPPING",
  "status": "OPEN",
  "checkoutId": "6f1c2d0e-7a4b-4e2f-9c1d-3b5a7e9f0a12",
  "merchantReference": "ORDER-10421",
  "amount": { "amount": "54.99", "currencyCode": "GBP" },
  "checkoutUrl": "https://pay.roqqett.com/ch/pay/s/0b8e5c3a-2f1d-4c6b-8a9e-7d4f2c1b0a93",
  "returnUrl": "https://shop.example.com/orders/ORDER-10421",
  "expiresAt": "2026-10-07T12:20:00Z"
}

The sample response shows the main fields. See Create a checkout session for the full request and response.

Field	Description
`idempotencyKey`	Use one key per payment journey. If you retry with the same key and the same body, you get the original session back with a `200` instead of a second session.
`merchantReference`	Your own reference, such as your order ID, up to 128 characters. It isn’t sent to the payer’s bank.
`amount`	A decimal string in major units, such as `"54.99"`. It must be in the checkout’s currency and equal the basket items plus shipping.
`description`	What the payment is for, as shown to the payer. Up to 140 characters.
`returnUrl`	Where the payer goes back to. Must be `https`. Defaults to the checkout’s return URL.
`basket`	Optional. Up to 100 items, shown to the payer while they pay.
`shipping`	Optional. The shipping charge, and the delivery address if you already have it. Leave it out on a checkout that fetches dynamic shipping rates.
`expiresAt`	Optional. When the session expires if it isn’t paid. Defaults to, and can’t be later than, 20 minutes after creation.

Roqqett sets the payment reference that appears on bank statements. It starts with RQ.

Step 2: Redirect the payer

Send the payer’s browser to checkoutUrl. They choose their bank and approve the payment in their banking app or online banking. On a desktop computer they can scan a QR code to carry on on their phone. Open checkoutUrl in the same tab or a new one. It doesn’t need the Roqqett JavaScript library.

Step 3: Handle the payer’s return

When the payment completes, Roqqett shows the payer a receipt with a button to return to returnUrl. Roqqett doesn’t add query parameters to the URL. To know which order the payer is returning to, put your own reference in each session’s returnUrl, as in the sample request. A payer reaching your returnUrl doesn’t prove they paid. Always check the session’s status on your server before you fulfil the order.

Step 4: Confirm the outcome

GET /v2/roqqett/checkout-sessions/{checkoutSessionId}

curl -i -X GET \
  'https://api.equalsmoney.com/v2/roqqett/checkout-sessions/0b8e5c3a-2f1d-4c6b-8a9e-7d4f2c1b0a93?accountId=F12345' \
  -H 'Authorization: ApiKey {apiKey}'

`status`	Meaning	What to do
`OPEN`	The payer hasn’t approved a payment yet. They can retry with any bank.	Wait.
`PROCESSING`	The payer approved the payment and the bank is settling it.	Wait. Don’t create another session for the same order.
`COMPLETED`	The payment is complete.	Fulfil the order. The session now has a `paymentId` and an `orderId`.
`CANCELLED`	The session was cancelled.	Offer the payer another way to pay.
`ABANDONED` or `EXPIRED`	The session ran out of time without being paid.	Offer the payer another way to pay.

COMPLETED, CANCELLED, ABANDONED and EXPIRED are final. A session that is PROCESSING when it reaches its expiry time still completes if the bank confirms the payment. To find sessions by your own reference, use List checkout sessions with merchantReference.

Cancel a checkout session

If the payer chooses another payment method or empties their basket, cancel the session so it can’t be paid.

POST /v2/roqqett/checkout-sessions/{checkoutSessionId}/cancel

You can only cancel an OPEN session. Once the payer may have approved the payment, cancelling returns 409.

​Before you begin

​Step 1: Create a checkout session

​Step 2: Redirect the payer

​Step 3: Handle the payer’s return

​Step 4: Confirm the outcome

​Cancel a checkout session

​Next steps

Before you begin

Step 1: Create a checkout session

Step 2: Redirect the payer

Step 3: Handle the payer’s return

Step 4: Confirm the outcome

Cancel a checkout session

Next steps