Generate JWS keys

Set up a public-private key pair to sign protected Transfers API requests. Transfers API requests that move money must include a JSON Web Signature (JWS). A JWS digitally signs data to ensure its integrity and authenticity. Protected actions include creating outbound transfers and returning inbound transfers.

Generate a public and private JWS key pair

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

This generates two files:

private_key.pem, containing your private key.
public_key.pem, containing your public key.

The files use the following formats:

public_key.pem

private_key.pem

-----BEGIN PRIVATE KEY-----
<redacted example private key content>
-----END PRIVATE KEY-----

Never share your JWS private keyYour JWS private key is sensitive and must remain confidential. Fintoc never asks for this key. Anyone with your private key can sign malicious transfer requests on your behalf.

Upload your public key to the dashboard

Go to dashboard.fintoc.com.
Open API Keys in the sidebar.
If your organization has products that require JWS, open JWS Public Keys, select Add JWS Key, and upload your JWS public key.

Generate a signature

After you upload your public key to the Fintoc dashboard, generate signatures with your private key. Each signature protects the integrity and authenticity of a Transfers API call that moves money.

Generate signatures with an SDK

The Node SDK and Python SDK generate signatures for you. Pass the private key when you initialize the Fintoc client. The SDK then signs each protected request:

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);

// The client now signs protected transfer requests

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'))

# The client now signs protected transfer requests

Generate a signature manually

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

Prepare the payload

JWS signature generation operates on the exact JSON string sent in the HTTP request. Create that string by serializing your outbound transfer request body with your language’s JSON serializer.

const body = {
  amount: 100000,
  currency: 'MXN',
  account_id: 'YOUR_ACCOUNT_ID',
  counterparty: {
    account_number: '000000000000000000'
  }
};

const rawBody = JSON.stringify(body);

import json

body = {
    "amount": 100000,
    "currency": "MXN",
    "account_id": "YOUR_ACCOUNT_ID",
    "counterparty": {
        "account_number": "000000000000000000"
    }
}

raw_body = json.dumps(body)

JSON string must be consistentWhen 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 difference between the JSON used to create the JWS signature and the HTTP request payload may invalidate the signature.

Load the private key and configure headers

Load your private key from the PEM file and configure the protected JWS header. The header includes the RS256 signing algorithm, a unique nonce, and the current Unix timestamp in ts. The crit field identifies ts and nonce as critical fields.

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

// Define the 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),             // Unix timestamp in seconds
  crit: ['ts', 'nonce']                          // Critical headers
};

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

# Define the JWS headers
headers = {
    "alg": "RS256",                  # Signing algorithm. Must be "RS256"
    "nonce": secrets.token_hex(16),  # Unique string for each request
    "ts": int(time.time()),          # Unix timestamp in seconds
    "crit": ["ts", "nonce"]          # Critical headers
}

Prevent replay attacks

Fintoc uses the nonce and ts headers during JWS authentication to protect against replay attacks and ensure request integrity. Include a unique, random nonce in every request. The nonce makes each signature distinct, even when you send the same data multiple times. Fintoc accepts each nonce only once and rejects requests that reuse a nonce. The Unix timestamp in ts records when you created the request. Fintoc validates that the timestamp falls within a 2-minute window and rejects outdated requests. Together, nonce and ts prevent replays: Fintoc rejects any intercepted request that reuses a nonce or falls outside the timestamp window.

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:

// Base64url-encode the protected JWS header without padding
const protectedBase64 = Buffer.from(JSON.stringify(headers))
  .toString('base64url');

// Base64url-encode rawBody without padding
const payloadBase64 = Buffer.from(rawBody)
  .toString('base64url');

// Join the encoded protected header and payload
const signingInput = `${protectedBase64}.${payloadBase64}`;

# Base64url-encode the protected JWS header without padding
protected_base64 = base64.urlsafe_b64encode(
    json.dumps(headers).encode()
).rstrip(b'=').decode()

# Base64url-encode raw_body without padding
payload_base64 = base64.urlsafe_b64encode(
    raw_body.encode()
).rstrip(b'=').decode()

# Join the encoded protected header and payload
signing_input = f"{protected_base64}.{payload_base64}"

Generate the JWS token signature

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

Sign the signing input with your private key using RSA and PKCS #1 v1.5 padding.
Base64url-encode the resulting signature without padding.

// Sign the signing input
const signatureRaw = crypto.createSign('sha256')
  .update(signingInput)
  .sign({
    key: privateKey,
    padding: crypto.constants.RSA_PKCS1_PADDING
  });

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

# Sign the signing input
signature_raw = private_key.sign(
    signing_input.encode(),
    padding.PKCS1v15(),
    hashes.SHA256()
)

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

Verify the JWS token (optional)

Some libraries re-encode JSON payloads with different spacing, key ordering, or character encoding. To debug a signature, decode the payload locally and confirm that it matches the raw_body sent in the HTTP request. Do not share a token that contains sensitive transfer data.

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

const payload = Buffer.from(payloadBase64, 'base64url').toString();
console.log(payload); // Should equal rawBody sent in the HTTP request

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

payload = base64.urlsafe_b64decode(
    payload_base64 + '=' * (-len(payload_base64) % 4)
)
print(payload.decode())  # Should equal 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:

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

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

Use the complete example

The following functions combine the manual signature steps. Install the Python cryptography package before running the Python example.

const crypto = require('crypto');
const { readFileSync } = require('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');

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

const payload = {
  amount: 100000,
  currency: 'MXN',
  account_id: 'YOUR_ACCOUNT_ID',
  counterparty: {
    account_number: '000000000000000000'
  }
};
const rawBody = JSON.stringify(payload); // Exact payload to send in the HTTP request

// Signature to include in the 'Fintoc-JWS-Signature' request header
const jwsSignatureHeader = generateJwsSignatureHeader(rawBody);

import base64
import json
import secrets
import time

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}"

    # Sign the signing input
    signature_raw = private_key.sign(
        signing_input.encode(),
        padding.PKCS1v15(),
        hashes.SHA256()
    )

    signature_base64 = base64.urlsafe_b64encode(signature_raw).rstrip(b'=').decode()

    return f"{protected_base64}.{signature_base64}"


body = {
    "amount": 100000,
    "currency": "MXN",
    "account_id": "YOUR_ACCOUNT_ID",
    "counterparty": {
        "account_number": "000000000000000000"
    }
}
raw_body = json.dumps(body)  # Exact payload to send in the HTTP request

# Signature to include in the 'Fintoc-JWS-Signature' request header
jws_signature_header = generate_jws_signature_header(raw_body)

Test the integration

Confirm your signature works before you go live. Using a test mode API key, sign a create outbound transfer request and send the signature in the Fintoc-JWS-Signature header.

Build the request body and serialize it with your JSON serializer.
Generate the signature from the serialized body with the function above.
Send the request with the Fintoc-JWS-Signature header set to the generated signature.

Fintoc returns 201 Created and the created transfer when the signature is valid. A signature error or 401 Unauthorized response can indicate a mismatched request body, a reused nonce, or a ts value outside the 2-minute window.

Home

Resources

Payments

Transfers

Movements

Generate JWS keys

Generate a public and private JWS key pair

Upload your public key to the dashboard

Generate a signature

Generate signatures with an SDK

Generate a signature manually

Prepare the payload

Load the private key and configure headers

Prevent replay attacks

Generate the signing input

Generate the JWS token signature

Verify the JWS token (optional)

Construct the `Fintoc-JWS-Signature` header

Use the complete example

Test the integration

​Generate a public and private JWS key pair

​Upload your public key to the dashboard

​Generate a signature

​Generate signatures with an SDK

​Generate a signature manually

​Prepare the payload

​Load the private key and configure headers

​Prevent replay attacks

​Generate the signing input

​Generate the JWS token signature

​Verify the JWS token (optional)

​Construct the Fintoc-JWS-Signature header

​Use the complete example

​Test the integration

Generate a public and private JWS key pair

Upload your public key to the dashboard

Generate a signature

Generate signatures with an SDK

Generate a signature manually

Prepare the payload

Load the private key and configure headers

Prevent replay attacks

Generate the signing input

Generate the JWS token signature

Verify the JWS token (optional)

Construct the `Fintoc-JWS-Signature` header

Use the complete example

Test the integration