Skip to main content
Every payment moves through a predictable series of states — from an initial reserve of funds through to final settlement or cancellation. Therius gives you two ways to move a payment through that lifecycle: a one-step flow that authorizes and captures in a single call, and a two-step flow that separates authorization from capture. Knowing which flow to use, and when each post-payment operation applies, will save you from edge cases and disputed charges.

​
One-Step Flow: Purchase

Use POST /payment/purchase when you can fulfill the order immediately — digital downloads, SaaS subscriptions, and any product you deliver the moment payment completes. A single round-trip reserves the funds and settles them in one go. The response carries status: "captured" and an id — the payment handle.

​
Two-Step Flow: Authorize → Capture

Use POST /payment/authorization to reserve funds without settling them. This is the right flow when you need to confirm availability before you fulfill — for example, physical goods that may go out of stock, or hotel reservations where you confirm the room before charging.
The authorization response includes an id (a UUID). That id is how you address the payment for every follow-up operation — pass it as the {id} path segment. A few rules apply:
  • Authorization window is typically 7 days, though some acquirers allow shorter or longer windows. If you do not capture within the window, the authorization expires and the funds are released automatically.
  • Partial capture is supported. You can capture any amount up to the authorized amount. For example, authorize 100andcapture100 and capture 80 if one item is out of stock.
  • Once a payment is captured you cannot capture again — use refund for any adjustments.

​
Refund

Call POST /payment/{id}/refund to return funds on a captured payment. Refunds can be full or partial, and you can issue multiple partial refunds as long as the cumulative total does not exceed the originally captured amount.
A partial refund of 5.00ona5.00 on a 19.99 payment returns the difference to the cardholder. The payment status moves to refunded once a full refund is processed.

​
Cancel

Call POST /payment/{id}/cancel to void an authorized payment before it is captured. Funds are released immediately and the customer is never charged. You cannot cancel a payment that has already been captured — call POST /payment/{id}/refund instead.

​
Auto Cancel or Refund

If you are not sure whether a payment is in authorized or captured state, call POST /payment/{id}/cancel_or_refund. Therius checks the current state and performs the correct operation automatically — a cancel if the payment is authorized, a full refund if it is captured.

​
Payment Statuses

​
State Machine

​
id, paymentCode, and orderCode

orderCode and paymentCode are reference fields only — they are echoed back on responses and webhooks. Inquiry accepts either the id or the paymentCode in its path. But capture, refund, cancel and cancel_or_refund take only the id. Always store the id from the authorize/purchase response and use it for those calls.