Para hacer solicitudes a nuestros endpoints de Transfers que mueven dinero, deberás incluir una JSON Web Signature (JWS). JWS es un estándar para firmar digitalmente datos y garantizar su integridad y autenticidad. Las acciones protegidas incluyen crear transferencias salientes y devolver transferencias entrantes.

Generar llaves JWS

Para firmar una llamada a la API, debes seguir estos pasos:

Generar un par de llaves JWS pública y privada

Ejecuta este comando en tu terminal:

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

Esto genera dos archivos:

private_key.pem que contiene tu llave privada
public_key.pem que contiene tu llave pública

Cada archivo debería verse similar a este ejemplo:

public_key.pem

private_key.pem

Nunca compartas tu llave JWS privadaTu llave JWS privada es altamente sensible y debe permanecer confidencial en todo momento. Fintoc nunca te pedirá esta llave. Si alguien obtiene acceso a tu llave privada, podría firmar maliciosamente solicitudes de transferencias en tu nombre.

Sube tu llave pública al Dashboard

Ve a dashboard.fintoc.com
Ve a la pestaña API Keys en la barra lateral
Si los productos que requieren JWS están activos para tu organización, verás una sección JWS Public Keys. Haz clic en el botón “Add JWS Key” y sube tu llave JWS pública.

Generar firma

Ahora que cargaste tu llave pública en tu Dashboard de Fintoc, puedes generar una firma basada en la llave privada. Esto es necesario para garantizar la integridad y autenticidad de cada llamada a la API de Transfers que mueve dinero.

Usando nuestro SDK

Si estás usando Python o Node, nuestros SDK de Python y SDK de Node generan automáticamente las firmas por ti. Simplemente inicializa el cliente de Fintoc con el argumento jws_private_key, y el SDK se encargará del resto:

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

Ejemplo paso a paso

Si quieres escribir tu propia implementación o usar otro lenguaje de programación, sigue estos pasos:

Preparar el payload

Para generar la firma JWS, necesitamos trabajar con el string JSON exacto que será enviado en la solicitud HTTP. Esto normalmente se crea convirtiendo el objeto del cuerpo de la solicitud de Outbound Transfer en un string JSON usando el serializador JSON de tu lenguaje.

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

El string JSON debe ser consistenteAl serializar el cuerpo de tu solicitud a JSON, debes usar exactamente el mismo string para dos propósitos:

Crear la firma JWS
Enviarlo como payload en tu solicitud HTTP

Cualquier pequeña diferencia entre el JSON usado para crear la firma JWS y el payload en tu solicitud HTTP puede invalidar la firma.

Cargar la llave privada y configurar los headers

Carga tu llave privada desde el archivo PEM y configura los headers JWS. Los headers incluyen el algoritmo de firma (RS256), un nonce único para prevenir firmas duplicadas, el timestamp actual y la especificación de campos críticos.

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

Prevenir un ataque de replay

Fintoc usa los headers nonce y ts (timestamp) en su proceso de autenticación JWS para protegerse contra ataques de replay y garantizar la integridad de la solicitud. El string nonce debe ser un valor único y aleatorio, y debe incluirse en cada solicitud, haciendo que cada firma sea distinta incluso si se envía la misma información varias veces. Fintoc se asegura de que cada nonce se use solo una vez y rechazará cualquier solicitud que contenga un nonce duplicado. El timestamp ts registra cuándo se creó la solicitud, y los servidores de Fintoc validan que esté dentro de una ventana de 2 minutos para evitar el procesamiento de solicitudes antiguas. Juntos, el nonce y el timestamp brindan una protección robusta al asegurar que las solicitudes interceptadas o manipuladas no puedan reutilizarse, protegiendo tu integración contra actividades maliciosas.

Generar el signing input

El signing input de un JWS consiste en concatenar los headers codificados en base64url y el raw_body codificado en base64url con un punto . entre ambos, ambos sin 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}"

Generar la firma del token JWS

Una vez que tengas el signing input listo, crearás la firma criptográfica usando tu llave privada. El proceso involucra:

Firmar el input usando tu llave privada con:
1. RSA con padding PKCS1v15
2. Codificar en Base64URL la firma resultante (sin padding)
Codificar en Base64URL la firma resultante (sin 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)

Opcional: verificar el token JWS

Algunas librerías pueden re-codificar payloads JSON con espacios o ordenamiento de keys distintos, o cambiar su codificación. Para depurar la firma, puedes inspeccionar el token generado en https://jwt.io para verificar su contenido. También recomendamos verificar que el payload del token JWS sea igual al raw_body enviado en la solicitud http.

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

Construir el header Fintoc-JWS-Signature

Construye el header Fintoc-JWS-Signature concatenando el header protegido y la firma:

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

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

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

Ejemplo completo

Aquí un ejemplo completo de una función que junta todo (tendrás que instalar las librerías mencionadas para probarla).

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) 

Inicio

Recursos

Pagos

Transferencias

Domiciliación bancaria

Movimientos

Generar llaves JWS

Generar llaves JWS

Generar un par de llaves JWS pública y privada

Sube tu llave pública al Dashboard

Generar firma

Usando nuestro SDK

Ejemplo paso a paso

Preparar el payload

Cargar la llave privada y configurar los headers

Prevenir un ataque de replay

Generar el signing input

Generar la firma del token JWS

Opcional: verificar el token JWS

Construir el header Fintoc-JWS-Signature

Ejemplo completo

​Generar llaves JWS

​Generar un par de llaves JWS pública y privada

​Sube tu llave pública al Dashboard

​Generar firma

​Usando nuestro SDK

​Ejemplo paso a paso

​Preparar el payload

​Cargar la llave privada y configurar los headers

​Prevenir un ataque de replay

​Generar el signing input

​Generar la firma del token JWS

​Opcional: verificar el token JWS

​Construir el header Fintoc-JWS-Signature

​Ejemplo completo

Generar llaves JWS

Generar un par de llaves JWS pública y privada

Sube tu llave pública al Dashboard

Generar firma

Usando nuestro SDK

Ejemplo paso a paso

Preparar el payload

Cargar la llave privada y configurar los headers

Prevenir un ataque de replay

Generar el signing input

Generar la firma del token JWS

Opcional: verificar el token JWS

Construir el header Fintoc-JWS-Signature

Ejemplo completo