Ivy tracks the status of instant bank transfers and manual bank transfers through the 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 change
The 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, canceledTerminal Status: No
canceled
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 the paid status will be set
Next possible statuses: paid, finalizing, failedTerminal 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, canceledTerminal Status: No
failed
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 the paid status will be set
Next possible statuses: in_refundTerminal 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_refundedTerminal Status: No
refunded
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_refundTerminal Status: No
It’s important to handle all possible status transitions in your integration, as payments may not always follow the most common path.