order
object. Use the order.status
field to trigger actions in your system.
Monitoring Payment Status
There are two ways to track the current status of a payment:1
Poll the Order Status
Make requests to the /order/details endpoint to check the current status
2
Set up Webhooks
Use the
order_updated
event to receive real-time updates through Webhooks for every status changeThe Ivy API fires the webhook event
order_updated
with all Order fields, including the order.status
field. Monitor the field 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.
Possible Status Values
processing
The Order has been created successfully and the end user has started the payment flow.Next possible statuses:
waiting_for_payment
, paid
, finalizing
, canceled
Terminal Status: Nocanceled
The payment flow was not completed and the session expired, either by the system or by the merchant via API.If a customer sends funds with the correct payment details, but the status is
canceled
, the incoming transaction is returned automatically.Next possible statuses: None (terminal status)Terminal Status: Yes (for all Orders)waiting_for_payment
The user has authorized the payment and completed the session successfully.At this stage:
- The user has authorized the payment within their bank
- Settlement is still pending
- Payment is not guaranteed
- If the settlement happens before the authorization notification is sent,
waiting_for_payment
will be skipped and instead thepaid
status will be set
paid
, finalizing
, failed
, canceled
Terminal Status: No (Yes for payments with direct settlement)finalizing
Payment received, finalizing booking verification. Typically completes in minutes, may take up to 48 hours if additional verification is required. You can still expire the order at this stage via API.Next possible statuses:
paid
, canceled
Terminal Status: Nofailed
Money has not arrived in Ivy’s collection account within 6 days (when
paymentMode
isinstant_preferred
or standard
) or within 24 hours (instant_only
) and will not arrive anymore.If money arrives after this time, it is returned automatically to the payer.Next possible statuses: None (terminal status)Terminal Status: Yes (for all Orders)paid
Money has successfully arrived in Ivy’s collection account or is being guaranteed by Ivy.Important timing notes:
- Can range from instant to 3 business days depending on the payment scheme
- For instant payments the “paid” status can sometimes arrive before “waiting_for_payment” . If this occurs, then “waiting_for_payment” will not be sent at all.
- This status only appears for settlement with Ivy, not for direct settlement
- If the settlement happens before the authorization notification is sent,
waiting_for_payment
will be skipped and instead thepaid
status will be set
in_refund
Terminal Status: Yes (unless you trigger a Refund process)in_refund
The Order is currently undergoing the refund process. Money is en route to the end user’s bank account.Next possible statuses:
refunded
, partially_refunded
Terminal Status: Norefunded
The Order has been fully refunded. Money has been sent to the end user’s bank account.Next possible statuses: None (terminal status)Terminal Status: Yes
partially_refunded
The Order has been partially refunded. Money has been sent to the end user’s bank account.Next possible statuses:
in_refund
Terminal Status: NoIt’s important to handle all possible status transitions in your integration, as payments may not always follow the most common path.