Endpoints
Base URL: https://bankaccountdata.gocardless.com. All requests require an Authorization: Bearer <access_token> header except the Authentication endpoints.
Authentication
Obtain JWT pair#
/api/v2/token/new/Request Body
secret_idstringrequiredSecret id from /user-secrets/
secret_keystringrequiredSecret key from /user-secrets/
Response 200
Obtain JWT response.
accessstringaccess_expiresintegerrefreshstringrefresh_expiresintegerErrors 401403429
Incorrect secret key or id
IP address not whitelisted
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredRefresh access token#
/api/v2/token/refresh/Request Body
refreshstringrequiredResponse 200
Refresh access token.
accessstringaccess_expiresintegerErrors 401403429
Token is invalid or expired
IP address not whitelisted
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredInstitutions
List all available institutions#
/api/v2/institutions/Query Parameters
| Name | Type | Description |
|---|---|---|
access_scopes_supported | string | Boolean value, indicating if access scopes are supported |
account_selection_supported | string | Boolean value, indicating if account selection is supported |
business_accounts_supported | string | Boolean value, indicating if business accounts are supported |
card_accounts_supported | string | Boolean value, indicating if card accounts are supported |
corporate_accounts_supported | string | Boolean value, indicating if corporate accounts are supported |
country | string | ISO 3166 two-character country code |
pending_transactions_supported | string | Boolean value, indicating if pending transactions are supported |
private_accounts_supported | string | Boolean value, indicating if private accounts are supported |
read_debtor_account_supported | string | Boolean value, indicating if debtor account can be read before submitting payment |
read_refund_account_supported | string | Boolean value, indicating if read refund account is supported |
separate_continuous_history_consent_supported | string | Boolean value, indicating if separate consent for continuous history is supported |
ssn_verification_supported | string | Boolean value, indicating if ssn verification is supported |
Response 200
list of supported Institutions in the country
Errors 400401403404429
Unknown Fields
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredGet details about a specific Institution and its supported features#
/api/v2/institutions/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired |
Response 200
Retrieve institution by id
idstringrequirednamestringrequiredbicstringtransaction_total_daysstringmax_access_valid_for_daysstringmax_access_valid_for_days_reconfirmationstringcountriesarrayrequiredlogostringrequiredsupported_featuresarrayrequiredidentification_codesarrayrequiredErrors 401403404429
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredEnd User Agreements
Retrieve all End User Agreements belonging to the company#
/api/v2/agreements/enduser/Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of results to return per page. |
offset | integer | The initial zero-based index from which to return the results. |
Response 200
Retrieve all end user agreements
countintegerrequirednextstring | nullpreviousstring | nullresultsarrayrequired8 properties
idstring
The ID of this End User Agreement, used to refer to this end user agreement in other API calls.
createdstring
The date & time at which the end user agreement was created.
institution_idstringrequired
an Institution ID for this EUA
max_historical_daysinteger
Maximum number of days of transaction data to retrieve.
access_valid_for_daysinteger
Number of days from acceptance that the access can be used.
access_scopearray
Array containing one or several values of ['balances', 'details', 'transactions']
acceptedstring | null
The date & time at which the end user accepted the agreement.
reconfirmationboolean
if this agreement can be extended. Supported by GB banks only.
Errors 401403404429
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredRetrieve end user agreement by ID#
/api/v2/agreements/enduser/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this end user agreement. |
Response 200
Retrieve end user agreement by ID
idstringcreatedstringinstitution_idstringrequiredmax_historical_daysintegeraccess_valid_for_daysintegeraccess_scopearrayacceptedstring | nullreconfirmationbooleanErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredDelete an end user agreement#
/api/v2/agreements/enduser/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this end user agreement. |
Response 200
summarystringrequireddetailstringrequiredErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredAccept an end-user agreement via the API#
/api/v2/agreements/enduser/{id}/accept/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this end user agreement. |
Request Body
user_agentstringrequiredip_addressstringrequiredResponse 200
Accept end user agreement
idstringcreatedstringinstitution_idstringrequiredmax_historical_daysintegeraccess_valid_for_daysintegeraccess_scopearrayacceptedstring | nullreconfirmationbooleanErrors 400401403404405429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
End User Agreements cannot be accepted more than once
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredRetrieve EUA reconfirmation#
/api/v2/agreements/enduser/{id}/reconfirm/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this end user agreement. |
Response 200
Reconfirmation details
reconfirmation_urlstringcreatedstringurl_valid_fromstringurl_valid_tostringredirectstring | nulllast_accessedstring | nulllast_submittedstring | nullaccountsobjectErrors 400401403404429
EUA does not have reconfirmation flag set.
Token is invalid or expired
Reconfirmation is not enabled for this company.
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredCreate EUA reconfirmation#
/api/v2/agreements/enduser/{id}/reconfirm/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this end user agreement. |
Request Body
redirectstring | nullOptional redirect URL for reconfirmation to override requisition's redirect.
Response 201
Reconfirmation created
reconfirmation_urlstringcreatedstringurl_valid_fromstringurl_valid_tostringredirectstring | nulllast_accessedstring | nulllast_submittedstring | nullaccountsobjectErrors 400401403404429
There are no accounts linked.
Token is invalid or expired
Reconfirmation is not enabled for this company.
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredRequisitions
Retrieve all requisitions belonging to the company#
/api/v2/requisitions/Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of results to return per page. |
offset | integer | The initial zero-based index from which to return the results. |
Response 200
Retrieve all requisitions
countintegerrequirednextstring | nullpreviousstring | nullresultsarrayrequired13 properties
idstringcreatedstring | null
The date & time at which the requisition was created.
redirectstring | nullrequired
redirect URL to your application after end-user authorization with ASPSP
statusobject
status of this requisition
institution_idstringrequired
an Institution ID for this Requisition
agreementstring
EUA associated with this requisition
referencestring
additional ID to identify the end user
accountsarray
array of account IDs retrieved within a scope of this requisition
user_languagestring
A two-letter country code (ISO 639-1)
linkstring
link to initiate authorization with Institution
ssnstring
optional SSN field to verify ownership of the account
account_selectionboolean
option to enable account selection view for the end user
redirect_immediateboolean
enable redirect back to the client after account list received
Errors 400401403404429
Unknown Fields
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredCreate a new requisition#
/api/v2/requisitions/Request Body
redirectstring | nullrequiredredirect URL to your application after end-user authorization with ASPSP
institution_idstringrequiredan Institution ID for this Requisition
agreementstringEUA associated with this requisition
referencestringadditional ID to identify the end user
user_languagestringA two-letter country code (ISO 639-1)
ssnstringoptional SSN field to verify ownership of the account
account_selectionbooleanoption to enable account selection view for the end user
redirect_immediatebooleanenable redirect back to the client after account list received
Response 201
Requisition has been successfully created
idstringcreatedstring | nullredirectstring | nullrequiredstatusobjectinstitution_idstringrequiredagreementstringreferencestringaccountsarrayuser_languagestringlinkstringssnstringaccount_selectionbooleanredirect_immediatebooleanErrors 400401402403404429
Field is required
Token is invalid or expired
Free usage limit exceeded
IP address not whitelisted
Errors related to 'agreement' field.
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredRetrieve a requisition by ID#
/api/v2/requisitions/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this requisition. |
Response 200
Get requisition by ID
idstringcreatedstring | nullredirectstring | nullrequiredstatusobjectinstitution_idstringrequiredagreementstringreferencestringaccountsarrayuser_languagestringlinkstringssnstringaccount_selectionbooleanredirect_immediatebooleanErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredDelete requisition and its end user agreement#
/api/v2/requisitions/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired | A UUID string identifying this requisition. |
Response 200
summarystringrequireddetailstringrequiredErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredAccounts
Access account metadata. Information about the account record, such as the processing status and IBAN. Account status is recalculated based on the error count in the latest req.#
/api/v2/accounts/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired |
Response 200
Sample account metadata
idstringcreatedstringlast_accessedstringibanstringbbanstringstatusstringinstitution_idstringowner_namestringnamestringErrors 401403404429
Token is invalid or expired
IP address not whitelisted
Account not found
Rate limit exceeded
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredAccess account balances. Balances will be returned in Berlin Group PSD2 format.#
/api/v2/accounts/{id}/balances/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired |
Response 200
Sample account balances
balancesarray6 properties
balanceAmountobjectrequired
balanceAmount
balanceTypestringrequired
balanceType
creditLimitIncludedboolean
creditLimitIncluded
lastChangeDateTimestring
lastChangeDateTime
referenceDatestring
referenceDate
lastCommittedTransactionstring
lastCommittedTransaction
Errors 400401403404409429500503
Invalid Account ID
AccountInactiveError
AccountResourceUnavailable
Account not found
Account state does not support this operation
RateLimitError
Couldn't update account balances
ConnectionError
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredAccess account details. Account details will be returned in Berlin Group PSD2 format.#
/api/v2/accounts/{id}/details/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired |
Response 200
Sample account details
accountobjectrequiredErrors 400401403404409429500503
Invalid Account ID
AccountInactiveError
AccountResourceUnavailable
Account not found
Account state does not support this operation
RateLimitError
Couldn't update account details
ConnectionError
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequiredAccess account transactions. Transactions will be returned in Berlin Group PSD2 format.#
/api/v2/accounts/{id}/transactions/Path Parameters
| Name | Type | Description |
|---|---|---|
id | stringrequired |
Query Parameters
| Name | Type | Description |
|---|---|---|
date_from | string | |
date_to | string |
Response 200
Sample account transactions
transactionsobjectrequiredlast_updatedstringErrors 400401403404409429500503
Incorrect date range in query parameters
AccountInactiveError
AccountResourceUnavailable
Account not found
Account state does not support this operation
RateLimitError
Couldn't update account transactions
ConnectionError
Error Body
summarystringrequireddetailstringrequiredtypestringstatus_codeintegerrequired