Object

Overview of the account.virtual object.

Shown below is a sample account.virtual object for wallets and collection tools.

{
  "id": "va_RcochEXjFd4TJunK0soMrmoon",
  "object": "account.virtual",
  "type": "virtual",
  "used_as": "wallet",
  "bank_name": "yes_bank",
  "name": "Anil Reddy",
  "mobile_number": "9000004727",
  "email": "[email protected]",
  "account_number": "3636365848485530",
  "ifsc_code": "YESB0CMSNOC",
  "vpa": "zwch1888959688@yesbank",
  "additional_vpa": [],
  "whitelisted_remitters": [
    {
      "account_number": "91021021021213",
      "ifsc_code": "ICIC0666667"
    }
  ],
  "whitelisted_beneficiaries": [
    {
      "account_number": "91021021021212",
      "ifsc_code": "ICIC0666666",
      "vpa": "zwch1405319881@yesbank"
    }
  ],
  "kyc": {
    "city": "Bangalore",
    "postal_code": "560005",
    "state_code": "KA",
    "pan": "XXXXXX000A",
    "business_type": "proprietership-or-huf",
    "business_category": "garage_owners",
    "contact_person": "Anil Reddy"
  },
  "customer": {
    "id": "cus_9AZ0Od3RcJLS3PzEtZyqGyL42",
    "mobile_number": "9000004727"
  },
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "status": "active",
  "created_at": 1681113234,
  "is_sandbox": true,
  "settlement_account_id": null
}
{
  "id": "va_u6b8LmK8EKEFaegcUKOLravtd",
  "object": "account.virtual",
  "type": "virtual",
  "used_as": "collection_tool",
  "bank_name": "yes_bank",
  "name": "Anil Reddy",
  "mobile_number": "9000000843",
  "email": "[email protected]",
  "account_number": "3636365909197251",
  "ifsc_code": "YESB0CMSNOC",
  "vpa": "zwch784698093@yesbank",
  "additional_vpa": [],
  "whitelisted_remitters": [
    {
      "account_number": "98909876123562",
      "ifsc_code": "HDFC0000123"
    }
  ],
  "whitelisted_beneficiaries": [],
  "kyc": {
    "city": "Bangalore",
    "postal_code": "560010",
    "state_code": "KA",
    "pan": "XXXXXX000F",
    "business_type": "partnership",
    "business_category": "garage_owners",
    "contact_person": "Sunil"
  },
  "customer": {
    "id": "cus_sCoO4JTuJgfaMkgxNP54PH81I",
    "mobile_number": "9000000843"
  },
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "status": "active",
  "created_at": 1653995905,
  "is_sandbox": true,
  "settlement_account_id": "va_UXjVUZdUuWpRezxRmuwQt4Vw0"
}

The table below lists the various parameters in the virtual account object.

ParametersTypeDescription
idstringUnique identifier of the virtual account in the ZWITCH database.

Has to be 28 characters.

Example: va_Y6evcApKFXhQ9X7qKQ5AaysEI

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • _
objectstringAPI object that is returned.

Possible value: account.virtual
typestringThe account type.

Possible value: virtual
used_asstringType of virtual account.

Possible values:
  • wallet
  • collection_tool

Types of virtual accounts.
bank_namestringBank where the virtual account is created.

Possible value: yes_bank
namestringApplicant's name.

Maximum 70 characters.

Example: Anil Reddy

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • .
  • /
  • \
  • -
  • _
  • ,
  • (
  • )
  • '
mobile_numberstringApplicant's mobile number.

Has to be 10 digits.

Example: 9876543210

Supported characters:
  • 0-9
emailstringApplicant's email address.

Example: [email protected]
account_numberstringVirtual account number.

Maximum 30 characters.

Example: 18539873916

Supported characters:
  • A-Z
  • a-z
  • 0-9
ifsc_codestringVirtual account IFSC.

Has to be 11 characters.

Example: STCB0000065

Supported characters:
  • A-Z
  • 0-9
vpastringVirtual payment number (VPA) linked to the virtual account.

Example: zwch1110526721@yesbank
additional_vpaarray of objectsArray of objects that contain a list of additional VPA handles linked to the virtual account and the status of each VPA handle.

Learn more about the additional_vpa child object.

You can create additional VPAs using the Update Virtual Account API.
whitelisted_remittersarray of objectsArray of objects that contain a list of accounts from which the virtual account holder wants to receive money.

Currently, only bank accounts can be whitelisted.

Learn more about the whitelisted_remitters child object.
kycobjectObject that contains the applicant's KYC details.

Learn more about the kyc child object.
customerobjectJSON object that contains details about the account holder.

Learn more about the customer child object.
metadataobjectObject of key-value pair that can be used to store additional information about the entity.

Note:
  • Maximum 5 key-value pairs.
  • Maximum 256 characters in the metadata object.
  • You cannot pass a URL.
  • You cannot use \.
Example: "key_1": "DD"
statusstringPossible values:
  • vpa_creation_pending: Virtual account has been successfully created and the account number and account IFSC have been issued.
    However, the VPA handle for the account has not yet been activated by the bank.
    A virtual account goes to this status only if the create_vpa parameter is set to true.
  • active: Virtual account and VPA handle have been successfully created.
  • deactivated: Account has been deactivated.
created_atinteger Unix timestamp when the create virtual account request was received by ZWITCH.

Example: 1640179951
is_sandboxbooleanPossible values:
  • true: API was triggered in sandbox mode
  • false: API was triggered in live mode
settlement_account_idstringShould only be used when creating a collection tool account

The unique identifier of the ZWITCH virtual account is used as a wallet.

Note: The status of the account should be active.

Has to be 28 characters.

Example: va_UXjVUZdUuWpRezxRmuwQt4Vw0

Supported characters:

  • A-Z
  • a-z
  • 0-9
  • _

[Child Object] Additional VPA

The table below lists the various parameters in the additional_vpa child object. This object is part of the account.virtual object.

ParametersTypeDescription
vpastringAdditional virtual payment number (VPA) linked to the virtual account.

Example: zwch1110526721@yesbank

You can create additional VPAs using the Update Virtual Account API.
statusstringStatus of the additional VPA handle.

Possible values:
  • vpa_creation_pending: The additional VPA handle has not yet been activated by the bank.
  • active: Additional VPA handle has been created and has been activated by the bank. The additional VPA handle is fully functional and ready to be used.
created_atintegerUnix timestamp when the create additional VPA handle request was received by ZWITCH.

Example: 1640179951

[Child Object] Whitelisted Remitters

The table below lists the various parameters in the whitelisted_remitters child object. This object is part of the account.virtual object.

ParametersTypeDescription
account_numberstringAccount number from which the virtual account holder wants to receive money.

Maximum 30 characters.

Example: 18539873916

Supported characters:
  • A-Z
  • a-z
  • 0-9
ifsc_codestringIFSC linked to the account from which the virtual account holder wants to receive money.

Has to be 11 characters.

Example: AAAA0000001

Supported characters:
  • A-Z
  • 0-9

[Child Object] Whitelisted Beneficiaries

The table below lists the various parameters in the whitelisted_beneficiaries child object. This object is part of the account.virtual object.

ParametersTypeDescription
account_numberstringAccount number to which the virtual account holder wants to send money.

Maximum 30 characters.

Example: 18539873916

Supported characters:
  • A-Z
  • a-z
  • 0-9
ifsc_codestringIFSC linked to the account to which the virtual account holder wants to send money.

Has to be 11 characters.

Example: AAAA0000001

Supported characters:
  • A-Z
  • 0-9
vpastringVirtual payment number (VPA) of the account.

Example: zwch1405319881@yesbank

[Child Object] KYC

The table below lists the various parameters in the kyc child object. This object is part of the account.virtual object.

ParametersTypeDescription
citystringAccount holder's city.

Example: Bangalore

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • space
  • _
  • ()
  • .
postal_codestringAccount holder's pincode.

Has to be 6 digits.

Example: 560005

Supported characters:
  • 0-9
state_codestringApplicant's state code.

Use the State Codes API to get a list of accepted values.

Example: KA
panstringApplicant's PAN number.

Has to be 10 characters.

Example: AAAPA0000A

Supported characters:
  • A-Z
  • 0-9
business_typestringThe business type for the virtual account.

Use the Business Types API to get a list of accepted values.

Example: partnership
business_categorystringThe business category for the virtual account.

Use the Business Categories API to get a list of accepted values.

Example: garage_owners
contact_personstringContact person's name for the virtual account.

Maximum 70 characters.

Example: Anil Reddy

Supported characters:

  • A-Z
  • a-z
  • 0-9
  • .
  • /
  • \
  • -
  • _
  • ,
  • (
  • )
  • '

[Child Object] Customer

The table below lists the various parameters in the customer child object. This object is part of the account.virtual object.

ParametersTypeDescription
idstringUnique identifier of the applicant in the ZWITCH database.

Has to be 29 characters.

Example: cus_lmPl9XliJ09yisvcWKrff2WCR.

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • _
mobile_numberstringMobile number of the applicant or registered business.

Has to be 10 digits.

Example: 9876543210

Supported characters:
  • 0-9