How to use mutual TLS

Rabobank protects its APIs with an extra layer of security. Clients or apps that want to interact with our mutual TLS enabled APIs should have an X-509 certificate. The traffic is encrypted over TLS.

To interact with mutual TLS protected APIs, you should follow the below listed steps:

  1. Get an X.509 certificate.
  2. Register the certificate on the Rabobank Developer Portal.
  3. Configure your client software to use the certificate during the TLS handshake.

Step 1: Get an X-509 certificate

Use the following certificates based on your API:

  • PSD2 - An eIDAS QSEAL certificate issued by the Qualified Trust Service Provider of your choice.
  • Premium - An EV SSL certificate for transport and an EV SSL signing certificate for signing messages. 
    • Rabobank accepts:
      • EV SSL certificates from the certificate issuers listed in the Mozilla CA Certificate report.
      • X.509 format
      • RSA: key length should be at least 2048-bit
      • Certificate should be valid for a maximum of one year.

In case you don't yet have an official certificate, you can use an example certificate for Sandbox.

⤓ cert.pem ⤓ key.pem

The signing certificate is sent with a signing request but not stored on the Rabobank developer portal. If you want to change/replace you can make changes on your own system.

You can also choose to have two valid certificates when allowed by your system.

You should use the certificate based on the environment:

Self signed

  • All Sandbox API's with mTLS enabled
  • Smart Pay Merchant Services API in Production
  • All Rabo Identity Services PreProduction products

Official PSD2 or EV SSL

  • All (other) Production APIs

Step 2: Register the certificate on the Rabobank Developer Portal

Info: Register your app before registering the TLS certificate. You can only register one TLS certificate per app.

To register the certificate:

  1. Log into the Rabobank developer portal.
  2. Click My Apps.
  3. Select the app that should make the TLS protected requests.
  4. Click Edit.
  5. Click the TLS Certificate field and upload your TLS client certificate. This certificate must be in PEM format. For more information, see RFC7468.
  6. Click Submit.

Step 3: Configure your client software to use the certificate during the TLS handshake

Note: This step assumes you have already subscribed your app to the product containing the API that requires an X-509 client certificate.

Before your application can call the API, you should configure your software to use the private key and certificate.

Make sure to add the following CA's used by Rabobank to your trust store before making the connection:

  • digicert
  • quovadis
  • sectigo

Set up MTLS connection

To set up an MTLS connection you are required to send your client certificate including the certificate chain, this is a sequence (chain) of certificates in the X.509v3 PEM or DER format.

For the sandbox environment you can use the example certificate, see: Signing requests for PSD2 APIs.

The client certificate must be first in the certificate sequence. Each following certificate should directly certify the one preceding it. This is because certificate validation requires that root keys to be distributed independently.

The self-signed certificate specifying the root certificate authority is optional and may be omitted from the chain.

Source: RFC 5246 7.4.2 -

See TLS error codes for expected error responses.

You can test the configuration as shown in the example below: 

--header 'x-ibm-client-id: CLIENT_ID'
RABOBANK_ENDPOINT_URLThe endpoint of the API you want to call.
CLIENT_IDThe client ID of your application.
PATH_TO_KEY_FILEPath to the key file on your system that belongs to your certificate.
PATH_TO_CERT_FILEPath of your client certificate on your system.

Replace TLS certificate

You can replace your TLS certificate using the following steps:

  1. Navigate to the Rabobank developer portal → Sign in to your account → My Apps. 
  2. Select the application for which you want to replace the TLS certificate.
  3. Click Edit and upload your TLS certificate in PEM format.

    Rabobank only supports one TLS certificate, any existing certificate should be removed. It is not possible to upload two TLS certificates at the moment.

  4. Click Save.


Server Name Indication (SNI) is an extension for the TLS protocol to indicate a hostname in the TLS handshake (source wiki).

Transport Layer Security Server Name Indication (TLS SNI) allows clients to include the name of the host they are trying to contact (the "server name") in a request, which allows the server to select and respond with a proper certificate.

To make the TLS connection with the provided hosts secure, all existing (migrating) and/or new customer(s) are required to enable SNI in their client software before interacting with the following Rabobank hostnames:





Note: A TPP not using SNI is most likely to get connection related error messages, for example, 500 internal server error.