Consultar y cancelar pagos

Guarda el id del pago al crearlo y úsalo para consultar el resultado desde tu servidor:

TypeScript

import { createTimbroPayments } from "@timbro/payments";

const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY! });
const payment = await timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr");

Python

import os

from timbro_payments import TimbroPayments

timbro = TimbroPayments(api_key=os.environ["TIMBRO_PAYMENTS_SECRET_KEY"])
payment = timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr")

status: "succeeded" confirma que el pago se completó. Comprueba que paymentReference, la moneda y el monto coincidan con tu pedido antes de marcarlo como pagado. Evita volver a registrarlo si ya lo hiciste. Si recibes processing o verifying, espera y consulta el mismo pago de nuevo. Revisa los demás estados. Un pago succeeded incluye refundable, que indica si un reembolso devolverá el dinero sin que intervenga el equipo de Timbro.

Cancelar

TypeScript

const canceled = await timbro.payments.cancel({ paymentId: "payment_123456789abcdefghjkmnpqr" });

Python

canceled = timbro.payments.cancel("payment_123456789abcdefghjkmnpqr")

No puedes cancelar un pago si ya se cobró dinero o si todavía se está comprobando el resultado. En esos casos, la API responde con un conflicto (409).

Si el pago está dividido y hay montos retenidos en las tarjetas, Timbro debe liberarlos antes de cancelarlo. Puedes recibir releasing: sigue consultando hasta recibir canceled. Para devolver dinero que ya se cobró, solicita un reembolso.

Buscar en el historial

TypeScript

const page = await timbro.payments.list({ limit: 20 });

Python

page = timbro.payments.list(limit=20)

list_all recorre todas las páginas por ti y acepta los mismos filtros, sin cursor:

for succeeded in timbro.payments.list_all(status=["succeeded"]):
    print(succeeded["paymentReference"], succeeded["totalAmount"]["value"])

data contiene los pagos de esta página. Si hasMore es true, envía nextCursor en la siguiente consulta para obtener más pagos, usando los mismos filtros. Consulta los filtros disponibles en la referencia REST.

Si no recibiste la respuesta al crear el pago, no crees otro. Reenvía la solicitud original con la misma referencia y Timbro te devolverá el mismo pago, o búscalo en el historial con el filtro exacto paymentReference.