Object

Overview of the account.virtual object.

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

{
  "id": "va_2BNgFqGdz0AqUDtKMgZgRfjG6",
  "object": "account.virtual",
  "type": "virtual",
  "used_as": "wallet",
  "bank_name": "yes_bank",
  "name": "Ganga Reddy",
  "mobile_number": "9000000842",
  "email": "[email protected]",
  "account_number": "36363651152266170",
  "ifsc_code": "YESB0CMSNOC",
  "vpa": "[email protected]",
  "whitelisted_remitters": [
    {
      "account_number": "98909876123562",
      "ifsc_code": "HDFC0000123"
    }
  ],
  "kyc": {
    "city": "Bangalore",
    "postal_code": "560005",
    "state_code": "KA",
    "pan": "XXXXXX000A",
    "business_type": "partnership",
    "business_category": "garage_owners"
  },
  "customer": {
    "id": "cus_nsBbFAngtyzfjRGVsy0fXuDvQ",
    "mobile_number": "9000000842"
  },
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "status": "active",
  "created_at": 1653995889,
  "is_sandbox": true
}
{
  "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": "[email protected]",
  "whitelisted_remitters": [
    {
      "account_number": "98909876123562",
      "ifsc_code": "HDFC0000123"
    }
  ],
  "kyc": {
    "city": "Bangalore",
    "postal_code": "560010",
    "state_code": "KA",
    "pan": "XXXXXX000F",
    "business_type": "partnership",
    "business_category": "garage_owners"
  },
  "customer": {
    "id": "cus_sCoO4JTuJgfaMkgxNP54PH81I",
    "mobile_number": "9000000843"
  },
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "status": "active",
  "created_at": 1653995905,
  "is_sandbox": true
}

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

ParametersTypeDescription
idstringUnique identifier of the savings 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: [email protected]
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

[Child Object] Whitelisted Remitters Object

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] KYC Object

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

[Child Object] Customer Object

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