Retrieve and cancel payments

Save the payment id when you create the payment and use it to retrieve the result from your server:

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" confirms that the money was captured. Compare paymentReference, currency, and amount with your order before applying the payment once. If you receive processing or verifying, wait and retrieve the same payment. See the other payment states. A succeeded payment includes refundable, which tells you whether a refund returns the money without the Timbro team stepping in.

Cancel

TypeScript

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

Python

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

If money has been captured or the outcome is still being confirmed, cancellation returns a conflict. For split payments with money held on the cards, it may return releasing until release is complete; retrieve the payment until it is canceled. To return money already collected, request a refund.

Search history

TypeScript

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

Python

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

list_all reads every page for you and takes the same filters, without cursor:

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

The listing returns data, hasMore, and nextCursor. To continue, send the cursor with the same filters. Available filters are in the REST reference.

If you lost the creation response, do not create another payment. Repeat the original request with the same reference to get the same payment, or find it in the history with the exact paymentReference filter.