Users

User statuses

The following table lists the statuses available that a user can assume on your platform.

StatusCodeDescription
pending23000The user is pending certain information for user verification approval.
pending_check23100The user has complete information received, however is still being reviewed and / or has not received payments yet.
approved_kyc_check23150The user has passed user verification review, but has been flagged for underwriting.
approved23200The user is considered in good standing and can transact normally.

📘

User Verification

To better understand our user verification and underwriting process, take a look at the article, How does user verification work with Zai?

Items

Item statuses

The following table lists the statuses available that an item can assume on your platform.

StatusCodeDescription
pending22000Transaction has not started yet, no payment received or requested.
payment_required22100Payment has been requested by the seller to the buyer.
wire_pending22110The buyer has acknowledged that they are wiring the funds in, they are on their way.
payment_pending22150Direct debit payment has been triggered, awaiting for these funds to clear.
payment_held22175Payment has been held as automatic triggers have been alerted. This will go through a manual review to move on to payment_deposited, or fraud_hold.
payment_authorized22180A credit card payment has been authorized for capture.
void_pending22185Void of a previous credit card payment authorization has been triggered, awaiting the authorization to be voided.
voided22195A previous credit card payment authorization has been voided.
payment_deposited22200Payment has been successfully received in our escrow vault.
work_completed22300Seller has requested release, they have delivered the goods or service.
problem_flagged22400A dispute has been raised by either the buyer/seller, transaction is on hold until it is resolved.
problem_resolve_requested22410The other party (who didn’t raise the dispute) has requested that the dispute should be resolved.
problem_escalated22420The dispute has not been resolved and has been escalated. This will go into a process of third party litigation.
completed22500The Item is completed, funds have been released.
Note: for card payments, Only after the card transaction settles (this could vary between 1-2 business days based on your settings) the funds will be applied to the seller/payee’s wallet account. Refer to Cards payin workflow.
cancelled22575The Item is cancelled and can no longer be accessed.
refunded22600The funds have been refunded to the funding source of the buyer.
refund_pending22610A refund action is initiated, but prior action is needed before the refund is applied (for example, the platform is waiting on a bank deposit or a batch processing).
refund_flagged22650The funds will be refunded to the funding source of the buyer, after manual review to approve the refund.
off_platform_refunded22670The funds have been refunded to the buyer through a means outside of the platform.
partial_completed22700Partial release of funds have been requested by the seller in the transaction.
partial_paid22800Partial release of funds have occurred in the transaction.
off_platform_chargedback22680The funds have been charged back by the buyer’s issuing bank through a means outside of the platform.

Item refund statuses

The following table lists the statuses that an item can undergo during a refund process. This is displayed, when applicable, under refund_state, in addition to the item state.

StatusCodeDescription
pending22600A refund has been initiated by the seller.
requested22620A refund has been requested by the buyer.
processing22622The refund has been triggered and is being processed.
pending_return22630The refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source.
pending_direct_credit22640The refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 2 business days, if the funds do not bounce.
failed22660The refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds.
success22690The refund has been successfully completed.

Refund statuses matrix

The following table shows both the item state and refund_state which an item undergoes during a refund process.

Full refund for a completed item

Item StateRefund StateDescription
refund_pendingpending_returnThe refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct debited, these will be returned to the item’s funding source.
pending_direct_creditThe refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 2 business days, if the funds do not bounce.
completedfailedThe refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds.
refundedsuccessThe refund has been successfully completed.

Partial refund for a completed item

Item StateRefund StateDescription
refund_pendingpending_returnThe refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source.
pending_direct_creditThe refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 2 business days, if the funds do not bounce.
completedfailedThe refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds.
successThe refund has been successfully completed.

Full refund for a non-completed item

Item StateRefund StateDescription
refund_pendingpending_returnThe refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct debited, these will be returned to the item’s funding source.
pending_direct_creditThe refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 2 business days, if the funds do not bounce
payment_deposited payment_held
partial_paid
partial_completed
work_completed
failedThe refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds.
refundedsuccessThe refund has been successfully completed.

Partial refund for a non-completed item

Item StateRefund StateDescription
refund_pendingpending_returnThe refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct debited, these will be returned to the item’s funding source.
pending_direct_creditThe refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 2 business days, if the funds do not bounce.
payment_deposited payment_held
partial_paid
partial_completed
work_completed
failedThe refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds.
successThe refund has been successfully completed.

Batches

Batch transaction states

StatusCodeDescription
successful12000The Batch Transaction has been processed successful, this means a direct debit has been received or a disbursement has been sent.
pending_successful12010The Batch Transaction has not bounced after 2 business days, but needs to be reviewed by our Payments Team before it is tagged successful.
pending12100The Batch Transaction is in a pending state. This refers to the early stages where the transaction has started and is followed by being batched
bpay_pending (Australia)12110The Batch Transaction for this bpay payin has been received from our bank as a notification however the bpay payin is pending until the funds have been settled into Zai's account
batched12200The Batch Transaction has been created and is being processed by the batch process. This process runs 4 times a day.
invalid_account_details12360The Batch Transaction has failed due to incorrect bank account details.
failed_direct_debit (Australia)12370The Batch Transaction has been dishonoured due to insufficient funds or other restrictions. Please refer user to contact their financial institution.
bank_processing12700The Batch Transaction has been imported to the bank and is being processed.
errored12900The Batch Transaction contained an error and will no longer be processed.

Batch transaction matrix

Both item states and batch transactions statuses show where the item is in a payment workflow. Together, these two fields can tell you the flow of funds after an item has been paid for.

For direct debit payments (payins) (Australia)

Item StateBatch Transaction StatusDescription
payment_pendingpendingThe direct debit payment has been triggered, but the payment hasn’t yet been included in a batch for processing.
batchedThe payment has been included in a transaction batch, which is waiting to be processed.
bank_processingThe payment, along with other payments in the same batch, is already being processed by the bank.
payment_depositedsuccessfulThe payment was successfully processed by the bank and the funds are now in the Zai escrow vault.
pendinginvalid_account_detailsThe payment wasn’t successful due to incorrect bank account details.
failed_direct_debitThe payment wasn’t honoured due to insufficient funds or other restrictions.

For direct credit payments (payouts)

Item StateBatch Transaction StatusDescription
completedpendingThe direct credit payment has been triggered, but the payment hasn’t yet been included in a batch for processing.
batchedThe payment has been included in a transaction batch, which is waiting to be processed.
bank_processingThe payment, along with other payments in the same batch, is already being processed by the bank.
successfulThe payment was successfully processed by the bank and the funds have now been credited to the seller’s bank account.
pendinginvalid_account_detailsThe payment wasn’t successful due to incorrect bank details.

Disbursements

Disbursement StateNPP Payout StateDescription
pendingnull / failedDirect credit payment has been triggered, but the payment hasn’t yet been included in a batch for processing.
bank_processingtryingReal time payout processing.
successfulnull / failedPayout was successfully processed by direct credit batch.
successfulPayout was successfully processed in real time.
invalid_account_detailsfailedInvalid bank account details provided. Funds remain in digital wallet.
cancelledfailedReal time payout failed. Funds returned to digital wallet.

Virtual account statuses (Australia)

The below table lists the different statuses a virtual account can transition into.

Virtual Account StatusDescription
pending_activationAs virtual account creation is an asynchronous process, this is the initial state in which a virtual account is created. This indicates it is not yet ready for payin reconciliations.
activeActive state indicates the virtual account is ready for payin reconciliations.
activation_failedIf activation fails due to some errors, the virtual account moves from pending_activation to activation_failed status and therefore cannot be used for payin reconciliations.

PayID Statuses (Australia)

The table below lists the different statuses a PayID can transition into.

PayID StatusDescription
pending_activationSince PayID registration is an asynchronous process, this is the initial status of the PayID. This indicates the PayID is not activated yet and therefore cannot be used for payin reconciliations yet.
activeActive status indicates the PayID is active and associated with a virtual account. It can be used for payin reconciliations.
activation_failedIf the PayID activation fails due to some errors, the PayID moves from pending_activation to activation_failed status and therefore cannot be used for payin reconciliations. Please try to register the PayID again.

PayTo Agreement Statuses (Australia)

The table below lists the different statuses a PayTo agreement can transition into.

PayTo Agreement StatusDescription
pending_validationSince agreement validation is an asynchronous process, this is the initial status of the agreement. This indicates the agreement validation request has been accepted and will be processed soon.
validatedThis indicates the agreement has been successfully validated by us and therefore can be created soon.
validation_failedThis indicates the validation of the agreement has failed due to some reason. The failure reason will be provided in WAPI notification and can also be fetched using the GET Agreement API.
pending_creationSince agreement creation is an asynchronous process, this is the initial status of the agreement creation step. This indicates the agreement creation request has been accepted and will be processed soon.
createdThis indicates the agreement has been successfully created with NPPA and is pending payer's approval due to which it cannot be used for payment initiations yet.
activeFor the AUPM agreement type, it indicates the payer has approved it.
For the MCGR agreement type, it indicates the agreement has been migrated successfully.

Overall, this status indicates the agreement is active and therefore payments can now be initiated as per the agreement terms and conditions.
creation_failedThis indicates the agreement creation has failed with NPPA due to some reason. The failure reason will be provided in WAPI notification and can also be fetched using the GET Agreement API.
suspendedThis indicates the agreement has been paused temporarily (either by the payer or by the initiator). Because the agreement is paused, payments cannot be initiated temporarily for the agreement.
cancelledThis indicates the agreement has been cancelled and is no longer available for payment initiations.
Cancelled is a final status and cannot be changed. If the initiator wants to initiate payments, they'd need to set up a new agreement with the payer.

Agreements can be cancelled due to the following reasons:
- Payer has cancelled and longer needs the goods or services provided by you.
- Initiator has cancelled because you no longer provide goods or services to your user.
- We cancelled the agreement because it is no longer valid and therefore not available for payment initiations (past the agreement validity end date).
- We cancelled the agreement after the last payment initiation completion.

PayTo Payment Initiation Request Statuses (Australia)

The table below lists the different statuses a PayTo payment initiation request can transition into.

Payment Initiation Request StatusDescription
pending_payment_initiationSince payment initiation for a PayTo agreement is an asynchronous process, this is the initial status of the request. This indicates the payment initiation request has been accepted and will be processed soon.
payment_initiatedThis indicates the payment has been requested from the payer's bank.
payment_initiation_completedThis indicates the payer's bank has cleared and settled a push payment towards Zai. Funds should soon be reconciled on your user's digital wallet in Zai.
payment_initiation_rejectedThis indicates the payment initiation request has been rejected to due to some reason. The failure reason will be provided in WAPI notification and can also be fetched using the GET Payment Initiation Request API.