Mutual TLS

Mutual certificate validation is a security process between two parties, such as with Wise and a client. 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>. The command output a private key called sandbox-PRIVATE-KEY.key and a Certificate sign request called sandbox-certificate-request.csr

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

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. Navigate to Generate certificate screen
   • type a certificate name
   • copy and paste the content of your CSR
3. After submission of the Generate certificate form, Certificate Details screen opens displaying the client certificate. Copy the content of it into a file with pem extension, for example, for sandbox: sandbox-CERTIFICATE.pem and securely store that certificate in your key store.
4. In Developer Hub, in the Authentication section, you will also find a button "Get Wise Certificate". Depending on the environment, by clicking the button will download a Wise certificate for Sandbox or for Production. Securely store Wise 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. 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.transferwise.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>'