Workflow for OP PSD2 Payment Initiation Service API V2

OP PSD2 Payment Initiation Service API V2 allows Client Applications to create payments on behalf of OP customers, as well as to authenticate the customer and request authorization for submitting the payments for processing.

Go to OP PSD2 PIS API V2 documentation.‍

This document explains the steps Third-Party Providers need to take in order to access our PSD2 PIS API V2.

All API calls described here are made using mutually authenticated TLS.

Please note that calling PSD2 APIs with Postman is currently not supported.

References‍

Terminology & abbreviations‍

Prerequisites‍

Statuses of different payment types‍

Authorization flows‍

Default authorization flow‍

Recurring and scheduled payment flow‍

Exemption flow‍

Cancellation flow‍

References

Open Banking Security Profile‍

FAPI Read-Only profile‍

FAPI-RW‍

OIDC Connect Core‍

MTLS‍

Terminology & abbreviations

AISP: Account Information Service Provider
ASPSP: Account Servicing Payment Service Provider
PISP: Payment Initiation Service Provider
PSP: Payment Service Provider
PSU: Payment Service User
TPP: Third-Party Provider accessing the API

Prerequisites

Before you can start using our PSD2 APIs, there are certain requirements you should meet.

Instructions for accessing the sandbox‍

Instructions for accessing production environment‍

Statuses of different payment types

SEPA payment & foreign payment

Action	Mandatory	Status(es)	Notes
Create payment	Y	Unauthorized	POST request to payment endpoint
Revoke payment	N	Revoked	Only an unauthorized payment can be revoked.
Start authorization	Y	Authorizing	Payment bundle is locked and no new payments can be added to it.
Reject payment	N	Rejected	The PSU can reject the payment upon authorization.
Authorize payment	Y	Authorized
PSU authorizes cancellation	N	Cancelled	Only payments with Authorized status can be cancelled by PSU via SCA.
Submit payment: success	Y	Accepted, Debited	Accepted status is most often observed with foreign payment only.
Submit payment: retryable failure	N	SubmissionPending	If submission fails, the TPP can try it again after using GET to verify the actual state of the payment. Retries are accepted for the same calendar day.
Submit payment: business failure	N	Rejected	This indicates payment failure such as insufficient funds.
Payment debited to payer account	N/A	Debited	To get the up-to-date status for a payment, use GET with the paymentId.
Payment has been successfully credited to the payee	N/A	Credited	Shown only for SEPA INST payments. To get the up-to-date status for a payment, use GET with paymentId.

Recurring payment

Action	Mandatory	Status(es)	Notes
Create payment	Y	Unauthorized	POST request to recurring-sepa-payments endpoint
Revoke payment	N	Revoked	Only an unauthorized payment can be revoked.
Start authorization	Y	Authorizing	Payment bundle is locked and no new payments can be added to it.
Reject payment	N	Rejected	The PSU can reject the payment upon authorization.
Authorize payment	Y	Authorized
Submit payment: success	Y	Accepted
Submit payment: retryable failure	N	SubmissionPending	If submission fails, the TPP can try it again.
Submit payment: business failure	N	Rejected	This indicates payment failure such as insufficient funds
The PSU authorizes cancellation	N	Cancelled	Cancellation takes place via SCA flow.
Get payment	N	Accepted, AwaitingDueDate, AwaitingFunds, Processing	Payment status reflects the status of the latest recurrence.
Payment debited to payer account	N/A	Debited	This is the terminal state when all recurrences have been settled. Also possible intermittently, when the latest recurrence has been paid and the next one is yet to be processed.

Payment recurrence states

Individual payment instances within a recurring payment support following states:

Action	Status(es)	Notes
The PSU authorizes cancellation	Cancelled	Cancelled by the TPP via SCA or by the PSU via OP's online channels.
Due date has not yet arrived	AwaitingDueDate
Due date has arrived	Processing	Payment has been locked for background processing.
Due date has arrived, no funds on the payment account	AwaitingFunds	Background processing tries to re-execute the payment for a certain period.
No funds and re-execution period has expired	Rejected	Background processing has stopped unsuccessfully for this recurrence.
Payment debited to payer account	Debited	To get up-to-date status for a payment recurrence, use GET with paymentID/recurrence/.

Scheduled payment

Action	Mandatory	Status(es)	Notes
Create payment	Y	Unauthorized	POST request to scheduled-sepa-payments endpoint
Revoke payment	N	Revoked	Only an unauthorized payment can be revoked
Start authorization	Y	Authorizing	Payment bundle is locked and no new payments can be added to it.
Reject payment	N	Rejected	PSU can reject the payment upon authorization
Authorize payment	Y	Authorized
Submit payment: success	Y	Accepted
Submit payment: retryable failure	N	SubmissionPending	If submission fails, the TPP can try it again after verifying with a GET request the current state of the payment.
Submit payment: business failure	N	Rejected	This indicates a payment failure such as insufficient funds.
The PSU authorizes cancellation	N	Cancelled
Get payment	N	Accepted, AwaitingDueDate, AwaitingFunds, Processing	Payment status reflects the status of the latest recurrence
Due date has not yet arrived	N/A	AwaitingDueDate
Due date has arrived	N/A	Processing	Payment has been locked for background processing
Due date has arrived, no funds on the payment account	N/A	AwaitingFunds	Background processing tries to re-execute the payment for a certain period.
No funds and wait period expires	N/A	Rejected	Background processing has stopped unsuccessfully for this recurrence.
Payment debited to payer account	N/A	Debited	This is the terminal state

Authorization flows

OP's PSD2 Payment Initiation Service provides two methods for initiating payments:

Default authorization flow: Strong Customer Authentication (SCA) for creating authorizations
Exemption flow: reusing an existing authorization with small payments

Default authorization flow (SCA)

The default authorization flow implements Strong Customer Authentication (SCA) that can be used in all situations with the PSD2 PIS API. The authorization flow requires completing the following steps:

End user requests to create a payment.
Client App authenticates with Client Credentials Flow.
Client App sets up the payment(s).
End user authenticates and authorizes the payments.
Client App exchanges an authorization code for an access token.
TPP gets the payment(s) (optional).
Client App submits the payment(s).
Client App polls payment status.
TPP verifies the response signature.

Now let's look at each of these steps one by one.

1. End user requests to create a payment

The user simply requests that the TPP client make a payment on their behalf. The client application may receive several payment orders from the end user, committing them at once.

2. Client App authenticates with Client Credentials Flow

To begin interacting with the Payment Initiation Service, the client application authenticates with the Oauth Client Credentials Flow.

The authentication request has the following format:

POST /oauth/token HTTPS/1.1
Host: psd2.mtls.sandbox.apis.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=payments&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>

The following cURL call can be used for completing this step. The call assumes that your current directory contains your client certificate (client.crt) and the related private key (key.pem) - both are created by the Registration Helper App‍.

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/oauth/token -d 'grant_type=client_credentials&scope=payments&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>'

If the request is successful, the response will look like this:

{
  "token_type" : "bearer",
  "access_token" : "Axqx362CnSmLABgzqcBasG0pxBj9",
  "scope" : "payments",
  "status" : "approved",
  "expires_in" : "86399",
}

Save the access_token for use in the next step.

3. Client App sets up the payment(s)

Depending on the payment type, the Client App sets up one or more payments at: - /payments-psd2/v2/sepa-payments - /payments-psd2/v2/foreign-payments - /payments-psd2/v2/scheduled-sepa-payments or - /payments-psd2/v2/recurring-sepa-payments.

Now the TPP application is in possession of an access token, which can be used to create payments. As an additional security measure, the TPP must create a detached JWS and attach it to the payment creation request.

With the default flow, the JWS signature header mandatory.

Creating the detached JWS signature

The TPP uses their QSEALC signing key to create a detached signature of the payment payload. The signature must be set in the x-jws-signature header.

Sample code:

import panva, { JWS, JWKS } from '@panva/jose';

const initPayment = async (
  token: string,
  sessionId: string,
  singlePayment: SepaPaymentRequest
) => {
  const detachedSignature = createDetachedSignature(
    singlePayment,
    ssaSigningKey
  );
  const headers = { 'x-jws-signature': detachedSignature, ...otherHeaders };
  //send payment initiation request with headers:
};

const createDetachedSignature = (payload: any, ssaSigningKey: Buffer) => {
  const jws = asymmetricSign(payload, ssaSigningKey);
  const \[header, b64Payload, signature] = jws.split('.');
  return `${header}..${signature}`;
};

const asymmetricSign = (claims: object, ssaSigningKey: Buffer) => {
  const jwk = panva.JWK.asKey(
    {
      key: ssaSigningKey,
      passphrase: getSecrets().CERT\_PASSPHRASE
    },
    {
      kid: 'example-kid',
      alg: 'RS256'
    }
  );
  const res = panva.JWS.sign(claims, jwk, { kid: jwk.kid });
  return res;
};

Creating a payment

To advance, the TPP establishes mutually authenticated TLS with the host and uses the access token and detached JWS to make a POST call to /payments-psd2/v2/sepa-payments.

cURL:

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v2/sepa-payments
-H 'x-api-key: <API_KEY>'
-H 'Authorization: Bearer <ACCESS_TOKEN>'
-H 'x-jws-signature: eyJraWQiOiJxZXNlYWwtQWZVeHhnIiwiYWxnIjoiRVMyNTYifQ..EHALGjFFfu2URCHuE4ZWPIrvNkkINgAiid_4370_a0GAyXz2pRa9Umsam_HoHKEBrdhOSz9dJ9QWLpq-Y7zC0w'
-H 'x-fapi-interaction-id: 351cd754-1177-4f87-812e-3a996a44aba8'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'x-idempotency-key: 10b2a89b-c491-4377-8fe0-a72d52028f3f'
-d '{"payee":{"iban":"FI2112345600000785","name":"test"},"amountEUR":"1.50","message":"test","payer":{"iban":"FI1258410220189833"}}'

Response body:

{
  authorizationId: '96b5076c-e2cc-41e0-8521-073e35f56731',
  paymentId: 'b4fac615-0fd7-441a-bbe3-271e1221aea2',
  created: '2022-12-21T17:48:13.424+02:00',
  modified: '2022-12-21T17:48:13.424+02:00',
  payer: { iban: 'FI1258410220189833' },
  message: 'test',
  amountEUR: '1.50',
  payee: { iban: 'FI2112345600000785', name: 'test' },
  status: 'Unauthorized'
}

After creating the first payment, the client application receives an authorizationId. If multiple payments are to be authorized in one bundle, subsequent POST requests to /payments-psd2/v2/sepa-payments can include this authorizationId in the request body. The table below explains the relationship between the authorizationId and paymentId.

Name	Legend
authorizationId	A value representing a single bundle of payments. Can be reused if several payments are to be authorized simultaneously.
paymentId	A string representing and identifying the individual payment resource. Used when submitting authorized payments.

With the authorization ID, the client application can create a bundle of payments by replaying the value when creating additional payments. Payments are created one-by-one, but the authorization ID links them together.

Examine or delete created payments

After creation, a single payment can be examined or deleted (i.e. erased before authorization) with a GET or DELETE call to /payments-psd2/v2/sepa-payments/{paymentId}.

Examine and revoke authorizations

The authorization ID can be used for examining the details of the authorization and/or the payments associated with it, or for deleting it, revoking the entire bundle of associated payments.

4. End user authenticates and authorizes the payments.

Authentication and authorization take place between the end user and the authorization server of the account service. The role of the TPP is to prepare an appropriate JWT request, fill in the necessary query parameters, and redirect to the authorization address.

4.1 Constructing the authorization request

The request is a JSON Web token that has been signed with a QSEALC private key (or a key which emulates QSEALC) using RS256 or ES256. The corresponding public key must be made available at a registered JWKS endpoint (not required in sandbox).

Padding characters ("=") should be omitted as per https://tools.ietf.org/html/rfc7515#section-2‍.

The header and payload of the JWT request have the following structure:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "Vi3hb" --> This value varies per key
}
.
{
  "aud": "https://mtls.apis.op.fi",
  "iss": "1ztgnp8NZzUmlmiAdNoC",
  "response_type": "code id_token",
  "client_id": "1ztgnp8NZzUmlmiAdNoC",
  "redirect_uri": "https://localhost:8181/oauth/access_token",
  "scope": "openid payments",
  "state": "bb16b497-097f-4528-9380-4305eb760232",
  "nonce": "76fb7d3a-3a14-4bf7-96fd-e770c3c1e33e",
  "max_age": 86400,
  "exp": 1613548257,
  "iat": 1613547357,
  "claims": {
    "userinfo": {
      "authorizationId": {
        "value": "976da7b0-1db2-410d-a5c9-e3a37bc4d7a1",
        "essential": true
      }
    },
    "id_token": {
      "authorizationId": {
        "value": "976da7b0-1db2-410d-a5c9-e3a37bc4d7a1",
        "essential": true
      },
      "acr": {
        "essential": true,
        "values": [
          "urn:openbanking:psd2:sca"
        ]
      }
    }
  }
}
.
<signature>

Field	Type	Required	Legend
typ	string	true	Type of the token. Always gets value JWT.
alg	string	true	The signing algorithm used. Possible values are RS256 and ES256.
kid	string	true	ID of the signing key. A key corresponding to this value must be available at a public JWKS endpoint. If you have used the registration app in sandbox, this value is found in the field ssaSigningKid in registration-result.txt (the key is in ssa-signing-key.pem).
aud	string	true	Intended audience of the JWT, i.e. the host URL of the API.
iss	string	true	Issuer of the token, i.e. Client ID of the TPP.
response_type	string	true	Specifies the type of the authorization flow. Allowed values for the default authorization flow are code and code id_token. When using the exemption flow, the value must be token.
client_id	string	true	Unique identifier of the client application.
redirect_uri	string	Default flow: true, Exemption flow: false	The address to which the end user will be redirected after authentication and authorization. The access token or error descriptors will be attached to this uri as query parameters.
scope	string	true	Scope names that identify the extent of the requested authorization, as a list of space-separated names. Per the OIDC specification‍ all requests (exemption flow notwithstanding) must contain the openid scope. Only one of the following scopes is allowed for each request: accounts, payments, fundsconfirmations. For PIS default flow, the required value is openid payments. In the exemption flow, the value must be payments.
state	string	true	A string that will be returned to the TPP. Used for validating responses and correlating requests with responses. Must only contain supported characters specified in RFC 4648 Section 5‍, Table 2.
nonce	string	true	A unique string that is used for protecting against replay attacks. Generated by the Client App.
max_age	number	true	Maximum allowed age for the authentication, in seconds.	exp	number	true	Token expiry timestamp
iat	number	true	Token issued at timestamp
claims	object	true	Contains information related to the request. The field authorizationId contains the authorizationId obtained while registering intent.
userinfo	object	true	Contains information related to the request. The field authorizationId contains the authorizationId obtained while registering intent.
id_token	object	true	The contents of this field are similar to userinfo.
acr	obj	true	Specifies the requested authorization contexts. In the default flow, the value must be urn:openbanking:psd2:sca. In the exemption flow, the value must be urn:openbanking:psd2:ca

Once the body and header have been constructed, follow these steps:

Base64 URL encode the header and body separately. Append the body to the header, separating the two parts with a dot.
Create a signature by taking a copy of the newly created string and encrypting it with your private key (from QSEALC or emulated) using the algorithm specified in the header. This is the signature.
Attach the signature to the encoded header and body with a dot. You'll get something like this:

eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJIZWxsbyJ9.N6-M8oOwCq9x820PR6HMtWo-_FL5GeWUSqQ66H2F5kA

Remember to leave out padding characters ("=").

See our example code for signing JWTs. This code assumes that you have private and public JWKS readily available. In the sandbox, developers may use the Registration Helper App‍ to auto-generate JWKSs.

ES256 or RS256 are allowed as signing algorithms.

import * as fs from "fs";
import { JWKS, JWK, JWT } from "jose";

//request is a valid pre-created JWT body
const asymmetricSign = (request: object, privateJwksPath: string) => {
  const privateJwks = JSON.parse(
    fs.readFileSync(privateJwksPath, "utf8").toString()
  );
  const privateJwk = JWKS.asKeyStore(privateJwks, {
    calculateMissingRSAPrimes: true,
  }).get({ alg: "RS256" });
  return JWT.sign(JSON.stringify(request), privateJwk);
};

You can validate the generated JWT with your public JWKS as follows:

import * as fs from 'fs';
import { JWT } from 'jose';

const publicJwks = JWKS.asKeyStore(JSON.parse(fs.readFileSync('path/to/publicjwks.json', 'utf8').toString()));

JWT.verify(jwt, publicJwks, {
    algorithms: \['ES256', 'RS256', 'PS256'],
    clockTolerance: '120s',
    maxTokenAge: '60s',
    complete: true,
});

Learn more about JWTs on jwt.io‍. Note that the JWT editor is currently incapable of processing this type of key.

4.2 Redirection

Once the request is complete, the TPP will redirect the customer to OP's auth server. The client app must append the following query parameters to the redirection URI:

request (the JWT request)
response_type
client_id
scope

The values of the parameters MUST match with those in the JWT request. Remember that all query parameters must be URL encoded.

The redirect will have the following structure:

https://authorize.psd2-sandbox.op.fi/oauth/authorize
?request=<your_JWT_string>
&response_type=code+id_token
&client_id=******
&scope=openid%20payments

Direct the customer to this URI in the browser.

4.3 The customer authenticates and authorizes

Authentication and authorization are the responsibility of the customer and the authorization server. The customer logs in and selects the authorizations they wish to confirm or reject.

The following test credentials are available in our sandbox:

Username	Password	Key code / mobile key
88888881	1122	1122
88888882	1122	1122

4.4 Back to Client Application

The auth server will redirect the end user to the redirect URI specified in the request. There are two possible outcomes:

Success:
<REDIRECT_URI>?state=<state>&code=<authorization_code>

Success with ID token:
<REDIRECT_URI>#state=<state>&code=<authorization_code>&id_token=<id_token>

Error:
<REDIRECT_URI>?state=<state>&error=<error_description>

For example:
https://localhost:8181/oauth/access_token?error=temporarily_unavailable&state=373b23cd-a1b3-449a-810f-cd4b36f7a60c

As the user returns to the TPP's application, the TPP should verify that the returning user is the same as the user who began started the authorization process. This can be achieved by inspecting the user's session ID.

ID tokens are created and returned on two occasions:

When using response type code id_token in the authorization request. The ID token will be delivered in a query parameter attached to the client app's redirect URI. Note that when an ID token is present, the query string is in fact an URI fragment (begins with "#" instead of "?").
When requesting a token from a token endpoint and scope includes openid (in OP PSD2, always). The token will be returned in the response body to the token request.

The ID token contains information about the authorization, and provides an additional layer of security.

The ID token contains the following information:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "12345"
}
.
{
  "iss": "https://authorize.psd2-sandbox.op.fi",
  "iat": 1234569795,
  "sub": "28c52f98-7541-42a2-9ca0-b86ceac47692",
  "acr": "urn:openbanking:psd2:sca",
  "authorizationId": "28c52f98-7541-42a2-9ca0-b86ceac47692,
  "aud": "s6BhdRkqt3",
  "nonce": "n-0S6_WzA2Mj",
  "exp": 1311281970,
  --ALTERNATIVE 1: AUTHORIZATION CODE FLOW---
  "s_hash": "76sa5dd",
  "c_hash": "asd097d"
  --ALTERNATIVE 2: TOKEN ENDPOINT---
  "rt_hash": "wFsWWP49hHo4sXwwVSHX-A",
  "at_hash": "bSUTLJiqrooANhJJ2X7pPw"
  }
.
{
<<signature>>
}

Field	Type	Legend
iss	string/URI	Issuer of the token.
iat	timestamp	Token issuance time as seconds since 1970-01-01T0:0:0Z.
sub	string	The authorization ID to which the ID token relates to.
acr	string	Authentication Context Class Reference, i.e. the level of authentication achieved. Currently, only urn:openbanking:psd2:sca is supported.
authorizationId	string	The authorization ID to which the ID token relates to.
aud	string/client ID	Intended audience of the ID token. WIll contain the Client ID of the Client Application.
nonce	string	A value originally provided by the TPP in the request, used for protecting against replay attacks.
exp	timestamp	Time of expiry, i.e. the time after which the token is no longer valid.
s_hash	string, case-sensitive	Returned with authorization code. State hash value: base64Url encoding of the left-most half of the hash of the octets of the ASCII representation of the state value, where the hash algorithm used is the hash algorithm used in the algHeader Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the code value with SHA-256, then take the left-most 256 bits and base64url encode them. The s_hashvalue is a case sensitive string.
c_hash	string, case-sensitive	Returned with authorization code. Code hash value: base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header.
rt_hash	string	Returned from token endpoint. Refresh token hash value: base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the refresh_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the refresh_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The rt_hash value is a case sensitive string.
at_hash	string	Returned from token endpoint. Access token hash value: base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

The ID token must be validated following the OIDC spec‍. In addition, the TPP should do the following:

Alternative 1: ID token received in redirection URI

Validate the authorization ID against that received earlier.
Validate the signature of the ID token.
Validate s_hash (state hash).
Validate c_hash (code hash).

Alternative 2: ID token in access token response body

Validate the authorization ID against that received earlier.
Validate the signature of the ID token.
Validate rt_hash (refresh token validation).
Validate at_hash (access token validation).

See the public key for validating ID token signatures.‍

5. Client App exchanges an authorization code for an access token

At this point the TPP is in possession of an authorization code. This must now be exchanged for an access token.

POST /oauth/token HTTPS/1.1
Host: psd2.mtls.sandbox.apis.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>

cURL:

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/oauth/token -d 'grant_type=authorization_code&client_id=<clienti_id>&client_secret=<APP_CLIENT_SECRET>&code=wpj94iuZRzFvmHHpIFba7b1QiZweXm&redirect_uri=https%3A%2F%2Flocalhost%3A8181'

A successful request will yield a response with the following content:

{
  "access_token":"TfOJ0yOywdg8cwthvKUE",
  "refresh_token":"TYiOBpLHMWSgXsTg0SJ7TlqVMhSsWnJ6vxL6dUk9",
  "id_token": "eyJraWQiOiI2ZzNRRU9SY0hNOVdVZTZlcVowZi1wdjNEUEV1Y2NHVTRUdDFVMHo0cFIwIiwiYWxnIjoiUlMyNTYifQ.eyJydF9oYXNoIj---90ZXN0X2NsaWVudCJ9.OMxF_fyVTS0af_---e9sQXEGMHW_S7bsA",
  "scope":"openid payments",
  "token_type":"bearer",
  "expires_in":3599,
}

Field	type	Legend
access_token	string	This is the access token. Use as a bearer token in the Authorization header to access protected resources.
refresh_token	string	Can be used to request additional access tokens. Valid for up to 45 days (Less if the authorization granted is shorter).
id_token	string	A signed JWT containing information about the authorization. See ID tokens for a full description on the contents and recommended validation procedures for ID tokens.
scope	string	A space-separated list of scope names describing the services to which the token grants authorization.
token_type	string	Token type. Always has the value "bearer".
expires_in	number	The period for which the token is valid, in seconds.

Refreshing tokens

Refresh tokens may be used for requesting additional access tokens, as well as for renewing refresh tokens. They remain valid for a maximum of 45 days.

Regardless of the length of the authorization, the end user must re-authorize the Client Application if the application fails to renew the refresh token within 45 days.

Refresh requests have the following structure:

POST /oauth/token HTTPS/1.1
Host: psd2.mtls.sandbox.apis.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>

The response to this request is similar to that of a normal token request.

6. TPP gets the payment(s) (optional)

TPP can GET the payments here to retrieve the payer account and account holder name, for example.

7. Client App submits the payment(s)

Armed with the access token and payment IDs, the Client Application submits each individual payment with a POST call to

/payments-psd2/v2/<payment type>/{paymentId}/submit.

Payment must be submitted immediately after authorization. For future dated payments use scheduled payments.

8. Client App polls payment status

TPP invokes the /payments endpoint for querying payment status. The status of each payment can be polled using paymentId.

9. TPP verifies the response signature

NOTE! Response signature verification applies to any response sent by PSD2 PIS API.

As a final verification step, the TPP must inspect the detached JWS signature of the body of the payload of the header x-jws-signature.

The format of the signature is header..signature, where header is a JWS header and signature a JWS signature of a usual compact serialized JWS.

The payload received in the response body must be inserted into the middle of the JWS string in as shown:

header. + BASE64URL(received payload) + .signature

Read further details.‍

To finish, the TPP verifies the resulting compact serialized JWS (header.payload.signature) against a matching JWK.

Recurring and scheduled payment flow

As of PIS API V2, recurring and scheduled payments are automatically submitted by a background process. The payments can be modified by the PSU in OP's online channels and the TPP can cancel the payment via SCA (see Cancellation flow).

Exemption flow

The exemption flow allows creating and submitting payments by reusing a previous authorization. When using the exemption flow, the TPP does not need to direct the customer to OP's authentication and authorization UI. The exemption flow is available when the payment adheres to the conditions and requirements described in this section.

The exemption flow is available both in sandbox and production.

Note that the exemption flow can only be used with immediate SEPA payments.

Conditions and requirements

The following conditions must be met:

The user has authorized the TPP app before (client possesses refresh token from an earlier SCA).
The payer account is owned by the person whose authorization is being reused.

Furthermore, the payment must fall under one of these categories:

Payment amount is less than 30 euros, the user has submitted fewer than 5 exemption payments since last SCA, and the cumulative value of the customer's exemption payments since latest SCA is less than 100 euros.
The payment is a transfer between two OP accounts owned by the customer.

Additionally, the following limitations apply:

Only SEPA payments are allowed.
Payments cannot be bundled together with a single authorization ID.

If the exemption flow fails at any point, the payment must be completed using the default authorization flow.

Overview of the exemption flow

Customer requests to create a payment.
Client App uses a refresh token to request an access token for the customer.
Client App creates the payment.
Client App creates a request JWT, confirming the reuse of the previous authorization.
Client App submits the payments one by one.

1. Customer requests to create a payment

As with the default flow, the process begins with the customer requesting to commit a payment. The payment must be within the bounds of the exemption flow. See conditions and requirements.

2. Client App uses a refresh token to request an access token for the customer

The Client App requests an access token from the token endpoint. This replaces Client Credentials Grant of the default authorization flow. The client uses the refresh token from a previously completed SCA instead of an access token representing the client itself:

POST /oauth/token HTTPS/1.1
Host: psd2.mtls.sandbox.apis.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<REFRESH_TOKEN_FROM_SCA>&scope=payments&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>

cURL:

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/oauth/token -d 'grant_type=refresh_token&refresh_token=<REFRESH_TOKEN_FROM_SCA>&scope=payments&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>'

3. Client App creates the payment

The client creates the payments as with the default flow. Note that the exemption flow does not allow payment bundling: each payment must be created and authorized separately.

When using the exemption flow, the header x-jws-signature is mandatory. See step 3 of the default flow for more information on how to construct the header contents.

The headers x-fapi-customer-ip-address, and x-customer-user-agent and x-fapi-customer-last-logged-time should also be set.

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v2/sepa-payments
-H 'x-api-key: <APP_API_KEY>'
-H 'Authorization: Bearer <ACCESS_TOKEN>'
-H 'x-jws-signature: eyJraWQiOiJxZXNlYWwtQWZVeHhnIiwiYWxnIjoiRVMyNTYifQ..EHALGjFFfu2URCHuE4ZWPIrvNkkINgAiid_4370_a0GAyXz2pRa9Umsam_HoHKEBrdhOSz9dJ9QWLpq-Y7zC0w'
-H 'x-fapi-customer-ip-address: <IP_ADDRESS>'
-H 'x-customer-user-agent: <USER_AGENT>'
-H 'x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC'
-H 'x-fapi-financial-id: test'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'x-idempotency-key: idempotent_5'
-d '{"payee":{"iban":"FI4950009420028730", "name":"Test_Person"}, "payer":{"iban":"FI5850009420172322"}, "message":"test_payment", "amountEUR":"5.00"}'

4. Client App creates a request JWT, confirming the reuse of the previous authorization

The Client constructs a JWT request as in the default authorization flow, with minor differences in its structure. Below is a sample exemption JWT body:

{...}
.
{
  "iss": "<CLIENT_ID>",
  "aud": "https://mtls.apis.op.fi",
  "response_type": "token",
  "client_id": "<CLIENT_ID>",
  "scope": "payments",
  "state": "1234",
  "nonce": "ttpp1573632173204",
  "max_age": 86400,
  "claims": {
    "id_token": {
      "acr": {
        "values": [
          "urn:openbanking:psd2:ca"
        ],
        "essential": true
      },
      "authorizationId": {
        "value": "26c71e03-e5e9-43b9-b913-36f30baf26d2",
        "essential": true
      }
    },
    "userinfo": {
      "authorizationId": {
        "value": "26c71e03-e5e9-43b9-b913-36f30baf26d2",
        "essential": true
      }
    }
  }
}

Differences to default JWT requests

Field	Difference
response_type	Must be token.
redirect_uri	Not required with exemption flow.
scope	Must be payments.
acr	The array field values must only contain value urn:openbanking:psd2:ca.

Once the exemption JWT is ready, the Client App uses it to fetch a new access token. The JWT request must be transmitted to the token endpoint in the body parameter assertion, along with the Client App's client credentials. The scope is payments.

Body parameters of the token call

Name	Description
client_secret	The Client Secret of the application.
grant_type	Grant type. Must be urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion	The JWT request constructed for the exemption flow.
response_type	Oauth response type. Must be token.

Example call to the token endpoint with JWT assertion

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/oauth/token -d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<EXEMPTION_JWT>&response_type=token&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>&scope=payments'

5. Client App submits the payments one by one

As with the default authorization flow, the Client App finally submits the payment using the newly acquired access token and receives its status in the JSON response.

cURL:

curl -vk --key key.pem --cert client.crt -X POST https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v2/sepa-payments/0427a7ba-2c83-4556-9fc9-98eee25c34ee/submit -H 'x-api-key: <API_KEY>' -H 'Authorization: Bearer <ACCESS_TOKEN>' -H 'Content-Length: 0'

Cancellation flow

Cancellation of a payment requires separate SCA. SEPA and foreign payments can only be cancelled when their status is Authorized.

Recurring and scheduled payments can be cancelled before the last due date.

The cancellation flow implements Strong Customer Authentication (SCA). The authorization flow requires completing the following steps:

The End user authenticates and authorizes the cancellation.
The Client App exchanges an authorization code for an access token.
The Client App cancels the payment(s).
The Client App polls payment status.
TPP verifies the response signature.

Now let's look at each of these steps one by one.

1. End user authenticates and authorizes the cancellation

1.1 Constructing the authorization request

Padding characters ("=") should be omitted as per https://tools.ietf.org/html/rfc7515#section-2‍.

The header and payload of the JWT request have the following structure:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "Vi3hb" --> This value varies per key
}
.
{
  "aud": "https://mtls.apis.op.fi",
  "iss": "clientId",
  "response_type": "code id_token",
  "client_id": "clientId",
  "redirect_uri": "https://tpp-demo-app.psd2-sandbox.test.aws.op-palvelut.net/oauth/access_token/payments",
  "scope": "openid payments:delete",
  "state": "80c00b913696c4a7c9598470",
  "nonce": "94052e00990cc84c6accbab4",
  "max_age": 86400,
  "exp": 1675755458,
  "iat": 1675754558,
  "claims": {
    "userinfo": {
      "authorizationId": {
        "value": "bfff2142-25dc-4c50-a4c5-000eb9f652c5",
        "essential": true
      },
      "paymentId": {
        "value": "371065fa-f134-4a43-815a-efa741407541",
        "essential": true
      }
    },
    "id_token": {
      "authorizationId": {
        "value": "bfff2142-25dc-4c50-a4c5-000eb9f652c5",
        "essential": true
      },
      "paymentId": {
        "value": "371065fa-f134-4a43-815a-efa741407541",
        "essential": true
      },
      "acr": {
        "essential": true,
        "values": [
          "urn:openbanking:psd2:sca",
          "urn:openbanking:psd2:ca"
        ]
      }
    }
  }
}
.
<signature>

Field	Type	Required	Legend
typ	string	true	Type of the token. Always gets value JWT.
alg	string	true	The signing algorithm used. Possible values are RS256 and ES256.
kid	string	true	ID of the signing key. A key corresponding to this value must be available at a public JWKS endpoint. If you have used the registration app in sandbox, this value is found in the field ssaSigningKid in registration-result.txt (the key is in ssa-signing-key.pem).
aud	string	true	Intended audience of the JWT, i.e. the host URL of the API.
iss	string	true	Issuer of the token, i.e. Client ID of the TPP.
response_type	string	true	Specifies the type of the authorization flow. Allowed values for the default authorization flow are code and code id_token. When using the exemption flow, the value must be token.
client_id	string	true	Unique identifier of the client application.
redirect_uri	string	Default flow: true, Exemption flow: false	The address to which the end user will be redirected after authentication and authorization. The access token or error descriptors will be attached to this uri as query parameters.
scope	string	true	Scope names that identify the extent of the requested authorization, as a list of space-separated names. Per the OIDC specification‍ all requests (exemption flow notwithstanding) must contain the openid scope.
state	string	true	A string that will be returned to the TPP. Used for validating responses and correlating requests with responses. Must only contain supported characters specified in RFC 4648 Section 5‍, Table 2.
nonce	string	true	A unique string that is used for protecting against replay attacks. Generated by the Client App.
max_age	number	true	Maximum allowed age for the authentication, in seconds.	exp	number	true	Token expiry timestamp
iat	number	true	Token issued at timestamp
claims	object	true	Contains information related to the request. The field authorizationId contains the authorizationId obtained while registering intent. The field paymentId must contain the paymentId to be cancelled.
userinfo	object	true	Contains information related to the request. The field authorizationId contains the authorizationId obtained while registering intent. The field paymentId must contain the paymentId to be cancelled.
id_token	object	true	The contents of this field are similar to userinfo.
acr	obj	true	Specifies the requested authorization contexts. In the default flow, the value must be urn:openbanking:psd2:sca.

Once the body and header have been constructed, follow these steps:

Base64 url encode the header and body separately. Append the body to the header, separating the two parts with a dot.
Create a signature by taking a copy of the newly created string and encrypting it with your private key (from QSEALC or emulated) using the algorithm specified in the header. This is the signature.
Attach the signature to the encoded header and body with a dot. You'll get something like this:

eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJIZWxsbyJ9.N6-M8oOwCq9x820PR6HMtWo-_FL5GeWUSqQ66H2F5kA

Remember to leave out padding characters ("=").

ES256 or RS256 are allowed as signing algorithms.

import * as fs from "fs";
import { JWKS, JWK, JWT } from "jose";

//request is a valid pre-created JWT body
const asymmetricSign = (request: object, privateJwksPath: string) => {
  const privateJwks = JSON.parse(
    fs.readFileSync(privateJwksPath, "utf8").toString()
  );
  const privateJwk = JWKS.asKeyStore(privateJwks, {
    calculateMissingRSAPrimes: true,
  }).get({ alg: "RS256" });
  return JWT.sign(JSON.stringify(request), privateJwk);
};

You can validate the generated JWT with your public JWKS as follows:

import * as fs from 'fs';
import { JWT } from 'jose';

const publicJwks = JWKS.asKeyStore(JSON.parse(fs.readFileSync('path/to/publicjwks.json', 'utf8').toString()));

JWT.verify(jwt, publicJwks, {
    algorithms: \['ES256', 'RS256', 'PS256'],
    clockTolerance: '120s',
    maxTokenAge: '60s',
    complete: true,
});

Learn more about JWTs on jwt.io‍. Note that the JWT editor is currently incapable of processing this type of key.

1.2 Redirection

Once the request is complete, the TPP will redirect the customer to OP's auth server. The client app must append the following query parameters to the redirection URI:

request (the JWT request)
response_type
client_id
scope

The values of the parameters must match with those in the JWT request. Remember that all query parameters must be URL encoded.

The redirect will have the following structure:

https://authorize.psd2-sandbox.op.fi/oauth/authorize
?request=<your_JWT_string>
&client_id=******
&response_type=code%20id_token
&scope=openid%20payments%3Adelete
&state=80c00b913696c4a7c9598470

Direct the customer to this URI in the browser.

1.3 The customer authenticates and authorizes

Authentication and authorization are the responsibility of the customer and the authorization server. The customer logs in and selects the authorizations they wish to confirm or reject.

The following test credentials are available in our sandbox:

Username	Password	Key code / mobile key
88888881	1122	1122
88888882	1122	1122

1.4 Back to Client Application

The auth server will redirect the end user to the redirect URI specified in the request. There are two possible outcomes:

Success:
<REDIRECT_URI>?state=<state>&code=<authorization_code>

Success with ID token:
<REDIRECT_URI>#state=<state>&code=<authorization_code>&id_token=<id_token>

Error:
<REDIRECT_URI>?state=<state>&error=<error_description>

For example:
https://localhost:8181/oauth/access_token?error=temporarily_unavailable&state=373b23cd-a1b3-449a-810f-cd4b36f7a60c

ID tokens are created and returned on two occasions:

When using response type code id_token in the authorization request. The ID token will be delivered in a query parameter attached to the client app's redirect URI. Note that when an ID token is present, the query string is in fact an URI fragment (begins with "#" instead of "?").
When requesting a token from a token endpoint and scope includes openid (in OP PSD2, always). The token will be returned in the response body to the token request.

The ID token contains information about the authorization, and provides an additional layer of security.

The ID token contains the following information:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "12345"
}
.
{
    "nonce": "94052e00990cc84c6accbab4",
    "authorizationId": "bfff2142-25dc-4c50-a4c5-000eb9f652c5",
    "iat": 1675754629,
    "iss": "https://authorize.psd2-sandbox.op.fi",
    "sub": "bfff2142-25dc-4c50-a4c5-000eb9f652c5",
    "exp": 1675758229,
    "acr": "urn:openbanking:psd2:sca",
    "aud": "hphza9KaLJRuvYI2bQyo"
    --ALTERNATIVE 1: AUTHORIZATION CODE FLOW---
    "s_hash": "76sa5dd",
    "c_hash": "asd097d"
    --ALTERNATIVE 2: TOKEN ENDPOINT---
    "rt_hash": "wFsWWP49hHo4sXwwVSHX-A",
    "at_hash": "bSUTLJiqrooANhJJ2X7pPw"
}
.
{
<<signature>>
}

Field	Type	Legend
iss	string/URI	Issuer of the token.
iat	timestamp	Token issuance time as seconds since 1970-01-01T0:0:0Z.
sub	string	The authorization ID to which the ID token relates to.
acr	string	Authentication Context Class Reference, i.e. the level of authentication achieved. Currently, only urn:openbanking:psd2:sca is supported.
authorizationId	string	The authorization ID to which the ID token relates to.
aud	string/client ID	Intended audience of the ID token. WIll contain the Client ID of the Client Application.
nonce	string	A value originally provided by the TPP in the request, used for protecting against replay attacks.
exp	timestamp	Time of expiry, i.e. the time after which the token is no longer valid.
s_hash	string, case-sensitive	Returned with authorization code. State hash value: base64Url encoding of the left-most half of the hash of the octets of the ASCII representation of the state value, where the hash algorithm used is the hash algorithm used in the algHeader Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the code value with SHA-256, then take the left-most 256 bits and base64url encode them. The s_hashvalue is a case sensitive string.
c_hash	string, case-sensitive	Returned with authorization code. Code hash value: base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header.
rt_hash	string	Returned from token endpoint. Refresh token hash value: base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the refresh_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the refresh_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The rt_hash value is a case sensitive string.
at_hash	string	Returned from token endpoint. Access token hash value: base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

The ID token must be validated following the OIDC spec‍. In addition, the TPP should do the following:

Alternative 1: ID token received in redirection URI

Validate the authorization ID against that received earlier.
Validate the signature of the ID token.
Validate s_hash (state hash).
Validate c_hash (code hash).

Alternative 2: ID token in access token response body

Validate the authorization ID against that received earlier.
Validate the signature of the ID token.
Validate rt_hash (refresh token validation).
Validate at_hash (access token validation).

See the public key for validating ID token signatures.‍

2. Client App exchanges an authorization code for an access token

At this point the TPP is in possession of an authorization code. This must now be exchanged for an access token.

POST /oauth/token HTTPS/1.1
Host: psd2.mtls.sandbox.apis.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>

cURL:

curl -vk --key key.pem --cert client.crt https://psd2.mtls.sandbox.apis.op.fi/oauth/token -d 'grant_type=authorization_code&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>&code=wpj94iuZRzFvmHHpIFba7b1QiZweXm&redirect_uri=https%3A%2F%2Flocalhost%3A8181'

A successful request will yield a response with the following content:

{
  "access_token":"TfOJ0yOywdg8cwthvKUE",
  "refresh_token":"TYiOBpLHMWSgXsTg0SJ7TlqVMhSsWnJ6vxL6dUk9",
  "id_token": "eyJraWQiOiI2ZzNRRU9SY0hNOVdVZTZlcVowZi1wdjNEUEV1Y2NHVTRUdDFVMHo0cFIwIiwiYWxnIjoiUlMyNTYifQ.eyJydF9oYXNoIj---90ZXN0X2NsaWVudCJ9.OMxF_fyVTS0af_---e9sQXEGMHW_S7bsA",
  "scope":"openid payments:delete",
  "token_type":"bearer",
  "expires_in":3599,
}

Field	type	Legend
access_token	string	This is the access token. Use as a bearer token in the Authorization header to access protected resources.
refresh_token	string	Can be used to request additional access tokens. Valid for up to 45 days (Less if the authorization granted is shorter).
id_token	string	A signed JWT containing information about the authorization. See ID tokens for a full description on the contents and recommended validation procedures for ID tokens.
scope	string	A space-separated list of scope names describing the services to which the token grants authorization.
token_type	string	Token type. Always has the value "bearer".
expires_in	number	The period for which the token is valid, in seconds.

Refreshing tokens

Refresh tokens may be used for requesting additional access tokens, as well as for renewing refresh tokens. They remain valid for a maximum of 45 days.

Regardless of the length of the authorization, the end user must re-authorize the Client Application if the application fails to renew the refresh token within 45 days.

Refresh requests have the following structure:

POST /oauth/token HTTPS/1.1
Host: psd2.mtls.sandbox.apis.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<APP_CLIENT_ID>&client_secret=<APP_CLIENT_SECRET>

The response to this request is similar to that of a normal token request.

3. Client App cancels the payment(s)

Armed with the access token and payment IDs, the Client Application cancels each individual payment with a DELETE call to

/payments-psd2/v2/<payment type>/{paymentId}.

4. Client App polls payment status

TPP invokes the payments endpoint for querying payment status. The status of each payment can be polled using paymentId.

5. TPP verifies the response signature

As a final verification step, the TPP must inspect the detached JWS signature of the body of the payload of the header x-jws-signature.

The format of the signature is header..signature, where header is a JWS header and signature a JWS signature of a usual compact serialized JWS.

The payload received in the response body must be inserted into the middle of the JWS string in as shown:

header. + BASE64URL(received payload) + .signature

Read further details.‍

To finish, the TPP verifies the resulting compact serialized JWS (header.payload.signature) against a matching JWK. In the sandbox, see the JWK here.‍

Workflow for OP PSD2 Payment Initiation Service API V2

Contents

References

Terminology & abbreviations

Prerequisites

Statuses of different payment types

SEPA payment & foreign payment

Recurring payment

Payment recurrence states

Scheduled payment

Authorization flows

Default authorization flow (SCA)

1. End user requests to create a payment

2. Client App authenticates with Client Credentials Flow

3. Client App sets up the payment(s)

Creating the detached JWS signature

Creating a payment

Examine or delete created payments

Examine and revoke authorizations

4. End user authenticates and authorizes the payments.

4.1 Constructing the authorization request

4.2 Redirection

4.3 The customer authenticates and authorizes

4.4 Back to Client Application

5. Client App exchanges an authorization code for an access token

Refreshing tokens

6. TPP gets the payment(s) (optional)

7. Client App submits the payment(s)

8. Client App polls payment status

9. TPP verifies the response signature

Recurring and scheduled payment flow

Exemption flow

Conditions and requirements

Overview of the exemption flow

1. Customer requests to create a payment

2. Client App uses a refresh token to request an access token for the customer

3. Client App creates the payment

4. Client App creates a request JWT, confirming the reuse of the previous authorization

Differences to default JWT requests

Body parameters of the token call

Example call to the token endpoint with JWT assertion

5. Client App submits the payments one by one

Cancellation flow

1. End user authenticates and authorizes the cancellation

1.1 Constructing the authorization request

1.2 Redirection

1.3 The customer authenticates and authorizes

1.4 Back to Client Application

2. Client App exchanges an authorization code for an access token

Refreshing tokens

3. Client App cancels the payment(s)

4. Client App polls payment status

5. TPP verifies the response signature