Common Request Headers

In order to successfully send API requests, TPPs must send a set of HTTP headers that allow the bank to check the request's validity. This includes signing the request with a qualified certificate.

Formulate the required headers for the Soldo API in accordance with these formatting rules:

  • Headers are case-insensitive
  • Header fields must be separated by a colon
  • Key-value pairs must be in clear-text string format
  • Denote the end of the header section with an empty field header

For a general review of HTTP 1.1 header formatting, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.

The headers listed in the following table marked "mandatory" are required. All others are optional.

Required Headers
Header Description/Purpose POST Requests GET
Requests
Authorization Passes valid credentials constructed for either Token Authentication (Basic) or JWT Authentication (Bearer) authentication schemes.

Ex: Use the links above for basic and bearer authentication to see the respective format and examples.

Mandatory Mandatory
customer-initiated Boolean. Lets the bank know that the API call was explicitly initiated by the PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both.. Useful in circumnavigating bank restrictions that impose a 4-times-a-day (i.e., the same 24-hour period) access limit on the same AISPClosedAccount Information Service Provider – a TPP authorised to access consumer or business account data from the account holder's financial institutions with the account holder's explicit consent. in accordance with RTS regulationsClosedRegulatory Technical Standard – detailed specifications to achieve the strict security requirements for payment service providers in the EU.. Optional Optional
request-timeout Integer. Sets the number of elapsed seconds until the call is aborted with a DEADLINE_EXCEEDED exception due to no response received. Optional Optional
token-customer-last-logged-time Time when the PSU last logged in with the TPP Optional Optional
token-customer-ip-address PSU's IP address if the PSUClosedPayment Services User – an individual person or legal business entity making use of an Open Banking service as a payee, payer or both. is currently logged in with the TPP.

If the customer IP addressClosedIPv4 addresses are represented in dot-decimal notation, consisting of four decimal numbers, each ranging from 0 to 255, separated by dots, e.g., 172.16.254.1. is supplied (recommended), it is inferred that the PSU is present during the session (i.e., the request is PSU-initiated; adding a "customer-initiated": "true" header makes this explicit).

For AIS calls, if the customer's IP address is not provided in the request, the bank assumes it is a TPP-initiated request and may limit the TPP to 4 TPP-initiated access attempts within a given 24-hour period.

Ex: 172.16.254.1

Optional Optional
token-customer-device-id Obtained by the TPP from details in the user agent information of the PSU.

Ex: 00000000-00000000-01234567-89ABCDEF

Optional Optional
token-customer-user-agent Specifies the user agent for the PSU..

Format: Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion

Ex: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0

Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0

If the PSU is using the TPP's mobile app, make sure the mobile app user-agent string is different than browser-based user-agent strings

Optional Optional
token-json-error Boolean. Converts the error response, if any, to JSON format. See Changing Error Responses to JSON Format. Optional Optional