In response to the Payment Services Directive 2 (PSD2), SMBC Group offers a collection of APIs that will allow third party providers (TPPs) to integrate the bank's services into their applications. This page will guide TPP developers through the necessary steps required to interact with SMBC Group's API services in the sandbox environment and retrieve simulated responses.  The reader should:

  1. review SMBC Group's implementations of PSD2 APIs (Berlin Group) and the OAuth v2 delegated access model
  2. review the section on using the sandbox including the sandbox API flows, testing your application and testing digital signatures
  3. register an account on the developer portal.  We will ask for some basic information, including your company's TPP authorisation number;
  4. register your sandbox application in the developer portal to obtain the credentials to interact with our sandbox API environment; and
  5. test your application against our sandbox API environment, making reference to our API documents section to obtain access to the mocked data.

PSD2 APIs

In support of the PSD2, SMBC Group has implemented APIs to enable its end-users, also referred to as payment service users (PSUs), to interact with the bank's payment services via a TPP.

To support pan-European payments interoperability, SMBC Group has adopted the Berlin Group Specification v1.3  standards, with refinements, to ensure a consistent level of service relative to its online banking solutions, e.g., a field that is optional in the Berlin Group specification may be mandatory when using the SMBC Group implementation.

The APIs fall into two broad categories:

  1. Account Information Service (AIS): These are operated by an Account Information Service Provider (AISP) that retrieves account information from financial institutions on behalf of the end-user. The AISP APIs enable the end-customer to retrieve account details, balances and transactions.
  2. Payment Initiation Service (PIS): These are operated by a Payment Information Service Provider (PISP) that provides payment initiation and authorisation services for the end-user. The PISP APIs enable the end-customer to initiate and authorise payments in addition to querying the status of payments.

OAuth v2 Delegated Access Model

As detailed in our token service page, SMBC Group implements two specific OAuth 2 flows:

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. To access production APIs, you will need a valid eIDAS qualified certificates for website authentication (QWAC).

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.

  1. TPP creates consents resource
  2. PSU authorises consents resource
  3. TPP performs AIS operation

#

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.

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  <SMBC Auth Server>/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

Additional Notes

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:

  1. TPP client credentials grant – returns TPP access token
  2. PSU Auth Code / access token exchange – returns PSU access and refresh tokens. Must also supply PKCE code_verifier.
  3. 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:

  1. Opening booked - Book balance of the account at the beginning of the reporting period, which may include uncleared funds.
  2. 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). 
  3. Interim booked - The current book balance at the time of the report, which may include uncleared funds.
  4. 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.

  1. Opening booked - Book balance of the account at the beginning of the reporting period, which may include uncleared funds.
  2. 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). 
  3. Interim booked - The current book balance at the time of the report, which may include uncleared funds.
  4. Interim available - The current available balance of cleared funds at the time of the report.
  5. Closing booked - Book balance of the account at the end of the reporting period, which may include uncleared funds. 
  6. 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:

  1. pain.001-internal-transfers
  2. pain.001-sepa-credit-transfers
  3. pain.001-swift-transfers
  4. pain.001-chaps-payments
  5. 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 requestclient_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 not required and will always be fixed at “S256” or SHA256. 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).

Testing your Digital Signatures with Sandbox Utilities

Developing and testing applications that implement digital signatures can be challenging as one needs to be very precise about how the signing string is constructed. To that end, SMBC Group have exposed a set of digital signature utilities for the sandbox to enable you to fully test your digital signature implementation before proceeding with the relevant PIS operations that require digital signatures. The Berlin Group specification adopts the IETF Draft for Signing HTTP Messages by Cavage/Sporny and introduces the following HTTP request headers.

  1. TPP-Signature-Certificate: This is the certificate used for signing the request, in base64 encoding. To access production APIs, you will need a valid eIDAS qualified certificates for electronic seals (QSeal) to digitally sign your requests; furthermore, note that the TPP Authorisation Number in both the QSeal and QWAC certificates must match.
  2. Digest: This header is included only if the "Signature" element is contained in the header of the request and contains a hash of the request payload. SMBC Group supports only SHA-256 for digests.
  3. Signature: The digital signature header in the format defined by the Cavage/Sporny specification and comprises the following parameters, all of which are mandated by SMBC Group:
    1. keyId: This is an opaque string that the server can use to look up the component they need to validate the signature.
    2. signature: This is a base64 encoded digital signature constructed using the "algorithm" and "headers" signature parameters to form a canonicalized "signing string".
    3. headers: This is used to specify the list of HTTP headers included when generating the signature for the message. Note that the order of the headers is significant as the signing string is constructed by concatenating the headers in the order defined by the "headers" parameter. While the full set of mandatory fields in "Signature/headers" will vary by operation for production APIs,  the common mandatory fields are: (request-target), date, digest.
    4. algorithm: This is used to specify the digital signature algorithm to use when generating the signature. SMBC Group supports only RSA-SHA256 for digital signature algorithm.

For your convenience, we have prepared the following sandbox certificate and private key for use with the sandbox APIs including the sandbox utilities described below. That said, you are free to use your own certificate/private key pairs.

SMBC Group recommends the following approach to develop and test your digital signature implementation:

#

Step and Use Case

Provenance

Endpoint

Parameters

1

Generate signing string and digital signature

  • This utility enables you to compare the three Berlin Group digital signature headers returned from this operation against what your code produces.
  • This utility further returns additional information that you can use for development and testing purposes including the derived signing string that we use to calculate the digital signature in both text and hashed formats. This enables you to validate the intermediate processing steps when generating the digital signature and needs to be correct before proceeding to the next step.
  • The "smbc-headers" HTTP header is Berlin Group operation agnostic and can be used to specify any headers of your choosing. This flexibility enables you to test both happy- and unhappy-paths for all your Berlin Group operations in relation to signing string and digital signature generation.

SMBC Group

POST /sandbox/v1/signature

HTTP headers

  • smbc-headers (SMBC): custom SMBC header used to specify the list of HTTP headers to be used when generating the signature for the message, e.g., consent-id, x-request-id, psu-id. Note that the order matters.
  • smbc-request-target (SMBC): In production, the (request-target) is derived from the production endpoint being used, for example "POST /berlingroup/v1/payments/pain.001-sepa-credit-transfers". This custom header enables you to simulate different production endpoints when testing your digital signature implementation.

Request payload

  • Any payload will do but we suggest using sample payloads that you are planning to use for, say, POST /payments.

 

2

Validate Berlin Group request headers for digital signatures

  • When you are satisfied that your application is generating the signing string and digital signature that matches POST /sandbox/v1/signature above, this utility enables you to validate the Berlin Group headers for the corresponding request.
  • As before, the "smbc-headers" HTTP header can be used to specify any headers of your choosing and therefore testing both happy- and unhappy-paths for all Berlin Group operations that require digital signatures.
SMBC Group

POST /sandbox/v1/signature/validation

HTTP headers

  • smbc-headers (SMBC): custom SMBC header used to specify the list of HTTP headers to be used when generating the signature for the message, e.g., consent-id, x-request-id, psu-id. Note that the order matters.
  • Digest (Berlin Group): hash of the request payload.
  • Signature (Berlin Group): digital signature header in the format defined by the Cavage/Sporny specification.
  • TPP-Signature-Certificate (Berlin Group): certificate used for signing the request, in base64 encoding.

Request payload

  • Any payload will do but we suggest using sample payloads that you are planning to use for, say, POST /payments.

3

Submit payment and signing basket requests with digital signatures

  • When you have fully tested the digital signatures for, say, payment creation using the digital signature validation utility above, you are now ready to submit the full request to POST /payments.
  • In addition to all the standard Berlin Group checks (e.g. OAuth2, mandatory headers), selected PISP operations such as POST /payments require you to include the three Berlin Group headers for digital signatures. If your tests have passed using the two utilities above, you should not expect any digital signature errors when invoking these Berlin Group operations.
  • This enables you to separate the development and testing of the digital signature elements of your application from the rest of your application (e.g. OAuth2, mandatory headers).

Berlin Group

All PISP operations requiring digital signatures including POST /payments/{payment-product}

See the respective API documentation pages.

Access to Production APIs

When your organisation is ready to connect to our production APIs, you should:

  1. register a dedicated TPP registration application in the developer portal with which you will manage the lifecycle of your production TPP application using the production Dynamic Client Registration Service;
  2. configure the TPP registration application with the following:
    1. credentials obtained from the developer portal for the TPP registration application;
    2. valid eIDAS qualified certificate for website authentication (QWAC) issued by a Qualified Trust Service Providers (QTSPs) to establish a mutually authenticated TLS connection between your TPP registration application and the production Dynamic Client Registration Service; and
    3. valid eIDAS qualified certificate for electronic seal (QSEAL) issued by a QTSP with which your TPP registration application must digitally sign your registration requests to the production Dynamic Client Registration Service.
  3. register your organisation's production TPP application with your TPP registration application;
  4. configure the production TPP application with the following:
    1. credentials obtained from the Dynamic Client Registration Service for the production TPP application;
    2. valid eIDAS QWAC issued by a QTSP to establish mutually authenticated TLS connection required for all production APIs; and
    3. valid eDIAS QSEAL certificate issued by a QTSP (for PISP only).
  5. access the production APIs using the production TPP application.

Sandbox Mock Data

Sandbox Mock Data - Common

#

Step > Sub-Step

PSU 1 using TPP 1

PSU 2 using TPP 1

1

TPP creates consent

The TPP creates a new consent for the PSU to authorise

1.1

> Get TPP access token

Not applicable – the TPP access token you receive is an authentic access token issued by the API Gateway.

As per PSU 1.

1.2

> Create consent

If the request is valid – see Testing Your Application above – the sandbox will always return a fixed consent response for PSU 1. Let’s call this consent 1.

  • PSU-ID="psu_01" (without double quotes)

As per PSU 2 but will return a fixed consent response for PSU 2 that will be different from that for PSU 1. Let’s call this Consent 2.

  • PSU-ID="psu_02" (without double quotes)

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

You must use the Consent ID for Consent 1, notably "d3a7cbff-76da-42b3-a90e-58ef0bff6f25" (without double quotes). Note that these identifiers are fixed and pre-configured in the Sandbox mock data. Note that the code_challenge, and by extension the code_verifier, are determined by you. The Sandbox will use any values you supply and enforce the PKCE checks in Step 2.4.

As per PSU 1 but using Consent 2, notably "q3j4pmrr-76jp-51o7-z35k-24qu0ljj3z41" (without double quotes).

2.2

> Get PSU authorisation code

Not applicable – this is an internal SMBC step.

As per PSU 1.

2.3

> SMBC redirects PSU back to TPP

Not applicable – no mock data in the redirection back to your TPP application.

As per PSU 1.

2.4

> Exchange PSU authorisation code for PSU access token

Not applicable – no mock data used in this step. Do note that you responsible for ensuring the correct code_verifier is supplied in this step. In particular, code_challenge in Step 2.1 must match SHA256(code_verifier).

As per PSU 1.

Sandbox Mock Data - Account Service

#

Step > Sub-Step

PSU 1 using TPP 1

PSU 2 using TPP2

3

AIS Operation

The TPP performs the operation using the PSU access token

3.1

> Get Account List

Consent 1 is authorised to access three accounts that we shall refer to as Account 1, Account 2 and Account 3. Each account has a unique identifier that you can use to retrieve the balances and transactions for that given account. The accounts list also returns the interim available balance.

Consent 2 is authorised for Account 1, Account 4 and Account 5. Note that there is an overlap between the two consents, namely Account 1.

3.2

> Get Account Balance

This returns all the balances of a given account as follows:

Account 1 (EUR)

  • Interim available = 1001.21
  • Interim booked = 1000.11
  • Opening booked = 1000.01
  • Closing booked = 1000.31

Account 2 (KWD)

  • Interim available = -200.022
  • Interim booked = -200.012
  • Opening booked = -200.002
  • Closing booked = 200.032

Account 3 (USD)

  • Interim available = 30000.23
  • Interim booked = 30000.13
  • Opening booked = 30000.03
  • Closing booked = 30000.33

This returns all the balances of a given account as follows:

Account 1 (EUR) – as per PSU 1.

Account 4 (JPY)

  • Interim available = 400024
  • Interim booked = 400014
  • Opening booked = 400004
  • Closing booked = 400034

Account 5 (GBP)

  • Interim available = 50.25
  • Interim booked = 50.15
  • Opening booked = 50.05
  • Closing booked = 50.35

3.3

> Get Account Transactions

This returns the transactions of a given account as follows:

Account 1 (EUR)

  • Txn1 = EUR 1001.01
  • Txn2 = JPY 20002
  • Tnx3 = EUR -3000.03

Account 2 (KWD)

  • Txn4 = KWD 4000.004
  • Txn5 = EUR -5000.05

Account 3 (USD) – no transactions

This returns all the balances of a given account as follows:

Account 1 (EUR) – As per PSU 1

Account 4 (JPY)

  • Txn6 = EUR -6000.06
  • Txn7 = DKK -7000.07

Account 5 (GBP)

  • Txn8 = GBP 8000.08
  • Txn9 = GBP-9000.09
  • Tnx10 = EUR 10000.10

Sandbox Mock Data - Payment Service

The following payments are pre-loaded in the sandbox for all non-POST operations.

Payment# Unique Identifier Product Type Currency Debit Amount Status Create Payment  Authorisation Get Payment Authorisation Delete Payment

 

PIS Operation

The TPP performs the operation using the PSU access token

Payment1 GPTPP190409125959000001 pain.001-sepa-credit-transfers EUR 100.55 PATC - partially accepted, technically correct
Awaiting SCA - locked
Failure - HTTP 409 Status Invalid Started Success - HTTP 204 No Content
Payment2 GPTPP190409125959000002 pain.001-internal-transfers USD 200.15 RJCT - rejected Failure - 409 Status Invalid Finalised Failure - HTTP 405 Cancellation Invalid
Payment3 GPTPP190409125959000003 pain.001-swift-transfers JPY 30035 PATC - partially accepted, technically correct Success - SCA redirection Finalised Success - HTTP 204 No Content
Payment5 GPTPP190409125959000005 pain.001-chaps-payments GBP 500000.55 n.a. Failure - HTTP 409 Status Invalid Finalised Failure - HTTP 405 Cancellation Invalid
Payment6 GPTPP190409125959000006 pain.001-faster-payments GBP 600.65 RJCT - rejected Failure - HTTP 409 Status Invalid Finalised Failure - HTTP 405 Cancellation Invalid

For example, the following operations are applicable to Payment1:

  1. Get payment details: GET /payments/pain.001-sepa-credit-transfers/GPTPP190409125959000001
  2. Create payment authorisation: POST /payments/pain.001-sepa-credit-transfers/GPTPP190409125959000001/authorisations
  3. Delete payment: DELETE /payments/pain.001-sepa-credit-transfers/GPTPP190409125959000001

Additionally, POST /payments always returns a fixed payment identifier for a given payment product, that is pre-loaded in the sandbox. This never changes regardless of the request payload. For example, POST /payments/pain.001-sepa-credit-transfers always returns GPTPP190409125959000008.

Sandbox Mock Data - Signing Basket Service

The following signing baskets are pre-loaded in the sandbox for all non-POST operations.

Basket#

Unique Identifier

Payments in Basket

Basket Status

 

PIS Operation

The TPP performs the operation using the PSU access token

Basket1

a9f28b85-9ac1-4aab-965c-e871cf2683e6

Payment1

Payment7

Finalised

Basket2

fab2d89e-5130-461b-9526-a738d96e728c

Payment5

Payment6

Failed

Basket3

7b461c2c-14ee-489f-b524-288359a94faf

Payment4

Payment5

Payment6

Payment7

Finalised

POST /signing-baskets always returns a fixed basket identifier, that is pre-loaded in the sandbox. This never changes regardless of the request payload. For example, POST /signing-baskets always returns 0de5878f-06dd-4f1c-9563-8e05e962bed3.

Sandbox Mock Data - Funds Confirmation Service

The funds confirmation service always returns "true" regardless of the request payload.