Menu Close
Developer Portal

Signature Setup

All API methods (except for OAuth2 Meta Data and OAuth2 Authorization request) mandate the use of a signature.

XS2A Interface uses the signature setup described in the NextGenPSD2 framework from the Berlin Group implementation guidelines. For more information, please visit https://www.berlin-group.org/nextgenpsd2-downloads (opens in new window)

When a signature is mandated, the following headers of the HTTP-request need to be part of the signature:

Header Description
(request-target) This field contains the HTTP-method (in lowercase) and the path including the query of the request. Example value for a HTTP-POST request to /api/v1/payments/sepa-credit-transfers?someQuery=value:
post: /api/v1/payments/sepa-credit-transfers?someQuery=value
Date This field contains the date of the request
Example value:
Fri, 21 Dec 2018 15:53:06 GMT
Digest This field contains the digest of the body of the request. If the body is empty or not present e.g. for a GET request, it contains the digest of an empty string. If the body contains a file stream of a bulk payment, it contains the digest of the content of the first file. If it is an XML file, it will be the digest of the XML content. If it is a ZIP file, it will be the digest of the ZIP file. Note that for bulk payments, only 1 file is supported. There are two supported hashing algorithms: SHA-256 and SHA-512. Find below an example of a body digest for an empty string:
SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Signature This field contains the signature of the request. The signature field is composed of multiple properties, known as:
  • keyId
    This property contains the serialnumber (SN) and the full Distinguished Name (CA) of the Certification Authority having produced the signature certificate provided in the header TPP-Signature-Certificate. Find an example of the value for keyId below:
    "SN=3F4129D95540B5E800,CA=CN=xs2a_sandbox_bngbank_client_signing, E=klantenservice@bngbank.nl, O=BNG Bank, OU=API XS2A Sandbox, C=NL, S=South-Holland, L=The Hague, OID.2.5.4.97=PSDNL-AUT-SANDBOX"
  • algorithm
    This property contains the algorithm that was used to generate the signature. The supported algorithms are SHA-256 (notations: sha256RSA and rsa-sha256) and SHA-512 (notations: sha512RSA and rsa-sha512) and full distinguished name of the signature certificate provided in the header TPP-Signature-Certificate.
  • headers
    This property contains a list of the HTTP headers included when generating the signature. If specified, it should be a lowercased, quoted list of HTTP header fields, separated by a single space character. Note that the list order is important, and MUST be specified in the order the HTTP header field-value pairs are concatenated together during signing. The following fields must be included if send in the request: digest, x-request-id, psu-id, psu-corporate-id. The following fields are mandatory: digest and x-request-id.
    Find an example of the value for headers below:
    "digest x-request-id"
  • signature
    This property contains the actual signature.
    Find below a list of steps to get to the signature:
    • Consider the following request:
      {
"method": "POST",
"uri": "/api/v1/payments/sepa-credit-transfers?someQuery=value",
"headers": {
"Content-Type": "application/json",
"Date": "Fri, 21 Dec 2018 15:53:06 GMT",
"X-Request-ID": "2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329",
"PSU-ID": "1234",
"PSU-ID-Type": "customer",
"PSU-Corporate-ID": "GEMALS",
"PSU-Corporate-ID-Type": "GEM",
"PSU-IP-Address": "123.12.12.12",
"PSU-User-Agent": "Chrome OS",
"PSU-Geo-Location": "51.20,4.2",
"Accept": "application/json",
},
"body": "{\"debtorAccount\":{\"iban\":\"NL34BNGT5532530633\"},\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"10.11\"},\"creditorAccount\":{\"iban\":\"NL77BNGT2034202452\"},\"creditorName\":\"A. Hoogland\",\"creditorAddress\":{\"streetName\":\"Bernardstraat 12\",\"townName\":\"Den Haag\",\"postcode\":\"1234AB\",\"country\":\"NL\"},\"remittanceInformationStructured\":{\"reference\":\"6000000178319454\"},\"requestedExecutionDate\":\"2021-01-25\"}"
}
    • The digest of the body is:
      SHA-256=+OQG7ny0jOidFJT0CMK/2G2ens8da81XuKqrROEF814=
    • The signing string is (because the psu-id, psu-corporate-id are send in the request and the (request-target), date, digest and x-request-id are mandatory):
      (request-target): post /api/v1/payments/sepa-credit-transfers?someQuery=value\n
date: Fri, 21 Dec 2018 15:53:06 GMT\n
digest: SHA-256=+OQG7ny0jOidFJT0CMK/2G2ens8da81XuKqrROEF814=\n
x-request-id: 2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329\n
psu-id: 1234\n
psu-corporate-id: GEMALS
    • The signature will be (when using the sandbox signing certificate):
      keyId=\"SN=3F4129D95540B5E800,CA=CN=xs2a_sandbox_bngbank_client_signing, E=klantenservice@bngbank.nl, O=BNG Bank, OU=API XS2A Sandbox, C=NL, S=South-Holland, L=The Hague, OID.2.5.4.97=PSDNL-AUT-SANDBOX\",algorithm=\"sha256RSA\",headers=\"(request-target) date digest x-request-id psu-id psu-corporate-id\",signature=\"jdR/2Okenu1lrhoAzds9MyQ2Lfn7nGxCXnsc8AOIwkUH1esjm2YTLWzjtJ/YrsvqRq/4rlte7jyOn5GeGkpqTu8YRBvbs2mkVVjlF1Vhfhq26fk8ZsKmK7Ot/Ea32ETk4zzeEUHoBK9KhwLeOjOf9irpR1pIym6xlPBNqtznM/jpXYeWL5XQe2kw+RhUK1NxXDs1m56phUfqJyFZkw+szy1f1Nsfw5wnfjbAocHGB8sF1VhKb2GePBlp7w/TWoNaO1LO8UZ6tMuTeCHSzLqJDaa3AeI+bdYGnPar5m2PeEH1uFDm/FHxsw3AR0fpws9cPQ+6ev68aOZQUzxsuEC6JVaLN6ruU7CZhCb6XOo01ydyiOZ507nEGKV5kjBUzMUdqxpDTherCBSxsNlOaRMYnXaTxBSUl1bvpBNFBKf3Jy1HABR0k/TE8q5Gr5Cy9ueQf1iIw8WPenvCErRrshj4LJvdhuW97a8vgImq1i4fOXUKDudmjsJM/l1bRQwgHlzZwgrnhxbZ/TUdX+0AoJqEMQTdw65k0Nc3dAXxKXdloDKbXdvWFIrWuUC2qU9KEXyoc4uo9AvQW70IflQ4EQYL6F6c0X1apSjO1LM360dx91V9lPcX+m8C7zOsnO8hr+czWpRape23sk2mZDG89dN1RMTBOIpTKiqCs9y3JDXC6fk=\"
TPP-Signature-Certificate This field contains the TPP signature certificate in PEM format used to generate the signature. Find below an example of the sandbox signature certificate in PEM format:
-----BEGIN CERTIFICATE-----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-----END CERTIFICATE-----

The signed request looks as follows:

{
"method": "POST",
"uri": "/api/v1/payments/sepa-credit-transfers?someQuery=value",
"headers": {
"Content-Type": "application/json",
"Date": "Fri, 21 Dec 2018 15:53:06 GMT",
"X-Request-ID": "2ca1b6b4-82b3-4fe3-a7ea-9ccae9700329",
"PSU-ID": "1234",
"PSU-ID-Type": "customer",
"PSU-Corporate-ID": "GEMALS",
"PSU-Corporate-ID-Type": "GEM",
"PSU-IP-Address": "123.12.12.12",
"PSU-User-Agent": "Chrome OS",
"PSU-Geo-Location": "51.20,4.2",
"Accept": "application/json",
"Digest": "SHA-256=+OQG7ny0jOidFJT0CMK/2G2ens8da81XuKqrROEF814=",
"Signature": "keyId=\"SN=3F4129D95540B5E800,CA=CN=xs2a_sandbox_bngbank_client_signing, E=klantenservice@bngbank.nl, O=BNG Bank, OU=API XS2A Sandbox, C=NL, S=South-Holland, L=The Hague, OID.2.5.4.97=PSDNL-AUT-SANDBOX\",algorithm=\"sha256RSA\",headers=\"(request-target) date digest x-request-id psu-id psu-corporate-id\",signature=\"jdR/2Okenu1lrhoAzds9MyQ2Lfn7nGxCXnsc8AOIwkUH1esjm2YTLWzjtJ/YrsvqRq/4rlte7jyOn5GeGkpqTu8YRBvbs2mkVVjlF1Vhfhq26fk8ZsKmK7Ot/Ea32ETk4zzeEUHoBK9KhwLeOjOf9irpR1pIym6xlPBNqtznM/jpXYeWL5XQe2kw+RhUK1NxXDs1m56phUfqJyFZkw+szy1f1Nsfw5wnfjbAocHGB8sF1VhKb2GePBlp7w/TWoNaO1LO8UZ6tMuTeCHSzLqJDaa3AeI+bdYGnPar5m2PeEH1uFDm/FHxsw3AR0fpws9cPQ+6ev68aOZQUzxsuEC6JVaLN6ruU7CZhCb6XOo01ydyiOZ507nEGKV5kjBUzMUdqxpDTherCBSxsNlOaRMYnXaTxBSUl1bvpBNFBKf3Jy1HABR0k/TE8q5Gr5Cy9ueQf1iIw8WPenvCErRrshj4LJvdhuW97a8vgImq1i4fOXUKDudmjsJM/l1bRQwgHlzZwgrnhxbZ/TUdX+0AoJqEMQTdw65k0Nc3dAXxKXdloDKbXdvWFIrWuUC2qU9KEXyoc4uo9AvQW70IflQ4EQYL6F6c0X1apSjO1LM360dx91V9lPcX+m8C7zOsnO8hr+czWpRape23sk2mZDG89dN1RMTBOIpTKiqCs9y3JDXC6fk=\"",
"TPP-Signature-Certificate": "-----BEGIN CERTIFICATE-----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-----END CERTIFICATE-----"
},
"body": "{\"debtorAccount\":{\"iban\":\"NL34BNGT5532530633\"},\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"10.11\"},\"creditorAccount\":{\"iban\":\"NL77BNGT2034202452\"},\"creditorName\":\"A. Hoogland\",\"creditorAddress\":{\"streetName\":\"Bernardstraat 12\",\"townName\":\"Den Haag\",\"postcode\":\"1234AB\",\"country\":\"NL\"},\"remittanceInformationStructured\":{\"reference\":\"6000000178319454\"},\"requestedExecutionDate\":\"2021-01-25\"}"
}