Vizo Digital Api
Sign in
guide

Airtel CMS Integration Guide

Cash Management System (CMS) Overview

What is CMS Service?

Cash Management System (CMS) is a suite of digital banking services designed to help businesses securely and efficiently manage cash collections, deposits, and settlements.

It simplifies complex financial operations by offering real-time visibility, faster reconciliations, and automated payment flows — ensuring optimized liquidity and smoother fund movement between customers, branches, and business partners.

How CMS Services Work

CMS operates through an integrated digital platform that connects collection points, payment gateways, and settlement accounts. The process typically follows these steps:

  1. Collection Setup – Businesses register their collection points, virtual accounts, or agents.
  2. Cash Deposit / Collection – Retailers or agents deposit cash at designated collection centers or partner banks.
  3. Instant Reconciliation – Each deposit is automatically mapped to the correct customer or transaction using unique reference IDs.
  4. Settlement Processing – Collected funds are transferred to the company’s main account.
  5. Reporting & Analytics – Businesses can access real-time dashboards for tracking collections, deposits, and settlements.

By integrating CMS APIs, companies can automate their entire cash management lifecycle, reducing manual errors and ensuring faster fund availability.

Key Features & Benefits

  • Real-Time Reconciliation – Automatically map deposits and collections to specific customers or invoices.
  • Multi-Channel Cash Collection – Accept deposits through retailers, collection points, and partner banks.
  • Automated Settlements – Enable direct settlement into the business’s central account.
  • Comprehensive Reporting – Access detailed reports on all cash transactions and settlements.
  • Reduced Operational Risk – Minimize manual handling of funds through secure digital workflows.
  • Scalable Architecture – Designed to handle large transaction volumes efficiently.
  • Improved Liquidity Management – Ensure timely fund availability for business operations.

Why Choose NOBLE API’s for CMS Services?

  • Rapid Deployment – Launch your CMS-enabled solutions quickly with plug-and-play APIs.
  • Unified API Architecture – Standardized and consistent APIs simplify integration across systems.
  • Smart Data Insights – Access detailed analytics to make informed business and treasury decisions.
  • High Scalability – Handle growing transaction volumes with robust infrastructure support.
  • Bank-Grade Security & Compliance – Adhering to strict financial standards ensures every transaction is safe and verified.
  • Guaranteed Uptime & Reliability – Enjoy 24/7 uninterrupted operations backed by enterprise-grade stability.

AIRTEL CMS

Airtel CMS Overview

Airtel CMS (Cash Management System) is a service provided by Airtel Payments Bank that enables businesses and retailers to collect, deposit, and settle funds securely through an integrated online platform.

The Airtel CMS flow follows a 4-step transaction process, where each step must be executed in order to ensure successful payment collection and settlement:

┌─────────────────────────────────┐
│  Step 1: Start Transaction      │
│  POST /api/v1/cms/airtel/start  │
└────────────────┬────────────────┘
                 │ Returns redirectionUrl
                 ▼
┌─────────────────────────────────┐
│  Step 2: Enter Details & OTP    │
│  (Airtel Bank Redirection UI)   │
└────────────────┬────────────────┘
                 │ Submits form & OTP
                 ▼
┌─────────────────────────────────┐
│  Step 3: OTP Verification &     │
│  Balance Check (Webhook 1 & 2)  │
└────────────────┬────────────────┘
                 │ APB processes txn
                 ▼
┌─────────────────────────────────┐
│  Step 4: Transaction Posting    │
│  (Final Webhook Callback)       │
└─────────────────────────────────┘

CMS 4-Step Process (Sequential Flow)

  1. Start Transaction – Initiate the cash collection process using the /api/v1/cms/airtel/start endpoint. This API redirects the user to the official Airtel Bank payment page (redirectionUrl) for completing the transaction.
  2. Enter Details & Generate OTP – On the Airtel page, the user enters Biller Name, Mobile Number, and Amount, then submits the form. The system responds with "OTP sent Successfully" to the provided mobile number.
  3. OTP Verification & Balance Check – The user enters the received OTP on the Airtel page. Upon successful verification, the system validates the account and confirms "OTP verification successful". In the background, Airtel sends balance_check and balance_check_debit webhook callbacks.
  4. Transaction Posting – Once verification is complete, the transaction is processed, and the posting activity is marked as completed (transaction_post). A response is then sent back to the client via the provided callback URL.

Zero Surcharge & Retailer Commission Engine

  • Zero Surcharge: Retailers and customers are NOT charged any extra surcharge on CMS collections.
  • Retailer Commission: The retailer earns commission per successful collection (either flat ₹ or a percentage, configured in Admin Portal under CMS Management → CMS Settings). Commission is instantly credited to the user's primary wallet upon successful transaction posting.
  • Instant Auto-Refund: If any transaction fails downstream with Airtel Bank after wallet debit, our auto-refund engine immediately restores 100% of the debited balance to the user's wallet with status REFUNDED.

Errors and Response Codes

1. CMS API Error Codes (Client Side & API Authentication Errors)

Status StatusCode Message Description
0 IR0001 Invalid Request Malformed or invalid request body. Check syntax and required fields.
0 PM0002 Parameter Missing {Value} parameter is missing.
0 VF0003 Validation Failed {Value} is required.
0 IE0004 Invalid Api Endpoint Invalid Api Endpoint.
0 IC0007 Invalid Credentials Authentication failed.
-1 SE0006 Internal Server Error Server is down. Please try again later.
0 AE0021 Invalid Header Header validation failed.
0 AE0022 Authentication Error Rate limit exceeded. Please try again later.
0 AE0023 Authentication Error Required headers are missing.
0 AE0024 Authentication Error Invalid timestamp format (must be yyyy-MM-ddTHH:mm:ss).
0 AE0025 Authentication Error Unsupported content type in header. Only 'application/json' is allowed.
0 AE0026 Authentication Error Header Token is invalid or inactive.
0 AE0027 Authentication Error Header token has expired.
0 AE0028 Authentication Error IP address not allowed.
0 AE0029 Authentication Error This endpoint is not allowed for the client.
0 AE0030 Authentication Error Request timed out or timestamp is invalid.

2. CMS API Error Codes (CMS Transaction Errors)

Status StatusCode Message Description
1 AC0001 Success Success Message
0 AC0002 Failed Failed Message
-1 AC0003 Error Error Message

2.1 System Defined Status Code for the Reason of Failure (APB Codes)

Status Code Description
APB_000 It is the ideal success code in all scenarios.
APB_001 Form Data not found (Biller is not configured in the system).
APB_002 Insufficient balance in account, please add funds and try again.
APB_004 Amount cannot be credited as account exceeds maximum balance limit.
APB_005 Similar transaction has already been fired.
APB_006 There is a credit freeze on the account, please ask beneficiary to contact the bank.
APB_009 Sorry! Invalid Debit Account Details.
APB_010 Either debit or credit account is closed.
APB_011 Sorry! Transaction could not be processed as Credit account is blocked.
APB_019 Sorry! Invalid Credit Account Details.
APB_030 Session expired, please try again.
APB_031 Request Type can't be null.
APB_032 Request Type not supported.
APB_033 Exception occurred while fetching fields details / No data found.
APB_034 Next form mapping not found.
APB_035 Exception occurred.
APB_036 Something went wrong. Please try again in some time.
APB_037 Please enter valid input for required fields.
APB_038 Object cannot be converted into JSON, please check your request.
APB_039 Input/output error while reading the request.
APB_040 We are experiencing some technical issues. Please try again after some time.
APB_041 Success.
APB_042 Transaction not possible since your permissible daily transaction amount has exceeded.
APB_043 Dear depositor, your transaction is pending. In case you have received a success message, deposited amount will be credited against your corresponding ID.
APB_044 Sorry! We are experiencing some technical issues. Please try again.
APB_111 This is the default error code defined in the system, with the proper description like Failure or Partner Not Found or Partner status is inactive.
APB_112 Txn failed. Reason may be due to duplicate one, please change your request and retry.
APB_113 Failure / Data issue.
APB_121 No such transaction exists in our system, please retry.
APB_122 Partner Not Found.
APB_123 Partner status is inactive.
APB_124 Partner ID is either missing or not same in URL and body.
912 Invalid Request.
APB_182 Balance not found for corresponding COD account.
APB_183 Account details not found.

2.2 Failed & Error Messages (AC0002 & AC0003)

  • API balance is not enough to perform CMS
  • Client authentication failed (CCN01/CCW01/CCT02)
  • Duplicate request found
  • Duplicate transaction
  • Invalid authentication or account is disabled
  • Message + (CCE03) (Client Side Error)
  • Message + (NWE01) (DB Error)
  • OTP was never sent for this transaction
  • Request timed out or partner Transaction ID is invalid
  • Request timed out or Transaction ID is invalid
  • Service is down from corporate partner. Please contact admin.
  • SMS service provider is not responding
  • System unable to identify merchant or admin
  • Transaction does not belong to NWS
  • Transaction not found
  • Transaction session expired

Airtel CMS – Client Callback Responses

During the Airtel CMS transaction process, the system sends three types of callback requests to the client’s callback URL:

POST https://api.vizodigital.com/api/v1/cms/airtel/callback

⚠️ Important Implementation Notes

  • Valid Callback URL: A valid HTTPS Callback URL is required to receive and handle the final transaction response.
  • POST Requests: The callback listener must accept incoming HTTP POST requests containing JSON payloads.
  • Response Format: The client must respond in valid JSON format.
  • Status Value: The status field accepts only "0" (Fail) or "1" (Success).
  • String Format: In the JSON request and response, all fields must be strings.
  • Timing: For the transaction_post (Final Callback), callback data is received up to 15 minutes after the transaction.
  • Client Responsibility: The client is fully responsible for any successful (status = "1") acknowledgment sent.

Callback 1. Balance Check (action: "balance_check")

Purpose: To verify whether the client/merchant has sufficient balance before initiating a transaction.

Client Receives (Incoming Request):

{
  "action": "balance_check",
  "merchantId": "123456789",
  "amount": "100",
  "transactionId": "DEMOTRAN123" 
}

Client Response:

{
  "status": "1",
  "message": "Success"
}

Callback 2. Balance Check Debit (action: "balance_check_debit")

Purpose: Debit the merchant’s account with the specified transaction amount.

Client Receives (Incoming Request):

{
  "action": "balance_check_debit",
  "merchantId": "123456789",
  "amount": "100",
  "transactionId": "DEMOTRAN123",
  "billerId": "011023",
  "billerName": "TEST",
  "mobile": "9829098290"
}

Client Response:

{
  "status": "1",
  "message": "Amount Debit Successful"
}

Callback 3. Transaction Post (Final Callback) (action: "transaction_post")

Purpose: Indicates that the final transaction posting process has been completed.

Client Receives (Incoming Request):

{
  "action": "transaction_post",
  "merchantId": "3123456789",
  "amount": "100",
  "transactionId": "DEMOTRAN123",
  "billerId": "011023",
  "billerName": "TEST",
  "utr": "DEMO0101012",
  "mobile": "9829098290",
  "tranDateTime": "07-10-2024 04:47:01",
  "commission": "0.1",
  "otherFields": "",
  "description": "DEMODEMODEMO 12132123",
  "tranStatus": "Success"
}

Client Response:

{
  "status": "1",
  "message": "Transaction Posting Successful"
}

Note: For the Transaction Post, client callback data will be received within 15 minutes after the transaction completes.

API Endpoint Reference

1. Start Transaction

POST /api/v1/cms/airtel/start

Initiates the cash collection process and returns the secure Airtel Payments Bank redirection URL.

Request Headers

Header Required Data Type Description Example
Authorization YES string Sanctum Bearer token Bearer <Authtoken>
X-Timestamp YES string IST timestamp with 15-second skew (yyyy-MM-ddTHH:mm:ss) 2024-10-20T21:27:09
Content-Type YES string Request format application/json
Accept YES string Response format application/json

Request Parameters (JSON Body)

Parameter Required Data Type Description Example
merchantId YES string Numeric merchant phone or ID (up to 10 digits). 9829098290
transactionId YES string Unique transaction ID between 12 to 25 characters long. NBSCMS1234567 
curl --location 'https://api.vizodigital.com/api/v1/cms/airtel/start' \
--header 'Authorization: Bearer <Authtoken>' \
--header 'X-Timestamp: 2024-10-20T21:27:09' \
--header 'Content-Type: application/json' \
--data '{
  "merchantId": "9829098290",
  "transactionId": "NBSCMS1234567"
}'

Success Response (AC0001)

{
  "status": 1,
  "statusCode": "AC0001",
  "message": "Success",
  "description": "Success",
  "responseData": [
    {
      "redirectionUrl": "https://api.airtelpayments.bank.in/RetailerPlugin?param=yy0149d7cb3ee4250c9169d76bd68ec6",
      "transactionId": "NBSCMS1234567",
      "merchantId": "9829098290"
    }
  ]
}

2. Status Check

POST /api/v1/cms/airtel/status

Retrieves the real-time status of a transaction, bank UTR, and posting details.

Request Headers

Header Required Data Type Description Example
Authorization YES string Sanctum Bearer token Bearer <Authtoken>
X-Timestamp YES string IST timestamp with 15-second skew (yyyy-MM-ddTHH:mm:ss) 2024-06-27T21:27:09
Content-Type YES string Request format application/json
Accept YES string Response format application/json

Request Parameters (JSON Body)

Parameter Required Data Type Description Example
transactionId YES string Unique transaction identifier between 12 to 25 characters long. NCMS428F49XXX 
curl --location 'https://api.vizodigital.com/api/v1/cms/airtel/status' \
--header 'Authorization: Bearer <Authtoken>' \
--header 'X-Timestamp: 2024-06-27T21:27:09' \
--header 'Content-Type: application/json' \
--data '{
  "transactionId": "NCMS428F49XXX"
}'

Success Response (AC0001)

{
  "status": 1,
  "statusCode": "AC0001",
  "message": "Success",
  "description": "",
  "responseData": [
    {
      "merchantId": "34654654",
      "amount": "100",
      "transactionId": "NCMS428F49XXX",
      "billerId": "174540XXX",
      "billerName": "Biller Name PRIVATE LIMITED_AGENT",
      "mobile": "9829098290",
      "tranDateTime": "07-10-2024 16:47:02",
      "utr": "PH51007169752XXXX",
      "commission": "0.10",
      "otherFields": "",
      "description": "",
      "tranStatus": "Success"
    }
  ]
}