SANDBOX DOCUMENTATION

General

Sandbox is targeted to be used for testing out the PSD2 API endpoints. The endpoints are the same which will be available in production later on. The sandbox however is a testing facility and does not contain real data, but some dummy example data instead. Only users registered to the developer portal can use the sandbox.

Sandbox Management

Register

You need to register an application to the sandbox before you can start using it. Registration can be done by initiating a POST HTTP request to /management/tpp-register-app endpoint of the sandbox. The request takes the following parameters:

A special header called Ocp-Apim-Subscription-Key

JSON body payload containing client name, description and list of redirect_uris

The Ocp-Apim-Subscription-Key header needs to be included in each of the requests made to the sandbox. You need to fill in valid subscrition key as a value for the requests to be accepted. You can find your subscription key from Profile page. The redirect_uris will be used in OAuth2 flows later on. An example registration HTTP request is given below:

POST /mngmt/management/tpp-register-app HTTP/1.1

Request Headers:

Content-Type: application/json
Ocp-Apim-Subscription-Key: test-001-keyd

Request Body:

{
"client_name": "name of the client",
"client_description": "free text description",
"redirect_uris": [ 
    "app://myapp.redirect.uri",
    "https://www.getpostman.com/oauth2/callback" 
    ]
}

In the response you will get back client_id and client_secret which will also need to be used in the OAuth2 flows. Example response payload below:

{
"client_id": "245828784172473",
"client_secret": "avnwA-tURDX-jZyBT-NqTYu",
"client_description": "free text description",
"redirect_uris": [
    "app://myapp.redirect.uri",
        "https://www.getpostman.com/oauth2/callback"
    ]
}

Executing future dated payments

All future dated payments up until the cut-off date given in the optional header parameter dateUntil are executed if the payments are otherwise valid (e.g. enough balance on debtor account). If dateUntil is missing, all future dated payments get executed instead. The practical function this endpoint serves is to accelerate the testing of future payment execution.

POST /mngmt/management/execute-future-dated-payments HTTP/1.1

Request Headers:

Ocp-Apim-Subscription-Key: test-001-key
dateUntil: 2021-01-01

Reset

You can reset the sandbox to the original state. You don’t need to register again after a reset, but all other data, like payments and consents which you have posted to the sandbox will be wiped out. Reset can be initiated by making a POST request to /management/reset endpoint of the Sandbox. HTTP 200 will be returned for successful resets. Example request is given below.

POST /mngmt/management/reset HTTP/1.1

Request Headers:

Ocp-Apim-Subscription-Key: test-001-key
Content-Length: 0

Sandbox OAuth

Consent and payment authorization flow and PSU simulation

The sandbox contains predefined test PSUs listed in below with accounts:

PSU: POPSandbox Customer-01
FI4343370010021679
FI2143370010021687

PSU: POPSandbox Customer-02
FI9643370010021695
FI7443370010021703

PSU: OmaSPSandbox Customer-01
FI1545370010011413
FI9045370010011421

PSU: OmaSPSandbox Customer-02
FI8945370010011439
FI6745370010011447

PSU: SPSandbox Customer-01
FI3745760010038400
FI3645760010038418

PSU: SPSandbox Customer-02
FI1445760010038426
FI8945760010038434

You can authorize consents, payments and payment cancellations as test PSU by simulating the PSU interactions through web user interface. You first need to create the consent or payment to be authorized by using the corresponding AIS / PIS endpoints, e.g. POST /v1/consents.

OAuth2 authorization

The authorization is then done using OAuth2 protocol. You start by doing a GET request to the authorize endopoint at /oauth/authorize using the standard OAuth2 parameters, example below:

GET /samlink-api-sandbox/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&response_type=code HTTP/1.1

Request Parameters

client_id=<client_id>
redirect_uri=https://www.getpostman.com/oauth2/callback
scope=<AIS/PIS:id value>
response_type=code

After PSU authorization as a response you will get a HTTP 302 redirect to your callback URI, example below

HTTP/1.1 302 Found
Location: https://app.getpostman.com/oauth2/callback?code=<code>

OAuth2 Token

You then exchange that to an actual token by doing a POST to the /oauth/token endpoint using the standard Oauth2 parameters. Example again below:

POST /samlink-api-sandbox/oauth/token?grant_type={grant_type}&code={code}&redirect_uri={redirect_uri}&client_id={client_id} HTTP/1.1

Request Headers:

Content-Type: application/x-www-form-urlencoded
X-Request-ID: dummy-value
Ocp-Apim-Subscription-Key: test-001-key
Authorization: Basic Base64Enc(clientId:ClientSecret)

Request Parameters:

grant_type=authorization_code
code=<code>
redirect_uri=https://www.getpostman.com/oauth2/callback
client_id=<client_id>

Other things to consider when using the Sandbox

After registration the PSD2 access to account API endpoints are available for usage. A separated testing area will be created for you when you do registration. It will contain a set of test PSUs and accounts for them. All PSD2 API endpoints will be available to you for testing so you are granted all different TPP roles: AISP, PISP and PIISP.