Requests to Transfers endpoints that move money require a JSON Web Signature (JWS). The signature verifies the integrity and authenticity of the request. Protected actions include creating outbound transfers and returning inbound transfers.

Generate JWS keys

Generate a key pair, upload the public key, and use the private key to sign each protected request.

Generate a pair of public and private JWS keys

Run these commands in your terminal:

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -outform PEM -pubout -out public_key.pem.pub

This generates two files:

private_key.pem, which contains your private key.
public_key.pem.pub, which contains your public key.

Each key should look similar to the following examples:

public_key.pem

private_key.pem

Never share your JWS private keyKeep your JWS private key confidential. Fintoc never asks for this key. Anyone with access to the private key can sign transfer requests on your behalf.

Upload your public key to the dashboard

Open dashboard.fintoc.com.
Select API Keys in the sidebar.
If your organization has a product that requires JWS, find the JWS Public Keys section. Select Add JWS Key, and upload your JWS public key.

Generate a signature

After you upload your public key to the Fintoc dashboard, use your private key to generate a signature. The signature verifies the integrity and authenticity of each Transfers API request that moves money.

Use an SDK

The Python SDK and Node SDK generate signatures for you. Initialize the Fintoc client with your private key:

import os

from fintoc import Fintoc

# Provide a path to your PEM file
client = Fintoc("your_api_key", jws_private_key="private_key.pem")

# Or pass the PEM key directly as a string
client = Fintoc("your_api_key", jws_private_key=os.environ.get('JWS_PRIVATE_KEY'))

# You can now create transfers securely

Node

const { Fintoc } = require('fintoc');

// Provide a path to your PEM file
const fintoc = new Fintoc('your_api_key', 'private_key.pem');

// Or pass the PEM key directly as a string
const fintoc = new Fintoc('your_api_key', process.env.JWS_PRIVATE_KEY);

// You can now create transfers securely

Follow a step-by-step example

Follow these steps to write your own implementation or use a different programming language.

Prepare the payload

Generate the JWS signature from the exact JSON string that you send in the HTTP request. Use your language’s JSON serializer to convert the outbound transfer request body to a JSON string.

import json

body = { ... } # your request body

raw_body = json.dumps(body)

const body = { ... } // your request body

const rawBody = JSON.stringify(body)

require 'json'

body = { ... } # your request body

raw_body = body.to_json

Use the same JSON stringUse the same serialized JSON string for both actions:

Create the JWS signature.
Send the payload in your HTTP request.

Any difference between the signed JSON and the HTTP request payload can invalidate the signature.

Load the private key and configure headers

Load your private key from the PEM file and configure the JWS headers. Include the RS256 signing algorithm, a unique nonce, the current Unix timestamp, and the critical header names.

# load the private key
with open('./private_key.pem', 'rb') as f:
    private_key = serialization.load_pem_private_key(
        f.read(),
        password=None
    )

# define jws headers
headers = {
    "alg": "RS256",                 # signing algorithm. must be "RS256"
    "nonce": secrets.token_hex(16), # unique string for each request
    "ts": int(time.time()),         # timestamp of the request
    "crit": ["ts", "nonce"]         # critical headers
}

// load the private key
const privateKey = readFileSync('./private_key.pem', 'utf8');

// define jws headers
const headers = {
  alg: 'RS256',                                  // signing algorithm. must be "RS256"
  nonce: crypto.randomBytes(16).toString('hex'), // unique string for each request
  ts: Math.floor(Date.now() / 1000),            // timestamp of the request
  crit: ['ts', 'nonce']                         // critical headers
};

# load the private key
private_key = OpenSSL::PKey::RSA.new(File.read('./private_key.pem'))

# define jws headers
headers = {
  'alg' => 'RS256',                # signing algorithm. must be "RS256"
  'nonce' => SecureRandom.hex(16), # unique string for each request
  'ts' => Time.now.to_i,           # timestamp of the request
  'crit' => ['ts', 'nonce']        # critical headers
}

Prevent a replay attack

Fintoc uses the nonce and ts headers to protect requests against replay attacks. The headers also help verify request integrity. Set nonce to a unique, random value for every request. This value makes each signature distinct, even when you send the same data more than once. Fintoc rejects a request if its nonce was already used. Set ts to the Unix timestamp when you create the request. Fintoc rejects requests outside a two-minute window. Together, nonce and ts prevent an intercepted request from being reused.

Generate the signing input

Create the JWS signing input by joining the base64url-encoded headers and raw_body with a period (.). Encode both values without padding:

# generate the procted section of the jws by base64 encoding the headers without padding
protected_base64 = base64.urlsafe_b64encode(
  json.dumps(headers).encode()
).rstrip(b'=').decode()

# generate the payload section of the jws by base64 encoding the raw_body without padding
payload_base64 = base64.urlsafe_b64encode(
  raw_body.encode()
).rstrip(b'=').decode()

# generate the signature input by concatenating the encoded protected and payload components
signing_input = f"{protected_base64}.{payload_base64}"

// generate the procted section of the jws by base64 encoding the headers without padding
const protectedBase64 = Buffer.from(JSON.stringify(headers))
  .toString('base64url');
  
// generate the payload section of the jws by base64 encoding the raw_body without padding
const payloadBase64 = Buffer.from(rawBody)
  .toString('base64url');

// generate the signature input by concatenating the encoded protected and payload components
const signingInput = `${protectedBase64}.${payloadBase64}`;

# generate the procted section of the jws by base64 encoding the headers without padding
protected_base64 = Base64.urlsafe_encode64(headers.to_json, padding: false)

# generate the payload section of the jws by base64 encoding the raw_body without padding
payload_base64 = Base64.urlsafe_encode64(raw_body, padding: false)

# generate the signature input by concatenating the encoded protected and payload components
signing_input = "#{protected}.#{payload_base64}"

Generate the JWS token signature

Create the cryptographic signature from the signing input and your private key:

Sign the input using your private key with:
1. RSA with PKCS1v15 padding
2. SHA-256 hashing
Base64URL-encode the resulting signature (without padding)

# generate the raw signature by signing the signing_input 
signature_raw = private_key.sign(
     signing_input.encode(),
     padding.PKCS1v15(),
     hashes.SHA256()
)

# base64 encode the raw signature without padding
signature_base64 = base64.urlsafe_b64encode(signature_raw).rstrip(b'=').decode()

// generate the raw signature by signing the signing_input 
const signatureRaw = crypto.createSign('sha256')
  .update(signingInput)
  .sign({
    key: privateKey,
    padding: crypto.constants.RSA_PKCS1_PADDING
  });

// base64 encode the raw signature without padding
const signatureBase64 = Buffer.from(signatureRaw)
    .toString('base64url');

# generate the raw signature by signing the signing_input 
signature_raw = private_key.sign(OpenSSL::Digest::SHA256.new, signing_input)

# base64 encode the raw signature without padding
signature_base64 = Base64.urlsafe_encode64(signature_raw, padding: false)

Optional: verify the JWS token

Some libraries re-encode JSON payloads with different spacing, key ordering, or character encoding. To debug a signature locally, decode the payload and compare it with the raw_body sent in the HTTP request. You can also inspect a token containing only non-sensitive test data at jwt.io.

token = f"{protected_base64}.{payload_base64}.{signature_base64}"
print(token)

payload = base64.urlsafe_b64decode(
  payload_base64 + '=' * (4 - len(payload_base64) % 4)
)
print(payload) # should be equal to raw_body sent in the http request

const token = `${protectedBase64}.${payloadBase64}.${signatureBase64}`
console.log(token)

const payload = Buffer.from(payloadBase64, 'base64url').toString()
console.log(payload) // should be equal to raw_body sent in the http request

token = "#{protected}.#{payload_base64}.#{signature}"
puts token

payload = Base64.urlsafe_decode64(payload_base64 + '=' * (4 - payload_base64.length % 4))
puts payload # should be equal to raw_body sent in the http request

Construct the `Fintoc-JWS-Signature` header

Construct the Fintoc-JWS-Signature header by joining the protected header and signature:

jws_signature_header = f"{protected_base64}.{signature_base64}"

const jwsSignatureHeader = `${protectedBase64}.${signatureBase64}`;

jws_signature_header = "#{protected_base64}.#{signature_base64}"

Review the complete example

The following function combines the preceding steps. Install the imported libraries before running the example.

import base64
import json
import time
import secrets
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

def generate_jws_signature_header(raw_body):
    # Read private key
    with open('./private_key.pem', 'rb') as f:
        private_key = serialization.load_pem_private_key(
            f.read(),
            password=None
        )

    # Create headers
    headers = {
        'alg': 'RS256',
        'nonce': secrets.token_hex(16),
        'ts': int(time.time()),
        'crit': ['ts', 'nonce']
    }

    # Base64url encode without padding
    protected_base64 = base64.urlsafe_b64encode(
        json.dumps(headers).encode()
    ).rstrip(b'=').decode()
    
    payload_base64 = base64.urlsafe_b64encode(
        raw_body.encode()
    ).rstrip(b'=').decode()
    signing_input = f"{protected_base64}.{payload_base64}"

    # Create signature
    signature_raw = private_key.sign(
            signing_input.encode(),
            padding.PKCS1v15(),
            hashes.SHA256()
        )
    
    signature_base64 = base64.urlsafe_b64encode(signature_raw).rstrip(b'=').decode()

    # Debug output
    print(f"Token: {protected_base64}.{payload_base64}.{signature_base64}")
    payload = base64.urlsafe_b64decode(
        payload_base64 + '=' * (4 - len(payload_base64) % 4)
    )
    print(f"Payload: {payload.decode()}")

    return f"{protected_base64}.{signature_base64}"


body = { ... }
raw_body = json.dumps(body) # the exact payload to be sent in the http request

# signature that must be included in the 'Fintoc-JWS-Signature' request header
jws_signature_header = generate_jws_signature_header(raw_body)

import crypto from 'crypto';
import { readFileSync } from 'fs';

function generateJwsSignatureHeader(rawBody) {
  // Read private key
  const privateKey = readFileSync('./private_key.pem', 'utf8');

  const headers = {
    alg: 'RS256',
    nonce: crypto.randomBytes(16).toString('hex'),
    ts: Math.floor(Date.now() / 1000),
    crit: ['ts', 'nonce']
  };

  const protectedBase64 = Buffer.from(JSON.stringify(headers))
    .toString('base64url');
  
  const payloadBase64 = Buffer.from(rawBody)
    .toString('base64url');

  const signingInput = `${protectedBase64}.${payloadBase64}`;
  const signatureRaw = crypto.createSign('sha256')
    .update(signingInput)
    .sign({
      key: privateKey,
      padding: crypto.constants.RSA_PKCS1_PADDING
    });

  const signatureBase64 = Buffer.from(signatureRaw)
    .toString('base64url');

  // Debug output
  console.log(`Token: ${protectedBase64}.${payloadBase64}.${signatureBase64}`);
  console.log(`Payload: ${Buffer.from(payloadBase64, 'base64url').toString()}`);

  return `${protectedBase64}.${signatureBase64}`;
}


const payload = { ... }
const rawBody = JSON.stringify(payload) // the exact payload to be sent in the http request

// signature that must be included in the 'Fintoc-JWS-Signature' request header
const jwsSignatureHeader = generateJwsSignatureHeader(rawBody)

require 'base64'
require 'openssl'
require 'securerandom'
require 'json'

class JwsSignatureHeaderGenerator
  def self.generate(raw_body)
    private_key = OpenSSL::PKey::RSA.new(File.read('./private_key.pem'))

    headers = {
      'alg' => 'RS256',
      'nonce' => SecureRandom.hex(16),
      'ts' => Time.now.to_i,
      'crit' => ['ts', 'nonce']
    }

    protected = Base64.urlsafe_encode64(headers.to_json, padding: false)
    payload_base64 = Base64.urlsafe_encode64(raw_body, padding: false)

    signing_input = "#{protected}.#{payload_base64}"
    signature_raw = private_key.sign(OpenSSL::Digest::SHA256.new, signing_input)
    signature = Base64.urlsafe_encode64(signature_raw, padding: false)

    "#{protected}.#{signature}"

  end
end

body = { ... }
raw_body = body.to_json # the exact payload to be sent in the http request

# signature that must be included in the 'Fintoc-JWS-Signature' request header
jws_signature_header = JwsSignatureGenerator.generate(raw_body) 

Home

Resources

Payments

Transfers

Direct debit

Movements

Generate JWS keys

Generate JWS keys

Generate a pair of public and private JWS keys

Upload your public key to the dashboard

Generate a signature

Use an SDK

Follow a step-by-step example

Prepare the payload

Load the private key and configure headers

Prevent a replay attack

Generate the signing input

Generate the JWS token signature

Optional: verify the JWS token

Construct the `Fintoc-JWS-Signature` header

Review the complete example

​Generate JWS keys

​Generate a pair of public and private JWS keys

​Upload your public key to the dashboard

​Generate a signature

​Use an SDK

​Follow a step-by-step example

​Prepare the payload

​Load the private key and configure headers

​Prevent a replay attack

​Generate the signing input

​Generate the JWS token signature

​Optional: verify the JWS token

​Construct the Fintoc-JWS-Signature header

​Review the complete example

Generate JWS keys

Generate a pair of public and private JWS keys

Upload your public key to the dashboard

Generate a signature

Use an SDK

Follow a step-by-step example

Prepare the payload

Load the private key and configure headers

Prevent a replay attack

Generate the signing input

Generate the JWS token signature

Optional: verify the JWS token

Construct the `Fintoc-JWS-Signature` header

Review the complete example