Digital Signatures

Digital Signatures

In this section we cover the different ways digital signatures are used for Security in the Open Banking API. There are three main uses :

  • Sending authorization requests
    • This applies to all Initiating Parties sending requests to the Open Banking Service.
  • Sending signed requests and responses (iDEAL 2.0 only)
    • This only applies to certain Acquirers in the IDEAL 2.0 service. If not applicable, this section can be skipped.
  • Receiving signed requests and responses (iDEAL 2.0 only)
    • This refers to the Notification requests that the Initiating Party receives from the Open Banking Service.
    • This only applies to certain Acquirers in the IDEAL 2.0 service. If not applicable, this section can be skipped.

Sending authorization requests

On the application level, the Initiating Party is authenticated and authorized by sending a digitally signed request to the POST /token endpoint (see Access Tokens - V1, or Access Tokens - V2). The signature validation allows the Open Banking Service to check the authenticity and integrity of the request. 

This is achieved by applying the "Authorization" scheme as described in https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12 and further detailed below.

The  'Authorization' field consists of the following elements, see also the examples below

  • 'Signature keyId’ =  The thumbprint of the public certificate of the Initiating Party, viewed with the SHA1 algorithm.
  • 'algorithm' = algorithm=”rsa-sha256” or algorithm=”SHA256withRSA”
  • 'headers' = the headers ”app client id date” which are part of the signature, the sequence which they are placed here should also be used in the 'signature'
  • 'signature' = The 'signature' is created with the private key associated with 'keyId' applying the chosen signature 'algorithm'. The string to sign is created by concatenating the lowercased 'headers' field names followed with an ASCII colon `:`, an ASCII space ` `, and the header field value. Leading and trailing optional whitespace (OWS) in the header field value MUST be omitted. If the value is not the last value, then an ASCII newline `\n` is appended. The 'signature' is then created with the private key associated with 'keyId' applying the chosen signature 'algorithm'.

Example: For the request

POST /authorize/token HTTP/1.1
App: IDEAL
Date: Fri, 25 Mar 2022 20:51:35 GMT
Client: idealClient
Id: 434

The concatenated "String to sign" would be:

app: IDEAL
client: idealClient
id: 434
date: Fri, 25 Mar 2022 20:51:35 GMT

The complete 'Authorization' field looks like this:

Authorization: Signature keyId="DCAC7209573D506FC56095B8B23E8555A8F38B29", algorithm="SHA256withRSA", headers="app client id date", signature="guoLSHgl/zGRujqkDnmaWCL8kgCVnDazqkKu7nWU/uAHrS+M9eQsI8ueB4uWgxyPOnZps3vpNgkW1f4aBsdFYLS0jYeup4yhCMN6vis2zfMKxUhZFkjELslQkit9Gwc9pqvcyH0IxUnDLbCQwkiYjf6nGbP1YNfoxVXQpfq6i6CbIXCotLfwH2kbkrnSWwAS5skZY77+znmLDjtP3et2K94C36yPo0EEGqGkQ5xkD7owA7YxzA30xzsvkDvU3hzDzTK5wZmsgVsoyjRvMrokG0HrszUpNTwUtxflukcgs0pH7GuT+JrIpQ55f1dpzULqxeBggnCvD9DRSuKeTakqlw=="

The Initiating Party must upload the used public certificate in the back office portal so that Open Banking Service is able to validate the signature. If the signature can be validated and the sender has a valid subscription, a response containing an access token is returned. 

This access token can be used in all follow-up API requests until it expires. After expiration a new access token must be requested via the POST /token endpoint.

Sending signed requests and responses (iDEAL 2.0 only)

Signing requests and responses could be enforced depending on the Acquirer configuration.

Signing would impact the following cases: 

  • POST /payments API requests 
  • GET /payments/{paymentId}/status API requests 
  • GET /preferences/{id}/ API requests
  • Notification API requests received by the Initiating Party
  • Responses received by the Initiating Party

In this section, we will be looking into signing POST /payments requests and the responses from the Open Banking Service.

If signatures are enforced by the Initiating Party's Acquirer, the following fields will be mandatory in the API requests sent by the Initiating Party to the Open Banking Service:

  • Signature
  • Digest

The Signature 

The digital signing should be done by the Initiating Party by applying the “Signature” scheme as described in https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

This is equivalent to the “Authorization” scheme and the same procedure is followed to generate the signature and header parts but it uses the Signature field instead of the Authorization field.

In order to generate the signature string that is signed with a key, the Initiating Party must use the values of following HTTP header fields:

  • Digest
  • X-Request-ID
  • MessageCreateDateTime

The headers used to generate the signature string also have to appear in the `headers` parameter of the Signature field, as shown below:

headers=”digest x-request-id messagecreatedatetime (request-target)”

To include the HTTP request target in the signature calculation, use the special `(request-target)` header field name. You can generate the header field value by concatenating the lowercased :method, an ASCII space, and the :path.

The (request-target) header field value to be used for the different APIs is:

API(request-target) header field value
POST /paymentspost /xs2a/routingservice/services/ob/pis/v3/payments
GET /payments/{paymentId}/statusget /xs2a/routingservice/services/ob/pis/v3/payments/{paymentId}/status*
GET /preferences/{Psuid}get /xs2a/routingservice/services/ob/pis/v3/preferences/{psuId}*

*The placeholders {paymentId} and {psuId} must be substituted with the values as obtained within the respective flows.

The signature string is created by concatenating the lowercased header field names followed with an ASCII colon `:`, an ASCII space ` `, and the header field value. Leading and trailing optional whitespace (OWS) in the header field value MUST be omitted. If the value is not the last value, then an ASCII newline `\n` is appended.

Example: For the payment request with the following required headers

POST /payments HTTP/1.1
digest: SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q=
x-request-id: 1aad5e0f-02d7-aefb-61e3-6f4d3322cf71
messagecreatedatetime: 2023-03-15T10:07:26.264Z

The concatenated "Signature String" would be:

digest: SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q=
x-request-id: 1aad5e0f-02d7-aefb-61e3-6f4d3322cf71
messagecreatedatetime: 2023-03-15T10:07:26.264Z
(request-target): post /xs2a/routingservice/services/ob/pis/v3/payments

The resulting signature parameter of the Signature field would be: 

signature="N7kFLMMi/2R5hCd1gdO+GYhS70DOLMl+n8hborf42nFuu0HFjreoqU70gvxFWzgTPaWjdmNYY/7sOAUAQWudsM61Vc536XmaOGrrSxOINlH9l9QBk31xZMlJBf/+1+GtPb1BR26PYBjxKDMbN9W7PEVZLCDoObSnVLkvKbkLRWl0U8a39mDkUBu70Jw8yWusDU0g1OVN+5YRfENPNtC2ZnVD80gxih4JoFV6f4WCcX4HXVl229veFNO5joNQyUc7qOkXUGN2g0omgN4iJxVGnzEJ9BCrNe+vK9T25LC0fwSp/W6A9dDfuHQzMZgDJZZKpaX0Gg34i68etmi5oLrM3A=="

The algorithm parameter of the Signature field is:

algorithm=”rsa-sha256” or algorithm=”SHA256withRSA”

The ‘keyId’ parameter of the Signature field is the thumbprint of the used certificate, viewed with the SHA1 algorithm. The private key associated with `keyId` is used to generate a digital signature on the concatenated signature string applying the chosen algorithm. The complete Signature header looks then like this:

Signature: keyId="DCAC7209573D506FC56095B8B23E8555A8F38B29", algorithm="SHA256withRSA", headers="digest x-request-id messagecreatedatetime (request-target)", signature="N7kFLMMi/2R5hCd1gdO+GYhS70DOLMl+n8hborf42nFuu0HFjreoqU70gvxFWzgTPaWjdmNYY/7sOAUAQWudsM61Vc536XmaOGrrSxOINlH9l9QBk31xZMlJBf/+1+GtPb1BR26PYBjxKDMbN9W7PEVZLCDoObSnVLkvKbkLRWl0U8a39mDkUBu70Jw8yWusDU0g1OVN+5YRfENPNtC2ZnVD80gxih4JoFV6f4WCcX4HXVl229veFNO5joNQyUc7qOkXUGN2g0omgN4iJxVGnzEJ9BCrNe+vK9T25LC0fwSp/W6A9dDfuHQzMZgDJZZKpaX0Gg34i68etmi5oLrM3A=="

In order for the Open Banking Service to validate the signature, the Initiating Party must upload the public certificate to the back office portal. Once the signature is confirmed and the iDEAL Subscription is authenticated, the Initiating Party will receive a successful response.

The Digest header

Calculate the Digest header as follows:

  • Step1: Create a SHA-256 hash of the Payload
    • Note-1: if the output is hex-encoded, please make sure to convert it to binary data (convert the hex-encoded string to a byte array)
    • Note-2: payload formatting is important. If the Digest is generated by using an unformatted JSON payload, then please make sure that it matches with an unformatted request body used in the API request.
  • Step 2: Base64-encode the SHA-256 hash
  • Step 3: Prepend 'SHA-256=' to the resulting base64-encoded value

Example payload :

{"PaymentProduct":["IDEAL"],"CommonPaymentData":{"Amount":{"Type":"Fixed","Amount":"10.00","Currency":"EUR"},"RemittanceInformation":"Cookie","RemittanceInformationStructured":{"Reference":"iDEALpurchase21"}},"IDEALPayments":{"UseDebtorToken":false,"FlowType":"Standard"}}

Step 1: The SHA-256 hash of this request body is: 0d426d36fca1659980b9e371b25e2f17281bb285a634290d3da04233249b56ca. (Note: this is a hex-encoded representation)

Step 2: The base64-encoded hash (Note: hex to base64 encoding): DUJtNvyhZZmAueNxsl4vFygbsoWmNCkNPaBCMySbVso=

Step 3: The Digest header value: SHA-256=DUJtNvyhZZmAueNxsl4vFygbsoWmNCkNPaBCMySbVso=

Receiving signed requests and responses (iDEAL 2.0 only)

Receiving signed requests and responses could be enforced depending on the Acquirer configuration. In the event the Acquirer enforces Signatures, the following headers will be present in the API requests and responses received by the Initiating Party: 

  • Signature
  • Digest

The digital signing performed by the Open Banking Service is done by applying the same “Signature” scheme as described above.

A notification request or response from Open Banking Service to the Initiating Party may contain the following headers (Signature and Digest included in the example):

Headers: {Authorization=Bearer iDEAL2.0testnotificationtoken, X-Request-ID=7e04be55-f710-4660-8254-a48d0246d56b, MessageCreateDateTime=2024-01-30T17:03:52.111+01:00, Digest=SHA-256=9CfdR8v5UlVl8YHNnpbO4v6uB/1B0EtWGLtnP7t2iVs=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="v+IzPw8RKwGD3GWgLyuy/4RbA25PVwJxpvzs8QbqfAGLUSvOLhEL9dpQwvZi05DDbC80Z+1H7Kdyh3DumXRdayY7XYnunA05tcirszq1fOmESP5S6iw0It9XoV5u/L8EPTgMvOXYECuDT+zVKDsB0PXRIyfT1p+kS1iKc7kckPvDycVGRYMyfXHATmcrlHY6lSjMuw7WMlBOUo9Ac+dU8AQeqWzpzFjMa2Nd5XZkhd1vyKeVqh5cmWapJ2tZDk4/FwDZnpH3Po9PWKXwX/s+UolR/vlIUcRw+avIhU7L6Qme7JDQDpZlcAgJfj/OpF8ZDlb6yfW32yFFzYnkMyGdYQ==",   Content-Type=application/json}

In order to ensure that the contents of the sent messages are correct and have not been altered during transmission or storage, the Initiating Party can validate the received signature. For the validation of the signature, the Initiating Party can use the public certificate of the Open Banking Service which can be downloaded from the back office portal.

The high-level steps that a Initiating Party needs to take in order to validate the Signatures are:

  1. Digest calculation (as Digest is a part of the Signature)
  2. Signature validation by re-creating the signature string 

The above steps (1) and (2) are detailed below to describe the process behind signature validation. 
These steps are by default followed if standard signature validation libraries are used by the Initiating Party. 

Digest header calculation for Notification requests and API responses 

To verify the digest header, calculate the value and ensure you receive the same value as what is in the header of the Request/Response from the Open Banking Service. This is demonstrated below using a Notification request body. 

{"PaymentProductUsed":"IDEAL","CommonPaymentData":{"PaymentStatus":"Expired","PaymentId":"141110","AspspPaymentId":"0001115682120510","AspspId":"10002","DebtorInformation":{"Name":"Edsger Wybe Dijkstra - Callback","Agent":"ABNANL2AXXX","Account":{"SchemeName":"IBAN","Identification":"NL44RABO0123456789"}}}}

Step 1 : The Open Banking Service always sends unformatted JSON payloads in the Requests/Reponses towards the Initiating Party. However, in case the Initiating Party sees a pretty-printed JSON object (e.g. by viewing logs via a tool), the payload should be converted to an unformatted JSON. All blank spaces should be removed unless they are part of the field value (Example: the debtor name has spaces which can remain).

Step 2 : Create a SHA 256 hash of this payload: b1219370189b7c7d67f64fd6f72168187343d639f3aeada8ea3a2b36e0fac297
Note that this string is hex encoded.

Step 3 : Convert this hex encoding to a base64 encoding : sSGTcBibfH1n9k/W9yFoGHND1jnzrq2o6jorNuD6wpc=

Step 4 : Finally prepend "SHA-256=" to the value. The final value is : SHA-256=sSGTcBibfH1n9k/W9yFoGHND1jnzrq2o6jorNuD6wpc=

This value should match the Digest as sent by the Open Banking Service. 

Signature validation in Notification requests and API responses

The digital signing is done by the Open Banking Service by applying the “Signature” scheme as described in https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12.

In order to verify the signature header, the Initiating Party should recreate the signature with the steps outlined below: 

Re-create signature string

In order to generate the signature string that is signed with a key, the Initiating Party must use the values of HTTP header fields:

  • MessageCreateDateTime
  • X-Request-ID
  • Digest

The headers used to generate the signature string also have to appear in the `headers` parameter of the Signature header, in the fixed order appearing below:

headers=”messagecreatedatetime x-request-id digest”

The signature string is created by concatenating the lowercased HTTP header field names followed with an ASCII colon `:`, an ASCII space ` `, and the HTTP header field value. Leading and trailing optional whitespace (OWS) in the HTTP header field value MUST be omitted. If the value is not the last value, then an ASCII newline `\n` is appended.

Example: For the notification request with the following required headers

POST /notification/status HTTP/1.1
Digest: SHA-256=9CfdR8v5UlVl8YHNnpbO4v6uB/1B0EtWGLtnP7t2iVs=
X-Request-ID: 7e04be55-f710-4660-8254-a48d0246d56b
MessageCreateDateTime: 2024-01-30T17:03:52.111+01:00

The concatenated "Signature String" would be:

messagecreatedatetime: 2024-01-30T17:03:52.111+01:00
x-request-id: 7e04be55-f710-4660-8254-a48d0246d56b
digest: SHA-256=9CfdR8v5UlVl8YHNnpbO4v6uB/1B0EtWGLtnP7t2iVs=

The string to verify is now defined and it can be validated using the public key of the Open Banking Service which can be downloaded from the Open Banking Service GUI.

Validate signature

The signature parameter of the Signature header sent by the Open Banking Service was: 

Base64 encoded signature

signature="v+IzPw8RKwGD3GWgLyuy/4RbA25PVwJxpvzs8QbqfAGLUSvOLhEL9dpQwvZi05DDbC80Z+1H7Kdyh3DumXRdayY7XYnunA05tcirszq1fOmESP5S6iw0It9XoV5u/L8EPTgMvOXYECuDT+zVKDsB0PXRIyfT1p+kS1iKc7kckPvDycVGRYMyfXHATmcrlHY6lSjMuw7WMlBOUo9Ac+dU8AQeqWzpzFjMa2Nd5XZkhd1vyKeVqh5cmWapJ2tZDk4/FwDZnpH3Po9PWKXwX/s+UolR/vlIUcRw+avIhU7L6Qme7JDQDpZlcAgJfj/OpF8ZDlb6yfW32yFFzYnkMyGdYQ=="

The signature algorithm used is also contained in the Signature header: algorithm=”SHA256withRSA”

In order to verify a signature, a server MUST:

  1. Re-create the signature string (see step above)
  2. Hash the signature string with SHA256
  3. Verify the signature with the public key of the Open Banking Service. 
Enable "on this page" menu on doc section
On

Notification Bearer Tokens

Notification Bearer Tokens

Notification Bearer Tokens are sent in the Authorization header of notifications sent from the Open Banking Service to the Initiating Party. Currently two Notification types exist:

  • Status Notification requests
  • Debtor token Callback requests

The Notification Bearer Token can be configured in the back office portal under a specific Subscription. Depending on the subscription one or more options exist: 

  • Static token
  • OAuth Client Credentials (Basic Auth)
  • OAuth Client Credentials (Query Parameters)
  • OAuth Client Credentials (Form Body) 

The 'Static token' does not have a set validity period. 

When receiving the notification request, the Initiating Party should verify that the value of the Notification Bearer Token matches what was set in the Subscription to ensure that the request is sent by Worldline.

Enable "on this page" menu on doc section
On

Access Token - Version 2

Access Token - Version 2

To interact with the Open Banking Service securely, you need to retrieve an access token. Compared to version 1, a version 2 token can be used for multiple services. Via this API JWS tokens are granted by the Central Authentication Service. 

This is done by a POST /auth/realms/{realm}/protocol/openid-connect/token call via the Authorization API. 

You can retrieve a token in 2 ways:

  • With Client Id/Secret: a Standard way to retrieve a token.
  • With a Certificate: This flow is meant to mimic the access token version 1, making migration easier.

Regardless of the chosen method, the token you will receive is the same.

Client Id/Secret based

Step 1 - Get your Client Id/Secret

The Client Id is a combination of the Tenant name and the Initiating Party Id and can be found in the merchant backoffice. More details can be found in the table below, see field 'Client_id'.

The Secret can be retrieved by pressing the 'Generate secret' button in the backoffice portal. The Password is then sent to the mail address of the merchant user. 

Step 2 - Retrieve an access token using Client Id/Secret

Endpoint : POST /token
Base URL: /auth/realms/{realm}/protocol/openid-connect

The parameter {realm} depends on the system you want to request a token for. For QA and Prod environment different values need to be used for {realm}:

  • QA-1: merchant-clients-qa1-tpp
  • QA-2: merchant-clients-qa2-tpp
  • Production: merchant-clients

The tables below explain which fields have to be filled when requesting a token with Client Id/Secret. The response is identical, regardless of the way the token was requested.

Request
Header fieldsMult.TypeDescription
Content-Type1..1String

To identify the media type of the source. Should be filled with "application/x-www-form-urlencoded"

If not provided, the Initiating Party can expect to come across the error "415, Unsupported Media Type".

 

Body fieldsMult.TypeDescription
grant_type1..1StringTo be set to: client_credentials
client_id1..1String

The Id of the client. This Id is constructed by the Tenant’s name and the Initiating Party’s Id provided to the Initiating Party during onboarding. {Tenant name}-{Initiating Party Id}

Example

Worldline-000021

For tokens that should provide access for a given sub Id only, the sub Id can be added to the InitiatingParty Id separated by a colon.

Example

Worldline-000021:17

client_secret1..1StringThe password
scope1..1StringThe list of the services. Any combination of whitespace separated values of AIS PIS IDEAL VOP is allowed. The Open Banking Service checks if you have a valid subscription for the requested service.
Response
Body fieldsMult.TypeDescription
access_token1..1StringJson Web Token to be used in further API calls. The contents of the access_token can be viewed by base64 decoding the text between the dots, or a tool like https://jwt.io/ can be used.
expires_in1..1Integer

Expiration time in seconds, relative to when the token was issued. 

The time the token was issued is stored within the access_token string. Name of the field is 'iat', which is filled with a unix timestamp

refresh_expires_in1..1IntegerThere is no refresh supported for Initiating Party Access Tokens. The field will be filled with: 0
token_type1..1StringType of the token: Bearer
not-before-policy1..1IntegerFilled with a unix timestamp. The token cannot be used before this timestamp. This feature is not used at the moment, the token will be valid immediately. The field will be filled with: 0
scope1..1StringThe list of the services for which the token is valid, it's a comma separated list.

Upon a successful request, the Open Banking Service provides you with an access token, which must be used in all future API interactions, such as POST /payments or GET /preferences, etc. This token should be included in the Authorization header of subsequent requests as follows:

Authorization:Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2l...qaVI-mQ3XeEqDcf4P3OrzMJBiQ

This access token allows the Open Banking Service to validate and authorize your API requests.

Example

Request
grant_type: "client_credentials"
client_id: "EquensWorldline-000021"
client_secret: "testtest"
scope: "VOP"
Response
ResponseCode: 200Headers: {X-Request-ID=2aa0dc88-21dd-4034-a027-1d98123596f1, MessageCreateDateTime=2024-02-08T18:31:38.385Z, Date=Thu, 08 Feb 2024 18:31:38 GMT, Content-Type=application/json;charset=UTF-8}Payload: {
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJnWEpSa0VzdGVHMjVoYnVTU0lOS1ZPZEdGV3B6NkstMlg2MklkVzVOc1BFIn0.eyJleHAiOjE3MjY1MDEzMTIsImlhdCI6MTcyNjUwMTAxMiwianRpIjoiOTU4N2FkYTQtMGI3NC00NjcxLWI5OWItZmU3YjBiMWRkZWQ0IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MjgwL2F1dGgvcmVhbG1zL21lcmNoYW50LWNsaWVudHMiLCJzdWIiOiI0ZDllYmUxNi1kZTkwLTRiMjctYjk4ZC1jNWVmYmE0M2E3NDYiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJXb3JsZGxpbmUtMDAwMDIyIiwiYWNyIjoiMSIsInNjb3BlIjoiQUlTIiwiY2xpZW50SWQiOiJXb3JsZGxpbmUtMDAwMDIyIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMS4xIiwicm9sZXMiOlsiSU5JVFAiXSwiZW52IjoibWVyY2hhbnQtY2xpZW50cyIsImluaXRpYXRpbmdQYXJ0eSI6IjAwMDAyMiIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEuMSIsInRlbmFudCI6IldvcmxkbGluZSJ9.pjro9uLmDcQiqzpIaE2JxpyIbRyVAQ-_CWzoWB0nxzuWXBIzpwWZ__R9RYl6zdNYb2_wBoVNs_bt6mQiTIWn-0oQ-5te5LujLehvCbVJZntK_C9mD80mobEuhDXnJiZCxPVS2hWD4FwYeSpy7mM0Vm3iCMZqtsIERmzm5QFQAY6N1Ym1al_gLIkFgYtaAo1hM-8ZpNCacEB4J8HtBzkOIvNsNegUZ4qdPp7N_Vl2u4pyecxrpNe_VdXPNQftncbQUE9JBOM12jp8G7ncEKW9PH29yKlapKWX_ssMvngGwGSTfZNR-GsQKrcnzef5A_rOjbv8ozUsHeMbLPA4Lh0yDA",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "VOP"
}

The token in the example will grant access to the AIS and PIS service. 

Certificate based

This client credential flow is similar to the way Access Token version 1 is implemented. Making this a good option if you switch from version 1 to version 2 with little effort (## can we tell the exact difference?)

Step 1 - Upload a certificate

Before making the Authorization request, you will first need to upload your public certificate under your merchant in our back office portal. You will get access to the back office portal as part of setting your test environment phase.
The certificate can be self signed and should adhere to the following requirements:

  • minimum leftover validity: more than 1 month
  • maximum validity: 5 years
  • key size/length: minimal length 2048, maximum length : 4096
  • algorithm: SHA - 256 with RSA

STEP 2 - Retrieve an access token using a certificate

Endpoint : POST /token
Base URL: /auth/realms/{realm}/protocol/openid-connect

The parameter {realm} depends on the system you want to request a token for. For QA and Prod environment different values need to be used for {realm}:

  • QA-1: merchant-clients-qa1-tpp
  • QA-2: merchant-clients-qa2-tpp
  • Production: merchant-clients

To request an access token, you must digitally sign the relevant request headers using the private key associated with the certificate that you have uploaded to the back office portal.

Steps on signing the Authorization requests are available within the section Digital Signatures - Sending authorization requests. You should follow the guidelines in order to properly sign the Authorization requests. 

Request
Header fieldsMult.TypeDescription
Content-Type1..1String

To identify the media type of the source.  Should be filled with "application/x-www-form-urlencoded"

If not provided, the Initiating Party can expect to come across the error "415, Unsupported Media Type".

Body fieldsMult.TypeDescription
grant_type1..1StringTo be set to: client_credentials
scope1..1StringThe list of the services. Any combination of whitespace separated values of AIS PIS IDEAL VOP is allowed. The Open Banking Service checks if you have a valid subscription for the requested service.
client_id1..1String

The Id of the client. This Id is constructed by the Tenant’s name and the Initiating Party’s Id provided to the Initiating Party during onboarding. {Tenant name}-{Initiating Party Id}

Example

Worldline-000021

For tokens that should provide access for a given sub Id only, the sub Id can be added to the InitiatingParty Id separated by a colon.

Example

Worldline-000021:17

date1..1Date

Should be filled with the current date.

The following date formats are supported:

1. EEE MMM dd HH:mm:ss zzz yyyy

2. ISO DATE: for example 2011-12-03T10:15:30+01:00

3. RFC 1123: for example Tue, 3 Jun 2008 11:05:30 GMT

signature1..1String

The signature. It contains the header attributes 'app', 'client', 'id' and 'date' signed with the private key of the client.

The signature will be used to sign the authorization request with the private key which corresponds to the certificate provided during the onboarding. 

Structure

Signature keyId=”<thumbprint of certificate>”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”<signature>”

Example

Signature keyId=”58AF4EC5ADD4C4A3F28D3AEFF60656B2F2xxxxxx”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”Abczym2rZF…r5qcvgmA==” 

Refer to the chapter Digital Signatures - Sending authorization requests for more information

Response
Body fieldsMult.TypeDescription
access_token1..1StringJson Web Token to be used in further API calls. The contents of the access_token can be viewed by base64 decoding the text between the dots, or a tool like https://jwt.io/ can be used.
expires_in1..1Integer

Expiration time in seconds, relative to when the token was issued. 

The time the token was issued is stored within the access_token string. Name of the field is 'iat', which is filled with a unix timestamp

refresh_expires_in1..1IntegerThere is no refresh supported for Initiating Party Access Tokens. The field will be filled with: 0
token_type1..1StringType of the token: Bearer
not-before-policy1..1IntegerFilled with a unix timestamp. The token cannot be used before this timestamp. This feature is not used at the moment, the token will be valid immediately. The field will be filled with: 0
scope1..1StringThe list of the services for which the token is valid, it's a comma separated list.

Upon a successful request, the Open Banking Service provides you with an access token, which must be used in all future API interactions, such as POST /payments or GET /preferences, etc. This token should be included in the Authorization header of subsequent requests as follows:

Authorization:Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2l...qaVI-mQ3XeEqDcf4P3OrzMJBiQ

This access token allows the Open Banking Service to validate and authorize your API requests.

Example

Request
Address: https:// https://digitalroutingservice-integration.awltest.de/auth/realms/merchant-clients-qa2-tpp/.well-known/openid-configurationHttpMethod: POST
Headers: {Accept=*/*, Date=2024-02-08T18:31:37.548Z, Authorization=Signature KeyID="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f", algorithm="SHA256withRSA", headers="client_id date", signature= "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJnWEpSa0VzdGVHMjVoYnVTU0lOS1ZPZEdGV3B6NkstMlg2MklkVzVOc1BFIn0.eyJleHAiOjE3MjY1MDAzMzUsImlhdCI6MTcyNjUwMDAzNSwianRpIjoiMDNjMDFiNTQtNGE0Zi00NWI0LWI2OTEtMTMwNWRhN2Y2NWIwIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MjgwL2F1dGgvcmVhbG1zL21lcmNoYW50LWNsaWVudHMiLCJzdWIiOiI0ZDllYmUxNi1kZTkwLTRiMjctYjk4ZC1jNWVmYmE0M2E3NDYiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJXb3JsZGxpbmUtMDAwMDIyIiwiYWNyIjoiMSIsInNjb3BlIjoiQUlTIiwiY2xpZW50SWQiOiJXb3JsZGxpbmUtMDAwMDIyIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMS4xIiwicm9sZXMiOlsiSU5JVFAiXSwiZW52IjoibWVyY2hhbnQtY2xpZW50cyIsImluaXRpYXRpbmdQYXJ0eSI6IjAwMDAyMiIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEuMSIsInRlbmFudCI6IldvcmxkbGluZSJ9.hfTjIfw7_je0TEaI742CEedzNWQSuBJAj1GZd3KxXeCISgbJrGtYpNymu_qPfgGs5PakL33FfeWp7vJ0hlQjmLJ1XknFxYU655AhlE7NT5kmz81Q8hVqAYpuknbRX5wH_zuutTbwpjB5s7lELpyLZjJF9axiLdiwTwBp0dnnC_M_3RUwL866raMLVpvWb2TPDGre2NFp0km79mXLBMMYDPb_P1omTQEocrnhgRHZK9Dtt1sqzJgHCA4AXkXk8lWsVe_kvkfboPmLVQQ0RjAn88h3cSEfr4iZAzwhzdWCOiR5U87Vh2HwzYSI255OqaVI-mQ3XeEqDcf4P3OrzMJBiQ", content-type=application/x-www-form-urlencoded, client_id=Worldline-000081}
Payload:
grant_type: "client_credentials"
scope: "AIS,PIS"
Response
ResponseCode: 200Headers: {X-Request-ID=2aa0dc88-21dd-4034-a027-1d98123596f1, MessageCreateDateTime=2024-02-08T18:31:38.385Z, Date=Thu, 08 Feb 2024 18:31:38 GMT, Content-Type=application/json;charset=UTF-8}Payload: {
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJnWEpSa0VzdGVHMjVoYnVTU0lOS1ZPZEdGV3B6NkstMlg2MklkVzVOc1BFIn0.eyJleHAiOjE3MjY1MDEzMTIsImlhdCI6MTcyNjUwMTAxMiwianRpIjoiOTU4N2FkYTQtMGI3NC00NjcxLWI5OWItZmU3YjBiMWRkZWQ0IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MjgwL2F1dGgvcmVhbG1zL21lcmNoYW50LWNsaWVudHMiLCJzdWIiOiI0ZDllYmUxNi1kZTkwLTRiMjctYjk4ZC1jNWVmYmE0M2E3NDYiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJXb3JsZGxpbmUtMDAwMDIyIiwiYWNyIjoiMSIsInNjb3BlIjoiQUlTIiwiY2xpZW50SWQiOiJXb3JsZGxpbmUtMDAwMDIyIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMS4xIiwicm9sZXMiOlsiSU5JVFAiXSwiZW52IjoibWVyY2hhbnQtY2xpZW50cyIsImluaXRpYXRpbmdQYXJ0eSI6IjAwMDAyMiIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEuMSIsInRlbmFudCI6IldvcmxkbGluZSJ9.pjro9uLmDcQiqzpIaE2JxpyIbRyVAQ-_CWzoWB0nxzuWXBIzpwWZ__R9RYl6zdNYb2_wBoVNs_bt6mQiTIWn-0oQ-5te5LujLehvCbVJZntK_C9mD80mobEuhDXnJiZCxPVS2hWD4FwYeSpy7mM0Vm3iCMZqtsIERmzm5QFQAY6N1Ym1al_gLIkFgYtaAo1hM-8ZpNCacEB4J8HtBzkOIvNsNegUZ4qdPp7N_Vl2u4pyecxrpNe_VdXPNQftncbQUE9JBOM12jp8G7ncEKW9PH29yKlapKWX_ssMvngGwGSTfZNR-GsQKrcnzef5A_rOjbv8ozUsHeMbLPA4Lh0yDA",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "AIS,PIS"
}

The token in the example will grant access to the AIS and PIS service.

Validity of access tokens

Tokens are valid for 5 minutes. If you ask for a new token you will get a new token. Older tokens which are valid can still be used. 

 

API Reference
Enable "on this page" menu on doc section
On

Access Token - Version 1

Access Token - Version 1

To interact with the Open Banking Service securely, you need to retrieve an access token. 

This is done by a POST /token call via the Authorization API. 

STEP 1 - Upload certificate

Before making the Authorization request, you will first need to upload your public certificate under a specific subscription in our back office portal. You will get access to the back office portal as part of setting your test environment phase.
The certificate can be self signed and should adhere to the following requirements:

  • minimum leftover validity: more than 1 month
  • maximum validity:  5 years
  • key size/length: minimal length 2048, maximum length : 4096
  • algorithm: SHA - 256 with RSA

STEP 2 - Retrieve an access token via the Authorization API

Endpoint : POST /token
Base URL: /xs2a/routingservice/services/authorize

To request an access token, you must digitally sign the relevant request headers using the private key associated with the certificate that you have uploaded to the back office portal.

Steps on signing the Authorization requests are available within the section Digital Signatures - Sending authorization requests. You should follow the guidelines in order to properly sign the Authorization requests. 

Important Fields for creating API call for Authorization API

Request

Header fields

Type

Description

Content-Type

required

String

To identify the media type of the source. 

If not provided, the Initiating Party can expect to come across the error "415, Unsupported Media Type".

Authorization

required

String

The signature. It contains the header attributes 'app', 'client', 'id' and 'date' signed with the private key of the client.

The signature will be used to sign the authorization request with the private key which corresponds to the certificate provided during the onboarding. 

Structure

Signature keyId=”<thumbprint of certificate>”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”<signature>”

Example

Signature keyId=”58AF4EC5ADD4C4A3F28D3AEFF60656B2F2xxxxxx”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”Abczym2rZF…r5qcvgmA==” 

Refer to the chapter Digital Signatures - Sending authorization requests for more information

App

required

String

The name of the service. Only PIS, IDEAL or AIS is allowed.

Client

required

String

The name of the client. This name is provided to the Initiating Party during onboarding. The name of the client is created by the Open Banking Service and will be provided to you.

Id

required

String

The combination of Initiating Party ID and sub Id separated by semi column. In case there is no sub id, no semi column should be provided. You can find these IDs in the back office portal. 

Example:

IP=433, subId=5 -> the ID will be 433:5.

IP=434, no subId -> the ID will be 434.

Date

required

Date

Should be filled with the current date.

The following date formats are supported:

1. EEE MMM dd HH:mm:ss zzz yyyy

2. ISO DATE: for example 2011-12-03T10:15:30+01:00

3. RFC 1123: for example Tue, 3 Jun 2008 11:05:30 GMT

Form Data

Mult.

Type

Description

grant_type

1..1

String

To be set to ‘client_credentials’

Response

Body fields

Mult.

Type

Description

access_token

1..1

String

Token to be used in further API calls

token_type

1..1

String

Type of the token: Bearer

expires_in

1..1

Integer

Expiration time in seconds.

Upon a successful request, the Open Banking Service provides you with an access token, which must be used in all future API interactions, such as POST /payments or GET /preferences, etc. This token should be included in the Authorization header of subsequent requests as follows:

Authorization:Bearer 4944daeae6c9115a10dafecbfad4a9c

This access token allows the Open Banking Service to validate and authorize your API requests.

Example: Authorization

Request
Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/authorize/token?grant_type=client_credentials
HttpMethod: POST
Headers: {App=IDEAL, Accept=application/json, Date=2024-02-08T18:31:37.548Z, Authorization=Signature KeyID="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f", algorithm="SHA256withRSA", headers="app client id date", signature= "r0EqeVMfc4au9fq7ZVhOwjfXbMHkf2GShAH/WIQtjMyjl2swlJss10Y0Fjpqt47aLdeBXpG28mVxzPLjwqNHPvnkNPslepJmHzB3W2A6YgXcoiUqFFv+pxzIBmohVoqVEGb5QC4rxTBpAleE178hSzIJrxxbhlCQv/dSAcoI5V1P1M3pU9VqM7vmql8XlB/yXOjmayeXVtB0T93BzqutHokHBwDjxN8ocKlsX40GcFoFjxov9cKoVjlyMZKyfHRkqZ5u1dUkcN+RFeGgJWCcCcaBydXSicK/elbpq55rAgLCTQF4xFldSDPjcrRsswMIYMZmGz0tCycjDV225pGPGg==", content-type=application/x-www-form-urlencoded, Id=000081, Client=Worldline}
Response
ResponseCode: 200
Headers: {X-Request-ID=2aa0dc88-21dd-4034-a027-1d98123596f1, MessageCreateDateTime=2024-02-08T18:31:38.385Z, Date=Thu, 08 Feb 2024 18:31:38 GMT, Content-Type=application/json;charset=UTF-8}
Payload: {
"access_token": "bb00ffd85e0b619a7a9da34df24346f8b309dae54383e5e5481bada22aaa000e",
"token_type": "Bearer",
"expires_in": 3600

 

Validity of access tokens 

As a default, tokens are valid for 60 minutes (3600 seconds). After 60 minutes have elapsed, you will need to request for a new token. 
There is an overlap period in the last 10 minutes (between 50th minute - 60th minute). This means if you were to request a new token between 50th minute to 60th minute, you would receive a new access token. 

However, for those 10 minutes, the previous token would also still be valid. 

Enable "on this page" menu on doc section
On

Transport Level Security

Transport Level Security

On the transport level, all requests to the Open Banking Service, as well as all requests sent by the Open Banking Service must be encrypted using TLS and be made over HTTPS:

  • TLS 1.3 SHOULD be used;
  • TLS 1.2 may be used.
  • Anything below TLS 1.2 must not be used and will be refused by the Open Banking Service.

The TLS authentication method used is one-way, the server's identity is authenticated by the client. That means in requests to Open Banking Service, the Open Banking Service authenticates itself with its certificate and in case of requests from Open Banking Service to the Initiating Party, the Initiating Party authenticates itself with its certificate. Any connection without TLS encryption, such as plain http will be refused.

Mutual TLS optional

Optionally the TLS authentication can be done two-way, that means that both client and server identities are authenticated mutually. That means that both The Open Banking Service and the Initiating Party identities are authenticated, providing a higher level of security.  

 

Enable "on this page" menu on doc section
On

Test Val

Test

What's Changed


List contract fees for an account (Membership fee and Account setup fee models) by external reference

GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/contract-fees
Response:

Changed property data (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

List contract fees for an account (Membership fee and Account setup fee models)

GET /issuers/{issuerId}/contracts/{contractReference}/contract-fees
Response:

Changed property data (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Replace a customer within a consumer contract

POST /issuers/{issuerId}/contracts/{contractReference}/replace-customer
Request body :

Changed property targetCustomer (object ReplaceCustomerInContractRequest.TargetCustomer)

Changed property newCustomer (object ReplaceCustomerInContractRequest.Customer)

Added property correspondenceName (string)

Replace a customer within a consumer contract by external reference

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/replace-customer
Request body :

Changed property targetCustomer (object ReplaceCustomerInContractRequest.TargetCustomer)

Changed property newCustomer (object ReplaceCustomerInContractRequest.Customer)

Added property correspondenceName (string)

Retrieve contract for an account by external reference

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/contract
Response:

Changed property data (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve contract for an account

GET /issuers/{issuerId}/accounts/{accountReference}/contract
Response:

Changed property data (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve contract for a card contract by external reference

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/contract
Response:

Changed property data (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve contract for a card contract

GET /issuers/{issuerId}/card-contracts/{cardContractReference}/contract
Response:

Changed property data (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate employee Accounts

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}
Response:

Changed property data (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate employee accounts by account external reference

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:

Changed property data (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate employee Accounts by contract external reference and account external reference

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:

Changed property data (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate employee Accounts by contract external reference

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}
Response:

Changed property data (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve contract by external reference

GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}
Response:

Changed property data (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve contract

GET /issuers/{issuerId}/contracts/{contractReference}
Response:

Changed property data (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate contract for an account by external reference (beta)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/corporate-contract
Response:

Changed property data (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate contract for an account (beta)

GET /issuers/{issuerId}/accounts/{accountReference}/corporate-contract
Response:

Changed property data (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate contract for a card contract by external reference

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/corporate-contract
Response:

Changed property data (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate contract for a card contract

GET /issuers/{issuerId}/card-contracts/{cardContractReference}/corporate-contract
Response:

Changed property data (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate contract

GET /issuers/{issuerId}/corporate-contracts/{contractReference}
Response:

Changed property data (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve corporate contract by external reference

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}
Response:

Changed property data (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Global Search for Contracts

POST /search-contracts
Response:

Changed property data (array)

Changed items (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Retrieve contracts by criteria

POST /issuers/{issuerId}/contracts/search
Response:

Changed property data (array)

Changed items (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

List contracts for a customer by external reference

GET /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contracts
Response:

Changed property data (array)

Changed items (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

List contracts for a customer

GET /issuers/{issuerId}/customers/{customerReference}/contracts
Response:

Changed property data (array)

Changed items (object Contract)

Changed property contractFees (array)

Changed items (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

List corporate contracts for a company

GET /issuers/{issuerId}/companies/{customerReference}/corporate-contracts
Response:

Changed property data (array)

Changed items (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

List corporate contracts for a company by external reference

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/corporate-contracts
Response:

Changed property data (array)

Changed items (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Search corporate contracts

POST /search-corporate-contracts
Response:

Changed property data (array)

Changed items (object CorporateContract)

Changed property corporateEmployeeAccounts (array)

Changed items (object CorporateEmployeeAccount)

Changed property contractFee (object ContractFee)

Added property membershipFeeAnniversaryDate (string)

Enable "on this page" menu on doc section
On

Product Override

Product Override

Retrieve the product extensions' load balancing

The API allows the parameters of the product extensions' load balancing to be retrieved. The parameters of the load balancing are used when a new card is requested.

The main input fields are:

  • The issuer ID
  • The issuer product external reference for which the detail of the product extensions' load balancing is requested.

API links

Override the product extensions' load balancing

The API allows a list of pre-defined parameters for a product extensions' load balancing to be overridden.

The parameters of the load balancing are used when a new card is requested.

The main input fields are:

  • The issuer ID
  • The issuer product external reference for which the changes are required.
  • The parameters (profiles or thresholds of a product) to be overridden

The parameters of the load balancing can be retrieved using the Retrieve the product extensions' load balancing API.

The overridden parameters should be consistent with the initial product configuration defined in the system (e.g., the profiles to be updated must exist in the system to be found).

API links

Retrieve the card producers' load balancing

The API allows the parameters of the load balancing between card producers to be retrieved.

The main input fields are:

  • The issuer ID
  • The card template reference for which the detail of the card producers' load balancing is requested

API links

Override the card producers' load balancing

The API allows for the replacement of the load balancing parameters between card producers.

The main input fields are:

  • The issuer ID
  • The card template reference for which the changes are requested
  • The parameters to be overridden

The overridden parameters of the card producers' load balancing can be retrieved using the Retrieve the card producers' load balancing API.

API links

Enable "on this page" menu on doc section
On

Release Notes: Recent Update

Release Notes: Recent Update

Version 2.29.1 to 2.30.1

What's New

GET /issuers/{issuerId}/cards/{cardReference}/letters/{letterId}

Retrieve letter for the card (beta)

Retrieve letter for the card by card reference and letter reference

DELETE /issuers/{issuerId}/cards/{cardReference}/letters/{letterId}

Delete a letter for a card (beta)

Delete a letter for a card

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}

Retrieve letter for a card by external reference (beta)

Retrieve letter for the card by card reference and letter reference

DELETE /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}

Delete a letter for a card by external reference (beta)

Delete a letter for a card

POST /issuers/{issuerId}/cards/{cardReference}/letters/{letterId}/validate

Validate a letter for a card (beta)

Validate a letter for a card

POST /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}/validate

Validate a letter for a card by external reference (beta)

Validate a letter for a card

POST /issuers/{issuerId}/cards/{cardReference}/generate-letter

Generate letter for a card (beta)

The API allows to generate a letter for a card. The main input fields requested by the API are: • The issuer ID • The card for which the letter generation is requested: It can be provided by using the card reference or the issuer external card reference • The letter template reference which is used to generate the letter

During letter generation following controls will be performed:

  • If the template parameter is defined with a validator, the validator will be applied on the provided value.
  • If the template parameter is a list (display type = list), the system will check that the provided value belongs to the list.
  • If the template parameter is not modifiable, the system will check that the provided value is equal to dynamically computed value.
  • If the value is defined as invalid, the system will check that the provided value is not equal to dynamically computed value.
  • If the template is configured with a validator (xsd file for instance), the validator will be applied on the generated letter.
  • If the value is not provided in input, the value dynamically computed by the system will be used.
POST /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/generate-letter

Generate letter for a card by external reference (beta)

The API allows to generate a letter for a card. The main input fields requested by the API are: • The issuer ID • The card for which the letter generation is requested: It can be provided by using the card reference or the issuer external card reference • The letter template reference which is used to generate the letter

During letter generation following controls will be performed:

  • If the template parameter is defined with a validator, the validator will be applied on the provided value.
  • If the template parameter is a list (display type = list), the system will check that the provided value belongs to the list.
  • If the template parameter is not modifiable, the system will check that the provided value is equal to dynamically computed value.
  • If the value is defined as invalid, the system will check that the provided value is not equal to dynamically computed value.
  • If the template is configured with a validator (xsd file for instance), the validator will be applied on the generated letter.
  • If the value is not provided in input, the value dynamically computed by the system will be used.
GET /issuers/{issuerId}/cards/{cardReference}/prefilled-letter-templates/{letterTemplateReference}

Get parameters for the defined letter templates (beta)

Get parameters for the defined letter templates by card reference

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/prefilled-letter-templates/{letterTemplateReference}

Get parameters for the defined letter templates by external reference (beta)

Get parameters for the defined letter templates by card reference

GET /issuers/{issuerId}/cards/letter-templates

List of available letter templates for cards (beta)

List of available letter templates for cards

GET /issuers/{issuerId}/cards/letter-templates/{letterTemplateReference}

Retrieve a specific letter template (beta)

Retrieve a specific letter template

POST /issuers/{issuerId}/cards/{cardReference}/advise-product-extension

Advice a product extension for a card (beta)

This API is used to get the product extension for a card replacement depending on the configured algorithm. The main input fields are: • The issuer ID • The card for which the advice is requested: It can be provided by using the card reference or the issuer card external reference. The API returns the product extension advised for the card replacement and also the current product extension of the card.

POST /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/advise-product-extension

Advice a product extension for a card by external reference (beta)

This API is used to get the product extension for a card replacement depending on the configured algorithm. The main input fields are: • The issuer ID • The card for which the advice is requested: It can be provided by using the card reference or the issuer card external reference. The API returns the product extension advised for the card replacement and also the current product extension of the card.

POST /issuers/{issuerId}/contracts/advise-product-extension

Advice a product extension (beta)

This API is used to get the product extension for a card creation depending on the configured algorithm. It can be used for the first card or additional card. The main input fields are:

  • The issuer ID
  • The issuer product external reference for which the advice is requested. The API returns the product extension advised for the card creation.
GET /issuers/{issuerId}/products/external-products/{issuerProductExternalReference}/product-extension-balancing

Retrieve the product extensions' load balancing by issuer product external reference (beta)

The API allows the parameters of the product extensions' load balancing to be retrieved. The parameters of the load balancing are used when a new card is requested. The main input fields are:

  • The issuer ID
  • The issuer product external reference for which the detail of the product extensions' load balancing is requested.
PATCH /issuers/{issuerId}/products/external-products/{issuerProductExternalReference}/product-extension-balancing

Override the product extensions' load balancing by issuer product external reference (beta)

The API allows a list of pre-defined parameters for a product extensions' load balancing to be overridden. The parameters of the load balancing are used when a new card is requested. The main input fields are:

  • The issuer ID
  • The issuer product external reference for which the changes are required
  • The parameters (profiles or thresholds of a product) to be overridden

The parameters of the load balancing can be retrieved using the Retrieve the product extensions' load balancing API. The overridden parameters should be consistent with the initial product configuration defined in the system (e.g., the profiles to be updated must exist in the system to be found).

GET /issuers/{issuerId}/card-products/{cardTemplateReference}/card-producer-balancing

Retrieve the card producers' load balancing (beta)

The API allows the parameters of the load balancing between card producers to be retrieved. The main input field is:

  • The issuer ID
  • The card template reference for which the detail of the card producers' load balancing is requested.
PATCH /issuers/{issuerId}/card-products/{cardTemplateReference}/card-producer-balancing

Override the card producers' load balancing (beta)

The API allows for the replacement of the load balancing parameters between card producers. The main input fields are:

  • The issuer ID
  • The card template reference for which the changes are requested
  • The parameters to be overridden

The overridden parameters of the card producers' load balancing can be retrieved using the Retrieve the card producers' load balancing API.

 

What's Changed

POST /search-transactions
Request body :

Added property cardIdentifier (object)

Added property accountIdentifier (object)

POST /issuers/{issuerId}/corporate-contracts/{contractReference}/add-corporate-contract-entity
Request body :

Changed property addCorporateContractEntity (object CreateCorporateContractRequest.AddCorporateContractEntity)

Changed property corporateContractEntityAccounts (array)

Changed items (object CreateCorporateContractRequest.CorporateContractEntityAccount)

Changed property account (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

POST /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/add-corporate-contract-entity
Request body :

Changed property addCorporateContractEntity (object CreateCorporateContractRequest.AddCorporateContractEntity)

Changed property corporateContractEntityAccounts (array)

Changed items (object CreateCorporateContractRequest.CorporateContractEntityAccount)

Changed property account (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

POST /issuers/{issuerId}/corporate-contracts/{contractReference}/add-corporate-employee-cards-accounts
Request body :

Changed property addCorporateEmployeeCardsAndAccounts (object CreateCorporateContractRequest.AddCorporateEmployeeCardsAndAccounts)

Changed property corporateEmployeeAccounts (array)

Changed items (object CreateCorporateContractRequest.CorporateEmployeeAccount)

Changed property account (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

POST /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/add-corporate-employee-cards-accounts
Request body :

Changed property addCorporateEmployeeCardsAndAccounts (object CreateCorporateContractRequest.AddCorporateEmployeeCardsAndAccounts)

Changed property corporateEmployeeAccounts (array)

Changed items (object CreateCorporateContractRequest.CorporateEmployeeAccount)

Changed property account (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

POST /issuers/{issuerId}/corporate-contracts/{contractReference}/add-virtual-cards-accounts-service
Request body :

Changed property addCorporateVcaServiceCardsAndAccounts (object CreateCorporateContractRequest.AddCorporateVcaServiceCardsAndAccounts)

Changed property corporateEmployeeAccounts (array)

Changed items (object CreateCorporateContractRequest.CorporateEmployeeAccount)

Changed property account (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

POST /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/add-virtual-cards-accounts-service
Request body :

Changed property addCorporateVcaServiceCardsAndAccounts (object CreateCorporateContractRequest.AddCorporateVcaServiceCardsAndAccounts)

Changed property corporateEmployeeAccounts (array)

Changed items (object CreateCorporateContractRequest.CorporateEmployeeAccount)

Changed property account (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

POST /issuers/{issuerId}/corporate-contracts/create-corporate-contract
Request body :

Changed property corporateContract (object CreateCorporateContractRequest.Contract)

Changed property corporateContractRootEntity (object CreateCorporateContractRequest.CorporateContractRootEntity)

Changed property rootAccount (object CreateCorporateContractRequest.Account)

Changed property sepaMandate (object CreateCorporateContractRequest.SepaMandate)

Changed property debtorPostalAddress (string -> object)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last
Response:

Changed property data (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/next
Response:

Changed property data (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}
Response:

Changed property data (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements/last
Response:

Changed property data (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements/next
Response:

Changed property data (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}
Response:

Changed property data (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/credit-transfers/{endToEndId}
Parameters:

Added: embed in query

Response:

Changed property data (object CreditTransfer)

Added property statusHistory (array)

GET /issuers/{issuerId}/direct-debits/{endToEndId}
Parameters:

Added: embed in query

Response:

Changed property data (object DirectDebit)

Added property statusHistory (array)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/credit-transfers
Response:

Changed property data (array)

Changed items (object CreditTransfer)

Added property statusHistory (array)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/direct-debits
Response:

Changed property data (array)

Changed items (object DirectDebit)

Added property statusHistory (array)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations/{operationId}
Response:

Changed property data (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements
Response:

Changed property data (array)

Changed items (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

POST /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/inquire-operation
Response:

Changed property data (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/credit-transfers
Response:

Changed property data (array)

Changed items (object CreditTransfer)

Added property statusHistory (array)

GET /issuers/{issuerId}/accounts/{accountReference}/direct-debits
Response:

Changed property data (array)

Changed items (object DirectDebit)

Added property statusHistory (array)

GET /issuers/{issuerId}/accounts/{accountReference}/operations/{operationId}
Response:

Changed property data (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements
Response:

Changed property data (array)

Changed items (object Statement)

Changed property reprintHistory (array)

Changed items (object ReprintHistory)

Added property origin (string)

Added property username (string)

POST /issuers/{issuerId}/accounts/{accountReference}/inquire-operation
Response:

Changed property data (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/next/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements/last/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements/next/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

GET /issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}/operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

POST /search-operations
Response:

Changed property data (array)

Changed items (object Operation)

Added property origin (string)

Added property username (string)

 

What's Deprecated

POST /issuers/{issuerId}/contracts/brand-advice

Get a brand selection advice (beta)

This API allows getting an advice on which brand to select for a card creation (either first card along new contract, additional card or replacement card). This is applicable for products on which brand selection is configured. The API returns the product extension for the advised card brand

GET /issuers/{issuerId}/contracts/brand-advice-config/{issuerProductExternalReference}

Retrieve brand advice algorithm configuration by issuer product external reference (beta)

The API allows the brand advice configuration to be retrieved. The main input fields are:

  • The issuer ID
  • The issuer product external reference for which the configuration details are requested.
PATCH /issuers/{issuerId}/contracts/brand-advice-config/{issuerProductExternalReference}

Update brand advice algorithm configuration by issuer product external reference (beta)

The API allows a list of pre-defined parameters (attributes) of a brand advice configuration to be updated. The main input fields are:

  • The issuer ID
  • The issuer product external reference for which configuration updates are required.
  • Parameters to be updated

The brand advice configuration parameters can be retrieved using the Retrieve brand advice detail API. The updated parameters should be consistent with the initial product configuration defined in the system (e.g., the profiles to be updated must exist in the system to be found).

 

Enable "on this page" menu on doc section
On