Getting started with Zwitch Transfers API

Bank transfers are hard for businesses. Most of the businesses would’ve experienced interruptions in doing transfers because of fixed banking hours. 

Delayed payments often lead to a stoppage in services. Automated payouts can help your business maintain a reliable cash flow in operation, enhance invoicing and the payments process, and save time and effort. 

At Zwitch, we make it easier for your business to solve all your payouts related problems in a matter of seconds. Zwitch Transfers API can be used for automated payouts from virtual accounts or an existing current account (currently supported for ICICI bank only and support for YES Bank, Axis Bank is coming soon).

Let’s get started.

Setup automated transfers using Transfers API

Zwitch Transfers API helps you transfer money from a virtual account or an ICICI current account. These transfers can be made from:

(i) a virtual account to a bank account, or

(ii) from a virtual account to another virtual account created as a wallet, or

(iii) from an existing ICICI bank current account linked using Zwitch APIs to any other bank account.

However, before making payment, you need to make sure that a beneficiary is added to the account from where you are initiating the transfers.

Before we discuss more about the Transfers API, let’s first understand how to create a beneficiary on the debit account from where the transfer happens. As mentioned above, this debit account could be your primary virtual account or customers’ virtual account (if you want to enable the “withdraw money to bank account” facility for your customers) or your linked ICICI bank current account.

Create a beneficiary

To initiate transactions from the virtual accounts, you need to add beneficiaries in the debit account. This is required only in case you are initiating transfers from a virtual account or from your linked ICICI bank current account to a bank account. 

If you are doing transfers from one virtual account to another virtual account created as a wallet, you can simply initiate the transfer via the Transfers API without adding beneficiaries.

While creating beneficiaries using Zwitch APIs, you can either pass account type as account_number or vpa handle to which the amount needs to be transferred. 

The other mandatory parameters to be included in the request body are:

• email
• phone
• name_of_account_holder

If you are passing the value of parameter type as account_number, then you need to pass the following additional parameters in the request body:-

• bank_account_number – Account number to which the amount needs to be transferred,
• bank_name – Name of the bank,
• bank_ifsc_code – IFSC code of the bank.

If you are passing the value of parameter type as vpa, then VPA needs to be included as additional parameters in the request body other than email, phone, and name_of_account_holder.

Depending on the value of type parameter, here is how the sample request body would look like:

curl --request POST \
     --url https://api.zwitch.io/v1/accounts/<debit_va_id>/beneficiaries \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <access_key>:<secret_key>' \
     --header 'Content-Type: application/json' \
     --data '
{
     "type": "account_number",
     "email": "[email protected]",
     "phone": "9675196666",
     "name_of_account_holder": "John Doe",
     "bank_account_number": "363636514348445576",
     "bank_ifsc_code": "YESB0CMSNOC",
     "bank_name": "Yes Bank",
     "vpa": "9675196666@upi"
}
'

Note: Make sure to update the <debit_va_id> with the Virtual Account’s ID or the linked ICICI bank Current Account’s ID from where the amount needs to be debited. You can find this ID from your Zwitch’s Sandbox Dashboard in the “Manage Keys” section under the column “ID” or returned in the response body when linking the account using our APIs.

Once the beneficiary is successfully created, you will get the beneficiary id as highlighted in the code below in your response body. The beneficiary ID will be used in the Transfers API to transfer the amount.

{
"id":"vab_2EL60lbRVG2rT4Z2mY4RY35I9"
"object":"beneficiary"
"type":"account_number"
"name_of_account_holder":"John Doe"
"email":"[email protected]"
"phone":"9675196666"
"bank_account_number":"363636514348445576"
"bank_ifsc_code":"YESB0CMSNOC"
"bank_name":"Yes Bank"
"vpa": "9675196666@upi"
"is_sandbox":false
}

There are other processes that you can do using Beneficiaries API. They are:

• Get beneficiary – To list details of a particular beneficiary,
• List all beneficiaries – To list all beneficiaries created under a virtual account, and
• Delete a beneficiary – To delete a particular beneficiary

Create a Transfer

To initiate a transfer, you’ve to pass the following parameters in the request body:

• The value of type could be account_number or vpa depending on the type of beneficiary added. In the case of virtual account to virtual account transfer, no beneficiary creation is required and the value of type should be wallet, 
• debit_account_id – The account id from which the amount will be transferred, 
• credit_account_id – The account id to which the amount will be credited (mandatory in case type is wallet),
• beneficiary_id – This is created using the above process (mandatory in case type is account_number or vpa),
• amount – The amount to be transferred,
• currency_code – It should be inr, and
• merchant_reference_id – A unique string that will identify the payouts

Here is a sample request body in case the beneficiary added is a Virtual Payment Address handle:

curl --request POST \
     --url https://api.zwitch.io/v1/transfers \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <access_key>:<secret_key>'' \
     --header 'Content-Type: application/json' \
     --data '
{
     "debit_account_id": "va_9KOI7QEqOADbDYII3NsI8GRJE",
     "type": "vpa",
     "amount": 1,
     "currency_code": "inr",
     "beneficiary_id": "vab_2EL60lbRVG2rT4Z2mY4RY35I9",
     "merchant_reference_id": "testtransfer"
}
'

You have to pass these additional parameters as well:

• payment_mode – Values can be imps, neft and rtgs and mandatory when the type is account_number
• payment_remark – This appears in the bank account statement. However, it may not be available on some beneficiary banks.
• async – by default the value is false. If it is made true, then transfers will happen asynchronously
• metadata –  additional parameters such as order id which you might require in the response

You’ll get the following response from the APIs if the amount is credited to a bank account and not on a VPA handle or other virtual account, on completing transfer successfully:

{
    "id": "tr_nrAyzIQHt888jDGQtCDegBqoR",
    "object": "transfer",
    "type": "account_number",
    "amount": 1,
    "transacted_at": 1622531493,
    "created_at": 1622531489,
    "status": "success",
    "bank_reference_number": "115212968196",
    "payment_mode": "imps",
    "paid_to": "67334963307",
    "merchant_reference_id": "456167114"
}

You can also take care of other processes with the Transfers API. They are:

• Retrieve transfer – Gets details of a particular transaction when the transaction id is passed
• List all transfers – This fetches the transfers created after and before a specific transaction. It also allows you to control how many transactions to be displayed on a single page with the default being 10 transactions and the maximum being 100 transactions.

Instant transfers are a great enhancement for a rich customer experience. Most of the startups leverage transfers to grow fast and become among the large players over a very short span of time. Now is the time to automate transfer flow across your business. 

To learn more about Beneficiaries and Transfers API, read our documentation here.