Overview
The Account Information Journey allows an Account Information Service Provider to retrieve account details, balances and booked transactions after the customer has authorised a valid consent.
Use a valid authorised Consent ID, the same TPP identity and institution endpoint, and an account resource ID returned under that consent. The certificate and AISP-role requirements in Security and Access also apply.
If the customer holds accounts with more than one supported SMBC institution, create a separate consent through each relevant institution endpoint. Keep Consent IDs and account resource IDs separate for each institution.
For consent creation and customer authentication, see Consents.
Accounts and balances
Retrieve the account list
Call: GET /accounts
The response contains the accounts available under the authorised consent.
Use the returned resourceId as the account ID. Resource identifiers are opaque; see Resource Identifiers in Technical Reference.
Retrieve one account
Call: GET /accounts/{account-id}
Use the resourceId returned by GET /accounts as the account-id.
The selected account must belong to the supplied consent and the institution endpoint through which that consent was created.
Retrieve balances
Call: GET /accounts/{account-id}/balances
Use withBalance=true with GET /accounts or GET /accounts/{account-id} to request an interimAvailable balance for the account or accounts returned, where available.
The dedicated balances endpoint may return the following balance types, where available:
- openingBooked;
- interimBooked; and
- interimAvailable.
Transaction history
Call: GET /accounts/{account-id}/transactions
Transaction requests must include:
- bookingStatus=booked; and
- Accept: application/xml.
Only booked transactions are supported. Transaction reports are returned only as camt.053.001.08 XML. JSON transaction responses and other camt message versions are not supported.
Select the transaction period
Use dateFrom and dateTo to define the required transaction period. When values are omitted from the date ranges, the dates default to today’s date.
The permitted transaction history depends on the consent type:
- a recurring consent supports transaction history with a maximum look-back period of 90 days
- a one-off consent supports transaction history with a maximum look-back period of 730 days.
A one-off consent does not replace or invalidate an existing recurring consent. After the one-off consent expires, an existing recurring consent may continue to be used until it expires, is revoked or is otherwise terminated.
Requests outside the permitted transaction period are rejected with PERIOD_INVALID.
Incremental retrieval
Transaction pagination
A transaction report may contain more than one page. Each page contains up to 200 transaction entries.
Where another page is available, the response includes the SMBC-Next header. The header contains the next transaction request with the page value increased by one.
To retrieve the next page:
- follow the request identified by SMBC-Next, or increment the page parameter by one;
- keep the same account resource ID;
- keep the same Consent ID;
- keep the same date range;
- keep bookingStatus=booked;
- retain entryReferenceFrom if it was supplied in the original request; and
- keep all other request parameters unchanged.
Continue until the camt.053.001.08 report indicates that the final page has been reached (LastPgInd=true).
SMBC-Next does not calculate or replace entryReferenceFrom. If the original request included entryReferenceFrom, the same value is retained in subsequent page requests.
Using entryReferenceFrom
The optional entryReferenceFrom parameter can be used when the TPP has retained the entry reference of a previously processed transaction.
Its behaviour is deterministic:
- if the supplied reference exists within the selected transaction period, the response begins with the next transaction in sequence;
- if the supplied reference does not exist within the selected transaction period, the response begins with the earliest available transaction in that period; and
- if entryReferenceFrom is omitted, the response begins with the earliest available transaction in the selected period.
Use the transaction entry reference exactly as returned. An entry reference is not an account resource ID, Consent ID or pagination token.
Process the response
Do not present API resource identifiers as customer-facing account references. See Content Types in Technical Reference for response formats.
The Accounts Service is read-only. A successful request retrieves information only. It does not change the account, the customer's permissions or the consent.
Request failures
An Accounts API request may be rejected where:
- the QWAC does not contain the AISP role;
- the consent is unknown, invalid, expired, revoked or not yet authorised;
- the account does not belong to the supplied consent;
- the consent or account resource belongs to a different institution endpoint;
- a mandatory header or parameter is missing or invalid;
- the transaction period is not permitted;
- bookingStatus is missing or is not booked; or
- the request to the Transactions endpoint does not specify Accept: application/xml.
Use the error response and the Accounts API Reference to identify the required correction. Do not retry an unchanged request where the response shows that the consent, account, role or requested period is invalid.
Account errors
The following table summarises common Accounts API request errors and recommended TPP actions. The Accounts API Reference defines the complete operation-specific response structures.
Error
ROLE_INVALID
HTTP status
401
Meaning
The TPP is not authorised for Account Information Services, for example because the QWAC does not contain the required AISP role.
TPP action
Use a certificate representing the required AISP role for the selected SMBC institution before retrying.
Error
CONSENT_INVALID
HTTP status
401
Meaning
The Consent ID exists but is not in a lifecycle state that permits the Accounts API operation, for example because the consent is expired, revoked or not yet authorised.
TPP action
Check the consent status and use only a valid authorised consent; create and authorise a new consent if the existing consent is no longer usable.
Error
CONSENT_UNKNOWN
HTTP status
403
Meaning
The consent is not accessible in the request context, for example because the Consent ID, TPP identity or institution endpoint does not match.
TPP action
Verify the Consent ID, TPP identity and SMBC institution endpoint, and use the same endpoint through which the consent was created.
Error
RESOURCE_UNKNOWN
HTTP status
404
Meaning
The requested account resource was not found or is not accessible under the authorised Consent ID, including where the account does not belong to the supplied consent or institution endpoint.
TPP action
Use the exact resourceId returned by GET /accounts for the same consent and institution endpoint; retrieve the current account list before retrying.
Error
invalid_request
HTTP status
400
Meaning
A mandatory header or parameter is missing or invalid, such as an invalid header format or invalid query parameter.
TPP action
Correct the missing or invalid header or parameter using the Accounts API Reference before retrying.
Error
FORMAT_ERROR
HTTP status
400
Meaning
The request does not comply with the required request format, including required request-format conditions for the Accounts API.
TPP action
Correct the request format using the operation definition in the Accounts API Reference before retrying.
Error
PERIOD_INVALID
HTTP status
400
Meaning
The transaction date range is invalid, for example where dateFrom is after dateTo or the requested look-back period exceeds the permitted period.
TPP action
Submit a permitted transaction period: up to 90 days for recurring consent or up to 730 days for one-off consent.