Set up Roqqett - Equals Documentation

Before you can take payments, your Roqqett merchant needs an approved settlement account and at least one checkout. You only do this once. After that, you create a checkout session for each payment.

Before you begin

Your Equals account must have Roqqett enabled. Speak to your account manager if it isn’t.
You need an Equals API key with access to Roqqett, and your IP address must be allowlisted. See About the API.
Every Roqqett request takes your account ID as the accountId query parameter.

All Roqqett endpoints are on https://api.equalsmoney.com/v2/roqqett.

Step 1: Check your merchant profile

GET /v2/roqqett/merchant

curl -i -X GET \
  'https://api.equalsmoney.com/v2/roqqett/merchant?accountId=F12345' \
  -H 'Authorization: ApiKey {apiKey}'

The response tells you what payers will see and what you’re allowed to change:

status must be ACTIVE before you can take payments.
name is shown to payers and sent to their bank as the payee name.
brandingPermissions says whether you can set your own colours or hide the “powered by Roqqett” logo.
canCreateTopUpCheckouts says whether you can take top-up payments.

To change your name, returns policy link or colours, use Update the merchant. To add a logo, use Upload the merchant logo with a PNG, JPEG or WebP file at least 256 pixels on its shortest side. Without a logo, payers see your initials.

Step 2: Add a settlement account

A settlement account is one of your own bank accounts. Payments settle straight into it. Use a GBP account to take GBP and a EUR account to take EUR. Set bankId to the bank that holds the account, from List banks. Roqqett uses it to pay refunds from this account, and refunds fail until it’s set.

POST /v2/roqqett/settlement-accounts

curl -i -X POST \
  'https://api.equalsmoney.com/v2/roqqett/settlement-accounts?accountId=F12345' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Main GBP account",
    "currencyCode": "GBP",
    "bankDetails": {
      "type": "SORT_CODE",
      "sortCode": "000000",
      "accountNumber": "00000000"
    },
    "bankId": "{bankId}"
  }'

curl -i -X POST \
  'https://api.equalsmoney.com/v2/roqqett/settlement-accounts?accountId=F12345' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Main EUR account",
    "currencyCode": "EUR",
    "bankDetails": {
      "type": "IBAN",
      "iban": "{iban}",
      "bic": "{bic}"
    },
    "bankId": "{bankId}"
  }'

name can be up to 18 characters: letters, numbers, spaces and &. A new account usually has an approvalStatus of PENDING while Equals checks it. It can only receive funds once it’s APPROVED. If it’s REJECTED, contact your account manager. You can’t change an account’s bank details after you add it. Instead, delete it and add a new one. Your first settlement account becomes your default. Checkouts that don’t name a settlement account pay into the default.

Step 3: Create a checkout

A checkout holds the settings that every checkout session on it shares. You can have several, for example one per currency or per website.

POST /v2/roqqett/checkouts

curl -i -X POST \
  'https://api.equalsmoney.com/v2/roqqett/checkouts?accountId=F12345' \
  -H 'Authorization: ApiKey {apiKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "SHOPPING",
    "name": "Web store",
    "currencyCode": "GBP",
    "returnUrl": "https://shop.example.com/order-complete",
    "shippingOptions": {
      "collectAddress": false
    }
  }'

Field	Description
`type`	`SHOPPING` to take payment for a basket. `TOP_UP` to pay into payees.
`name`	Your name for the checkout, up to 64 characters. Payers don’t see it.
`currencyCode`	`GBP` or `EUR`. You can’t change it later.
`returnUrl`	Where payers go back to after a checkout session. Must be `https`. A checkout session can set its own.
`settlementAccountId`	An approved settlement account in the same currency. Omit it to use your default.
`shippingOptions`	Set `collectAddress` to `true` to ask the payer for a shipping address. Add `dynamicRatesUrl` to fetch shipping rates from your server once the payer gives an address.
`locale`	The default language for payer screens, for example `en-GB`. Omit it to use the payer’s browser language.

Keep the id from the response. You need it to create checkout sessions. To switch a checkout off, or to change its return URL or settlement account, use Update a checkout.

​Before you begin

​Step 1: Check your merchant profile

​Step 2: Add a settlement account

​Step 3: Create a checkout

​Next steps

Before you begin

Step 1: Check your merchant profile

Step 2: Add a settlement account

Step 3: Create a checkout

Next steps