Recover an uncertain payment

A timeout does not prove that the payment failed. Keep the order pending until you confirm the outcome. In Python, the error has outcome_unknown set to True.

If you got no response when creating the payment

Send the saved request again with the same paymentReference and the same data. You will get the same payment. Retry without creating another payment

To find it without sending the request again, list payments with the exact paymentReference filter. The page holds at most that one payment:

TypeScript

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

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

export async function findPayment(paymentReference: string) {
  const page = await timbro.payments.list({ paymentReference });
  return page.data.at(0);
}

Python

import os

from timbro_payments import TimbroPayments
from timbro_payments.types import Payment

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


def find_payment(payment_reference: str) -> Payment | None:
    page = timbro.payments.list(payment_reference=payment_reference)
    return page["data"][0] if page["data"] else None

If the page is empty, send the saved request again with the same reference. It cannot create a second payment.

If you already have the id

TypeScript

const payment = await timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr");

Python

payment = timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr")

• succeeded: confirm the reference, currency, and amount, then apply the payment once.
• processing or verifying: wait and retrieve the same payment again. Do not start another collection.
• requires_customer_action: the payment is still open. With lastDecline, the last attempt was declined and the customer can try again from checkout.url.
• canceled or expired: the payment has ended. Before you create another one, check whether any part is still pending, especially in a split payment.

Space out retrievals and use webhooks to receive updates. If the outcome remains unresolved or retrieval also fails, leave the order under review and write to us with the payment id, paymentReference, the mode (Test or Live), and Request-Id if you have it.

checkout.url remains the link for the original payment and may show its verification or result. Resending the reference of a payment that has ended does not create a new payment.