Take top-up payments - Equals Documentation

A TOP_UP checkout session pays into a payee: a bank account you name, other than your settlement account. Use it when each payment needs to go to a different account, for example to fund a customer’s wallet held elsewhere.

Top-ups must be enabled by Equals. Check canCreateTopUpCheckouts in Retrieve the merchant, and speak to your account manager if it’s false.

Step 1: Create a top-up checkout

Create a checkout with "type": "TOP_UP". A top-up checkout has no settlement account or shipping options. See Set up Roqqett.

Step 2: Add a payee

POST /v2/roqqett/payees

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

Use SORT_CODE details for GBP and IBAN details for EUR. If you add the same bank details again, you get the existing payee back with a 200. A payee can only be paid once its approvalStatus is APPROVED. A payee that is still PENDING is being checked by Equals.

Step 3: Create a checkout session

Create a checkout session as in Accept payments, with "type": "TOP_UP" and the payeeId. Top-up sessions have no basket or shipping.

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": "TOP_UP",
    "checkoutId": "{topUpCheckoutId}",
    "payeeId": "d2a7c9e1-5b3f-4a8d-9e6c-1f0b2a4c8e57",
    "idempotencyKey": "wallet-7781-topup-0042",
    "merchantReference": "TOPUP-0042",
    "amount": { "amount": "100.00", "currencyCode": "GBP" }
  }'

Then redirect the payer to checkoutUrl and confirm the outcome in the same way. A completed top-up session has a paymentId but no orderId. Top-up payments can’t be refunded through the API.

​Step 1: Create a top-up checkout

​Step 2: Add a payee

​Step 3: Create a checkout session

Step 1: Create a top-up checkout

Step 2: Add a payee

Step 3: Create a checkout session