Workflow for PSD2 Payments API

OP PSD2 Payment Initiation Service API 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.

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

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

NOTE: Calling PSD2 APIs with Postman is not currently not supported.

See PSD2 PIS API documentation >


Contents

References

Terminology & abbreviations

Prerequisites

Overview of OP PSD2 PIS

Default Authorization Flow - Create & authorize payments

Exemption Flow - Reuse previous authorization


References

Open Banking Security Profile

FAPI - FAPI Read-Only profile

FAPI-RW

OIDC Connect Core

MTLS


Terminology & abbreviations

  • TPP: the Third-Party Provider accessing the API.
  • Client App: an application developed by the TPP for accessing the API.

Prerequisites

Before you can start using our PSD2 APIs, ensure that you meet the requirements outlined in this section.

Sandbox

The following is required for PSD2 sandbox:

  • A registered app on OP Developer: API key and client secret
  • Certificates and related keypairs from our certificate generation API for mutually authenticated TLS
  • Successful registration via the TPP registration endpoint (incl. functional JWKS URIs, redirect URIs...)

In sandbox, the host addresses are the following:

ServiceHost
Authentication and authorizationhttps://authorize.psd2-sandbox.op.fi
Business APIs & token endpointshttps://mtls-apis.psd2-sandbox.op.fi
JWKS URI for ID token signature verificationhttps://authorize.psd2-sandbox.op.fi/oauth/jwks/PSD2_OIDC
JWKS URI for validating payment response signatureshttps://sandbox.apis.op-palvelut.fi/psd2/sandbox/jwks/payments/jwks.json

Production

The following is required for PSD2 APIs in production:

  • Support for TLS version 1.2
  • Valid AISP/PISP registration and approval from a European financial authority, passported if necessary
  • Valid eIDAS certificates: QWAC for establishing MTLS, QSEAL for signing JWTs
  • Successful registration via the TPP registration endpoint (incl. functional JWKS endpoints, redirect uris...)

From February 15th 2020 onwards, TLS versions below 1.2 will not be supported.

The following host names are available in production:

ServiceHost
Authentication & authorizationhttps://authorize.op.fi
Business APIs and token endpointshttps://mtls.apis.op.fi
JWKS URIhttps://apis.op.fi/psd2/jwks/payments/jwks.json

Overview of OP PSD2 PIS

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

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

The following section will explain the default authorization flow. To learn about the exemption flow, see Exemption Flow.

Default authorization flow (SCA)

PAYMENT FLOW DARK 2020

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

  1. End user requests to create a Payment
  2. Client App authenticates with Client Credentials Flow
  3. Client App sets up one or more payments at /payments-psd2/v1/sepa-payments
  4. End user authenticates and authorizes all payments with the same authorizationId
  5. Client App receives an Authorization Code (validates user/session match) and exchanges it for an Access Token
  6. Client App creates payment-submission
  7. Client App polls payment status.

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

1. End user requests payment creation

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. TPP app authenticates using the Client Credentials flow and receives an access token with the scope payments.

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: mtls-apis.psd2-sandbox.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://mtls-apis.psd2-sandbox.op.fi/oauth/token -d 'grant_type=client_credentials&scope=payments&client_id=<client_id>&client_secret=<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. TPP sets up the payment(s)

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 is optional from February 11th 2020 onwards, and will be mandatory starting on June 1st 2020.

Creating the detached JWS signature

The TPP then 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/v1/sepa-payments.

cURL
curl -vk --key key.pem --cert client.crt https://mtls-apis.psd2-sandbox.op.fi/payments-psd2/v1/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-financial-id: test'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'x-idempotency-key: idempotent_1'
-d '{"payee":{"iban":"FI4950009420028730", "name":"Test_Person"}, "payer":{"iban":"FI4950009420028730"}, "message":"test_payment", "amountEUR":"4.00"}'

Response body

{
  "paymentId": "8efb669f-c105-4f74-ab13-aef176d94f91",
  "authorizationId": "934e82fc-fdc4-4378-8bcf-038075a259sd",
  "status": "Unauthorized",
  "created": "2019-11-01T10:00:00.000+02:00",
  "modified": "2019-11-01T100:00:00.000+02:00",
  "detailsOfCharges": "SHA",
  "paymentOrder": "SEPA",
  "count": 1,
  "payer": {
    "iban": "FI4950009420028730"
  },
  "message": "test_payment",
  "paymentType": "SepaPayment",
  "payee": {
    "name": "Test_Person",
    "iban": "FI4950009420028730"
  },
  "amountEUR": "4.00"
}

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/v1/sepa-payments can include this authorizationId in the request body. The table below explains the relationship between authorizationId and paymentId.

NameLegend
authorizationIdA value representing a single bundle of payments. Can be reused if several payments are to be authorized simultaneously.
paymentIdA 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 submission) with a GET or DELETE call to /payments-psd2/v1/sepa-payments/{paymentId}.

Examine and revoke authorizations

The authorizationId 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. Authentication and authorization

Authentication and authorization take place between the end user and the auth server of the account servicer. 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,
  "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>
FieldTypeRequiredLegend
typstringtrueType of the token. Always gets value JWT.
algstringtrueThe signing algorithm used. Possible values are RS256 and ES256.
kidstringtrueID 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).
audstringtrueIntended audience of the JWT, i.e. the host URL of the API.
issstringtrueIssuer of the token, i.e. Client ID of the TPP.
response_typestringtrueSpecifies 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_idstringtrueUnique identifier of the client application.
redirect_uristringDefault flow: true, Exemption flow: falseThe address to which the end user wil be redirected after authentication and authorization. The access token or error descriptors will be attached to this uri as query parameters.
scopestringtrueScope 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.
statestringtrueA 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.
noncestringtrueA unique string that is used for protecting against replay attacks. Generated by the Client App.
max_agenumbertrueMaximum allowed age for the authentication, in seconds.
claimsobjecttrueContains information related to the request. The field authorizationId contains the authorizationId obtained while registering intent.
userinfoobjecttrueContains information related to the request. The field authorizationId contains the authorizationId obtained while registering intent.
id_tokenobjecttrueThe contents of this field are similar to userinfo.
acrobjtrueSpecifies 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:

  1. Base64Urlencode the header and body separately. Append the body to the header, separating the two parts with a dot.
  2. 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.
  3. 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 ("=").

Example code for signing JWTs

This code assumes that a file named ssa-signing-key.pem exists in the current directory. In sandbox, developers may use the Registration Helper App, which automatically generates a key with this filename.

import * as fs from 'fs';
import * as jwt from 'jsonwebtoken';

//claims is a valid pre-created JWT body
const asymmetricSign = (claims: object) => {
  const algorithm = 'ES256';
  const signCert = fs.readFileSync(`./ssa-signing-key.pem`, 'ascii');
  const jwtOptions = {
    header: {
      typ: 'JWT',
      kid: 'BSyrDg'
    },
    algorithm
  };
  return jwt.sign(JSON.stringify(claims), signCert, jwtOptions);
};

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 URLencoded.

The redirect will have the following structure:

https://authorize.psd2-sandbox.op.fi/oauth/authorize
?request=<your_JWT_string>
&response_type=code
&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 business of the customer and the auth server. The customer logs in and selects the authorizations they wish to confirm or reject.

Test credentials

The following test credentials are available in our sandbox:

UsernamePasswordKey code / mobile key
8888888111221122
8888888211221122

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 e.g. inspecting the user's session ID.

ID tokens are created and returned on two occasions:

  1. 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 "?").
  2. 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>>
}
FieldTypeLegend
issstring/URIIssuer of the token.
iattimestampToken issuance time as seconds since 1970-01-01T0:0:0Z.
substringThe authorizationId to which the ID token relates to.
acrstringAuthentication Context Class Reference, i.e. the level of authentication achieved. Currently, only urn:openbanking:psd2:sca is supported.
authorizationIdstringThe authorizationId to which the ID token relates to.
audstring/client IDIntended audience of the ID token. WIll contain the Client Id of the Client Application.
noncestringA value originally provided by the TPP in the request, used for protecting against replay attacks.
exptimestampTime of expiry, i.e. the time after which the token is no longer valid.
s_hashstring, case-sensitiveReturned 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_hashstring, case-sensitiveReturned 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_hashstringReturned 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_hashstringReturned 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 authorizationId 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 authorizationId against that received earlier
  • Validate the signature of the ID token
  • Validate rt_hash (refresh token validation)
  • Validate at_hash (access token validation).

The public key for validating ID token signatures is available here.

5. TPP requests an access token for the user

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: mtls-apis.psd2-sandbox.op.fi/oauth/token
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://mtls-apis.psd2-sandbox.op.fi/oauth/token -d 'grant_type=authorization_code&client_id=VxEjWZCQ98ngGN0imOOd&client_secret=WOf1v30GGeJq7MZL6FXs&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,
}
FieldtypeLegend
access_tokenstringThis is the access token. Use as a bearer token in the Authorization header to access protected resources.
refresh_tokenstringCan be used to request additional access tokens. Valid for up to 45 days (Less if the authorization granted is shorter).
id_tokenstringA signed JWT containing information about the authorization. See ID tokens for a full description on the contents and recommended validation procedures for ID tokens.
scopestringA space-separated list of scope names describing the services to which the token grants authorization.
token_typestringToken type. Always has the value "bearer".
expires_innumberThe 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: mtls-apis.psd2-sandbox.op.fi/oauth/token
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 submits the payment(s)

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

/payments-psd2/v1/sepa-payments/{paymentId}/submissions/{submissionId}.

Here, submissionId is a value generated by the TPP for the submission.

7. TPP invokes the /payments endpoint for querying payment status.

The status of each payment can be polled using paymentId.

8. 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

For further details refer to https://www.rfc-editor.org/rfc/rfc7515.html#appendix-F .

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


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 limitations described in this section.

The exemption flow is available both in sandbox and production.

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

Payments Exemption Flow 2020 01 16

  1. The Customer requests to perform a payment that is within the bounds of the exemption flow.
  2. The Client App uses a refresh token (from a previous SCA) to request an access token for the customer (this replaces the Client Credentials Grant of the default authorization flow).
  3. The Client App creates the requested payment using the access token.
  4. The Client creates a request JWT, confirming the reuse of the previous authorization
  5. The Client 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.

2. Client App reuses existing authorization

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: mtls-apis.psd2-sandbox.op.fi
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<REFRESH_TOKEN_FROM_SCA>&scope=payments&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>
cURL
curl -vk --key key.pem --cert client.crt https://mtls-apis.psd2-sandbox.op.fi/oauth/token -d 'grant_type=refresh_token&refresh_token=<REFRESH_TOKEN_FROM_SCA>&scope=payments&client_id=<CLIENT_ID>&client_secret=<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://mtls-apis.psd2-sandbox.op.fi/payments-psd2/v1/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 confirms reuse of existing 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
FieldDifference
response_typeMust be token.
redirect_uriNot required with exemption flow.
scopeMust be payments.
acrThe 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 requrest 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
NameDescription
client_secretThe Client Secret of the application.
grant_typeGrant type. Must be urn:ietf:params:oauth:grant-type:jwt-bearer.
assertionThe JWT request constructed for the exemption flow.
response_typeOauth response type. Must be token.
Example call to the token endpoint with JWT assertion
curl -vk --key key.pem --cert client.crt https://mtls-apis.psd2-sandbox.op.fi/oauth/token -d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<EXEMPTION_JWT>&response_type=token&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=payments'

5. Client App submits the payment

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 PUT https://mtls-apis.psd2-sandbox.op.fi/payments-psd2/v1/sepa-payments/0427a7ba-2c83-4556-9fc9-98eee25c34ee/submissions/111 -H 'x-api-key: <API_KEY>' -H 'Authorization: Bearer <ACCESS_TOKEN>' -H 'Content-Length: 0'