Payment Status
Understanding the lifecycle and states of payments in the Ivy system
Overview
When a user successfully completes a Checkout Session, Ivy creates an Order object that contains:
- All the fields from the original
CheckoutSession - An additional
statusfield indicating the current state of the transaction
Monitoring Payment Status
There are two ways to track the current status of a payment:
Poll the Order Status
Make requests to the /order/details endpoint to check the current status
Set up Webhooks
Receive real-time updates through Webhooks when the status changes
The Ivy API fires the webhook event order_updated with all Order fields, including the order.status field. Monitor order.status to update your system accordingly.
Status values are consistent between both the API endpoints and webhooks. Learn more about webhooks in the webhook basics section.
Payment Status Types
The Order has been created successfully and the end user has started the payment flow.
Terminal Status: No
The payment flow was not completed and the session expired.
Terminal Status: Yes (for all Orders)
The user has authorized the payment and completed the session successfully.
At this stage:
- The bank has sent the money
- Settlement is still pending
- Payment is not guaranteed
Terminal Status: Yes (for payments with direct settlement)
Money has not arrived in Ivy’s collection account within 6 days and will not arrive anymore.
Terminal Status: Yes (for all Orders)
Money has successfully arrived in Ivy’s collection account or is being guaranteed by Ivy.
Important timing notes:
- Time to reach this status depends on bank transfer speed
- Can range from instant to 48 hours
- This status only appears for settlement with Ivy, not for direct settlement
Terminal Status: Yes (for Orders with settlement with Ivy)
The Order is currently undergoing the refund process. Money is en route to the end user’s bank account.
Terminal Status: No
The Order has been successfully refunded. Money has arrived in the end user’s bank account.
Terminal Status: Yes
The Order has been partially refunded. Money has arrived in the end user’s bank account.
Terminal Status: No
Status Flow Diagram
The following diagram illustrates how Orders progress through different statuses:
It’s important to handle all possible status transitions in your integration, as payments may not always follow the most common path.