Paying for an order

An order has to be paid for the moment it is placed. There are two ways that happens, and which one applies is a setting on your account rather than a choice you make per request.

Funded accounts

Most accounts are funded: you top up a balance in advance, and each order debits it. Call GET /funding-accounts to see what the calling key can draw from.

[
  {
    "id": 5,
    "name": "Master float",
    "isMaster": true,
    "currency": "GBP",
    "balance": 12400.00,
    "label": "Master float (master float) (GBP): £12400.00"
  },
  {
    "id": 18,
    "name": "Marketing",
    "isMaster": false,
    "currency": "GBP",
    "balance": 400.00,
    "label": "Marketing (GBP): £400.00"
  }
]

You get the accounts the service account your key belongs to has been assigned, plus any your account admin has opened to everyone who can send. Pass the one you want as accountId on the send.

Picking the right account

Two rules:

1. Currency must match. The order is priced in the gift’s currency; an account holding a different currency is rejected with a 400. Accounts of every currency come back from GET /funding-accounts, labelled with theirs — filter client-side.
2. Always name one. If you top up a balance, accountId is required on every send, even if your key can only use one account. Omitting it is rejected with a 400. The API never picks an account for you, so an order always draws from the account you chose.

Insufficient balance

If the account cannot cover the order, nothing is placed and you get 402 Payment Required. No codes are issued and no partial order is created — retry after topping up.

Tip

balance is a snapshot. Don’t gate your own sends on it: between reading it and sending, someone else may have spent it. Send, and handle the 402.

Invoiced accounts

Some accounts are invoiced rather than funded. For those, GET /funding-accounts returns an empty array — there is nothing to choose from. Omit accountId entirely; orders are placed against your invoice and settled on your normal billing terms.

An empty array is not an error, and does not mean your key lacks permission.

What an order costs

totalCost on the send response is what was actually charged, in the order’s currency. For digital gifts that is the face value times the number of codes. For physical gifts it includes postage and VAT, which is why their price is fixed rather than chosen.