Repetir la solicitud sin duplicar el pago

Guarda la solicitud de pago antes de enviarla. Si pierdes la respuesta, vuelve a enviar esa solicitud con el mismo paymentReference: Timbro devuelve el mismo pago y su estado actual.

TypeScript

import { createTimbroPayments, type CreatePaymentCommand } from "@timbro/payments";

const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY! });

export async function recoverPayment(savedRequest: CreatePaymentCommand) {
  return timbro.payments.create(savedRequest);
}

Python

import os

from timbro_payments import TimbroPayments
from timbro_payments.types import CreatePaymentRequest, Payment

timbro = TimbroPayments(api_key=os.environ["TIMBRO_PAYMENTS_SECRET_KEY"])


def recover_payment(saved_request: CreatePaymentRequest) -> Payment:
    return timbro.payments.create(saved_request)

El SDK genera automáticamente una clave de idempotencia (Idempotency-Key) para identificar la solicitud y vuelve a intentarla hasta 2 veces si ocurre una falla temporal. Si esos intentos no resuelven el problema, conserva la solicitud para reenviarla después.

Si tu sistema es un ERP, puedes derivar la referencia del pedido y su versión con paymentReferenceForSource en TypeScript o payment_reference_for_source en Python. La misma versión del pedido siempre produce la misma referencia.

Qué puedes repetir

• Reenvía la solicitud para el mismo comercio y modo, Prueba o En vivo. Las referencias se identifican por comercio y modo.
• Reenvía los mismos datos. Si cambias el monto, los artículos, el impuesto, la afiliación seleccionada u otros campos, recibirás un conflicto (409).
• Si enviaste expiresAfterSeconds, repítelo igual. Forma parte de la solicitud: un valor distinto, o no enviarlo después de haberlo enviado, produce un conflicto (409).
• Un cambio posterior en la configuración del comercio no modifica un pago que Timbro ya aceptó.
• Si el pago venció o se canceló, repetir la referencia devuelve ese mismo pago; no crea uno nuevo.

Si usas HTTP directamente, reenvía el mismo cuerpo. No es obligatorio añadir Idempotency-Key al crear pagos o reembolsos. Si la envías, usa la misma en cada intento. Algunas operaciones, como registrar un webhook, sí la requieren. Deriva esa clave de un registro que tu sistema conserva, como el pedido o la línea del pedido, y nunca generes una clave nueva en cada intento.

Si no recibes una respuesta, el pago aún podría completarse. Confirma qué pasó con el pago antes de volver a cobrar.