Guía para desarrolladores

Esta guía es para desarrolladores que implementan la integración del plugin Bank Transfer. Cubre los patrones y las decisiones que van más allá de las llamadas a endpoints individuales: idempotencia, estrategia de reintentos, manejo de estados y validación de webhooks. Para los parámetros de los endpoints y los esquemas de respuesta, consulta la Referencia de API.

Idempotencia

Cada solicitud que modifica datos (initiate, process, cancel, return) requiere un encabezado X-Idempotency. Una solicitud sin él se rechaza con 400 BTF-0001. Si envías la misma solicitud dos veces con una misma clave, el plugin devuelve la respuesta original sin crear una operación duplicada. Reglas:

Usa un UUID v4 o un identificador de negocio único (p. ej. el ID de pedido de tu sistema)
Longitud máxima: 255 caracteres, formados por letras, dígitos, ., _ y -
El plugin limita cada clave a la organización efectiva. La misma clave desde dos organizaciones cuenta como dos solicitudes distintas.
El plugin repite una respuesta exitosa durante 7 días. Una repetición lleva el mismo código de estado y el mismo cuerpo, más el encabezado X-Idempotency-Replayed: true.
Una respuesta 4xx no consume la clave: corrige la solicitud y envíala de nuevo con la misma clave.
Después de una respuesta 5xx, el resultado es desconocido: lee primero el recurso y envía la solicitud de nuevo solo con una clave nueva. Una clave que la respuesta bloqueó (X-Idempotency-Fenced: true) se rechaza con 422 BTF-0014. Una respuesta 503 BTF-9000 o 503 BTF-9017 no ejecutó nada: envía la solicitud de nuevo con la misma clave.
La misma clave con un cuerpo distinto se rechaza con 422 BTF-0017. Un reenvío mientras la primera solicitud sigue en ejecución recibe 409 BTF-0016 con Retry-After.
Cada rechazo de idempotencia indica su solución en detail. Léela antes de reenviar.

POST /v1/transfers/initiate
X-Organization-Id: 019c9ac2-3f5d-7df9-9215-bdccc1451def
X-Idempotency: 7f3d9a1b-4e2c-4f8a-b3d1-9e6f2a4c8b7e

No reutilices claves de idempotencia entre operaciones distintas. No reutilices una clave de initiate para hacer process o cancel de la misma transferencia.

Detección de duplicados

Más allá de las claves de idempotencia, el plugin detecta duplicados basados en el contenido. Construye una huella a partir de:

senderAccountId
los datos del receptor (ISPB, sucursal, cuenta, documento del titular)
el monto
el propósito

El plugin guarda la huella en Redis durante 5 minutos. El valor predeterminado es 300 segundos. Los operadores lo ajustan por tenant a través del ajuste del systemplane idempotency.duplicate_guard_ttl_seconds. La organización no forma parte de la huella. El aislamiento entre tenants viene del prefijo de la clave de Redis. El plugin rechaza la solicitud con 409 BTF-0012 si el cliente ya envió una transferencia coincidente dentro de la ventana. Esto detecta los casos en que el cliente envía la misma transferencia con una clave de idempotencia distinta. Un ejemplo es un reintento después de un timeout, cuando el cliente no recibió la respuesta original.

Estrategia de reintentos

Usa backoff exponencial para los errores transitorios. No reintentes todos los errores.

Estado HTTP	¿Reintentar?	Notas
`400`	No	Error de validación. Corrige la solicitud antes de reintentar
`404`	No	No encontrado. El recurso no existe
`409`	Depende	`BTF-0016`: la primera solicitud sigue en ejecución; reenvía con la misma clave después de `Retry-After`. Cualquier otro `409`: no reenvíes
`410`	No	Expirado. Crea un nuevo inicio
`422`	No	Regla de negocio (horario de operación, límites) o rechazo de idempotencia. La condición debe cambiar primero
`429`	Sí	Rate limit. Espera el valor del encabezado `Retry-After` (segundos)
`5xx`	Lee primero	El resultado es desconocido. Lee la transferencia y luego reintenta con backoff, con una clave nueva, solo si la operación no ocurrió. Una respuesta `503 BTF-9000` o `503 BTF-9017` no ejecutó nada: reintenta con la misma clave

Programa de backoff recomendado para 5xx: 0s, 5s, 25s, 60s, 120s (5 intentos en total).

Durante POST /v1/transfers/process, cuando JD SPB no está disponible, la respuesta es HTTP 503 con code BTF-1000, o BTF-1003 en un timeout de JD. upstream.code lleva el código propio de JD cuando JD devolvió uno. transferId y transferStatus identifican la transferencia. Una transferencia en PROCESSING mantiene su retención mientras la conciliación le pide el resultado a JD: no la proceses de nuevo.

Manejo de estados

Máquina de estados de TED OUT

Las transferencias siguen una progresión estricta. No puedes cancelar una transferencia después de que sale de CREATED o PENDING.

Qué hacer en cada estado:

Estado	Significado	Acción recomendada
`CREATED`	Confirmada por el usuario, en cola para el envío	Muestra “Procesando” en la interfaz; consulta o espera el webhook
`PENDING`	El plugin prepara el envío a JD	Muestra “Procesando”; la cancelación todavía es posible
`PROCESSING`	Enviada a JD, a la espera del resultado de la liquidación	Muestra “Procesando”; no permitas la cancelación. Si `reconciliationStatus` es `MANUAL_REVIEW`, la retención sigue vigente y un operador resuelve la transferencia
`COMPLETED`	Liquidada	Muestra la confirmación con `confirmationNumber`
`REJECTED`	JD o el STR rechazó la transferencia	Muestra el error al usuario; los fondos ya se liberaron
`FAILED`	El ledger rechazó la retención, o la conciliación no pudo liquidar la transferencia	Muestra el error. Si `reconciliationStatus` es `MANUAL_REVIEW`, la retención sigue vigente y un operador todavía puede liquidar la transferencia: no ofrezcas una nueva transferencia hasta que se resuelva
`CANCELLED`	Cancelada antes del envío	Muestra la confirmación de la cancelación

Máquina de estados del inicio

El endpoint initiate crea una entidad PaymentInitiation. Esta entidad tiene su propio ciclo de vida antes de que el plugin cree una Transfer.

Máquina de estados de TED IN

Máquina de estados de P2P

P2P no tiene un estado PENDING. La liquidación es atómica e instantánea.

Polling frente a webhooks

Prefiere los webhooks para el estado en tiempo real. Si todavía no configuraste webhooks, consulta GET /v1/transfers/{transferId}. Usa como máximo 10 intentos con el mismo programa de backoff que los reintentos. Marca la transferencia para revisión manual después de 10 minutos sin un estado terminal (COMPLETED, REJECTED, FAILED, CANCELLED). Consulta Get Transfer y Webhooks.

Integración de webhooks

Para los esquemas de payload de los eventos y la lista completa de eventos, consulta Webhooks.

Validación de la firma

Cada solicitud de webhook incluye encabezados que tu endpoint usa para verificar la autenticidad:

X-Webhook-Signature: firma HMAC-SHA256 versionada con la forma v1,sha256=<hex>
X-Webhook-Timestamp: marca de tiempo Unix en segundos (UTC) del momento en que el plugin construyó la solicitud
X-Webhook-Event: el tipo de evento (por ejemplo, transfer.completed). Este encabezado no forma parte de la firma.

El plugin calcula la firma así:

X-Webhook-Signature: v1,sha256=hex(HMAC_SHA256(signingSecret, "v1:" + <timestamp> + "." + <raw_body>))

La cadena firmada tiene cuatro partes en orden: el prefijo v1:, el valor de la marca de tiempo de X-Webhook-Timestamp, un punto ASCII (.), y luego los bytes del cuerpo de la solicitud sin procesar. Usa los bytes del cuerpo exactamente como llegan por la red. No los analices ni los vuelvas a codificar antes. Para validar:

Lee X-Webhook-Signature y X-Webhook-Timestamp de los encabezados de la solicitud.
Construye la cadena firmada: "v1:" + timestamp + "." + rawBody.
Calcula HMAC-SHA256 sobre la cadena firmada con el signingSecret del registro del webhook, y luego codifica el resultado en hexadecimal.
Antepón v1,sha256=, y luego compáralo con X-Webhook-Signature con una función de igualdad de tiempo constante.
Rechaza la solicitud si la marca de tiempo queda fuera de una ventana de frescura aceptable (una tolerancia de 5 minutos es lo típico) para evitar repeticiones.

JavaScript

const crypto = require('crypto');
const express = require('express');

const TOLERANCE_SECONDS = 300; // 5 minutes

function validateWebhook(rawBody, timestamp, signature, secret) {
  if (!timestamp || !signature) return false;

  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10));
  if (Number.isNaN(ageSeconds) || ageSeconds > TOLERANCE_SECONDS) return false;

  const signedPayload = Buffer.concat([
    Buffer.from('v1:', 'utf8'),
    Buffer.from(timestamp, 'utf8'),
    Buffer.from('.', 'utf8'),
    rawBody,
  ]);

  const expected = 'v1,sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(signature);
  if (expectedBuf.length !== receivedBuf.length) return false;

  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

// Use raw body — not req.body (parsed JSON)
app.post('/webhooks/ted',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const timestamp = req.headers['x-webhook-timestamp'];
    const signature = req.headers['x-webhook-signature'];

    if (!validateWebhook(req.body, timestamp, signature, process.env.TED_WEBHOOK_SIGNING_SECRET)) {
      return res.status(401).send('Invalid signature');
    }

    const payload = JSON.parse(req.body.toString());
    // process payload...
    res.status(200).send('OK');
  }
);

Python

import hmac
import hashlib
import time

TOLERANCE_SECONDS = 300  # 5 minutes

def validate_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if not timestamp or not signature:
        return False

    try:
        age = abs(int(time.time()) - int(timestamp))
    except ValueError:
        return False
    if age > TOLERANCE_SECONDS:
        return False

    signed_payload = b"v1:" + timestamp.encode() + b"." + raw_body
    expected = "v1,sha256=" + hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)

const toleranceSeconds = 300 // 5 minutes

func validateWebhook(rawBody []byte, timestamp, signature, secret string) bool {
    if timestamp == "" || signature == "" {
        return false
    }

    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return false
    }
    if diff := time.Now().Unix() - ts; diff < -toleranceSeconds || diff > toleranceSeconds {
        return false
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte("v1:"))
    mac.Write([]byte(timestamp))
    mac.Write([]byte("."))
    mac.Write(rawBody)
    expected := "v1,sha256=" + hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(expected), []byte(signature))
}

Procesamiento idempotente de webhooks

Tu endpoint puede recibir el mismo evento más de una vez (entrega al menos una vez). Usa transferId + el encabezado X-Webhook-Event como clave compuesta para deduplicar. Para los eventos de devolución de una TED IN, agrega status y reconciliationReasonCode del cuerpo a la clave.

const alreadyProcessed = await db.webhookEvents.exists({
  transferId: payload.transferId,
  event: req.headers['x-webhook-event'],
  status: payload.status, // return events of a TED IN
  reconciliationReasonCode: payload.reconciliationReasonCode,
});

if (alreadyProcessed) {
  return res.status(200).send('OK'); // acknowledge without reprocessing
}

Patrones de manejo de errores

Asigna los códigos de error de la API a acciones de cara al usuario. Consulta la lista completa de errores para todos los códigos.

Escenario	Mensaje de cara al usuario	Acción
Fuera del horario de operación (`BTF-0010`)	“Transferencias disponibles de lunes a viernes, 06:30–17:00 (Brasilia). Próxima ventana: “	Muestra el próximo horario disponible
Límite de uso excedido (`BTF-0011`)	“Límite de transferencias alcanzado para este período.”	Muestra `period`, `limit` y `current` del error
Transferencia duplicada (`BTF-0012`)	“Esta transferencia ya se envió.”	Busca la transferencia anterior con List Transfers
Datos del receptor inválidos (`BTF-0001`)	“Revisa los datos del receptor e inténtalo de nuevo.”	Resalta los campos inválidos
Inicio expirado (`BTF-0202`)	“La sesión expiró. Empieza una nueva transferencia.”	Reinicia el flujo de inicio
JD SPB no disponible (`BTF-1000` o `BTF-1003`, HTTP `503`)	“Servicio de transferencias no disponible temporalmente. Te mantendremos informado.”	Lee la transferencia indicada en `transferId`; no la proceses de nuevo
Midaz no disponible (`BTF-2000`)	“Servicio no disponible temporalmente. Inténtalo de nuevo en unos minutos.”	Reintenta con backoff

Las respuestas de error son documentos de problema RFC 9457 (application/problem+json). Los campos específicos de cada ruta van en el nivel superior:

{
  "type": "https://errors.lerian.studio/v1/BTF-0010",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "transfers can only be initiated Monday-Friday between 06:30 and 17:00 America/Sao_Paulo time",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "BTF-0010",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "category": "deterministic",
  "currentTime": "2026-01-21T18:30:00-03:00",
  "nextAvailableTime": "2026-01-22T06:30:00-03:00",
  "openTime": "06:30",
  "closeTime": "17:00",
  "timezone": "America/Sao_Paulo"
}

Lista de verificación para salir a producción

Antes de habilitar la integración en producción:

Introducción

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Guía para desarrolladores

Idempotencia

Detección de duplicados

Estrategia de reintentos

Manejo de estados

Máquina de estados de TED OUT

Máquina de estados del inicio

Máquina de estados de TED IN

Máquina de estados de P2P

Polling frente a webhooks

Integración de webhooks

Validación de la firma

Procesamiento idempotente de webhooks

Patrones de manejo de errores

Lista de verificación para salir a producción

​Idempotencia

​Detección de duplicados

​Estrategia de reintentos

​Manejo de estados

​Máquina de estados de TED OUT

​Máquina de estados del inicio

​Máquina de estados de TED IN

​Máquina de estados de P2P

​Polling frente a webhooks

​Integración de webhooks

​Validación de la firma

​Procesamiento idempotente de webhooks

​Patrones de manejo de errores

​Lista de verificación para salir a producción

Idempotencia

Detección de duplicados

Estrategia de reintentos

Manejo de estados

Máquina de estados de TED OUT

Máquina de estados del inicio

Máquina de estados de TED IN

Máquina de estados de P2P

Polling frente a webhooks

Integración de webhooks

Validación de la firma

Procesamiento idempotente de webhooks

Patrones de manejo de errores

Lista de verificación para salir a producción