Community

Integration Flow - Virtual Account Wallets

Learn how you can use ZWITCH to create a virtual account wallet from your application.

Suggest Edits

Functionally, wallets are similar to physical accounts. They come with an account number, IFSC, and VPA handle and can be used to accept payments and make transfers. Wallets are not linked to another physical account. Money deposited or paid to a wallet remains in the wallet until it is transferred to another account.

Currently, we allow you to create virtual account wallets using yes_bank and axis_bank.

Integrating your application with ZWITCH lets your customer open a virtual account wallet.

Virtual Account Wallet Integration Flow

Virtual Account Wallet Integration Flow

Follow the below steps to open a virtual account.

  1. PAN Verification
  2. Bank Account Verification
  3. Name Verification
  4. Create a Virtual Account wallet

1. PAN Verification

PAN verification is a mandatory requirement to open any bank account. PAN verification allows the applicant to perform high-value transactions and avoids paying double taxes.

Use the below endpoint to verify the PAN.

POST: https://api.zwitch.io/v1/kycs/pan

Below is a sample request and response for the PAN Verification API.

{
  "pan": "AAAAA0000A",
  "merchant_reference_id": "10101101",
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  }
}

{
  "id": "pan_bd1ldpyyMlg7nywIYpjjiklNS",
  "object": "pan_verification",
  "pan": "AAAAA0000A",
  "name_on_pan": "NAME AS PER PAN RECORDS",
  "status": "success",
  "merchant_reference_id": "10101101",
  "message": "PAN Verified",
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "created_at": 1654155992,
  "is_sandbox": true
}

2. Bank Account Verification

Use bank account verification to instantly verify the validity and ownership of bank accounts and VPA handles. You can only use the verified bank account to load or withdraw money from the virtual account.

Use the below endpoint to verify the bank account.

POST: https://api.zwitch.io/v1/verifications/bank-account

Below is a sample request and response for the Bank Account Verification API.

{
  "bank_account_number": "10000000000875",
  "bank_ifsc_code": "HDFC0000123",
  "force_penny_drop": true,
  "force_penny_drop_amount": 1,
  "merchant_reference_id": "1000875",
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  }
}

{
  "id": "accver_BhOM01sUb3tXprWwTGBLlKZVG",
  "object": "bank_account_verification",
  "bank_account_number": "10000000000875",
  "bank_ifsc_code": "HDFC0000123",
  "name_as_per_bank": "Anil Reddy",
  "force_penny_drop": true,
  "force_penny_drop_amount": 1,
  "status": "success",
  "message": "",
  "last_verified_at": "2024-01-23",
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "merchant_reference_id": "1000875",
  "created_at": 1648030636,
  "is_sandbox": true
}

📘

Note:

  • For Axis Bank virtual accounts use the generated bank verification ID against the verified_remitters.account_verification_id.
  • You can load funds only from this verified account to your virtual account.
  • For Yes Bank virtual accounts use the generated bank verification ID against the verified_beneficiaries.account_verification_id.
  • You can only use this verified account to withdraw funds from your virtual account.

3. Name Verification - PAN vs Account Verification API

Use this API to verify the PAN name with their existing Bank account name.

Use the below endpoint to verify the applicant's name.

POST: https://api.zwitch.io/v1/kycs/name-match

Below is a sample request and sample response for the Name Verification - PAN vs Account Verification API.

{
  "type": "pan_vs_account_verification",
  "pan_verification_id": "pan_vTQ7sBPRAApHORmN5PfT3Uk3N",
  "account_verification_id": "accver_wIEhmszz13go8eiUSbYDZlBKu",
  "minimum_match_score": 60.5,
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  }
}

{
  "id": "nm_BbDMJHOVydaXraXQuSWPPquoZ",
  "type": "pan_vs_account_verification",
  "object": "name_match.pan_vs_account_verification",
  "minimum_match_score": 60.5,
  "status": "success",
  "name_as_per_pan": "Anil Reddy",
  "pan_verification_id": "pan_vTQ7sBPRAApHORmN5PfT3Uk3N",
  "account_verification_id": "accver_wIEhmszz13go8eiUSbYDZlBKu",
  "name_as_per_verification": "Anil Reddy",
  "match_score": 70.83,
  "message": "success",
  "review_needed": false,
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "created_at": 1704868805,
  "updated_at": 1704868805,
  "is_sandbox": true
}

4. Create a Virtual Account Wallet

Use this API to create a virtual account wallet.

Use the below endpoint to create a virtual account wallet.

POST: https://api.zwitch.io/v1/accounts

Below is a sample request and sample response for the Create Virtual Account Wallet API.

{
  "type": "virtual",
  "used_as": "wallet",
  "name": "Anil Reddy",
  "mobile_number": "9876543210",
  "email": "[email protected]",
  "bank_name": "yes_bank",
  "create_vpa": true,
  "kyc": {
    "city": "Bangalore",
    "postal_code": "560005",
    "state_code": "KA",
    "pan": "AAAPA0000A",
    "business_type": "partnership",
    "pan_verification_id": "pan_bd1ldpyyMlg7nywIYpjjiklNS",
    "business_category": "garage_owners",
    "contact_person": "Rahul Reddy"
  },
  "verified_beneficiaries": [
    {
      "account_verification_id": "accver_BhOM01sUb3tXprWwTGBLlKZVG",
      "name_match_id": "nm_BbDMJHOVydaXraXQuSWPPquoZ"
    }
  ],
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  }
}

{
  "id": "va_RcochEXjFd4TJunK0soMrmoon",
  "object": "account.virtual",
  "type": "virtual",
  "used_as": "wallet",
  "bank_name": "yes_bank",
  "name": "Anil Reddy",
  "mobile_number": "9876543210",
  "email": "[email protected]",
  "account_number": "3636365848485530",
  "ifsc_code": "YESB0CMSNOC",
  "vpa": "zwch1888959688@yesbank",
  "additional_vpa": [],
  "whitelisted_beneficiaries": [
    {
      "account_number": "91021021021213",
      "ifsc_code": "ICIC0000001"
    }
  ],
  "verified_beneficiaries": [
    {
      "account_verification_id": "accver_BhOM01sUb3tXprWwTGBLlKZVG",
      "name_match_id": "nm_BbDMJHOVydaXraXQuSWPPquoZ"
    }
  ],
  "whitelisted_remitters": [],
  "verified_remitters": [],
  "kyc": {
    "city": "Bangalore",
    "postal_code": "560005",
    "state_code": "KA",
    "pan": "XXXXXX000A",
    "business_type": "partnership",
    "pan_verification_id": "pan_bd1ldpyyMlg7nywIYpjjiklNS",
    "business_category": "garage_owners",
    "contact_person": "Rahul Reddy"
  },
  "customer": {
    "id": "cus_9AZ0Od3RcJLS3PzEtZyqGyL42",
    "mobile_number": "9876543210"
  },
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "status": "active",
  "created_at": 1681113234,
  "is_sandbox": true,
  "settlement_account_id": null
}

📘

Note:

While creating a virtual account with Axis Bank, set the create_vpa argument to false. This is because Axis Bank virtual accounts do not allow vpa designations on their account.

Refer to our Virtual Account documentation for more details.

Custom VPA

We allow you to create a custom VPA handle for your Yes Bank Virtual Account Wallets and Collection Tools.

Contact our Integrations Team to learn more.

📘

Note:

  • You can create custom VPA handled when creating a Yes Bank virtual account or when adding additional VPA handles to a virtual account.

Updated 2 months ago