To make requests to our Transfers endpoints that move money, you’ll need to include a JSON Web Signature (JWS). JWS is a standard for digitally signing data to ensure its integrity and authenticity. Protected actions include creating outbound transfers and returning inbound transfers.

Generate JWS Keys

To sign an API call, you'll need to follow these steps:

Generate a pair of Public and Private JWS Keys

Execute this command 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 containing your private key
public_key.pem containing your public key

Each file should look similar to this example:

🚧
Never share your JWS Private Key
Your JWS Private Key is highly sensitive and must remain confidential at all times. Fintoc will never ask for this key. If someone gains access to your private key, they could maliciously sign transfer requests on your behalf.

Upload your Public Key to the Dashboard

Go to dashboard.fintoc.com
Go to the API Keys tab on the side bar
If products that require JWS are active for your organization, you'll see a JWS Public Keys section. Click the "Add JWS Key" button and upload your JWS Public Key.

Generate JWS Signature

Now that you loaded your Public Key to your Fintoc Dashboard, you can generate a signature based on the Private Key. This is necessary to ensure integrity and authenticity for each Transfer API call that moves money.

Using our SDK

If you’re using Python, our SDK automatically generates the signatures for you. Simply initialize the Fintoc client with the jws_private_key argument, and the SDK will take care of the rest:

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

Step by step example

If you want to write your own implementation or use a different programming language, follow these steps:

Prepare the payload

For JWS signature generation, we need to work with the exact JSON string that will be sent in the HTTP request. This is typically created by converting your Outbound Transfer request body object into a JSON string using your language's JSON serializer.

body = { ... } # your request body

raw_body = json.dumps(body)

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

const rawBody = JSON.stringify(body)

body = { ... } # your request body

raw_body = body.to_json

📘
JSON string must be consistent
When serializing your request body to JSON, you must use the exact same string for two purposes:

Creating the JWS signature

Sending as the payload in your HTTP request

Any slight difference between the JSON used to create the JWS signature and the payload in your HTTP request may invalidate the signature.

Load Private Key and Configure Headers

Load your private key from the PEM file and set up the JWS headers. Headers include the signing algorithm (RS256), a unique nonce to prevent duplicated signatures, current timestamp, and critical fields specification.

# 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
  iat: Math.floor(Date.now() / 1000),            // timestamp of the request
  crit: ['iat', '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
}

Preventing a replay attack

Fintoc uses the nonce and ts timestamp headers in its JWS authentication process to protect against replay attacks and ensure request integrity.

The nonce string should be a unique, random value and needs to be included in every request, making each signature distinct even if the same data is sent multiple times. Fintoc ensures that each nonce is used only once, and will reject any request that contains a duplicated nonce.

The ts timestamp records when the request was created, and Fintoc’s servers validate that it falls within a 2 minute time window to prevent the processing of outdated requests.

Together, the nonce and timestamp provide robust protection by ensuring that intercepted or tampered requests cannot be reused, safeguarding your integration against malicious activities.

Generate the Signing Input

The signing input for a JWS consists of concatenating the base64url-encoded headers and the base64url-encoded raw_body with a period . between them, both 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 JWS Token Signature

Once you have the signing input ready, you'll create the cryptographic signature using your private key. The process involves:

Sign the input using your private key with:
1. RSA with PKCS1v15 padding
2. Base64URL-encode the resulting signature (without padding)
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 JWS Token

Some libraries may re-encode JSON payloads with different spacing or key ordering, or change its encoding. To debug the signature, you can inspect the generated token at https://jwt.io to verify its content. We also recommend to double-check that the JWS Token payload is equal to the raw_body being sent in the http request.

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 concatenating the protected header and signature:

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

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

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

Complete example

Here's a complete example function that puts it all together (you will have to install the mentioned libraries to try it out).

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)

Generate a JWS Signature

Generate JWS Keys

Generate a pair of Public and Private JWS Keys

🚧
Never share your JWS Private Key

Upload your Public Key to the Dashboard

Generate JWS Signature

Using our SDK

Step by step example

Prepare the payload

📘
JSON string must be consistent

Load Private Key and Configure Headers

Preventing a replay attack

Generate the Signing Input

Generate JWS Token Signature

Optional: Verify JWS Token

Construct the Fintoc-JWS-Signature Header

Complete example

Generate JWS Keys

Generate a pair of Public and Private JWS Keys

🚧Never share your JWS Private Key

Upload your Public Key to the Dashboard

Generate JWS Signature

Using our SDK

Step by step example

Prepare the payload

📘JSON string must be consistent

Load Private Key and Configure Headers

Preventing a replay attack

Generate the Signing Input

Generate JWS Token Signature

Optional: Verify JWS Token

Construct the Fintoc-JWS-Signature Header

Complete example

🚧
Never share your JWS Private Key

📘
JSON string must be consistent