JSON Web Signature (JWS)

The signing is completed via a JWS mechanism, supported by JOSE. Generally, this means:

1. The client creates a key pair and delivers the public key to Wise (please contact your implementation manager for details). The format, type, and details required are included below.
2. Wise installs the public key to be consumed by our API. Multiple keys can be installed to enable rotation.
3. Once installed, the partner can now call the funding endpoint with signed request body.
4. Wise will verify the signature using the public key provided runs other checks including the validity of the URL.
5. Wise will return the response encoded and signed, the partner’s system must accept the media type provided (see details below).
6. The partner verifies and decodes the header and payload from the returned JWS

Contact your implementation manager about submitting your public key details to Wise.

When delivering the public key, we require the following information:

• Key Material
• Algorithm used
• KeyID: UUID (Optional)
• Expiration Timestamp (Optional)
• Deletion Timestamp (Optional)
• Activation Timestamp (Optional)

Expiration, deletion, and activation timestamps are all optional. If not included, once installed, the key will remain active until Wise is instructed to remove it.

The KeyID, denoted in the JWS header as kid is an indicator of which key to use to validate the signature. This should be supplied if the caller plans to have multiple keys active at once, either for multiple services or rotation.

Here is a step-by-step workflow with example commands to manually sign a request.

Create a request body as-per our usual API reference, and sign it with the request URL in the header block (see example).

The header and body should then be base64url encoded and signed, with the signature appended as per the JOSE standard for JWS. It is recommended that an established library be used to complete this process to avoid difficulties and errors in the encoding and signing process.

The example here uses the header and body as shown above and signs it with a private key. The three parts of this JWS are:

• Base64(base64url) Encoded Header
• Base64(base64url) Encoded Body
• Signed header + Body

The request must include the following headers (all are required):

• Content-Type: application/jose+json
• Accept: application/jose+json
• X-TW-JOSE-Method: jws

Verify the response of the API call by fetching the latest Wise public key and checking the signature. See Get Wise JWT public key

The response is a fully formed JWS with a Base64 encoded JSON body.