Payment states

Use the status from a payment retrieved on your server to decide what to do:

State	What to do
requires_customer_action	Open checkout.url so the customer can continue. With lastDecline, the last attempt was declined and the customer can try again.
processing	The payment is in progress. Wait and retrieve the same payment.
verifying	The outcome is not known yet. Wait; do not start another payment.
partially_paid	Some money is captured and a balance is still due on a split payment.
succeeded	The money is captured. Apply the payment to the order once.
canceled	The payment ended as canceled.
expired	Checkout was not completed before expiresAt. Create another payment if the customer still wants to pay; for a Subscription, see the rule below.

The terminal states are succeeded, canceled, and expired. Repeating their paymentReference returns that same payment; it does not reopen it. For a new payment, use another reference after resolving the previous result.

Declined attempts

A decline ends the attempt, not the payment. The payment returns to requires_customer_action, and lastDecline carries the normalized reason (code), a message for the customer, and attemptedAt. The customer can try again from the same link until the payment expires. Each declined attempt sends the payment.declined webhook. Do not create another payment because of a decline.

Payment window

expiresAt tells you when Checkout closes. The default is 30 minutes with a returnUrl and 1 hour without one. Send expiresAfterSeconds when you create the payment to change it, from 300 to 86400 seconds. Choose how long the QR code stays open.

Subscription payments

The first payment to set up a Subscription expires after 24 hours. When it expires, the Subscription is terminal; create another Subscription with a new subscriptionReference to start again. A renewal can remain in requires_customer_action with expiresAt and checkout.expiresAt both null until the email provider accepts the pending payment notice. Timbro then sets a 7-day deadline. Keep the Checkout link available and do not show a countdown while the deadline is null. Resending the notice does not extend a deadline that is already set. If the provider rejects the notice, recoveryNotice.problem is notice_handoff_failed and Timbro does not retry it: share the link or resend the notice. Each payment allows 3 resends in 24 hours.

Split payments

partially_authorized and authorized mean money is held on the cards. capturing means capture is in progress, and releasing means held money is being released. These states do not confirm the full payment. partially_paid can also coexist with pending portions: check the split progress.

If you requested an e-CF

succeeded confirms collection only. Retrieve the Invoice by its invoiceId to check fiscal acceptance and file readiness. Invoice at the time of payment.

Recover an uncertain payment