How Payment Transfer APIs Work

This integration guide will take you through Zai’s bank-to-bank payin (collection) and payout (disbursement) options that are available to our customers located in the UK.

Key terminology

The following terminology is used throughout these guides:

• Platform​ refers to you as a Zai customer, or your website, application, or marketplace, etc.
• User​ refers to your customer who'll have a user record in Zai.
• Item​ is the mechanism for moving funds between users in the API.
• Float user is a user you may create, if required, to temporarily hold the balance of funds (float) you wish to split and transfer to multiple users' wallet accounts before you perform the payouts.
• Payin​ is money being paid into the Zai ecosystem from a bank account.
• Payout​ is money being paid out of the Zai ecosystem to a bank account.
• Customer reference number (CRN) is how payments are matched and is automatically generated and assigned to a user’s wallet account.
• Sort code is a 6-digit number that identifies your bank.

How payin payments are managed

Payments that come into Zai will fund a transaction between two users (a buyer and a seller) on your platform and can be pushed to us to match the target user’s account.

The following bank-to-bank transfer systems are available for payins (GBP):

• Bacs
• CHAPS
• FPS
• SWIFT

Your platform will be assigned a virtual account, which is made up of a unique bank account number used to collect funds. Note that these aren't stand-alone bank accounts or holding accounts. They’re only used in relation to payment flows, and for identification, they contain:

• an account number and sort code when used for domestic GBP payins.
• an International Bank Account Number (IBAN) and Bank Identifier Code (BIC) when sending funds to other countries where a user is outside of the UK. Your IBAN and BIC (also known as SWIFT code) are your account number and sort code written in a standard, internationally recognised format.

📘

Please note

In the UK, a virtual account is assigned at the platform level. This is different to a virtual accounts in Australia which is linked to an individual user's wallet.

As this is a unique account number, there are no additional, mandatory fields required and you can streamline the tracking, managing, and reconciliation of payments.

When users are created on your platform, a wallet account is generated by default. To identify users, a Customer Reference Number (CRN) is associated to the wallet. Once Zai receives the payin notification, we:

• validate the CRN details,
• process information within the payin notification,
• then use the CRN details to reconcile funds.

In the case of any unreconciled payin notifications (for example, if a CRN doesn’t exist in Zai), we’ll generate a payin return transaction, notifying the bank to return the funds.

How payout payments are managed

Payout disbursements are set up as bank transfers and funds are sent to your user’s bank once the payout request is completed.

The following bank-to-bank transfer systems are available for payouts (GBP):

• FPS
• CHAPS (payouts >£1m)
• SWIFT

Our withdraw funds API matches with a unique transaction ID that we refer to as a UUID and withdraws funds from the users wallet account to the specified bank account.

To identify your payout, we offer an optional field, reference_id to trigger the withdraw funds. This is unique reference information that can be specified for a wallet withdraw request. Once specified for the payout, you'll not be able to do a withdraw using the same reference_id if it's already been used.

We recommend that you create webhooks on the following objects to receive notifications from us of state and status changes:

• Transactions
• Items
• Users
• Batch Transactions
• Accounts

To create a webhook, you'd call ​POST/webhooks. More information on webhooks can be ​found here​. Also reference our Best Practices for Webhooks.

Once a payout transaction is completed and a payout response has been received, Zai will send you a webhook notification. This notification includes the payout and a status that defines an action towards a payout. The webhook notification you’ll receive is based on the response that we get from the bank.

Payout responses

• Successful — our bank has successfully debited the amount, and the user’s bank account has already credited the amount.
• Rejection — informs you that there are issues around the actual bank information, for example, if there are invalid bank account details.
• Payout reversal — if the bank is not able to settle funds into an account (while the bank account could be valid, but for some reason, not accepting any settlement) the bank will send payout reversal information to us.

Responses are added to the batch transaction webhooks and you’ll be sent a webhook notification when updates occur. You'll also see reason codes in the API to be able to talk to your bank if the response created isn't successful.