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.

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

9 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

Defines individual limits for business and personal accounts.

2 properties

dailyobject

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

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

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.

statusstring

The status of the institution

enableddisabledtemporarily_disabled

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

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

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

List institutions for Billing Request#

GET/billing_requests/{billing_request_id}/institutions

Returns all institutions valid for a Billing Request.

This endpoint is currently supported only for FasterPayments.

Path Parameters

Name	Type	Description
`billing_request_id`required	string	The billing request id

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

9 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

Defines individual limits for business and personal accounts.

2 properties

dailyobject

singleobject

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.

statusstring

The status of the institution

enableddisabledtemporarily_disabled

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

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

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject