Skip to main content

​
Core Concepts

At the center of the API is the Payment entity. A payment represents a financial transfer order and includes key details such as the amount and currency. It 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.

​
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

​
Statuses

  • Pending – The payment has been created but not yet processed.
  • Authorized – The consumer’s payment method has been validated and funds have been reserved, but not yet transferred.
  • Captured – The payment has been successfully processed and funds have been transferred from the consumer to the merchant’s account.
  • Voided (or Reversed) – A payment is canceled before money movement is complete. Consumer might see a temporary hold, but it will drop off without a debit.
  • Refunded – A previously captured payment is returned to the consumer.
  • Failed - The payment request has failed.

​
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 if an authorization hold is placed
  • Transition directly to Captured if the merchant uses captureNow
  • Transition to Failed if the authorization request is declined
Authorized payments can:
  • Transition to Captured (funds transferred to the merchant)
  • Transition to Voided (authorization canceled before settlement)
Captured payments can:
  • Be Refunded (funds returned to the consumer)
  • In some cases, be Voided/Reversed if the capture is undone before settlement
Voided and Refunded both cancel payments, but differ in timing:
  • Voided – before settlement is complete (funds never reach the merchant)
  • Refunded – after settlement, triggering a new transaction to return funds
Failed is a terminal state, the payment cannot progress further.