> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accept payments

> Take a Roqqett payment by creating a checkout session and redirecting the payer to the hosted checkout.

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](/pages/roqqett/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.

<Note>
  **POST** `/v2/roqqett/checkout-sessions`
</Note>

<CodeGroup>
  ```bash Sample request theme={null}
  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" }
      }
    }'
  ```

  ```json Sample response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

The sample response shows the main fields. See [Create a checkout session](/api-reference/checkout-sessions/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

<Note>
  **GET** `/v2/roqqett/checkout-sessions/{checkoutSessionId}`
</Note>

```bash theme={null}
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](/api-reference/checkout-sessions/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.

<Note>
  **POST** `/v2/roqqett/checkout-sessions/{checkoutSessionId}/cancel`
</Note>

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

## Next steps

* [Refund payments](/pages/roqqett/refund-payments)
* [Roqqett webhooks](/pages/roqqett/webhooks)