Integration guides
Search documentation... ⌘K
Open merchant dashboard
Advanced features
Open in Markdown

Payment lifecycle

Check payment statuses, available actions, refunds, and disputes.

Overview

Use a payment's status to decide what to show your customer and what to do next: fulfill the order, capture it, refund it, or check again later. To get the current status, call find-payment with the Reservepay payment ID or your external_id.

Before you capture, reverse, void, or refund, check the matching flag on the payment: capturable, reversible, voidable, or refundable. The flags tell you what's allowed right now, which the status alone can't.

Statuses

Status Meaning What to do
PENDING The payment was created, but the customer hasn't finished paying. Wait for a webhook or check again later.
AUTHORIZED The funds are held on the customer's card but not captured (capture: false). Capture or reverse it within 7 days.
SUCCESSFUL The payment was captured. Fulfill the order.
FAILED The payment attempt failed. Read the failure code. To retry, start a new payment with a new external_id.
EXPIRED The customer didn't finish paying before expires_at. To retry, start a new payment with a new external_id.
REVERSED You released an authorization with reverse-payment. Nothing. No money moved.
VOIDED You canceled a captured payment with void-payment before it settled. Nothing. No money moved.
PARTIALLY_REFUNDED Part of a successful payment has been refunded. Refund more if needed.
REFUNDED The full amount of a successful payment has been refunded. Nothing.
DISPUTED The customer disputed the payment with their bank. Respond before the dispute's deadline_at. See Disputes.

For a FAILED card payment, look up its code in Payment failure codes.

How statuses change

From To When
PENDING AUTHORIZED The authorization succeeds and the payment was created with capture: false.
PENDING SUCCESSFUL The payment succeeds and was created with capture: true.
PENDING FAILED The payment attempt fails.
PENDING EXPIRED The customer doesn't finish paying in time.
AUTHORIZED SUCCESSFUL You capture it with capture-payment.
AUTHORIZED REVERSED You reverse it with reverse-payment.
SUCCESSFUL VOIDED You void it with void-payment while voidable is true.

PARTIALLY_REFUNDED, REFUNDED, and DISPUTED describe a successful payment that has refunds or a dispute attached. They aren't separate steps. If a payment has a dispute, its status shows DISPUTED even when it also has refunds, and it keeps showing DISPUTED after the dispute closes. To see both, call list-refunds-by-payment and list-disputes-by-payment.

Statuses that can still change

Occasionally, a late confirmation from the acquiring bank moves a FAILED or EXPIRED payment to SUCCESSFUL. Don't treat these payments as closed for good. Check unresolved payments again with find-payment when you reconcile. See Reconciliation.

For capture and reversal windows, see Authorization and capture. For refunds and voids, see Refunds, voids, and reversals.

Integrate further

Dive deeper into these advanced integration topics to unlock Reservepay's full potential with our in-depth guides.

Refunds, voids, and reversals

Issue refunds, void transactions before they settle, and reverse authorizations when needed.

Read the guide
Disputes

Find disputed payments, submit evidence, and respond before the deadline.

Read the guide
Authorization and capture

Separate authorization from capture to hold funds without charging. Perfect for pre-orders or reservations

Read the guide
Working with Terminal

Build your own POS, or work with our app by sending commands or using deep links.

Read the guide
Customer intelligence

Build profiles by attaching customer data. Gain insights, reduce fraud risk, and create experiences that drive loyalty.

Read the guide
Sending funds

Send payouts to your primary bank account or to your contacts via bank account, mobile number or national ID.

Read the guide
Real-time notifications

Stay informed about payment events with real-time webhooks. Automate your order processing, and more...

Read the guide
Payment lifecycle

Check payment statuses, available actions, refunds, and disputes.

Read the guide
Reconciliation

Filter payments and payouts, export CSVs, read balance holds, and reconcile daily statements.

Read the guide
Payment failure codes

Look up what each Reservepay failure code means when a payment is declined.

Read the guide

No account yet?

Start integrating all these amazing features into your app or website by creating your own merchant account today. It's free to sign up and only takes a few minutes to get started.

Create your merchant account