Mutual TLS

Mutual certificate validation is a security process between two parties, such as with Wise and a partner. Once both parties have successfully validated each others certificates, they proceed to establish a secure, encrypted communication channel.

Some more resources on mutual certificate validation:

• What is mutual TLS (mTLS)?
• Generate and Secure Your Private Keys
• Private And Public Keys

Step 1: Generate a CSR

You can use the following command to generate a Certificate Signing Request as an example, and replace <name of your organisation>.

openssl req -nodes -newkey rsa:4096 -keyout sandbox-PRIVATE-KEY.key -out sandbox-certificate-request.csr -subj "/C=EU/O=<name of your organisation>"

This will generate a private key called sandbox-PRIVATE-KEY.key.

CSR Requirements

1. The key algorithm should be RSA or ECC.
   • For an RSA key, the length should be at minimum 2048 bits (we support 2048, 3072, and 4096 bits).
   • For an ECC key, the length should be either 256 or 384 bits.
2. You will need to set an organisation name, as the example command above shows.
3. We will set a CN (Common Name) for you, which will be your Client ID. If you put anything else in, it will be overriden to be your Client ID.
4. The CSR should be in PEM format.
5. We do not allow any comments or plain text metadata in the CSR.
6. Do not share your private key with anyone-- including us.

Step 2: Upload the CSR and Download a Certificate

Once you have generated your CSR:

1. Log in to , and select the "Authentication" section in the menu on the left.
   • If you are testing in Sandbox, please use Developer Hub Sandbox and log in with the Sandbox account that you shared when you requested client credentials.
   • If you are implementing in Production, please use Developer Hub and log in with the Production account that you shared when you requested client credentials.
2. Upload your CSR in the Authentication section of the Developer Hub UI.
3. You will receive a client certificate once you've uploaded your CSR-- download and securely store that certificate in your key store.
   • For Sandbox you can call it sandbox-CERTIFICATE.pem if you would like to copy the example commands at the bottom of this guide.
4. In Developer Hub you will also find the Wise public certificate for both Sandbox and Production-- download and securely store that certificate in your trust store.
5. Test the certificate.

Certificate Limitations

1. The certificate returned to you when you submit a CSR on Dev Hub is valid for 1 year.
2. We only allow up to 10 active certificates at a time.
3. You must reach out to your CSM if you need to revoke a certificate.
4. All certificates must have unique names.

Sandbox

You can get the Wise public test certificate from Developer Hub. Once you have obtained the OAuth credentials and your certificate, you can test mTLS right away by changing the host to: https://api-mtls.sandbox.transferwise.tech.

Production

Once you have completed your integration to Sandbox please follow the same process for Production. You can use mTLS right away by changing the host to: https://api-mtls.wise.com.

Open a terminal/cmd window, navigate to the newly created cert folder.

To test the integrity of the private key and generated certificate, you can try executing:

openssl rsa -in sandbox-PRIVATE-KEY.key -noout -modulus
openssl x509 -in sandbox-CERTIFICATE.pem -noout -modulus

and compare that the outputs are the same.

To test an example request, you can try executing:

curl --key sandbox-PRIVATE-KEY.key \
     --cert sandbox-CERTIFICATE.pem \
     --cacert wise.ca-certificate.sandbox.pem \
    https://api-mtls.sandbox.transferwise.tech/v1/authenticated/playground \
    -H 'Authorization: Bearer <access_token>'