Skip to main content
Every object in Zapyd has a lifecycle. This page covers all possible statuses, how they transition, and what your integration should do when each one fires.

​
Color coding

All flow diagrams use the same color convention:
  • Green: success
  • Red: failed
  • Amber: refunds, holds and reviews, which need attention but aren’t failures

​
Customer status

What to do:
  • VERIFIED: unlock transaction flows for this customer
  • FAILED: check failure_reason in the CUSTOMER webhook. If recoverable (e.g., DOCUMENT_VERIFICATION_FAILED), prompt the user to retry. If terminal (KYC_FAILED), contact Zapyd support with the customer ID. See KYC sharing for the update endpoint per reason

​
Bank status

What to do:
  • VERIFIED: the bank account is ready for payout orders
  • FAILED: check failure_reason in the BANK webhook. Common reasons: ACCOUNT_TYPE_NRE, NAME_MISMATCH, PENNY_DROP_FAILED. Prompt the user to add a different account or correct the details

​
Quotation status

What to do:
  • EXPIRED: fetch a new quotation and present the updated rate to the user before retrying

​
Payin status

What to do:
  • SUCCESS: release crypto to the user. Record the id from the webhook as your reconciliation reference
  • FAILED: check failure_reason in the PAYIN webhook (e.g., INCORRECT_UTR, PAYMENT_NOT_RECEIVED). Notify the user. Do not release crypto
  • REFUND_INITIATED: wait for REFUNDED before updating the user
  • REFUNDED: notify the user that their fiat has been returned. Do not release crypto
  • ON_HOLD: do not release crypto. Contact Zapyd support with the payin ID

​
Payout status

What to do:
  • SUCCESS: confirm delivery to the user. Use metadata.utr from the webhook as the transfer reference
  • FAILED: failure_reason is always the generic Payout failed. Notify the user. Contact Zapyd support with the payout ID for details
  • REFUNDED: notify the user. The transaction did not complete; see metadata.refund_reason
  • IN_REVIEW: if the webhook carries metadata.rfi_link, send the customer there to answer the request for information. Otherwise wait; the payout moves to SUCCESS or FAILED

​
EDD status

Enhanced Due Diligence applies to customers whose transaction volume triggers additional verification requirements. What to do:
  • DOCS_REQ: tell the customer that more documents are needed
  • VERIFIED: update the customer’s displayed limits in your UI
  • FAILED: inform the user their limits remain unchanged. They can resubmit EDD documents if the failure reason is correctable