Get site bank accounts by EFT system ID

GET /api/configuration/{siteId}/bank-accounts/{eftSystemId}

Success: 200 OK

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Returns the one bank account a site holds for a given EFT system — the account that money collected under that scheme is paid into.

An EFT system is a bank-collection integration: BACS direct debit in the UK, its equivalents in Ireland, Australia and across the eurozone, or a third-party bureau such as Smart Debit. It is the mechanism a direct debit payment method actually collects through. Each EFT system declares which banking details it needs — sort code, account number, BIC and IBAN are each mandatory or not per scheme — and a site holds one bank account per scheme it collects under. The pairing is exactly one-to-one: an account is identified by EFT system and site together, so a site has at most one account per scheme, and that is why this endpoint returns a single account rather than a collection.

Reach for it when you already know which scheme you care about. If you do not, call Get all site bank accounts for the site and read eftsystemId off each account instead — that avoids guessing an id and getting a 404.

Where the EFT system id comes from. Ids are fixed platform-wide, not per operator, but which of them an operator has configured is not. Get the list from Get all EFT systems. The ids are: 1 BACS direct debit, 2 AIB, 3 Ulster Bank, 4 National Irish Bank, 5 Bank of Ireland, 6 Australian direct debit, 7 Dutch guilders, 8 French, 9 Spanish, 10 Swiss bank, 11 German, 12 Italian, 13 BACS credit, 14 Australian credit card, 15 Swiss post office, 16 Austrian, 17 Dutch euro, 18 Swedish, 19 Belgian francs, 20 Belgian euro, 21 Smart Debit, 22 third-party collections, 23 Danske Bank.

Which fields are mandatory depends on the scheme. The write endpoint, Create or update site bank account, validates a different set of fields for each EFT system id, so which fields are populated on an account you read back varies the same way. The rule applied:

EFT system id	Fields it requires
`1` BACS direct debit, `10` Swiss bank, `18` Swedish	`name`, `number`, `sortCode`
`2` AIB, `3` Ulster Bank, `4` National Irish Bank, `5` Bank of Ireland	`name`, `number`, `sortCode`, `userNumber`
`6` Australian direct debit	`name`, `number`, `sortCode`, `userNumber`, `financialInstitution`
`8` French, `12` Italian	`name`, `number`, `sortCode`, `bankCode`, `userNumber`
`11` German	`name`, `number`, `bankCode`
`13` BACS credit	`name`, `number`, `sortCode`, `bankCode`, `userNumber`, `merchantNumber`
`14` Australian credit card	`name`, `number`, `cdtfid`, `merchantNumber`
`15` Swiss post office	`name`, `number`, `userNumber`
`7` Dutch guilders, `16` Austrian, `17` Dutch euro	`name`, `number`
`19` Belgian francs, `20` Belgian euro	`name`, `number`, `sortCode`, `bankCode`, `userNumber`, `financialInstitution`
`9` Spanish, `21` Smart Debit, `22` third-party collections	`name` only
anything else, including `23` Danske Bank	`name`, `number`

On top of that, a scheme flagged as requiring a BIC also requires bic — rejected with Property Bic cannot be null — and a scheme that both requires a BIC and is configured to show BIC and IBAN for sites also requires iban, rejected with Property Iban cannot be null. In the shipped configuration every scheme requires a BIC except 11 German, and every scheme also requires an IBAN except 6 Australian direct debit, 7 Dutch guilders, 11 German, 14 Australian credit card, 19 Belgian francs, 21 Smart Debit and 22 third-party collections. Those two flags are per-operator settings rather than constants, so confirm them for the tenant you are integrating with rather than hard-coding this list. Everything outside a scheme's required set is optional and commonly null in the response.

Endpoint

GET {base_url}/api/configuration/{siteId}/bank-accounts/{eftSystemId}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`siteId`	string	Yes	The site whose bank account you want, maximum 15 characters. Take it from `id` on Get site by ID or the site list. Checked first and independently: a site that does not exist returns `404` with the body `Site with id {siteId} was not found`, which is a different message from the one you get when the site is real but has no account for the scheme.
`eftSystemId`	integer (int32)	Yes	The bank-collection scheme, as an integer id. Take it from `id` on Get all EFT systems, or from `eftsystemId` on an account returned by Get all site bank accounts. Unlike the write endpoint, this one does not check the id is a real EFT system — it simply looks for a matching account, so a nonsense id and a valid scheme the site has not configured both give the same `404`.

Sample request

cURL

curl -X GET '{base_url}/api/configuration/{siteId}/bank-accounts/{eftSystemId}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'

Response fields

The body is a single object, not an array. The field paths below carry a [] prefix, but the response is one account object — there is no array wrapper. Read the sample below, not the prefixes.

None of the account's encrypted fields are included here; the values you get are returned in plain text.

Field	Type	Description
`[].bankCode`	string	The bank's own institution code, maximum 25 characters. Used by the French, Italian, German, BACS credit and Belgian schemes, where it is mandatory; null for every other scheme. Not the same thing as `sortCode`.
`[].cdtfid`	string	The Australian credit-card scheme's transaction file identifier, maximum 25 characters. Mandatory for EFT system `14` (Australian credit card) and null everywhere else.
`[].eftsystemId`	integer (int32)	The EFT system this account collects under. Echoes the `eftSystemId` you asked for, and identifies the account together with `siteId`. Note the lower-case `s` in the field name — it is `eftsystemId` in the body but `eftSystemId` in the URL.
`[].financialInstitution`	string	The collecting financial institution's identifier, maximum 25 characters. Mandatory for the Australian direct debit and Belgian schemes; null otherwise.
`[].merchantNumber`	string	The merchant number issued by the acquirer or scheme, maximum 25 characters. Mandatory for BACS credit and Australian credit card; null otherwise.
`[].name`	string	The name the bank account is held in, maximum 32 characters. This is the only field every scheme requires, so it is the one field you can rely on being populated. Note the 32-character ceiling — shorter than most of the other text fields, and shorter than many legal account names.
`[].number`	string	The bank account number, maximum 30 characters, in whatever format the scheme uses. Required by every scheme except Spanish, Smart Debit and third-party collections. This is account-holder data — treat it as confidential and do not log it. For SEPA schemes the equivalent value is `iban`.
`[].originatorPlusInd`	integer (int32)	A Bank of Ireland-only flag: `0` no, `1` yes. Ignore it for any other EFT system. It can come back null rather than `0`.
`[].processInAuddisRun`	integer (int32)	Whether this account's direct debit instructions are included in the AUDDIS run — the BACS process that lodges new and amended mandates with the paying banks. `0` no, `1` yes. Null is possible and means the operator has never set it.
`[].siteId`	string	The site the account belongs to, maximum 15 characters. Echoes the `siteId` you asked for, and identifies the account together with `eftsystemId`.
`[].sortCode`	string	The branch sort code, maximum 25 characters. Mandatory for the BACS direct debit, Irish, Australian direct debit, French, Italian, Swiss bank, Swedish, BACS credit and Belgian schemes; null otherwise. For SEPA schemes the equivalent value is `bic`.
`[].userNumber`	string	The direct debit originator or service user number the scheme issues to the operator, maximum 25 characters. It is the direct debit user number used in Australia, France, Ireland and Italy; it is also mandatory for the Swiss post office and BACS credit schemes. Null where the scheme does not use it.
`[].bic`	string	The bank identifier code, maximum 25 characters — the SEPA equivalent of the sort code. Mandatory for every scheme whose EFT system settings flag a BIC as required, which in the shipped configuration is all of them except `11` German.
`[].iban`	string	The international bank account number, maximum 50 characters — the SEPA equivalent of the account number, and confidential banking data. Mandatory only where the scheme both requires a BIC and is configured to show BIC and IBAN for sites; in the shipped configuration that excludes `6` Australian direct debit, `7` Dutch guilders, `11` German, `14` Australian credit card, `19` Belgian francs, `21` Smart Debit and `22` third-party collections, which collect domestically.

Sample response

200 OK

{
  "bankCode": "string",
  "cdtfid": "string",
  "eftsystemId": 12345,
  "financialInstitution": "string",
  "merchantNumber": "string",
  "name": "string",
  "number": "string",
  "originatorPlusInd": 1,
  "processInAuddisRun": 1,
  "siteId": "string",
  "sortCode": "string",
  "userNumber": "string",
  "bic": "string",
  "iban": "string"
}

Errors

Status	Meaning	When
`404`	Not found	Two distinct causes, each with its own plain-text body — branch on the message, not just the status. `Site with id {siteId} was not found` means the site id does not exist at all. `Bank Account with site id {siteId} and eft system id {eftSystemId} was not found` means the site exists but holds no account for that scheme; this is the ordinary "not configured yet" case, and it is also what you get for an EFT system id that is not a real scheme, because the id itself is never validated on this endpoint.
`500`	Internal server error	An unexpected server-side failure while resolving the site or reading the account. The response has no body, so there is nothing to diagnose from in the response.

This page as markdown · All pages · llms.txt