Skip to main content

​
Core Concepts

At the center of the API is the Payment entity. A payment represents the intent to move funds. That intent is fulfilled through one or more Transactions. Each transaction is an immutable record of an operation attempted on the payment, such as authorization, capture, void, or refund. Transactions should be understood as actions performed on a payment. They describe what was attempted and the outcome of that attempt, but they never change once created. If a transaction fails, a new transaction must be created to attempt the same action again. The Payment acts as:
  • The logical container for all related transactions.
  • The lifecycle owner, whose status is derived from the sequence and outcome of its transactions.
A payment does not change state directly. Its status evolves only when a transaction completes successfully. If a transaction is attempted but does not succeed, the transaction is still recorded, but the payment status remains unchanged. For example, when attempt to refund a captured payment a new refund transaction is created and linked to the payment. The preceding capture transaction is unchanged. If that refund succeeds, the payment transitions to Refunded; if it fails, the payment remains Captured. A payment is composed of the following sub-entities:
  • Consumer – The individual making the purchase.
  • Payment Method – The type and details of the method used to complete the payment (e.g., credit card, digital wallet).
  • Billing – The billing address and contact information associated with the payment method.
  • Shipping – The delivery address and contact information for where the purchased items will be sent.
  • Product Items – The individual products or services being purchased, including details such as name, quantity, unit price, and goods type. Providing accurate product information increases the likelihood of payment approval.
  • Previous Failures – Information about previous failed payment attempts with other providers. Providing this context can help improve approval rates when retrying payments.
  • Transactions – The immutable records of operations attempted on the payment, such as authorization, capture, void, or refund.

​
Payment Lifecycle

A payment moves through several statuses as it is processed. The diagram below shows the full state machine with the possible transitions across states: Payment Lifecycle

​
Payment Statuses

  • PENDING – The payment has been created but not yet processed. This is a temporary status.
  • AUTHORIZED – Funds have been reserved in the consumer’s account, but not yet captured.
  • CAPTURED – Funds have been debited from the consumer’s account.
  • VOIDED – Funds reserved during authorization are unfrozen and available to the consumer again. This is a final status, a VOIDED payment can no longer be CAPTURED.
  • REFUNDED – Funds debited during capture are returned to the consumer. This is a final status, a refund cannot be reversed.
  • FAILED - The payment failed to be authorized. This is a final status, a new payment should be created to reattempt authorization.

​
Key Notes

After creating a payment, the response status can be:
  • PENDING (only if asynchronous processing is enabled), or directly
  • AUTHORIZED, CAPTURED, or FAILED
When a payment is PENDING, it may:
  • Transition to AUTHORIZED when funds are successfully reserved in the consumer’s account by setting captureNow=false.
  • Transition directly to CAPTURED when funds have been debited from the consumer’s account by setting captureNow=true.
  • Transition to FAILED if funds could not be authorized.
AUTHORIZED payments can:
  • Transition to CAPTURED when funds are debited from the consumer’s account.
  • Transition to VOIDED when reserved funds are unfrozen before capture.
CAPTURED payments can:
  • Be REFUNDED when debited funds are returned to the consumer’s account.
VOIDED and REFUNDED both represent canceled payments. These are final states and cannot be reversed. FAILED is a final state, the payment cannot progress further.

​
Transactions Types

  • SALE – Authorization and capture of funds in a single request. Initiated in payment creation when the captureNow flag is set as true.
  • AUTHORIZATION – Authorization of funds with a separate capture request required to trigger movement of funds. Initiated in payment creation when the captureNow flag is set as false.
  • CAPTURE – Debiting of funds following successful authorization. Initiated by calling the capture endpoint.
  • REFUND – Return of captured funds to the consumer’s account. Initiated by calling the refund endpoint.
  • VOID – Cancelation of authorized funds in the consumer’s account. Initiated by calling the void endpoint.

​
Key Notes

A transaction represents a single operation performed against a payment that may change its state. Each transaction:
  • Is immutable once created
  • Has a specific type (see above)
  • Has a specific result: SUCCEEDED or FAILED
  • Represents what happened at a specific point in time
Relationship with payments:
  • A payment in PENDING state may not have any transactions associated with it
  • Once processed, a payment can contain one or more transactions
  • Transactions are always associated with exactly one payment
  • The payment’s state is derived from the sequence and results of its transactions