Purpose
A consent authorises a Third-Party Provider (TPP) to use the account-information and payment-related services available to the Payment Service User (PSU). Subsequent account-information and payment-related API requests require a valid Consent ID.
A valid consent does not replace the separate Strong Customer Authentication (SCA) required to authorise a payment or signing basket.
The Consents API Reference defines the request headers, request and response schemas, and operation-specific errors.
SMBC consent model
SMBC uses a bank-offered consent model. The request does not select accounts or permissions; access is derived from the PSU's current corporate-banking permissions, which are administered outside the XS2A API.
Before creating a consent
Before creating a consent, use the relevant institution endpoint, obtain the PSU's online-banking user ID and prepare the request defined in the Consents API. The access, certificate and role requirements in Before You Start and Security and Access also apply.
Create and use the consent through the same institution endpoint. A separate consent is required for each supported SMBC institution through which the TPP needs to access accounts or payment services.
PSU identity and headers
SMBC uses PSU-ID. The value is the same user ID that the PSU uses for SMBC online banking. The PSU enters this value through the TPP's interface.
Do not supply PSU-Corporate-ID. SMBC does not use that header.
POST /consents requires:
- X-Request-ID;
- PSU-ID;
- TPP-Redirect-URI;
- PSU-IP-Address;
- PSU-Device-ID; and
- Content-Type: application/json.
PSU-Device-ID is required because POST /consents starts an SCA journey. It must be supplied as the UUID-format device or application-installation identifier observed in the PSU context.
See the Consents API Reference for optional PSU-context headers and their formats.
The PSU provides authentication information only through the SMBC-hosted SCA journey.
PSU_CREDENTIALS_INVALID may be returned where the PSU information supplied for consent creation cannot be accepted, including where the PSU cannot complete the required Strong Customer Authentication journey. The response does not identify the specific underlying condition.
Create a consent
Call: POST /consents
The request body must contain:
- access;
- recurringIndicator;
- validUntil;
- frequencyPerDay; and
- combinedServiceIndicator.
Access
Supply access as an empty object:
{
"access": {}
}Do not include IBANs, BBANs, account resource identifiers or permission lists. SMBC derives access from the PSU's current corporate-banking permissions.
Frequency per day
frequencyPerDay is mandatory for Berlin Group compatibility. SMBC does not use its value to limit the number of requests.
Combined services
combinedServiceIndicator is mandatory. SMBC treats every consent as a combined consent for account-information and payment-related services, regardless of the value supplied. Supply true in the public request examples.
Consent type and validity
Use recurringIndicator to identify the consent type:
- true: recurring consent; and
- false: one-off consent.
For a recurring consent:
- validUntil is supplied as a date and represents an exclusive end date. The consent expires at 00:00:00 local UK time, meaning GMT or BST as applicable, at the start of the specified date and is not valid during that date;
- validUntil must therefore be at least one calendar day after the request date. A recurring consent request with validUntil equal to the request date is rejected with HTTP 400 because the consent has already expired at the start of that date;
- validUntil may be no later than 180 calendar days after the request date;
- the consent may be reused for supported account-information and payment-related services during its validity; and
- a transaction-history request may not request a dateFrom earlier than 90 calendar days before the transaction request date.
For example, a recurring consent with validUntil set to 2026-08-13 expires at 00:00:00 local UK time at the start of 13 August 2026. It is therefore not valid during 13 August 2026.
For a one-off consent:
- validUntil must be exactly two calendar days after the request date;
- validUntil represents an exclusive end date. The consent expires at 00:00:00 local UK time, meaning GMT or BST as applicable, at the start of the specified date and is not valid during that date;
- once authorised, the consent may be used for supported account-information and payment-related services until it expires; and
- a transaction-history request may request a dateFrom up to 730 calendar days before the transaction request date.
For example, a one-off consent requested on 20 August 2026 must use validUntil set to 2026-08-22. The consent expires at 00:00:00 local UK time at the start of 22 August 2026 and is not valid during that date.
Recurring consent request example
For a recurring consent request made on 20 August 2026, validUntil must be from 21 August 2026 (D+1) to 16 February 2027 (D+180). This example uses the latest accepted date.
{
"access": {},
"recurringIndicator": true,
"validUntil": "2027-02-16",
"frequencyPerDay": 4,
"combinedServiceIndicator": true
}One-off consent request example
For a one-off consent request made on 20 August 2026, validUntil must be 22 August 2026 (D+2).
{
"access": {},
"recurringIndicator": false,
"validUntil": "2026-08-22",
"frequencyPerDay": 4,
"combinedServiceIndicator": true
}Consent response and SCA
A successful POST /consents returns 201 Created and prepares the SCA session without a separate consent-authorisation subresource.
The TPP must:
- store the returned Consent ID;
- redirect the PSU’s browser to the URL returned in the scaRedirect link;
- allow the PSU to complete the SCA challenge using the PSU’s mobile device and the SMBC Digital mobile application;
- receive the PSU at the TPP-Redirect-URI supplied in the consent request; and
- call the consent-status operation to determine the outcome.
The redirect back to TPP-Redirect-URI does not indicate whether SCA succeeded or failed. SMBC does not append a success code, failure code or SCA result. If the TPP included a state query parameter in TPP-Redirect-URI, SMBC preserves that value on the return redirect.
The TPP must determine the outcome by retrieving consent status. Completion of the browser redirect alone does not establish that the consent is valid or usable.
SMBC does not support a separate failure redirect URI. The PSU is returned to the same TPP-Redirect-URI after either a successful or unsuccessful SCA attempt.
Single-use redirect
The SCA redirect URL is single-use. Once it has been opened in the PSU's browser, do not reuse it.
If the PSU does not complete SCA after opening the URL, the SCA status becomes failed and the consent status becomes rejected. The TPP must create a new consent and use the new redirect URL.
Check consent status
Use the consent-status operation defined in the Consents API Reference.
Consent status describes the lifecycle and usability of the consent. SCA status describes the progress or outcome of the PSU authentication and authorisation journey. Completion of the browser redirect alone does not establish that the consent is usable.
The following table summarises common consent and SCA status combinations used in the journey. Use the Consents API Reference for the complete response model and any additional status values.
Common consent and SCA status interpretation
Consent status
received
SCA status
started
Meaning
The consent exists and SCA is not complete.
TPP action
Do not use the consent. Redirect the PSU only if the returned SCA URL has not already been opened.
Consent status
valid
SCA status
finalised
Meaning
The consent is authorised and usable.
TPP action
Retrieve the consent details and use only the access returned.
Consent status
rejected
SCA status
failed
Meaning
Consent SCA was unsuccessful or was not completed after the SCA URL was opened.
TPP action
Create a new consent.
Consent status
expired
SCA status
Not specified
Meaning
The consent is no longer usable.
TPP action
Create a new consent if access is still required.
Consent status
revokedByPsu
SCA status
Not specified
Meaning
The consent has been revoked outside the TPP termination operation.
TPP action
Stop using the consent.
Consent status
terminatedByTpp
SCA status
Not specified
Meaning
The TPP terminated the consent.
TPP action
Stop using the consent.
Only consentStatus = valid indicates that the consent may be used. The TPP must not use a consent in any other status.
Retrieve consent access
Use the consent-retrieval operation defined in the Consents API Reference.
This operation is available only where the consent is authorised and valid. The response returns consent metadata and access arrays derived from the PSU's current permissions.
The access categories are:
- accounts: accounts whose details the TPP may retrieve;
- balances: accounts whose balances the TPP may retrieve;
- transactions: accounts whose transaction history the TPP may retrieve;
- paymentCreations: accounts for which the PSU may create and view payments; and
- paymentAuthorisations: accounts for which the PSU may perform payment-authorisation and signing-basket actions.
Accounts, balances and transactions are granted together when present.
An empty array means that the PSU has no access under that service category. Not all account references necessarily include an IBAN; use the identifiers returned by the API.
The consent response returns the access available to the PSU at the time of retrieval.
The TPP should retrieve the current consent details before relying on previously returned access.
Consent lifecycle
Use Consent-ID in every subsequent account-information and payment-related request. Continue using the institution endpoint through which the consent was created.
A consent is owned by the TPP identity under which it was created. It cannot be transferred to another TPP identity.
A consent is not bound to a particular QWAC certificate instance. Renewing or replacing a QWAC, including using another accepted trust service provider, does not invalidate the consent where the replacement certificate represents the same TPP identity and required regulated role.
Multiple valid consents are supported for the same TPP and PSU. Creating a new consent does not replace or terminate another valid consent. Each Consent ID has its own lifecycle and must be managed separately.
Terminate a consent
Use the consent-termination operation defined in the Consents API Reference.
A successful request returns 204 No Content. Termination takes effect immediately. The Consent ID can no longer be used for account information, payment creation, payment authorisation or signing-basket operations.
Terminating one consent does not affect another consent held by the same TPP or PSU. It does not delete the corporate user or change the PSU's underlying corporate-banking permissions.
Repeating the request for an already expired or terminated consent does not return another successful deletion response. The API may return CONSENT_INVALID.
Consent errors
The following table summarises common consent errors and recommended TPP actions. The Consents API Reference defines the complete operation-specific response structures.
Common consent errors and TPP actions
Error
PSU_CREDENTIALS_INVALID
HTTP status
401
Meaning
The PSU information supplied for consent creation cannot be accepted, including where the PSU cannot complete the required Strong Customer Authentication journey. The response does not identify the specific underlying condition.
TPP action
Ask the PSU to verify the SMBC online-banking user ID and confirm that they are able to complete SMBC Strong Customer Authentication. Correct the relevant condition before retrying consent creation.
Error
SERVICE_BLOCKED
HTTP status
403
Meaning
The consent service is blocked for the request context.
TPP action
Do not retry the same request unchanged.
Error
CONSENT_INVALID
HTTP status
401
Meaning
The Consent ID exists for the requesting TPP and institution but is not in a lifecycle state that permits the operation.
TPP action
Check the consent status. Continue the existing journey only where still possible; otherwise create a new consent where the existing consent is rejected, expired, revoked or terminated.
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 institution endpoint.
The Consents API Reference defines the complete operation-specific response structures.