Sign your payment requests
Learn how to sign requests to our Payments API.
When you sign your requests to our APIs, you ensure a second layer of security on top of the authorisation bearer token, guaranteeing that the payload has not been tampered with.
When you make a modification request (like POST
or DELETE
) to our Payments APIs, you must authenticate them with a client_credentials
token generated by TrueLayer's auth server. You must also sign requests by including a valid Tl-Signature
HTTP header.
To sign an HTTP request using ECDSA you will need to generate an Elliptic Curve (EC) key pair. You will need:
- a public key, to upload to Console
- a private key, to sign requests. Don't share this with anyone outside of your organisation.
Signing algorithms
We only support the ES512 signing algorithm for modification requests to our Payments APIs.
ES512 belongs to the family of Elliptic Curve Digital Signature Algorithms (ECDSA).
ES512, in particular, requires a key pair that uses the P-521 family of elliptic curves (also known as
secpt521r1
).
Generate a signing key pair
You can generate a key pair with:
To check which version of either software you have on your device, run this command in your terminal:
openssl version
If you don't have either OpenSSL or LibreSSL installed on your device, go to their website to install your preferred library.
- To generate a private key, run the following command in your terminal:
openssl ecparam -genkey -name secp521r1 -noout -out ec512-private-key.pem
- Then, to generate a public key, run the following command in your terminal:
openssl ec -in ec512-private-key.pem -pubout -out ec512-public-key.pem
- Go to Console > Payments Settings and upload your public key, the file
ec512-public-key.pem
.
Sign your requests with our libraries
In our Github, we maintain libraries in a range of languages. Our backend libraries also use these libraries for the API requests.
E.g. Java com.truelayer.truelayer-signing
// `Tl-Signature` value to send with the request.
String tlSignature = Signer.from(kid, privateKey)
.header("Idempotency-Key", idempotencyKey)
.method("post")
.path(path)
.body(body)
.sign();
Sign your requests without using libraries
To manually generate Tl-Signature
headers, or verify webhook signatures, it’s still recommended to refer to our Github reference implementations & examples.
In particular see the document describing the signing scheme.
Manual signing
Instead of signing requests manually, we recommend that you use our signing libraries for easier integration.
Test your signing logic
Send a POST or DELETE request to our /test-signature
endpoint to verify that you have correctly implemented request signing. The /test-signature
endpoint will validate your Tl-Signature
header and return a 204 No Content
if it is successful. It does not perform any kind of validation on the body schema.
curl -X POST \
-H "Authorization: Bearer ${access_token}" \
-H "Tl-Signature: ${signature}" \
--data '{"nonce":"9f952b2e-1675-4be8-bb39-6f4343803c2f"}' \
https://api.truelayer-sandbox.com/test-signature
Troubleshooting
- Ensure that the
path
you are signing is the same as the path you use to send the request. If you're testing againsthttps://api.truelayer-sandbox.com/test-signature
, the path should be/test-signature
.
- Ensure that all signed headers are sent with the request exactly as they were signed and none are missing. So if you sign
Idempotency-Key
you must also send exactly the same value in the request. Note:/test-signature
does not require any headers, so it is possible to test request signing without signing headers here (though headers are required for other endpoints).
- Ensure that the body passed to the signing library matches the body sent with the request exactly, byte for byte. It must not be formatted differently or have fields in a different order. Ensure the request body has no trailing newlines if it was not signed that way.
- Ensure the public key ID and private key you are signing with match the public KID in our Console.
- Try testing the endpoints using Insomnia and the insomnia-plugin-jws-by-truelayer plugin. The plugin generates
Tl-Signature
headers using the private key and KID environment variables, so can be used to check that the keys and Console configuration are correct.
Import our Insomnia collection
Updated 15 days ago