# Zai Documentation > Documentation for Zai ## Guides - [Developer Checklist](https://developer.hellozai.com/docs/developer-checklist.md) - [Build a Platform](https://developer.hellozai.com/docs/build-a-platform.md) - [Wallet Accounts](https://developer.hellozai.com/docs/wallet-accounts-1.md): Learn about user wallet accounts with Zai. - [Onboarding a Payin User](https://developer.hellozai.com/docs/onboarding-a-pay-in-user.md) - [CoP](https://developer.hellozai.com/docs/cop.md): Confirmation of Payee - [BPAY Payin Workflow](https://developer.hellozai.com/docs/bpay-payins-workflow.md) - [PayTo](https://developer.hellozai.com/docs/payto.md): A smarter, digital alternative to direct debit payment rails. - [WooCommerce](https://developer.hellozai.com/docs/woocommerce.md) - [3DS2](https://developer.hellozai.com/docs/3ds2.md) - [NPP Last Domestic Leg](https://developer.hellozai.com/docs/npp-last-domestic-leg.md) - [Webhooks](https://developer.hellozai.com/docs/webhooks.md): Use webhooks to enable Zai to push real-time notifications to your application. - [Verify Webhook Signatures](https://developer.hellozai.com/docs/verify-webhook-signatures.md): Use webhook signature verification for protection from a variety of attacks. - [Statuses](https://developer.hellozai.com/docs/statuses.md) - [Test Data](https://developer.hellozai.com/docs/test-data.md) ## API Reference - [Token](https://developer.hellozai.com/reference/token.md): Exchange client application credentials for a bearer token. Please ensure to call the auth issuing server as described at https://developer.assemblypayments.com/reference#authentication - [Show Address](https://developer.hellozai.com/reference/showaddress.md): Show details of a specific Address using a given address `:id`. - [Overview](https://developer.hellozai.com/reference/overview.md) - [Show Bank Account](https://developer.hellozai.com/reference/showbankaccount.md): Show details of a specific **Bank Account** using a given `:id`. - [Redact Bank Account](https://developer.hellozai.com/reference/redactbankaccount.md): Redact a **Bank Account** using a given `:id`. Redacted **Bank Accounts** can no longer be used as a funding source or a Disbursement destination. - [Send Penny Amount](https://developer.hellozai.com/reference/sendpennyamount.md): When penny verification is enabled, this API call sends two penny transactions to the specified bank account for verification. **Note**: This API call is not required when your platform has automatic penny verification enabled, as this is instead done by the system. Penny credit verification is only supported for US platforms. - [Create Bank Account](https://developer.hellozai.com/reference/createbankaccount.md): Create a **Bank Account** to be used as either a funding source or a Disbursement destination. Store the returned `:id` and use it for a `make_payment` **Item Action** call. The `:id` is also referred to as a `token` when involving **Bank Accounts**. - [Verify Penny Amount](https://developer.hellozai.com/reference/verifypennyamount.md): When penny verification is enabled, this API call verifies the two penny transactions that were sent to a specified bank account using **Send Penny Amount**. **Note**: This API call requires you to provide a front-end interface to your end-users into which they can input the penny amounts required for a successful verification. Your front-end interface should then pass the information into this API call. Penny credit verification is only supported for US platforms. - [Show Bank Account User](https://developer.hellozai.com/reference/showbankaccountuser.md): Show the **User** the **Bank Account** is associated with using a given `:id`. - [Validate Routing Number](https://developer.hellozai.com/reference/validateroutingnumber.md): Validate a US bank routing number before creating an account. This can be used to provide on-demand verification, and further information of the bank information a User is providing. - [Show BPay Account](https://developer.hellozai.com/reference/showbpayaccount.md): Show details of a specific **BPay Account** using a given `:id`. - [Create BPay Account](https://developer.hellozai.com/reference/createbpayaccount.md): Create a **BPay Account** to be used as a Disbursement destination. - [Show BPay Account User](https://developer.hellozai.com/reference/showbpayaccountuser.md): Show the **User** the **BPay Account** is associated with using a given `:id`. - [Pay a Bill](https://developer.hellozai.com/reference/billpayment.md): Pay a bill by withdrawing funds from a **Wallet Account** to a specified bpay account. - [Show Wallet Account User](https://developer.hellozai.com/reference/showwalletaccountuser.md): Show the **User** the **Wallet Account** is associated with using a given `:id`. - [Withdraw Funds](https://developer.hellozai.com/reference/withdrawfunds.md): Withdraw funds from a **Wallet Account** to a specified disbursement account. - [Show Wallet Account](https://developer.hellozai.com/reference/showwalletaccount.md): Show details of a specific **Wallet Account** using a given `:id.` - [Show Wallet Account NPP Details](https://developer.hellozai.com/reference/showwalletaccountnppdetails.md): Show NPP details of a specific **Wallet Account** using a given `:id.` - [Show Wallet Account BPAY Details](https://developer.hellozai.com/reference/showwalletaccountnbpaydetails.md): Show BPAY details of a specific **Wallet Account** using a given `:id.` - [Initiate Last Domestic Leg Payout](https://developer.hellozai.com/reference/npplastdomesticleg.md): Facilitate the real-time settlement of the last domestic leg payout for International Funds Transfer Instructions (IFTI) through NPP rails. - [List Sub-wallets](https://developer.hellozai.com/reference/listsubwallets.md): List all the sub-wallets that belong to a user's wallet account. These are specified by the wallet `account_id`. - [Create Sub-wallet](https://developer.hellozai.com/reference/createsubwallet.md): Create a sub-wallet for a user's wallet account.This is specified by the wallet `account_id`. Use sub-wallets as a part of building your own scheduling and workflow. Create as many as you want to manage, with no limits to the amount. - [Show Sub-wallet](https://developer.hellozai.com/reference/showsubwallet.md): Show details of a specific sub-wallet using the given`:id`. - [Redact Sub-wallet](https://developer.hellozai.com/reference/deletesubwallet.md): Redact a sub-wallet using the given `:id`. Only sub-wallets with zero balance can be redacted. Once this is done, the sub-wallet can no longer be used as a funding source. - [Update Sub-wallet](https://developer.hellozai.com/reference/updatesubwallet.md): Update an existing sub-wallet using the given `:id`. You can change the `name` of an enabled sub-wallet. You can change the `active` status of a `redacted` sub-wallet. - [Fund transfers](https://developer.hellozai.com/reference/transfersubwallet.md): Fund transfers between a wallet account and its sub-wallet as well as between any sub-wallets that belong to the same wallet account. The `source` and `destination` accounts must be `active` and use the same currency. - [List Sub-wallet transactions](https://developer.hellozai.com/reference/showsubwallettransactions.md): List all transactions of a sub-wallet using the given `:id`. - [Pay a Bill](https://developer.hellozai.com/reference/billpaymentsubwallet.md): Pay a bill to a specified BPAY account that's associated with its `account_id` by withdrawing funds from a sub-wallet using the given `id`. - [Withdraw Funds](https://developer.hellozai.com/reference/withdrawfundssubwallet.md): Withdraw funds from a sub-wallet using the given `id` and move the specified amount to a disbursement account associated with the `account_id`. - [Show Sub-wallet User](https://developer.hellozai.com/reference/showsubwalletuser.md): Show the user that a sub-wallet is associated with using the given `:id`. - [Show the Wallet Account of a Sub-wallet](https://developer.hellozai.com/reference/showsubwalletwalletaccount.md): Show the details of the wallet account that a sub-wallet is associated with using the given `:id`. - [List User's BPay Accounts](https://developer.hellozai.com/reference/listuserbpayaccounts.md): List the **BPay Accounts** the **User** is associated with using a given `:id`. - [Show User Card Account](https://developer.hellozai.com/reference/showusercardaccount.md): Show the user's active card account using a given `:id`. - [Show User](https://developer.hellozai.com/reference/showuser.md): Show details of a specific User using a given `:id`. - [Update User](https://developer.hellozai.com/reference/updateuser.md): Update an existing **User's** attributes using a given `:id`. - [Verify User (Prelive Only)](https://developer.hellozai.com/reference/verifyuser.md): Sets a user's verification state to `approved` on pre-live given the **User** `:id`. Ensure that a **User** has the required user verification information before using this call, otherwise the call will fail. **Note**: This API call will only work in our pre-live environment. The user verification workflow holds for all users in production. - [Show User Bank Account](https://developer.hellozai.com/reference/showuserbankaccount.md): Shows the user's active bank account using a given `:id`. - [Set User Disbursement Account](https://developer.hellozai.com/reference/setuserdisbursementaccount.md): Set the **User's Disbursement Account** using a given **User** `:id` and a **Bank Account** `:account_id`. - [List Users](https://developer.hellozai.com/reference/listusers.md): Retrieve an ordered and paginated list of existing **Users**. - [Create User](https://developer.hellozai.com/reference/createuser.md): Create a **User** that can be associated with **Items** as either a buyer or a seller. **Users** can't be both the buyer and seller for the same **Item**. You can also use this endpoint to create a **company** for the user. To create a company for the user, you need to send company parameters in the same request. **Note**: Some parameters are required for user verification. See our guide on [Onboarding a Payout User/Seller](https://developer.hellozai.com/docs/onboarding-a-pay-out-user) for more information. - [List User Items](https://developer.hellozai.com/reference/listuseritems.md): Retrieve an ordered and paginated list of existing **Items** the **User** is associated with using a given `:id`. - [Show User Wallet Account](https://developer.hellozai.com/reference/showuserwalletaccounts.md): Show the **User's Wallet Account** using a given `:id`. - [Show Callback](https://developer.hellozai.com/reference/showcallback.md): Show details of a specific **Callback** using a given `:id`. - [Delete Callback](https://developer.hellozai.com/reference/deletecallback.md): Delete an existing Callback using a given `:id`. - [Update Callback](https://developer.hellozai.com/reference/updatecallback.md): Update an existing **Callback** using a given `:id`. You can change the `URL`, the `object_type` and whether the **Callback** is `enabled` or `disabled`. - [List Callback Responses](https://developer.hellozai.com/reference/listcallbackresponse.md): Retrieve an ordered and paginated list of the responses garnered from a callback using a given `:id`. - [Show Callback Response](https://developer.hellozai.com/reference/showcallbackresponse.md): Show details of a specific **Callback** response using a given `:id`. - [List Callbacks](https://developer.hellozai.com/reference/listcallbacks.md): Retrieve an ordered and paginated list of all created **Callbacks**. - [Create Callback](https://developer.hellozai.com/reference/createcallback.md): Create a **Callback** to notify you at the `URL` when the `object_type` changes - [Create Card Account](https://developer.hellozai.com/reference/createcardaccount.md): Create a Credit **Card Account** to be used as a funding source. Store the returned `:id` and use it for a `make_payment` **Item Action** call. The `:id` is also referred to as a **token** when involving Credit Cards. - [Show Card Account User](https://developer.hellozai.com/reference/showcardaccountuser.md): Show the **User** the Credit **Card Account** is associated with using a given `:id`. - [Verify Card](https://developer.hellozai.com/reference/verifycard.md): Where pre-authorization is enabled on a platform, verifies a **Card Account** when a **Card Account** is successfully verified, its verification status is `verified`. - [Show Card Account](https://developer.hellozai.com/reference/showcardaccount.md): Show details of a specific Credit **Card Account** using a given `:id`. You can toggle the card account number display to show the first 6 digits in addition to the last 4 digits. Contact Assembly if you want to toggle the card account display. - [Redact Card Account](https://developer.hellozai.com/reference/redactcardaccount.md): Redact a Credit **Card Account** using a given `:id`. Redacted Credit **Card Accounts** can no longer be used as a funding source. - [List Companies](https://developer.hellozai.com/reference/listcompanies.md): Retrieve an ordered and paginated list of existing **Companies**. - [Create Company](https://developer.hellozai.com/reference/createcompany.md): Create a **Company** associated with the **User** using a given `user_id`. **Note**: Some parameters are required for user verification. See our guide on [Onboarding a Payout User/Seller](https://developer.assemblypayments.com/docs/onboarding-a-pay-out-user) for more information. - [Show Company](https://developer.hellozai.com/reference/showcompany.md): Show details of a specific **Company** using a given `:id`. - [Update Company](https://developer.hellozai.com/reference/updatecompany.md): Update an existing **Company** attributes using a given `:id`. - [List Direct Debit Authorities](https://developer.hellozai.com/reference/listdirectdebitauthorities.md): Retrieve an ordered and paginated list of existing **Direct Debit Authorities**. - [Create Direct Debit Authority](https://developer.hellozai.com/reference/createdirectdebitauthority.md): Create a **Direct Debit Authority** associated with a **Bank Account**. The **Direct Debit Authority** is required to use a **Bank Account** as a funding source (Direct Debit/ACH). - [Show Direct Debit Authority](https://developer.hellozai.com/reference/showdirectdebitauthority.md): Show details of a specific **Direct Debit Authority** using a given `:id`. - [List Fees](https://developer.hellozai.com/reference/listfees.md): Retrieve an ordered and paginated list of existing **Fees**. - [Create fee](https://developer.hellozai.com/reference/createfee.md): Create a **Fee** to be associated with an **Item**. **Fees** will add or subtract from the **Item** amount based on the **User**, payment type or Disbursement account type. **Fees** can be `Fixed` or `Percentage` based. **Fees** can be capped, have a maximum amount and/or a minimum amount. - [Show Fee](https://developer.hellozai.com/reference/showfee.md): Show details of a specific **Fee** using a given `:id`. If the `item_amount` is specified, the response also shows the `calculated_fee` based on a percentage of the `item_amount`. - [List Charges](https://developer.hellozai.com/reference/listcharges.md): Retrieve an ordered and paginated list of **Charges**. - [Create Charge](https://developer.hellozai.com/reference/createcharge.md): Create a **Charge**. **Charges** require a specified **Card Account** or **Bank Account**. You may pass through an existing **User**, or define the `user_id` of the new user that will be associated with the **Charge** and the provided Account. The `user_id` can be left blank if you wish for a new user to be created for the **Charge**, or specified if you wish for a new **User** to be created with the passed `user_id`. - [Show Charge](https://developer.hellozai.com/reference/showcharge.md): Show details of a specific **Charge** using a given `:id`. - [Show Charge Status](https://developer.hellozai.com/reference/showchargestatus.md): Show status of a specific **Charge** using a given `:id`. - [Show Charge Buyer](https://developer.hellozai.com/reference/showchargebuyer.md): Show the buyer **User** associated with the **Charge** using a given `:id`. - [Show Marketplace](https://developer.hellozai.com/reference/showmarketplace.md): Show details of your **Platform**, providing access to your configuration and related **User** and **Company**. - [Generate Token](https://developer.hellozai.com/reference/generatetoken.md): Create a token, either for a bank or a card account, that can be used with the **PromisePay.js** package to securely send Assembly credit card details. - [Health check](https://developer.hellozai.com/reference/healthcheck.md): Displays a health check of the Assembly service. - [List Transactions](https://developer.hellozai.com/reference/listtransactions.md): Retrieve an ordered and paginated list of **Transactions**. Note: `created_before` and `created_after` range can not be greater than 31 days - [Show Transaction Bank Account](https://developer.hellozai.com/reference/showtransactionbankaccount.md): Show the **Bank Account** associated with the **Transaction** using a given `:id`. - [Show Transaction](https://developer.hellozai.com/reference/showtransaction.md): Show details of a specific **Transaction** using a given `:id`. - [Show Transaction Card Account](https://developer.hellozai.com/reference/showtransactioncardaccount.md): Show the **Card Account** associated with the **Transaction** using a given `:id`. - [Show Transaction Fees](https://developer.hellozai.com/reference/showtransactionfees.md): Show the **Fees** associated with the **Transaction** using a given `:id`. - [Show Transaction Wallet Account](https://developer.hellozai.com/reference/showtransactionwalletaccount.md): Show the **Wallet Account** associated with the **Transaction** using a given `:id`. - [Show Transaction User](https://developer.hellozai.com/reference/showtransactionuser.md): Show the **User** associated with the **Transaction** using a given `:id`. - [List Batch Transactions](https://developer.hellozai.com/reference/listbatchtransactions.md): Retrieve an ordered and paginated list of existing **Batch Transactions**. The list can be filtered by **Account**, **Batch ID**, **Item**, and **Transaction Type**. - [Show Batch Transaction](https://developer.hellozai.com/reference/showbatchtransaction.md): Get a batch transaction using its ID - [List Disbursements](https://developer.hellozai.com/reference/listdisbursement.md): Retrieve an ordered and paginated list of existing **Disbursements**. The list can be filtered by **Batch ID**. - [Show Disbursement](https://developer.hellozai.com/reference/showdisbursement.md): Get a disbursment using its ID - [Show Disbursement Transactions](https://developer.hellozai.com/reference/showdisbursementtransactions.md): Get all the transactions relating to a disbursment ID - [Show Disbursement Wallet Accounts](https://developer.hellozai.com/reference/showdisbursementwalletaccounts.md): Get all the wallet accounts relating to a disbursment ID - [Show Disbursement Bank Accounts](https://developer.hellozai.com/reference/showdisbursementbankaccounts.md): Get all the bank accounts relating to disbursement ID - [Show Disbursement Users](https://developer.hellozai.com/reference/showdisbursementusers.md): Get all the users relating to disbursement ID - [Show Disbursement Items](https://developer.hellozai.com/reference/showdisbursementitems.md): Get all the items relating to a disbursement ID - [List Items](https://developer.hellozai.com/reference/listitems.md): OK - [Create Item](https://developer.hellozai.com/reference/createitem.md): Create an **Item**. Items require two **Users**, a buyer and a seller. The `buyer_id` and `seller_id` are your unique user identifiers. - [Show Item](https://developer.hellozai.com/reference/showitem.md): Show details of a specific **Item** using a given `:id`. - [Delete Item](https://developer.hellozai.com/reference/deleteitem.md): Delete an existing **Item** using a given `:id`. - [Update Item](https://developer.hellozai.com/reference/updateitem.md): Update an existing **Items** attributes using a given `:id`. Note: An item can only be updated if it's in `pending` state. Once an item has begun a payment process, you cannot update it. - [Show Item Seller](https://developer.hellozai.com/reference/showitemseller.md): Show the seller **User** associated with the **Item** using a given `:id`. - [Show Item Buyer](https://developer.hellozai.com/reference/showitembuyer.md): Show the buyer **User** associated with the **Item** using a given `:id`. - [Show Item Fees](https://developer.hellozai.com/reference/showitemfees.md): Show the **Fees** associated with the **Item** using a given `:id`. - [Show Item Wire Details](https://developer.hellozai.com/reference/showitemwiredetails.md): Show the **Item** wire payment details using a given `:id`. - [List Item Transactions](https://developer.hellozai.com/reference/listitemtransactions.md): Retrieve an ordered and paginated list of **Transactions** associated with the **Item** using a given `:id`. - [List Item Batch Transactions](https://developer.hellozai.com/reference/listitembatchtransactions.md): Retrieve an ordered and paginated list of **Batch Transactions** associated with the `Item` using a given `:id`. This will include both direct debits coming in, and the disbursements going out. - [Show Item Status](https://developer.hellozai.com/reference/showitemstatus.md): Show the status of an **Item** using a given `:id`. - [Make Payment](https://developer.hellozai.com/reference/makepayment.md): Make a payment for an **Item**. Pass the `:account_id` of a **Bank Account** or a **Card Account** associated with the **Item's** buyer. The **Item** state will transition to one of `payment_held`, `payment_pending` or `completed` for an **Express** or **Approve** payment type. - [Cancel](https://developer.hellozai.com/reference/cancelitem.md): Cancel an **Item**. This will transition the **Item** state to `cancelled`. **Items** can only be cancelled if they haven't been actioned in any other way. - [Refund](https://developer.hellozai.com/reference/refund.md): Refund an **Item**'s funds. A partial `amount` can be specified otherwise the full amount will be refunded. This will transition the **Item** state to 'refunded' if the full amount is refunded, or to the previously held state if a partial `amount` is specified. - [Authorize Payment](https://developer.hellozai.com/reference/authorizepayment.md): Where pre-authentication is enabled on a platform, initiates a credit card payment authorization for an item. When an authorization is successful, your platform holds the item amount for capture, but there is no transfer of funds happening. This call is used with the Capture Payment or Void Payment calls. - [Capture Payment](https://developer.hellozai.com/reference/capturepayment.md): Where pre-authentication is enabled on a platform, completes a credit card payment for an item whose payment is authorized. This call is used with the Authorize Payment call. - [Void Payment](https://developer.hellozai.com/reference/voidpayment.md): Where pre-authentication is enabled on a platform, voids the `payment_authorized` status for an item. This call is used with the Authorize Payment call. **Note**: Not all payment gateways support the Void Payment API call. In this case, you can wait until a payment authorization expires. A payment authorisation expires after 3 to 6 days if not captured. - [Release Payment (Deprecated - Do Not Use)](https://developer.hellozai.com/reference/releasepayment.md): Included for legacy purposes for existing customers that use Escrow payments which are no longer supported for new flows/customers. Release funds held in escrow from an **Item** with an **Escrow** or **Escrow Partial Release** payment type. This will transition the **Item** state to `completed`. - [Make an async Payment](https://developer.hellozai.com/reference/makepaymentasync.md): Initiate a card payment with 3D Secure 2.0 authentication support. This endpoint initiates the payment process and returns a `payment_token` required for 3DS2 component initialisation. - [Overview](https://developer.hellozai.com/reference/overview-va.md) - [Create Virtual Account](https://developer.hellozai.com/reference/createvirtualaccount.md): Create a _Virtual Account_ for a given _Wallet Account_. - [List Virtual Accounts](https://developer.hellozai.com/reference/listvirtualaccountbywalletaccount.md): List _Virtual Accounts_ for a given _Wallet Account_. - [Show Virtual Account](https://developer.hellozai.com/reference/showvirtualaccount.md): Show details of a specific _Virtual Account_ using the given `id`. - [Update AKA Names](https://developer.hellozai.com/reference/updatevirtualaccountakaname.md): Replace the list of AKA Names for a _Virtual Account_. - [Update Account Name](https://developer.hellozai.com/reference/updatevirtualaccountaccountname.md): Change the name of a _Virtual Account_. - [Update Virtual Account Status](https://developer.hellozai.com/reference/updatevirtualaccount.md): Update the status of a _Virtual Account_. - [Register PayID](https://developer.hellozai.com/reference/registerpayid.md): Register a _PayID_ for a given _Virtual Account_. - [Update PayID Status](https://developer.hellozai.com/reference/updatepayidstatus.md): Update the status of the _PayID_. - [Retrieve a PayID](https://developer.hellozai.com/reference/getpayid.md): Retrieve the details of a specific _PayID_ using the unique id parameter `id`. Only one _PayID_ record is returned. - [Overview](https://developer.hellozai.com/reference/overview-1.md) - [Initiate PayTo Payment](https://developer.hellozai.com/reference/initiatepaymentrequest.md): This endpoint is to initiate a payment to collect funds from the debtor's account or to retry if the previous payment collection request was rejected due to valid business reasons. This API should be invoked strictly as per the terms and conditions established in the agreement to avoid payment claims. Even the retries should be attempted as per the agreement terms and conditions. Payment initiation request statuses - - PENDING_PAYMENT_INITIATION - when the payment initiation request has been accepted for processing - PAYMENT_INITIATED - when the payment initiation request is being processed - PAYMENT_INITIATION_COMPLETED - when the payment initiation request is cleared and settled successfully. Funds can be expected in the user's wallet soon - PAYMENT_INITIATION_REJECTED - when the payment initiation request is rejected for processing due to validation, funds not available in the debtor's account or any other business reason. A retry can be performed in such scenarios If the payment collection request has been rejected due to valid business reasons (example - insufficient funds), a retry can be attempted 5 times within 24 hours for the same request. Payment_request_uuid generated will be the same for the payment collection request and all subsequent retry attempts, however, instruction_id differs for each. Note - If Payment initiated on the agreement validity end date fails, it will not be possible to retry or initiate again on the following date as the agreement will be marked as CANCELLED automatically after the agreement validity_end_date. Hence, it is recommended to initiate the last payment few days before the agreement validity end date to cater for retries needed if any. - [Get PayTo Payment Initiation Request Details](https://developer.hellozai.com/reference/getinitiatepaymentstatus.md): This operation is to retrieve details of an initiated payment request. This API should be invoked to know the latest status of the payment initiation request if needed. Payment initiation request statuses which will be returned via this endpoint - - PENDING_PAYMENT_INITIATION - when the payment initiation request has been accepted for processing - PAYMENT_INITIATED - when the payment initiation request is being processed - PAYMENT_INITIATION_COMPLETED - when the payment initiation request is cleared and settled successfully. Funds can be expected in the user's wallet soon - PAYMENT_INITIATION_REJECTED - when the payment initiation request is rejected for processing due to validation, funds not available in the debtor's account or any other business reason. A retry can be performed in such scenarios - [Get All PayTo Payment Initiation Requests for an Agreement](https://developer.hellozai.com/reference/getinitiatepaymentstatuslist.md): This operation is to retrieve all payment requests initiated for an agreement in the provided period (date range). Payment requests for a period of maximum one year or less than it can be retrieved at a time. By default, all payment initiation requests (along with details) irrespective of the status will be listed via this endpoint. However, the results can be filtered based on status(es) if needed. Request parameter descriptions: - status - List of valid agreement statuses. Example - Retrieve active and suspended payments only. - Valid values - PENDING_PAYMENT_INITIATION, PAYMENT_INITIATED, PAYMENT_INITIATION_COMPLETED, PAYMENT_INITIATION_REJECTED - start_date - Date range start, example - fetch all payments created between June to December 2022. - end_date - Date range end, example - fetch all payments created between June to December 2022. - size - Number of payments per page. Default value is 20. - page - Page number. Default value is 0. - [Create PayTo Agreement](https://developer.hellozai.com/reference/createagreement.md): This operation creates the agreement with NPPA and hence must be invoked only after validating the agreement via the “Validate PayTo Agreement” operation. It should be invoked immediately once the agreement has been validated successfully and resolved PayID details are confirmed with the user. Agreement Creation will be successful only if it is performed within 5 minutes post successful validation. Post successful creation, agreement id (generated by NPPA) which uniquely identifies the agreement will be notified. Note - AUPM agreements will be ACTIVE only post debtor authorization. By default (if custom expiry duration is not provided via response_requested_by field), debtor will have 5 days to authorise the agreement, post which the authorization request will expire automatically. The agreement will be marked as CANCELLED after the 6th day if not CANCELLED automatically by the payer institution after the 5th day. MGCR agreements will be ACTIVE immediately post creation however, payments can be initiated only after 5 calendar days. - [Validate PayTo Agreement](https://developer.hellozai.com/reference/validateagreement.md): Validate PayTo agreement details before creation. This operation must be invoked first, followed by the “Create PayTo Agreement” operation. This operation validates the details of the agreements along with ensuring the debtor and creditor are NPP and PayTo reachable before the actual agreement creation with NPPA. PayID details provided for the debtor are also resolved as part of this operation. Customers should share the resolved PayID details with their users for confirmation before the actual agreement creation. Post successful validation, agreement UUID is returned in the response which uniquely identifies the agreement. This UUID should be used in subsequent API calls for that particular agreement. Note - Zai may reformat the debtor account number if it is not as per the format expected by payer institutions. Reformatted debtor account number can be accessed either via GET PayTo Agreement Details API after the validation step or via WAPI notification sent by Zai after successful agreement creation step. - [Amend PayTo Agreement Status](https://developer.hellozai.com/reference/amendagreementstatus.md): Amend Status of a particular agreement via its UUID. Below status amends are possible via this API: - ACTIVE -> SUSPENDED - ACTIVE -> CANCELLED - SUSPENDED -> ACTIVE (only if suspended via Zai) - SUSPENDED -> CANCELLED Only one status amendment is allowed at any given point of time. Example - If a request to suspend the agreement is already in progress, another status change request will not be accepted until the first completes. Resuming a suspended agreement can only be performed by the party that suspended the agreement. Hence, moving the agreement from SUSPENDED to ACTIVE will be accepted only if the Suspension was performed via Zai. CANCELLED is final agreement status and hence is irreversible. - [Recall PayTo Agreement](https://developer.hellozai.com/reference/recallagreementaction.md): This operation is to recall a pending agreement creation/bilateral amendment authorisation request before it is approved by debtor. By default, all debtor authorization requests expire after 5 days post creation. If a custom expiry duration (anything less than 5 days) has been specified in the request via “response_requested_by” field, then this Recall API should be invoke to expire the authorisation request post the custom duration has elapsed. Example - For a use-case, if the debtor should approve/reject the agreement within 15 mins post creation, and if the debtor does not respond within 15 mins, this API should be invoked to recall the agreement creation action post 15 mins. Recall Agreement Creation - If a custom expiry duration is specified during agreement validation step, this API should be used to recall the pending agreement creation authorisation request. - Allows recalling agreement authorisation request only for AUPM agreement type. - After the recall operation is successful, the current agreement would be considered as CANCELLED and a new agreement should be created to seek the debtor’s approval again. Recall Bilateral Amendment Request - If a custom expiry duration is specified during bilateral agreement amendment, this API should be used to recall the pending amendment authorisation request. - Allows recalling amendment authorisation requests for both AUPM and MGCR agreement types. - After the recall operation is successful, the bilateral amendments are discarded and the agreement is not updated. If the changes are still needed, a new amendment request should be created to seek the debtor’s approval again. - [Amend PayTo Agreement Details](https://developer.hellozai.com/reference/amendagreementdetails.md): Amend details of a particular agreement via its UUID. There are two types of amendments possible via this operation: - Unilateral amendments - which does not need debtor approval and will be effective immediately - Bilateral amendments - which does require debtor approval and will be effective post debtor authorisation Optional fields can also be cleared via an amend request if needed. Passing an hyphen(-) character for any optional field would indicate its value needs to be cleared. Either unilateral or bilateral amendments will be accepted in an amendment request. Both types of amendments cannot be provided in a single request. At any given point of time, only a single unilateral or a single bilateral amendment will be allowed. Example - If a bilateral amendment is already in progress, another bilateral amendment request will not be accepted until the first completes. Unilateral details that can be amended: - description - short_description - creditor_info - payment_initiator_info Bilateral details that can be amended: - validity_end_date - transfer_arrangement - automatic_renewal - payment_terms - payment_amount_info, first_payment_info, last_payment_info, maximum_amount_info and point_in_time can be amended at any point however frequency and count_per_period can be amended only if no payments have been requested for the agreement yet. Note - Bilateral amendments will be effective only post debtor authorization. Debtor should authorize the amendments within 5 days (default duration) or within the custom expiry duration (response_requested_by) specified in the amendment request. - [Get PayTo Agreement Details](https://developer.hellozai.com/reference/getagreementdetails.md): Retrieve details of a PayTo agreement by UUID which uniquely identifies the agreement. This UUID is returned as part of the “Validate PayTo Agreement” operation. It provides complete details of a particular agreement irrespective of its current status - [Get All PayTo Agreements for a User](https://developer.hellozai.com/reference/getagreementsbyuser.md): This operation is to retrieve all PayTo agreements associated with a particular user in the provided period (date range). Agreements can be retrieved for a maximum period of one year or less at a time i.e. the period between start and end date cannot exceed more than one year. By default, all agreements will be returned irrespective of status and type (AUPM/MGCR). However, if required, results can be filtered for a particular status or agreement type. Example - Retrieve all suspended and cancelled migrated agreements. Request parameter descriptions: - user_external_id - Unique identifier of the user that is associated with the agreement. - status - List of valid agreement statuses. Example - Retrieve active and suspended agreements only. - Valid values - PENDING_VALIDATION, VALIDATED, PENDING_CREATION, CREATED, ACTIVE, SUSPENDED, CANCELLED - agreement_type - List of valid agreement types. Example - Retrieve only migrated agreements. - Valid values - AUPM, MGCR - start_date - Date range start, example - fetch all agreements created between June to December 2022. - end_date - Date range end, example - fetch all agreements created between June to December 2022. - size - Number of agreements per page. Default value is 20. - page - Page number. Default value is 0. - [Overview](https://developer.hellozai.com/reference/webhooks-overview.md) - [Overview](https://developer.hellozai.com/reference/async-overview.md)