Set up mutual TLS (mTLS)

Configure mutual TLS (mTLS) for inbound and outbound connectivity with Thales D1.

The D1 API requires mutual TLS (mTLS). This applies to inbound and outbound API calls.

Set up mTLS before you start integrating D1 eCom Enablement.

You integrate as a merchant gateway. Thales provides you a merchantGatewayId.

D1 environments are isolated. Set up connectivity separately for PreProd and Production.

Inbound flow: your host to Thales D1

mTLS inbound flow

General requirements:

1. Mutual authentication

2. TLS 1.2 or 1.3

3. Over the internet (no IP allowlist)

4. Thales server certificate is signed by AWS CA: https://www.amazontrust.com/repository/

5. Your client certificate is signed by the Thales CA

Client certificates

To access the D1 API, you need a client certificate signed by the Thales CA. Send a certificate signing request (CSR) to your Thales representative.

General requirements:

1. Algorithm: RSA encryption with 4096-bit or ECDSA P-256 keys and SHA256 hashing.

2. Common Name (CN): format and value are enforced and checked by Thales. The value should follow the pattern described in step 2 of the example below.

Example CSR generation

Repeat the procedure for each environment (PreProd and Production).

1. Generate a new key pair for your CSR either RSA or ECDSA.

You can create a RSA 4096 key pair with the following OpenSSL command:

openssl req -new -newkey rsa:4096 -nodes -keyout private_rsa.key -out customer_pp.csr -subj "/C=<Country>/ST=<State>/L=<Locality>/O=<Customer Organization>/OU=<Customer Organization Unit>/CN=TLSMA-RSA\/<merchantGatewayId>\/D1.<env>"

You can create an ECDSA P-256 key pair with the following OpenSSL commands:

openssl ecparam -name prime256v1 -genkey -noout -out d1-mtls-client-cert.key
openssl req -new -key d1-mtls-client-cert.key -out d1-mtls-client-cert.csr -subj "/C=<country>/ST=<state>/L=<locality>/O=<Customer Organization>/OU=<Customer Organization Unit>/CN=TLSMA-ECDSA\/<merchantGatewayId>\/D1.<env>"

1. Details for mTLS client certificate.

where:

• country is your country.

• state is your state.

• locality is your locality.

• Organization Name is your organization name.

• Organizational Unit is your organizational unit.

• CN means Common Name.

• merchantGatewayId is the ID provided by Thales.

• env is the environment targeted by this certificate. For pre-production: PPR, for production: PRD

• ECDSA vs RSA in CN depends on key type.

Your backend must always resolve the D1 domain name and subdomains through DNS. Thales D1 does not provide static IP addresses. Do not hardcode or cache D1 IPs beyond the DNS TTL.

Outbound flow: Thales D1 to your host

mTLS outbound flow

General requirements:

1. Mutual Authentication

2. TLS 1.2, 1.3

3. Your server must listen on port 443 (or 8443, but 443 is preferred)

4. Over the internet (no IP whitelisting)

5. You must trust the Thales Client CA to authenticate the mTLS client certificate presented by D1. The Thales Client CA is shared during onboarding.

6. Thales D1 must trust your server certificate. Provide your server CA chain during onboarding.

Thales expects a TLS certificate issued by a CA recognized by Mozilla. If your endpoint relies on a private CA, provide a PEM-formatted trust store to the Thales delivery team. Notify Thales before any CA change.

You must endorse only the Thales Client CA, and you must not "pin" the Thales client certificate. The Thales client certificate is signed by the Thales Client CA. D1 may rotate its client certificate at any time before its expiry date without prior notice to you.

FAQ

Can I use an RSA 2048 client certificate?

No, it is not possible.

Can I connect without mTLS?

No, it is not possible.

Is VPN supported?

Thales does not support VPN for inbound or outbound connectivity. Use mTLS over the internet. OAuth 2.0 is also required.

What is the validity period of the client certificate?

The client certificate issued for Thales backend connectivity is signed by Thales Business PKI and has a validity period of 5 years.

What is the renewal process for the client certificate?

During the renewal process, the customer generates a new Certificate Signing Request (CSR) using the Distinguished Name (DN) policy specified on this page. This CSR will then be signed by the Thales Business PKI.