Learn how to set up mTLS with Wise.
Mutual certificate validation is a security process between two parties, such as with Wise and a client. Once both parties have successfully validated each other's certificates, they proceed to establish a secure, encrypted communication channel.
If you'd like to learn more about mutual certificate validation, visit the following resources:
- Cloudflare: What is mutual TLS (mTLS)?
- SSL.com: Generate and secure your private keys
- SSL.com: Private and public keys
Use the following command to generate a Certificate Signing Request (CSR) 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>"
The command outputs a private key called sandbox-PRIVATE-KEY.key and a certificate signing request called sandbox-certificate-request.csr.
Do not share your private key with anyone — including us.
- 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.
- You must set an organisation name, as in the example command above.
- Wise sets a Common Name (CN) for you, which will be your Client ID. If you put anything else in, it will be overridden to be your Client ID.
- The CSR should be in PEM format.
- We do not allow any comments or plain text metadata in the CSR.
Once you have generated your CSR:
- Log into Developer Hub and go to the Authentication section.
- If you are testing in the sandbox, 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, use Developer Hub and log in with the production account that you shared when you requested client credentials.
- Go to the Generate certificate screen, type a certificate name, and paste in the content of your CSR.
- After you submit the form, the Certificate Details screen opens displaying the client certificate.
- Copy the client certificate content into a file with pem extension (for example,
sandbox-CERTIFICATE.pemin the sandbox) and securely store that certificate in your key store. - Go back to the Developer Hub Authentication section and click the Get Wise Certificate button.
- This will download a Wise certificate for Sandbox or for Production (based on the environment you are in). Securely store the certificate in your trust store.
- Test the certificate.
- The certificate returned to you when you submit a CSR on Dev Hub is valid for 1 year.
- We only allow up to 10 active certificates at a time.
- All certificates must have unique names.
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.wise-sandbox.com.
Once you have completed your integration to the sandbox, 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 and go to the newly created cert folder.
To test the integrity of the private key and generated certificate, try executing:
openssl rsa -in sandbox-PRIVATE-KEY.key -noout -modulus
openssl x509 -in sandbox-CERTIFICATE.pem -noout -modulus
Compare that the outputs are the same.
To test an example request, try executing:
curl --key sandbox-PRIVATE-KEY.key \
--cert sandbox-CERTIFICATE.pem \
--cacert wise.ca-certificate.sandbox.pem \
https://api-mtls.wise-sandbox.com/v1/authenticated/playground \
-H 'Authorization: Bearer <access_token>'