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_idstringSecret id from /user-secrets/
secret_keystringSecret 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
summarystringdetailstringtypestringstatus_codeintegerRefresh access token#
/api/v2/token/refresh/Request Body
refreshstringResponse 200
Refresh access token.
accessstringaccess_expiresintegerErrors 401403429
Token is invalid or expired
IP address not whitelisted
Rate limit exceeded
Error Body
summarystringdetailstringtypestringstatus_codeintegerInstitutions
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
summarystringdetailstringtypestringstatus_codeintegerGet details about a specific Institution and its supported features#
/api/v2/institutions/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string |
Response 200
Retrieve institution by id
idstringnamestringbicstringtransaction_total_daysstringmax_access_valid_for_daysstringmax_access_valid_for_days_reconfirmationstringcountriesarraylogostringsupported_featuresarrayidentification_codesarrayErrors 401403404429
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringdetailstringtypestringstatus_codeintegerEnd 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
countintegernextstringpreviousstringresultsarray8 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_idstring
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
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
summarystringdetailstringtypestringstatus_codeintegerRetrieve end user agreement by ID#
/api/v2/agreements/enduser/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this end user agreement. |
Response 200
Retrieve end user agreement by ID
idstringcreatedstringinstitution_idstringmax_historical_daysintegeraccess_valid_for_daysintegeraccess_scopearrayacceptedstringreconfirmationbooleanErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringdetailstringtypestringstatus_codeintegerDelete an end user agreement#
/api/v2/agreements/enduser/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this end user agreement. |
Response 200
summarystringdetailstringErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringdetailstringtypestringstatus_codeintegerAccept an end-user agreement via the API#
/api/v2/agreements/enduser/{id}/accept/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this end user agreement. |
Request Body
user_agentstringip_addressstringResponse 200
Accept end user agreement
idstringcreatedstringinstitution_idstringmax_historical_daysintegeraccess_valid_for_daysintegeraccess_scopearrayacceptedstringreconfirmationbooleanErrors 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
summarystringdetailstringtypestringstatus_codeintegerRetrieve EUA reconfirmation#
/api/v2/agreements/enduser/{id}/reconfirm/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this end user agreement. |
Response 200
Reconfirmation details
reconfirmation_urlstringcreatedstringurl_valid_fromstringurl_valid_tostringredirectstringlast_accessedstringlast_submittedstringaccountsobjectErrors 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
summarystringdetailstringtypestringstatus_codeintegerCreate EUA reconfirmation#
/api/v2/agreements/enduser/{id}/reconfirm/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this end user agreement. |
Request Body
redirectstringOptional redirect URL for reconfirmation to override requisition's redirect.
Response 201
Reconfirmation created
reconfirmation_urlstringcreatedstringurl_valid_fromstringurl_valid_tostringredirectstringlast_accessedstringlast_submittedstringaccountsobjectErrors 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
summarystringdetailstringtypestringstatus_codeintegerRequisitions
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
countintegernextstringpreviousstringresultsarray13 properties
idstringcreatedstring
The date & time at which the requisition was created.
redirectstring
redirect URL to your application after end-user authorization with ASPSP
statusobject
status of this requisition
institution_idstring
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
summarystringdetailstringtypestringstatus_codeintegerCreate a new requisition#
/api/v2/requisitions/Request Body
redirectstringredirect URL to your application after end-user authorization with ASPSP
institution_idstringan 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
idstringcreatedstringredirectstringstatusobjectinstitution_idstringagreementstringreferencestringaccountsarrayuser_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
summarystringdetailstringtypestringstatus_codeintegerRetrieve a requisition by ID#
/api/v2/requisitions/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this requisition. |
Response 200
Get requisition by ID
idstringcreatedstringredirectstringstatusobjectinstitution_idstringagreementstringreferencestringaccountsarrayuser_languagestringlinkstringssnstringaccount_selectionbooleanredirect_immediatebooleanErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringdetailstringtypestringstatus_codeintegerDelete requisition and its end user agreement#
/api/v2/requisitions/{id}/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | A UUID string identifying this requisition. |
Response 200
summarystringdetailstringErrors 400401403404429
Invalid ID
Token is invalid or expired
IP address not whitelisted
Not found error
Rate limit exceeded
Error Body
summarystringdetailstringtypestringstatus_codeintegerAccounts
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 |
|---|---|---|
idrequired | string |
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
summarystringdetailstringtypestringstatus_codeintegerAccess account balances. Balances will be returned in Berlin Group PSD2 format.#
/api/v2/accounts/{id}/balances/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string |
Response 200
Sample account balances
balancesarray6 properties
balanceAmountobject
balanceAmount
balanceTypestring
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
summarystringdetailstringtypestringstatus_codeintegerAccess account details. Account details will be returned in Berlin Group PSD2 format.#
/api/v2/accounts/{id}/details/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string |
Response 200
Sample account details
accountobjectErrors 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
summarystringdetailstringtypestringstatus_codeintegerAccess account transactions. Transactions will be returned in Berlin Group PSD2 format.#
/api/v2/accounts/{id}/transactions/Path Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string |
Query Parameters
| Name | Type | Description |
|---|---|---|
date_from | string | |
date_to | string |
Response 200
Sample account transactions
transactionsobjectlast_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
summarystringdetailstringtypestringstatus_codeinteger