Amounts, currencies and dates

Amounts on the Client API are integers in the currency's minor units: pence, cents, and so on. GET /v1/reference/currencies returns every supported currency with the number of minor units it uses, so you can convert reliably instead of assuming two decimal places.

Amounts in responses

Requests carry a bare integer in amount alongside a separate currency. Responses do not: wherever the API returns money it returns an Amount object that gives you both representations at once.

{
  "amountInMinorUnits": 25000,
  "value": 250.00,
  "currency": "GBP"
}

You will meet this object as amount on a transaction and as balance on a currency account.

Currencies

Currencies are ISO 4217 three-letter codes in upper case, for example GBP, EUR, USD. GET /v1/reference/currencies is the source of truth for which currencies are supported and how precise each one is; every entry returns code, name and minorUnit. Read it at start-up and cache it rather than hard-coding a table, because not every currency uses two decimal places. An account holds a balance per currency, so the currency you send must be one the debiting account actually holds.

Transaction amounts and direction

On GET /v1/transactions, amountInMinorUnits and the amountFrom/amountTo filters are unsigned magnitudes. The sign of the movement is carried separately by direction, which is Credit or Debit. A debit of 250.00 GBP therefore appears as 25000 with direction: Debit, not as a negative number.

A transaction that touches more than one currency account is returned as one row per currency account touched, so the same transactionId can appear more than once. The identity of a row is the pair (transactionId, currencyAccountId).

Dates

date and valueDate are dates, not timestamps: the UK (Europe/London) business date, formatted YYYY-MM-DD.

• On POST /v1/outbound-payments, leaving valueDate blank resolves to the nearest available date for the resolved rail. A date outside the earliest-available or maximum-future window is rejected.
• A payment with a future valueDate sits at Scheduled and only enters the lifecycle on that date.
• GET /v1/reference/fx-value-dates/{pair} lists the available value dates for a currency pair. On POST /v1/fx/quotes, omitting valueDate uses the earliest available date for the pair.
• The dateFrom and dateTo filters on GET /v1/transactions are UK business dates too, so a transaction's value date will not always match the UTC day on which it was created. Use the createdFrom and createdTo filters on the list endpoints when you need to find something by when you sent it rather than by when it settles.

Everything else that carries a time (createdAt, expiresAt, accountDetailsConfirmedAt) is a full ISO 8601 date-time in UTC. Do not compare one of those directly against a date orvalueDate.