Using the sandbox

Overview of Sandbox

The Sandbox offers a safe environment for end-to-end testing of TPP client applications backed by mock services and static datasets to simulate a pre-defined set of scenarios, covering both happy and unhappy paths.

Functionally, the sandbox APIs are almost identical to the production APIs with differences only in configuration to ensure a consistent experience between environments and confidence that your client application will be ready for production.

There are four differences between the sandbox and production environments:

Stateless mock services with static datasets: The sandbox does not manage state. All responses are fixed and derived from static datasets.
Sandbox authorisation service: This is strictly for use in the sandbox and stands in for the SMBC Group portal that will be used in production as the OAuth2 authorisation server. The sandbox requires no authentication credentials and will return a PSU authorisation code if all the request parameters are valid. Furthermore, it deviates from the OAuth2 specification in how the authorisation code response step is handled; instead of redirecting the PSU back to the TPP redirect URI using HTTP 302, we will return the "Location" HTTP response header using HTTP 200. This is an intentional deviation from the OAuth2 specification since the authorisation code is returned to the TPP and not the PSU/user-agent in the sandbox.
Simulated PSU authorisation: Unlike production, the pre-configured static dataset for consents assumes that the PSU has already authorised the TPP for the given consent. Only the pre-configured consents are “pre-authorised”.
Restricted mutually authenticated (MA) TLS connection: The sandbox supports MA TLS using a custom TLS certificate issued by SMBC Group for testing purposes only (see table below). To access production APIs, you will need a valid eIDAS qualified certificates for website authentication (QWAC).

Download our Sandbox Test QWAC and QSEAL certificates here.

These differences have the following impacts:

Resources are never created nor deleted: For example, the POST /consents operation does not create a new consents resource and none of the request data is persisted or used in subsequent operations. Instead, it returns a static response from a pre-configured set of consents that are provisioned in the sandbox for testing purposes. The operation still validates all your request parameters in addition to enforcing OAuth2 semantics, e.g., you must supply a valid and unexpired TPP access token. And likewise, the sandbox Dynamic Client Registration Service does not create a new application with dedicated client credentials when you invoke POST /register using the sandbox APIs; to use the Berlin Group sandbox APIs, you should use the client credentials for the sandbox application and not the credentials returned from the sandbox Dynamic Client Registration Service.
Sequence of Berlin Group operations: The sandbox force operations to occur in sequence. For example, you can retrieve the accounts list before you create a new consent because we have provisioned a set of “pre-authorised” consent IDs in the sandbox as part of the static dataset. Technically, you can start your testing flow at step 1 below “TPP redirects PSU to SMBC Group sandbox authorisation service” to obtain a PSU authorisation code. Note OAuth2 token semantics are strictly enforced so you must first obtain a PSU authorisation code to exchange for a PSU access token.
OAuth2 TPP redirection: You are not required to implement the TPP redirect URI in step 2.3 when the sandbox authorisation service returns the PSU authorisation code back to your TPP sandbox test application. All you need to do is extract the query parameters from the redirection URI in step 2.3, such as the PSU authorisation code, that you will need for step 2.4 when exchanging the PSU authorisation code for a PSU access token.
Simplified development workflow: In the end-to-end flows above, we have depicted the PSU/user-agent separate from the TPP sandbox test application. However, the PSU/user-agent is not strictly required for testing purposes. This role could be fulfilled by your TPP sandbox test application to simplify your development workflow. The module that stands in for the PSU/user-agent can later be removed for pre-production testing.

The simplified workflow is made possible by implementing the OAuth2 authorisation server endpoint using an API instead of a web portal that requires human intervention.

Sandbox API Flows

The following sequence diagrams step the developer through the steps required for a TPP to initiate its first API call to access account information on behalf of a PSU.

TPP creates consents resource
PSU authorises consents resource
TPP performs AIS operation

Sandbox Flows

#	Step > Sub-Step	Description	API Request and Response
1	TPP creates consent The TPP creates a new consent for the PSU to authorise
1.1	> Get TPP access token	Your TPP obtains a TPP access token that must be presented to create a new consent in the next step. This uses the OAuth2 client credentials grant for machine-to-machine authentication.	OAuth2 POST /token (TPP client credentials, grant_type=client_credentials)
1.2	> Create consent	The TPP creates a new consent resource that represents the access rights to account and payment services. SMBC will return the Consent ID and the URI to the OAuth2 authorisation server.	Berlin Group POST /consents
2	PSU authorises consent with OAuth The PSU must explicitly authorise the TPP to act on his behalf
2.1	> TPP redirects PSU to SMBC Sandbox Authorisation Service	The TPP is responsible for redirecting the PSU to the authorisation server and must include the required OAuth2 parameters (e.g. Client ID and state). Furthermore, the TPP must append the code_challenge that is required for the Proof Key for Code Exchange (PKCE). SMBC requires this to be a SHA256 hash of the plain text code_verifier that the TPP will supply later. The code_challenge_method parameter must be present with value "S256". Sandbox authorize endpoint: https://api-sandbox.smbcdigital.com/sandboxauth/v1/authorize Important note: The Berlin Group specification uses the “scope” query parameter to identify the Consent. The Consent ID in the “scope” parameter must match that returned in Step 1.2 above.	OAuth2 HTTP 302 /sandboxauth/v1/authorize ( OAuth2 request parameters, PKCE code_challenge)
2.2	> Get PSU authorisation code	If all the OAuth2 request parameters are valid, the Sandbox Auth Service will generate a PSU authorisation code. This will be included in the redirection of the PSU back to the TPP. Sandbox note: Unlike the Production flows, the Sandbox Auth Service will not require secure customer authentication before issuing the PSU authorisation code. This is an intentional simplification for the Sandbox.	Internal within SMBC
2.3	> SMBC redirects PSU back to TPP	At the conclusion of Step 2, the SMBC Sandbox Auth Service redirects the PSU back to the TPP with the OAuth2 response parameters (e.g. authorisation code, state). Furthermore, SMBC must append the code_challenge in accordance with PKCE.	OAuth2 HTTP 200 <TPP Redirect URI> (OAuth2 response parameters, PKCE code_challenge)
2.4	> Exchange PSU authorisation code for PSU access token	This is the standard OAuth2 flow that exchanges the (PSU) authorisation code for a (PSU) access token. Furthermore, the TPP must append the code_verifier, in accordance with PKCE, which represents the unhashed, plain text value of the code_challenge previously supplied in Step 2.1. In particular, the token endpoint will verify the following: SHA256(code_verifier) == code_challenge	OAuth2 POST /token (TPP client credentials, grant_type=authorization_code, code=<PSU authorisation code>, redirect_uri=<TPP Redirect URI>, code_verifier=<Plain Unhashed Code>)
3	AIS/PIS Operation The TPP performs the AIS/PIS operation using the PSU access token
3.1	> AIS example: Get Account List	Your application requests the list of accounts on behalf of the PSU using the PSU access token. Other AIS operations are listed below in the Technical API Documentation below. Important Note: The mandatory Consent ID supplied in the HTTP request header must match the Consent ID associated with the PSU access token which the PSU had previously authorised in relation to the Consent.	Berlin Group GET /accounts
3.2	> PIS example: Create Payment	Your application submits a payment on behalf of the PSU using the PSU access token. Note that two authorisations are required per payment. Furthermore, the PSUs for both payment authorisations must be unique. Other PIS operations are listed below in the Technical API Documentation. Important Note: The mandatory Consent ID supplied in the HTTP request header must match the Consent ID associated with the PSU access token which the PSU had previously authorised in relation to the Consent.	Berlin Group POST /payments/{payment-product}

Technical API Documentation for Sandbox

The Sandbox implements the following operations:

#	SMBC Service	Provenance	Basepath & Endpoints	Authorisation
1	OAuth2 Token Service	OAuth2	Full basepath: api-sandbox.smbcdigital.com/oauth/ v1/token
1.1	> Token	POST / token	HTTP basic authentication using TPP client credentials	The token endpoint is used in three OAuth2 token scenarios: TPP client credentials grant – returns TPP access token PSU Auth Code / access token exchange – returns PSU access and refresh tokens. Must also supply PKCE code_verifier. PSU refresh token / access token exchange – returns new PSU access and refresh tokens
2	Consent Service	Berlin Group	Full basepath: api-sandbox.smbcdigital.com/berlingroup/ v1/consents
2.1	> Create new Consent	POST /consents	TPP access token	This must be a PSU-attended call and must include the PSU IP Address and Device ID in the HTTP request headers.
2.2	> Get Consent Status	GET /consents/{ID} /status	TPP access token
2.3	> Get Consent Details	GET /consents/{ID}	PSU access token	This includes all the accounts and associated access on those accounts for the given Consent. TPP access must be explicitly authorised, hence the use of PSU access token.
2.4	> Delete Consent Details	DELETE /consents/{ID}	PSU access token
3	Account Service	Berlin Group	Full basepath: api-sandbox.smbcdigital.com/berlingroup/ v1/accounts
3.1	> Get account list	GET /accounts	PSU access token	This always returns the interim available balance and ignores the “withBalance” query parameter.
3.2	> Get specified account details	GET /accounts/{ID}	PSU access token	This always returns the interim available balance and ignores the “withBalance” query parameter.
3.3	> Get account balances	GET /accounts/{ID} /balances	PSU access token	This returns four types of balances: Opening booked - Book balance of the account at the beginning of the reporting period, which may include uncleared funds. Opening available - Cleared funds which are available to the account owner at the beginning of the reporting period (if credit balance), or the balance which may be subject to interest charges (if debit balance). Interim booked - The current book balance at the time of the report, which may include uncleared funds. Interim available - The current available balance of cleared funds at the time of the report.
3.4	> Get account transactions	GET /accounts/{ID} /transactions	PSU access token	This supports filtering as defined in the Berlin Group, e.g., using from and to dates. Furthermore, the transactions response supports both JSON and XML response payloads which includes balances for the given account. Opening booked and opening available balances are always included for the given dateFrom. If dateTo is today, the interim booked and interim available balances are included, otherwise the closing booked and closing available balances are included. Consequently, you should expect only four of the following six balance types for each transaction record depending on your request parameters. Opening booked - Book balance of the account at the beginning of the reporting period, which may include uncleared funds. Opening available - Cleared funds which are available to the account owner at the beginning of the reporting period (if credit balance), or the balance which may be subject to interest charges (if debit balance). Interim booked - The current book balance at the time of the report, which may include uncleared funds. Interim available - The current available balance of cleared funds at the time of the report. Closing booked - Book balance of the account at the end of the reporting period, which may include uncleared funds. Closing available - Cleared funds which are available to the account owner at the end of the reporting period (if credit balance), or the balance which may be subject to interest charges (if debit balance).
4	Payment Service	Berlin Group	Full basepath: api-sandbox.smbcdigital.com/berlingroup/ v1/payments
4.1	> Create payment	POST /payments/ {payment-product}	PSU access token	The method to initiate a payment is submitted in an ISO 20022 pain.001.001.03 format. The supported payment products are: pain.001-internal-transfers pain.001-sepa-credit-transfers pain.001-swift-transfers pain.001-chaps-payments pain.001-faster-payments
4.2	> Get payment details	GET /payments/ {payment-product}/{ID}	PSU access token	Returns payment details in ISO20022 pain.001.001.03 format.
4.3	> Get payment status	GET /payments/ {payment-product}/{ID} /status	PSU access token	Returns payment status in ISO20022 pain.002.001.03 format.
4.4	> Create payment authorisation	POST /payments/ {payment-product}/{ID}/ authorisations	PSU access token	Creates authorisation sub-resource for the specified payment. Note that two authorisations are required per payment. Furthermore, the PSUs for both payment authorisations must be unique.
4.5	> Get payment authorisation	GET /payments/ {payment-product}/{ID}/ authorisations/{AuthID}	PSU access token	Returns status of the authorisation sub-resource for the specified payment.
4.6	> Delete payment	DELETE /payments/{payment-product}/{ID}	PSU access token	Cancels existing payment
5	Signing Basket Service	Berlin Group	Full basepath: api-sandbox.smbcdigital.com/berlingroup/ v1/signing-baskets
5.1	> Create signing basket	POST /signing-baskets	PSU access token	Creates a signing basket resource with one or not more than 100 payments for authorisation
5.2	> Get signing basket	GET /signing-baskets/{ID}	PSU access token	Returns the list of payments in the signing basket resource
6	Funds Confirmation Service	Berlin Group	Full basepath: api-sandbox.smbcdigital.com/berlingroup/ v1/funds-confirmations
6.1	> Request funds confirmation	POST /funds-confirmations	PSU access token	Returns 'true' or 'false' on availability of PSU funds

Testing your Application

As we’ve noted, the Sandbox APIs are built from the same codebase as the Production APIs and are not simplified nor modified in any way to implement the Sandbox. This helps you to test your application thoroughly using the code, processes and rules that we will use in production. We describe in the table below a selection of happy and unhappy paths that you can test using the Sandbox.

#	Step > Sub-Step	Happy Path	Unhappy Paths
1	TPP Creates Consent The TPP creates a new Consent for the PSU to authorise
1.1	> Get TPP access token	OAuth2: Correct credentials in the Authorization header. Additionally grant_type must be set to “client_credentials”.	OAuth2: Any combination with mismatching credentials data, e.g., valid username with invalid password. Any other grant_type will fail, e.g.,(authorisation) code, refresh_token, token (implicit grant).
1.2	> Create consent	OAuth2: The TPP access token returned in Step 1.1 above. PSU-ID: Must be one of the pre-configured PSU Identifiers we have setup in the mock data. HTTP headers: All mandatory headers are checked and, for selected headers, the formats too, e.g., TPP-Redirect-URI and PSU-IP-Address. Note that the sandbox is stateless so none of the request data is persisted nor used in subsequent operations. For example, supplying a different TPP Redirect URI in Step 2.1 will not result in an error. Request payload: The consent request payload must match the OpenAPI v3 schema defined in the Berlin Group specification. Note that the request payload is never persisted in the Sandbox; it is merely validated. Response handling: You will need to store the Consent-ID returned in the response for subsequent AIS operations. Furthermore, you will need to use the scaRedirect value in the _links response for Step 2.1 below.	OAuth2: Unhappy paths include invalid or expired TPP access token, and PSU access token. PSU-ID: Unrecognised PSU Identifier, i.e., not one of those in our mock data. HTTP headers: Missing mandatory headers or invalid format for any combination of the headers. Request payload: Unhappy paths include missing mandatory properties (e.g. validUntil) and type mismatches (e.g. validUntil is an integer instead of a date).
2	PSU Authorises Consent with OAuth The PSU must explicitly authorise the TPP to act on his behalf
2.1	> TPP redirects PSU to SMBC Sandbox Authorisation Service	OAuth2: All the standard mandatory OAuth2 parameters for an authorisation request – client_id must be valid (you will find this in the Developer Portal) and response_type must be “code”. Berlin Group OAuth2: The Berlin Group further mandates the following optional OAuth2 parameters: scope, state, redirect_uri. Additionally, the format of the redirect_uri must be valid. PKCE: The Berlin Group further mandates the PKCE parameter: code_challenge. Note that the code_challenge_method is required and must always be fixed at “S256”. As you are free to determine the values for code_verifier and code_challenge, you must keep a copy of the unhashed code_verifier as this must be supplied when exchanging the authorisation code for an access token below in Step 2.4.	OAuth2: Unhappy paths: Missing or random client_id; or response_type set to any value other than “code”, e.g., “token” or other value. Berlin Group OAuth2: Unhappy paths: Missing mandatory headers and invalid format for redirect_uri. PKCE: Unhappy paths: Missing code_challenge, or a value other than SHA256 hash of the code_verifier. This is verified in Step 2.4 below.
2.2	> Get PSU authorisation code	This is an internal SMBC step that will validate the parameters in Step 2.1. Any errors will be flagged at that point.	There are no alternate or unhappy flows if the request parameters in Step 2.1 are all valid.
2.3	> SMBC redirects PSU back to TPP	OAuth2: The redirection must have the following three parameters: (authorisation) code, state and code_challenge. Specifically, the value of state must match the request parameter in Step 2.1, and likewise for code_challenge. Note that the authorisation code has a fixed expiry of 2 minutes.	There are no alternate or unhappy flows if the request parameters in Step 2.1 are all valid. But you must validate that the state and code_challenge match the request you made in Step 2.1.
2.4	> Exchange PSU authorisation code for PSU access token	OAuth2: All the standard mandatory OAuth2 parameters for a token exchange. These include TPP client credentials, grant_type (must be “authorization_code”), client_id (match that supplied in Step 2.1), redirect_uri (must match that supplied in Step 2.1), and code (must be a valid authorisation code in Step 2.3). PKCE: The plaintext value code_verifier, must be supplied. In particular, SHA256(code_verifier) must match the code_challenge supplied in Step 2.1. Response handling: You will need to store both the PSU access token and PSU refresh token for the given PSU’s consent (Consent-ID in Step 1.2). The access token has a fixed expiry of 10 minutes and the refresh token has a maximum time-to-live (max TTL) fixed at 21 minutes from the point when the first PSU access token is returned, after which you will need to repeat Step 2 again. Production note: In production, SMBC will require the PSU to be securely authenticated using strong customer authentication (SCA), at the end of the consent validity period, subject to a maximum of 90 days. In sandbox, the max TTL for “re-authentication” is 21 minutes.	OAuth2: Unhappy paths include missing or invalid mandatory parameters (e.g. grant_type is missing or not “authorization_code”), or the select OAuth2 parameters do not match those in Step 2.1. Any combination with mismatching credentials data, e.g., valid username with invalid password. PKCE: The code_verifier is not supplied or does not match the code_challenge supplied in Step 2.1. SMBC: The authorisation code has expired (older than 2 minutes after Step 2.3).
3	AIS operation The TPP performs the AIS operation using the PSU access token
3.1	> Get account list	OAuth2: A valid PSU access token must be used (re. Step 2.4). Berlin Group: All the mandatory Berlin Group parameters must be supplied, including X-Request-ID and PSU-IP-Address (if request is in direct response to PSU action in “attended” mode). Very importantly, the Consent-ID must be supplied and must match the value returned in Step 1.2, for which you obtained the PSU access token in Step 2.4.	OAuth2: Unhappy paths include supplying an invalid access token (some random value) or an access token associated with another consent. Furthermore, using an expired access token (older than 10 minutes after Step 2.4) will return an error. Berlin Group: Unhappy paths include any combination of missing mandatory parameters. Very importantly, the Consent-ID must match that in Step 1.2; using any other value will return an error. Refresh token: In the event the access token has expired, you can use the PSU refresh token to obtain a new pair of PSU access and refresh tokens. Note that the refresh token has a max TTL of 21 minutes (see Step 2.4). This enables you to test how your application handles refresh tokens for subsequent SCA flows for a given Consent for two further access tokens.
4	PIS operation The TPP performs the PIS operation using the PSU access token
4.1	> Create payment	OAuth2: A valid PSU access token must be used (re. Step 2.4). Berlin Group: All the mandatory Berlin Group parameters must be supplied, including X-Request-ID and PSU-IP-Address (if request is in direct response to PSU action in “attended” mode). Very importantly, the Consent-ID must be supplied and must match the value returned in Step 1.2, for which you obtained the PSU access token in Step 2.4. Request payload: The payment initiation request payload must match the ISO 20022 pain.001.001.03 messages. Note that the request payload is never persisted in the sandbox; it is merely validated. Digital signature: All three Berlin Group digital signature headers must be correct (see below for more information).	OAuth2: Unhappy paths include supplying an invalid access token (some random value) or an access token associated with another consent. Furthermore, using an expired access token (older than 10 minutes after Step 2.4) will return an error. Berlin Group: Unhappy paths include any combination of missing mandatory parameters. Very importantly, the Consent-ID must match that in Step 1.2; using any other value will return an error. refresh token: In the event the access token has expired, you can use the PSU refresh token to obtain a new pair of PSU access and refresh tokens. Note that the refresh token has a max TTL of 21 minutes (see Step 2.4). This enables you to test how your application handles refresh tokens for subsequent SCA flows for a given consent for two further access tokens. Request payload: Unhappy paths include any deviations from the ISO 20022 schema. Digital signature: Invalid digital signature headers for your request and covers all three Berlin Group headers "Digest", "Signature" and "TPP-Signature-Certificate". Some unhappy paths include: The "TPP-Signature-Certificate" is not a valid base 64 encoded certificate or does not match the digital signature (e.g. digital signature generated using a private key for a different certificate). The "Digest" does not match SHA256(request payload). The "Signature" does not have all the required parameters (e.g. missing "headers"), uses an unsupported algorithm (i.e. anything other than RSA-SHA256) or "signature" is not correct (e.g. generated using a different signing string, certificate or algorithm).

Overview of Sandbox

Sandbox API Flows

Technical API Documentation for Sandbox

Testing your Application

About us

Need help?