Changelog
Community
Back to All

January 2022

March 9th, 2022 by Hem G

We work hard to ensure everyone who uses ZWITCH gets the best experience. Every day we take small steps towards developing new products, enhancing existing features, and improving the performance of our system. We also fix (the occasional) bug in the system.

Below is a list of new feature releases, product improvements, and bug fixes from January 2022.

📘

Note

  • Except for breaking changes, all other changes are backward compatible.
  • Currently, we work on a daily release cycle. We push changes to the production environment as they are developed. However, we will notify you about breaking changes, new feature releases, and major enhancements via email before they are released.

🚀 New Features

Below are the new features we introduced in January 2022.

Accounts API

Below are the changes made to the Accounts API in January 2022.

Upload Document API

Documents such as the customer’s photo, business registration certificate, GST certificate, and TIN certificate are required when creating a new account. These are regulatory requirements set by our partner banks.

To help you upload these documents, we have introduced the Upload Documents API. Once a document is uploaded it can be used in multiple places as required.

Currently, you can only use this API to upload the customer’s photo when creating a new Savings Account on ZWITCH.

Savings Account - Upload Customer Photo

Banks require the customer’s photo when creating a new savings account. To upload the customer’s photo while creating a new savings account, we have introduced a documents object in the Create Savings Account API.

Follow the below steps to upload the customer’s photo when creating a new savings account.

  1. Upload the customer’s photo using the Upload Documents API. If the file is successfully uploaded, you get a document id (example: doc_eqcy7LACx9PAPQF2NYtYdWyNG) in the API response.
  2. Pass the required document id and type in the document object in the Create Savings Account API.

📘

Mandatory from Feb 08, 2022

This will be made a mandatory input parameter from February 08, 2022.

Webhook

Get All Webhook Events

We have added the Get All Webhook Events API to ZWITCH. This API fetches a list of all webhooks triggered by you.

Below is a sample response for the API.

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "evl_SnAVQuMNc85fJBOXJjlcNhsl5",
      "object": "event",
      "name": "kycs.pan.created",
      "delivery_status": "success",
      "is_sandbox": true,
      "data": {
        "object": {
          "id": "pan_1IEU3w1DDAqczfsDUyMA4tQi1",
          "object": "pan_verification",
          "pan": "ADBPH4883P",
          "name_on_pan": "NAME AS PER PAN RECORDS",
          "status": "success",
          "merchant_reference_id": "1000027",
          "metadata": {
            "key_1": "DD",
            "key_2": "XOF"
          },
          "created_at": 1646919610,
          "is_sandbox": true
        }
      },
      "created_at": 1646919610
    },
    {
      "id": "evl_RlDKAYhtxrXM5lHa1g0qZ6gwR",
      "object": "event",
      "name": "verifications.bank_account.created",
      "delivery_status": "success",
      "is_sandbox": true,
      "data": {
        "object": {
          "id": "accver_IRutjgMyHkyUFFNXaOp6752iz",
          "object": "bank_account_verification",
          "bank_account_number": "10000000000026",
          "bank_ifsc_code": "HDFC0000123",
          "name_as_per_bank": "Name as per bank",
          "force_penny_drop": false,
          "force_penny_drop_amount": 1.23,
          "status": "success",
          "message": "Transaction Successful",
          "last_verified_at": "2022-03-10",
          "metadata": {
            "key_1": "DD",
            "key_2": "XOF"
          },
          "merchant_reference_id": "1000026",
          "created_at": 1646919498,
          "is_sandbox": true
        }
      },
      "created_at": 1646919498
    }
  ]
}

🎉 Enhancements

Below are the enhancements we made in January 2022.

General

To enhance your experience when querying our APIs, we have added the following query parameters to all our Get All APIs. These query parameters filter results using the created_at timestamp.

  • from_date: Returns objects created after the specified timestamp.
  • to_date: Returns objects created till the specified timestamp.

Accounts API

We have made a few enhancements to the Accounts APIs. These changes were made to enhance developer experience and make API naming conventions and data type consistent.

Nominee Object

We have renamed the parameters within the nominee object. Earlier, all parameters within the nominee object contained the prefix nominee_.

Below is an example of the old nominee object that was used in the Account API.

"nominee": [
  {
    "nominee_name": "Ganga Reddy",
    "nominee_relation": "mother",
    "nominee_address": "221B Baker Street",
    "nominee_state_code": "KA",
    "nominee_city": "Bangalore",
    "nominee_postal_code": "560001",
    "nominee_date_of_birth": "1963-12-31"
  }
]

We have now removed the prefix for all parameters within the nominee object. Below is an example of the new nominee object we have added to the Account API.

"nominee": [
  {
    "name": "Ganga Reddy",
    "relation": "mother",
    "address": "221B Baker Street",
    "state_code": "KA",
    "city": "Bangalore",
    "postal_code": "560001",
    "date_of_birth": "1963-12-31"
  }
]

Customer Object

We have added a customer object to all our Accounts API responses. This object contains the customer's mobile number and a list of all accounts linked to the mobile number. This allows you to keep track of all accounts created for a customer.

Below is an example of the customer object returned as part of the Account API response.

"customer": {
  "id": "cus_1oycz5mgvxYSoxpDc8Ti6jRJY",
  "mobile_number": "9876543210",
  "accounts": [
    "sa_DDgPws4YQfOhWnzj2lmIC96lJ",
    "va_xa53e6G4kKhGGpZXij25XYs90",
    "va_DdIloRqfh1MJbZ6HrZLlKUgt1",
    "lca_sEQ0XTBwqaNOnsNKkSgwNniEH"
  ]
}

Income Parameter

The income parameter within the kyc object now accepts inputs as float values. Earlier, only integer values were accepted as valid inputs.

City Parameter

The city parameter within the nominee and address object now accepts any string as a valid input.
Earlier, only the 3-letter ISO city code was accepted as valid inputs.

Postal Code Parameter

The postal_code parameter within the nominee and address object now only accepts inputs as string values. This allows us to accept postal codes from across the world.

Earlier, both string and integers as valid inputs.

KYC APIs

We have made a few enhancements to the Accounts APIs. These changes were made to enhance the developer experience.

Verify Aadhaar Webhook Events

Aadhaar verification is mandatory to activate a savings account. We automatically initiate Aadhaar verification during the account creation process. Alternatively, you might want to manually verify your customer’s Aadhaar details using our Verify Aadhaar APIs.

In both cases, it is important for you to know the Aadhaar verification status. This allows you to keep your customers informed and perform further actions as per your business needs.

We have added the following webhook events to keep you informed about the Aadhaar verification status.

  • kycs.aadhaar.created: Triggered when the Verify Aadhaar Send OTP API call is successfully made automatically by ZWITCH or manually by you.

  • kycs.aadhaar.updated: Triggered when the Verify Aadhaar Verify OTP API call is successfully made automatically by ZWITCH or manually by you.

Below are sample payloads for the webhook events.

{
  "id": "evl_080vEcLFduVUyrHNu6NZoGpyx",
  "object": "event",
  "name": "kycs.aadhaar.created",
  "is_sandbox": true,
  "data": {
    "object": {
      "id": "adh_z2jI8M2JTGbT1S2DFHHYi2KDv",
      "object": "aadhaar_verification",
      "aadhaar_number": "XXXXXXXX2109",
      "name": "Anil Reddy",
      "message": "OTP sent to registered mobile number",
      "status": "success",
      "remark": null,
      "merchant_reference_id": "testardjvkndrjk",
      "created_at": 1646896277,
      "is_sandbox": true
    }
  }
}

{
  "id": "evl_azeFOgiaBoZqI1j4Vna1zNFxU",
  "object": "event",
  "name": "kycs.aadhaar.updated",
  "is_sandbox": true,
  "data": {
    "object": {
      "id": "adh_z2jI8M2JTGbT1S2DFHHYi2KDv",
      "object": "aadhaar_verification",
      "message": "Aadhaar XML file downloaded successfully",
      "status": "success",
      "name": "Name as per Aadhar Records",
      "aadhaar_number": "XXXXXXXX2109",
      "date_of_birth": "YYYY-MM-DD",
      "gender": "M",
      "father_name": "Father",
      "address": "Address as per aadhaar records",
      "postal_code": "560035",
      "state": "Kerala",
      "state_code": "KL",
      "city": "wanaparthy",
      "remark": null,
      "merchant_reference_id": "testardjvkndrjk",
      "is_sandbox": true
    }
  }
}

Aadhaar Verification - Remarks

When verifying Aadhaar for a new savings account, the verify Aadhaar response contains a remark parameter. This parameter contains details of the account for which Aadhaar verification is being done. You can view this information:

  • From the Logs section on the Dashboard.
  • From the kycs.aadhaar.created and kycs.aadhaar.updated webhook events.

📘

Note

The remark parameter is present in all Verify Aadhaar API responses. However, the parameter only contains information of the account which is being verified when the Verify Aadhaar API is triggered automatically by ZWITCH when creating a savings account.

When you fire the Verify Aadhaar API on its own, the remark parameter returns null.

Aadhaar Test Data

To help you test your integration in different scenarios, we have added the following test information to our sandbox environment.

  • Fail Aadhaar verification: Use Aadhaar number 811111111111 to fail Aadhaar verification.
  • Invalid Aadhaar OTP: Use OTP 123456 to simulate the invalid OTP scenario.

📘

Note

These details only work in the Sandbox environment. Do not use these details in the Live Environment.

🛠️ Bug Fixes

Below is a list of bugs we fixed in January 2022.

Accounts API

Mobile Number Update No Longer Allowed

You can no longer update the customer’s phone number using the Update Account API.

This change was done because we use the phone number as the primary key to identify the customer.

📆 Upcoming Changes

Below are some planned changes we intend to implement in February 2022.

📘

Note

This is not an exhaustive list of upcoming changes.

Accounts API

Below is the change we will be making live in February 2022.

Savings Account - Upload Customer Photo (Mandatory)

As mentioned above, our partner banks require the customer’s photo to be uploaded while creating a new savings account. We have introduced the Upload Document API and have added the document object to the Create Savings Account API to support this.

Currently, the document object is optional. We will be making this a mandatory parameter on February 08, 2022.