Institution

Institutions that are supported when creating Bank Authorisations for a particular country or purpose.

Not all institutions support both Payment Initiation (PIS) and Account Information (AIS) services.

List Institutions#

GET/institutions

Returns a list of supported institutions.

Query Parameters

Name	Type	Description
`country_code`	string	ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default.
`scheme`	string	The scheme that institutions support. The available options include `faster_payments`, `sepa_credit_transfer`, and `sepa_instant_credit_transfer`. If nothing is provided, no scheme filter is applied to the returned institutions.
`feature`	string	The feature that institutions support. The available options include `pis`, `vrp_sweeping`, and `vrp_commercial`. If nothing is provided, institutions supporting 'pis' are returned by default.
`branch_code`	string	(Currently only supports UK sort-codes) The six-digit number that identifies both the bank and the specific branch where an account is held, eg. '601234'.
`include_disabled`	enum	Indicates whether to include temporarily disabled institutions in the response. If not provided or set to false, only enabled institutions will be returned.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/institutions?country_code=GB HTTP/1.1

@client.institutions.list(params: { country_code: "GB" })

client.institutions.list(params={"country_code": "GB" }).records

// List of all institutions.
const institutions = await client.institutions.list();

// List of institutions for a country code.
const gbInstitutions = await client.institutions.list({ country_code: 'GB'});

$client->institutions()->list([
  "params" => ["country_code" => "GB"]
]);

for (Institution institution : client.institutions().all().withCountryCode("GB").execute()) {
  System.out.println(institution.getId());
}

institutionListParams := gocardless.InstitutionListParams{}
institutionListResult, err := client.Institutions.List(ctx, institutionListParams)
for _, institution := range institutionListResult.Institutions {
    fmt.Println(institution.Id)
}

var request = new GoCardless.Services.InstitutionListRequest()
 {
     CountryCode = "GB",
 };

var institutionListResponse = await client.Institutions.ListAsync(request);
foreach (GoCardless.Resources.Institution institution in institutionListResponse.Institutions)
{
    Console.WriteLine(institution.Id);
}

Responsehttp

HTTP/1.1 200 OK
Content-Type: application/json
{
  "institutions": [
    {
      "id": "monzo",
      "name": "Monzo",
      "logo_url": "https://assets.gocardless.com/icon",
      "icon_url": "https://assets.gocardless.com/icon",
      "country_code": "GB",
      "limits": {
        "daily": {
          "business": "5000000",
          "personal": "2000000"
        },
        "single": {
          "business": "5000000",
          "personal": "2000000"
        }
      }
    }
  ]
}

Response 200

Successful response

institutionsarray

7 properties

idstring

The unique identifier for this institution

namestring

A human readable name for this institution

icon_urlstring

A URL pointing to the icon for this institution

logo_urlstring

A URL pointing to the logo for this institution

rolesarray

The roles assigned to this institution, representing the open banking features it supports.

country_codestring

ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default.

limitsobject | null

Defines individual limits for business and personal accounts.

2 properties

dailyobject | null

Daily limit details for this institution, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). The 'limits' property is only available via an authenticated request with a generated access token

singleobject | null

Single transaction limit details for this institution, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). The 'limits' property is only available via an authenticated request with a generated access token

metaobject

2 properties

limitintegerrequired

cursorsobjectrequired

2 properties

beforestring | nullrequired

Cursor pointing to the end of the desired set.

afterstring | nullrequired

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

List institutions for Billing Request#

GET/billing_requests/{billing_request_id}/institutions

Restricted

this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.

Returns all institutions valid for a Billing Request.

This endpoint is currently supported only for FasterPayments.

Path Parameters

Name	Type	Description
`billing_request_id`	stringrequired	The billing request id

Query Parameters

Name	Type	Description
`search`	string	A search substring for retrieving institution(s), based on the institution's name.
`ids`	string \| array	ID(s) of the institution(s) to retrieve. More than one ID can be specified using a comma-separated string.
`country_code`	stringrequired	ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default.
`include_disabled`	enum	Indicates whether to include temporarily disabled institutions in the response. If not provided or set to false, only enabled institutions will be returned.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/billing_requests/BRQ123/institutions?country_code=GB&include_disabled=true HTTP/1.1

@client.institutions.list_for_billing_request("BR123", {
  params: { country_code: "GB" }
})

client.institutions.list_for_billing_request("BR123", params={
  "country_code": "GB"
}).records

const institutions = await client.institutions.list_for_billing_request("BR123", { country_code: 'GB'});

$client->institutions()->listForBillingRequest("BR123", [
  "params" => ["country_code" => "GB"]
]);

client.institutions().listForBillingRequest("BR123").withCountryCode("GB").execute();

institutionListForBillingRequestParams := gocardless.InstitutionListForBillingRequestParams{
  CountryCode: "GB",
}
institutionListForBillingRequestResult, err := client.Institutions.ListForBillingRequest(ctx, "BR123", institutionListForBillingRequestParams)
for _, institution := range institutionListForBillingRequestResult.Institutions {
    fmt.Println(institution.Id)
}

var request = new GoCardless.Services.InstitutionListForBillingRequestRequest()
 {
     CountryCode = "GB",
 };

var institutionListResponse = await client.Institutions.ListForBillingRequestAsync("BR123", request);

Responsehttp

HTTP/1.1 200
Content-Type: application/json
{
  "institutions": [
    {
        "id": "BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1",
        "name": "Bank of Scotland Business",
        "logo_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "icon_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "country_code": "GB",
        "autocompletes_collect_bank_account": true,
        "status": "enabled"
    },
    {
        "id": "BANK_OF_SCOTLAND_BOFSGBS1",
        "name": "Bank of Scotland Personal",
        "logo_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "icon_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
        "country_code": "GB",
        "autocompletes_collect_bank_account": true,
        "status": "temporarily_disabled"
    }
  ]
}

Response 200

Successful response

institutionsarray

7 properties

idstring

The unique identifier for this institution

namestring

A human readable name for this institution

icon_urlstring

A URL pointing to the icon for this institution

logo_urlstring

A URL pointing to the logo for this institution

country_codestring

ISO 3166-1 alpha-2 code. The country code of the institution. If nothing is provided, institutions with the country code 'GB' are returned by default.

autocompletes_collect_bank_accountboolean

Flag to show if selecting this institution in the select_institution action can auto-complete the collect_bank_account action. The bank can return the payer's bank account details to GoCardless.

statusenum

The status of the institution

Possible values:enableddisabledtemporarily_disabled

metaobject

2 properties

limitintegerrequired

cursorsobjectrequired

2 properties

beforestring | nullrequired

Cursor pointing to the end of the desired set.

afterstring | nullrequired

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

errorobjectrequired

Generic error

6 properties

codeinteger

documentation_urlstring

errorsarrayrequired

6 properties

reasonstring

fieldstring

request_pointerstring

messagestringrequired

metadataobject

linksobject

messagestringrequired

request_idstringrequired

typestring

Was this helpful?

Support Dashboard