For connecting to iDEAL Hub Direct Connection APIs, Merchant/CPSPs need:

1. a certificate used for message signing, issued by Currence iDEAL

2. a short lived iDEAL access token, issued by Acquirer

3. an mTLS client certificate, issued by Currence iDEAL

1. JWS - Signing and validation

In the messaging between the iDEAL Hub and any connecting party, all parties authenticate (application level) by providing the signature in the signature header using JSON Web Signatures (JWS). The use of JWS serves as a mechanism for authentication and guarantees the integrity of all requests that are sent to and from iDEAL. The following specifications apply:

For requests and responses to iDEAL

• The JWS MUST be included in all API requests and responses using a signature header.

  • The only exceptions are the response to the callback APIs (transaction-callback, user-token-callback and qr-callback). No signature needs to be provided in the response of these callbacks.

• All requests and responses to the iDEAL Hub MUST be signed using a Detached JWS Signature.

• Merchants/CPSPs MUST provide the certificate used for signing in JSON Web Key (JWK) format as part of JWS in each request. Only the leaf certificate must be included in the x5c parameters of the JWK.

• The signing certificates used by Merchants/CPSPs MUST be issued by Currence. These certificates can be requested via your Acquirer using a CSR. See below section on CSR requirements for more details.

For requests and responses from iDEAL

• All requests and responses from iDEAL MUST be authenticated by verifying signatures. This includes the body, path and certain headers of each request/response.

• For verifying the signatures, iDEAL shares a JSON Web Key Set (JWKS) through a publicly hosted URL (see below for for the URLs).

  • For ease of key exchange, the Merchant/CPSP should fetch the JWKS from the specified URL frequently (at least every 1 hour) and cache the latest data.

• Merchants/CPSP MUST verify the signature in messages from iDEAL Hub by validating the used JWK against the ones shared on the JWKS URL.

  • The JWK used for signature verification will be identified by the Key Id (kid) which, for messages coming from iDEAL, is part of the JSON Object Signing and Encryption (JOSE) Header of the JWS

  • The kid MUST NOT be hardcoded in any way. iDEAL may use different Keys for signing each response, therefore it is important to specifically use the kid in the headers to fetch the right public key from JWKS.

• After fetching the iDEAL JWKS data from iDEAL, each party MUST perform the following validation steps before it can trust and use the X509 certificates:

  • The iDEAL JWKS URL is served with a valid TLS certificate

  • The X509 certificates in the JWKS data must have valid data:

    1. Type is Organization Validation (OV) (the certificate has at least one of its policy OIDs on 2.23.140.1.2.2)

    2. Validity must not be in the past or future

    3. countryName (C) MUST match ‘LU’

    4. organizationName MUST be ‘Payconiq International S.A.’

    5. Either one of

       • localityName (L) MUST be 'Luxembourg'

       • stateOrProvinceName (ST/S) MUST be 'Luxembourg'

  • In line with the RFC on JWKS, each leaf certificate (first position in the x5c property in each JWK),
    must be signed with the next one, and so on, until trust can be validated against the trusted CA list (see Trusted CA list ).

  The certificate must not be pinned; static trust is derived as described above. Pinning certificates or public keys will brake dynamic rotation of certificates.

2. iDEAL Access Token

Merchants/CPSPs must provide an iDEAL Access Token with every request to the iDEAL Hub. This JWT token is issued and signed by their Acquirer, and contains information such as validity period and creditor details. The iDEAL Hub will validate the integrity of the Access Token using the Acquirer’s certificate. In the API specifications, the token is referred to as JWT Access Token.

• The iDEAL Access Token:

  • serves as an extra level of authentication by including the domain of the Merchant/CPSP in its contents. The iDEAL Hub validates that the domain provided by the Acquirer in the Access Token matches with the domain of the provided Merchant/CPSP certificate.

  • serves as authorization by the Acquirer for the Merchant/CPSP to initiate transactions with the iDEAL Hub.

  • guarantees the integrity and validity of the creditor details of the Merchant/CPSP by including them in the signed token payload.

• The Acquirer regularly provides the signed iDEAL Access Token to the Merchant/CPSP.

  • It is up to the Acquirer and Merchant/CPSP to define how the token is exchanged. An automated process is highly recommended.

• The Merchant/CPSP shares the iDEAL Access Token with the iDEAL Hub in the Authorization header of every request.

• The iDEAL Hub verifies the signature of the iDEAL Access Token using the Acquirer’s certificate and checks the validity time.

  • The Acquirer is in control of the token validity time. The maximum validity period is 24 hours.

Token structure

The Access Token is structured as follows:

base64URLEncode(Header).base64URLEncode(Payload).base64URLEncode(Signature)

Header

Token specifications

For the payload of the Access Token, the following detailed specifications apply:

• It is up to the Acquirer to determine the Access Token expiration time. The Access Token expiration time MUST NOT be later than 24 hours after the Access Token creation time (i.e. tokens have a maximum validity period of 24 hours)

• In case of scope:Merchant the mcc MUST be provided in the Access Token

• In case of scope:cPSP the mcc MUST NOT be provided in the Access Token and the cpspSchemeId MUST be provided in the Access Token

• Any subCreditor details (if applicable) are not included in the Access Token, as these will be provided by the Merchant / CPSP in the transaction initiation

Token exchange

It is up to the Acquirer to define the process and technical interface for exchanging the iDEAL Access Token with their Merchants / CPSPs. Since tokens must be exchanged regularly (at least once every 24 hours), an automated process is highly recommended.

3. Establishing Secure Connection using mTLS

General message encryption requirements

All requests to and from the iDEAL Hub 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 nor supported by all parties.

• For requests to the iDEAL Hub (so for iDEAL - Merchant/CPSP API) the TLS authentication method used is two-way (mTLS), where both the connecting party validates the iDEAL Hub and the Hub validates the connecting party, to ensure that it receives data from the intended system.

• For requests from the iDEAL Hub to connecting parties (so for Merchant/CPSP Callback API), the TLS authentication method used can be either one-way or two-way using mTLS. More information is provided in the next section on mTLS.

• All parties MUST refuse any connections without TLS encryption, such as plain HTTP.

mTLS

For requests to iDEAL (calls to iDEAL - Merchant/CPSP API )

• Merchants/CPSPs MUST be able to support mTLS (TLS with Mutual Authentication).

• Acquirers request an mTLS certificate with iDEAL on behalf of the Merchant/CPSP via a Certificate Signing Request (CSR) and must (securely) share this certificate with the Merchant/CPSP.

• See below section on Security for Direct Connection | CSR requirements

For requests from iDEAL (calls to Merchant/CPSP Callback API )

• Merchants/CPSPs MAY whitelist IP addresses of iDEAL Hub to ensure that they receive data from the intended system. iDEAL offers a fixed list of IP addresses for both the Sandbox and Production Environment.

  • See “Connection and Security info” below for IP addresses used by iDEAL Hub for callbacks

• Merchants/CPSPs MAY ask for a client certificate (mTLS) to ensure that they receive data from the intended system.

  • See “Connection and Security info” below for client certificate details that can be used for validation

• Merchants/CPSPs MUST do one of the above and SHOULD do both.

CSR requirements

To request an iDEAL issued certificate (either mTLS client certificate or Signing certificate), the Merchant/CPSP must provide a Certificate Signing Request (CSR) to its Acquirer, who can use this as input for requesting a certificate with iDEAL. The CSR has the following specifications:

• The Distinguished Name (DN). The DN (or Subject) has to match with the official/legal details of the Merchant/CPSP that submitted the CSR. The following fields should be filled out:

  • CN: CommonName

  • O: Organization

  • OU: OrganizationalUnit

  • L: Locality

  • S: StateOrProvinceName

  • C: CountryName

  • EMAIL: EmailAddress (optional)

• The Public Key Algorithm: field needs to be “id-ecPublicKey” or “rsaEncryption” (only for mTLS client certificates with with RSA)

• The CSR contains “-----BEGIN CERTIFICATE REQUEST-----“, “-----END CERTIFICATE REQUEST-----” blocks and it has new line characters after every 64 characters.

• The CSR must be generated by using one of the Supported Algorithms:

Connection and Security info

Host names

• Acceptance (EXT): https://merchant-cpsp-mtls.ext.idealapi.nl/v2

• Production (PROD): https://merchant-cpsp-mtls.idealapi.nl/v2

JWKS URLs

• Acceptance (EXT): https://ext.idealapi.nl/acquirer-certificates

• Production (PROD): https://idealapi.nl/acquirer-certificates

IP addresses

• Acceptance: (EXT): 3.124.104.48 , 52.59.104.179

• Production (PROD): 35.157.56.77, 35.157.143.122, 3.64.143.99, 99.81.182.17, 34.251.231.175, 54.155.63.1, 15.188.142.37, 35.180.183.3, 13.36.6.41

iDEAL mTLS client certificate details (can be used for validation)

• CommonName used in iDEAL mTLS client certificate (for callbacks)

  • EXT: mtls.ext.idealapi.nl

    • Root Certificate: AAACertificateServices

  • PROD: acquirer.mtls.idealapi.nl

    • Root Certificate: R5 GlobalSign Root Certificate