Understanding the Payment Flow

The Purse system is designed to orchestrate and simplify online payments. Whether you're dealing with cards, wallets, gift cards, or split payments, the process remains consistent and fully traceable.

This page walks you through the main stages of a payment lifecycle, highlighting the objects created and how they interact.

It all starts with a Client Session

Before any transaction can begin, a Client Session must be created.
This object acts as the order data referential: it holds the amount, the order, the customer info, and the merchant’s preferences.

Once the session is created, the merchant presents the payment options to the customer, through a widget, a redirect, or a custom interface.

• When the customer selects and confirms a method, the session is submitted, and the payment process begins.

For more technical details, refer to the Client Session Reference section.

Payment takes the lead

When the session is submitted, a Payment object is created.
This is the core object in the system: it records the method selected, the amount processed, and all future actions (like refunds or captures).

The payment also includes advanced information such as:

• Authorization result
• Split configuration (if several methods are used)
• Status and amounts breakdown
• Links to related operations (via HATEOAS)

Merchants can query this object at any time to track the transaction lifecycle with the GetPayment endpoint or by using webhooks notifications.

For more technical details, refer to the Payment Reference section.

Capturing the funds

For most card-based methods, an authorization is first performed, reserving the funds.
To actually receive the money, the merchant must trigger a Capture.

This operation can be full or partial, and it is critical to finalize the transaction.
For some payment methods (gift cards, wallets…), the capture may happen automatically.

For more technical details, refer to the Capture Reference section.

Handling refunds

Once funds are captured, merchants can issue Refunds — either total or partial — directly through the API.
Each refund is tied to the original Payment and appears in its financial breakdown.

Refunds may apply to one or several payment methods depending on the split.
Purse handles the routing and processing of each refund internally.

For more technical details, refer to the Refund Reference section.

Canceling authorizations

Sometimes, a payment is authorized but never completed.
The merchant may decide to cancel it, for example due to stock issues or customer abandonment.

This action is handled by a Void, which cancels the reserved funds before capture.
Once voided, the payment can no longer be captured. A void can be partial or total.

For more technical details, refer to the Void Reference section.

Payment Operation Summary

Tracking & reconciliation

All payment operations (authorization, capture, refund, void) are reflected in the Payment object.

You’ll find consolidated data such as:

• amounts.total_authorized, total_captured, total_refunded, etc.
• available_to_capture, available_to_refund, available_to_void
• overview: which operations have been completed
• status: overall state of the transaction (SUCCESS, PENDING…)

This provides full transparency and allows accurate reconciliation.