Airtel CMS · Airtel CMS Services

Start Transaction

Initiate cash collection process and retrieve Airtel Payments Bank redirection URL

POST request

URL: https://uat-api.vizodigital.com/api/v1/cms/airtel/start

Body

{
    "merchantId": "9829098290",
    "transactionId": "NBSCMS1234567"
}

Include a valid Bearer token with every request

Code sample

curl --location 'https://api.vizodigital.com/api/v1/cms/airtel/start' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'X-Timestamp: 2026-10-30T11:25:06' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "merchantId": "9829098290",
    "transactionId": "NBSCMS1234567"
}'

<?php

$client = new \GuzzleHttp\Client();
$response = $client->post('https://api.vizodigital.com/api/v1/cms/airtel/start', [
    'headers' => [
        'Authorization' => 'Bearer <YOUR_API_TOKEN>',
        'X-Timestamp' => '2026-10-30T11:25:06',
        'Content-Type' => 'application/json',
        'Accept' => 'application/json',
    ],
    'json' => array (
  'merchantId' => '9829098290',
  'transactionId' => 'NBSCMS1234567',
),
]);

echo $response->getBody();

import requests

url = 'https://api.vizodigital.com/api/v1/cms/airtel/start'
headers = {
    'Authorization': 'Bearer <YOUR_API_TOKEN>',
    'X-Timestamp': '2026-10-30T11:25:06',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}
payload = {
    "merchantId": "9829098290",
    "transactionId": "NBSCMS1234567"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const axios = require('axios');

axios.post('https://api.vizodigital.com/api/v1/cms/airtel/start', {"merchantId":"9829098290","transactionId":"NBSCMS1234567"}, {
  headers: {
    'Authorization': 'Bearer <YOUR_API_TOKEN>',
    'X-Timestamp': '2026-10-30T11:25:06',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
})
.then(res => console.log(res.data))
.catch(err => console.error(err));

Success Example

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

Failure response

{
    "status": 0,
    "statusCode": "AC0002",
    "message": "Failed",
    "description": "Failure Message",
    "responseData": []
}

Overview

Start Cash Collection

This endpoint initiates a transaction process for the Airtel CMS service. Upon successful authentication, the API returns a redirection URL within the responseData object. This URL should be used to redirect the user/cashier to the Airtel Bank Retailer CMS Plugin for completing the transaction.

Request Parameters (JSON Body)

Parameter	Required	Data Type	Description	Example
`merchantId`	YES	`string`	Numeric merchant phone or ID (must be numeric up to 10 digits).	`9829098290`
`transactionId`	YES	`string`	Unique transaction ID between 12 to 25 characters long.	`NBSCMS1234567`

Response Structure

Field	Data Type	Description
`status`	`number`	Status code: `1` (Success), `0` (Failed), `-1` (Error)
`statusCode`	`string`	Status code identifier: `AC0001` (Success), `AC0002` (Failed), `AC0003` (Error)
`message`	`string`	High-level status message
`description`	`string`	Detailed status description
`responseData[].redirectionUrl`	`string`	The official Airtel Bank Retailer Plugin payment page URL
`responseData[].transactionId`	`string`	Unique transaction identifier
`responseData[].merchantId`	`string`	Merchant phone / ID

Headers

Authorization · string required

An authentication token required for the request (Sanctum Bearer Token or Noble API token).

Example: Bearer <YOUR_API_TOKEN>
X-Timestamp · string required

Generated at the time of request, with skew time of 15 seconds (must be in format yyyy-MM-ddTHH:mm:ss).

Example: 2024-10-20T21:27:09
Content-Type · string required

Request content-type. Only application/json is allowed.

Example: application/json
Accept · string required

Response content-type. Must be application/json.

Example: application/json

Body

application/json required

JSON payload for Start Transaction

Schema

{
    "type": "object",
    "required": [
        "merchantId",
        "transactionId"
    ],
    "properties": {
        "merchantId": {
            "type": "string",
            "description": "Numeric merchant phone or ID (must be numeric up to 10 digits).",
            "example": "9829098290"
        },
        "transactionId": {
            "type": "string",
            "description": "Unique transaction identifier between 12 to 25 characters long.",
            "example": "NBSCMS1234567"
        }
    }
}

Example

{
    "merchantId": "9829098290",
    "transactionId": "NBSCMS1234567"
}

Responses

200 · application/json default

Airtel Bank Retailer CMS Plugin redirection URL generated successfully.

Example

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

422 · application/json

Response 3: Failure (AC0002)

Example

{
    "status": 0,
    "statusCode": "AC0002",
    "message": "Failed",
    "description": "Failure Message",
    "responseData": []
}

500 · application/json

Response 2: Error (AC0003)

Example

{
    "status": -1,
    "statusCode": "AC0003",
    "message": "Error",
    "description": "Error Message",
    "responseData": []
}

Errors

IR0001 · HTTP 400

Invalid Request: Malformed or invalid request body. Check syntax and required fields.

Invalid Request: Malformed or invalid request body. Check syntax and required fields.
```
{
    "status": 0,
    "statusCode": "IR0001",
    "message": "Invalid Request: Malformed or invalid request body. Check syntax and required fields."
}
```

PM0002 · HTTP 422

Parameter Missing: Required parameter is missing.

{
    "status": 0,
    "statusCode": "PM0002",
    "message": "Parameter Missing: Required parameter is missing."
}

VF0003 · HTTP 422

Validation Failed: Input validation failed.

{
    "status": 0,
    "statusCode": "VF0003",
    "message": "Validation Failed: Input validation failed."
}

IE0004 · HTTP 404

Invalid Api Endpoint: Endpoint not found.

{
    "status": 0,
    "statusCode": "IE0004",
    "message": "Invalid Api Endpoint: Endpoint not found."
}

IC0007 · HTTP 401

Invalid Credentials: Authentication failed.

{
    "status": 0,
    "statusCode": "IC0007",
    "message": "Invalid Credentials: Authentication failed."
}

SE0006 · HTTP 500

Internal Server Error: Server is down. Please try again later.

Internal Server Error: Server is down. Please try again later.
```
{
    "status": 0,
    "statusCode": "SE0006",
    "message": "Internal Server Error: Server is down. Please try again later."
}
```

AE0021 · HTTP 400

Invalid Header: Header validation failed.

{
    "status": 0,
    "statusCode": "AE0021",
    "message": "Invalid Header: Header validation failed."
}

AE0022 · HTTP 429

Authentication Error: Rate limit exceeded. Please try again later.

Authentication Error: Rate limit exceeded. Please try again later.
```
{
    "status": 0,
    "statusCode": "AE0022",
    "message": "Authentication Error: Rate limit exceeded. Please try again later."
}
```
AE0024 · HTTP 400

Authentication Error: Invalid timestamp format (must be yyyy-MM-ddTHH:mm:ss).

Authentication Error: Invalid timestamp format (must be yyyy-MM-ddTHH:mm:ss).
```
{
    "status": 0,
    "statusCode": "AE0024",
    "message": "Authentication Error: Invalid timestamp format (must be yyyy-MM-ddTHH:mm:ss)."
}
```
AE0026 · HTTP 401

Authentication Error: Header Token is invalid or inactive.

Authentication Error: Header Token is invalid or inactive.
```
{
    "status": 0,
    "statusCode": "AE0026",
    "message": "Authentication Error: Header Token is invalid or inactive."
}
```

AE0028 · HTTP 403

Authentication Error: IP address not allowed.

{
    "status": 0,
    "statusCode": "AE0028",
    "message": "Authentication Error: IP address not allowed."
}

AC0001 · HTTP 200

Success: Transaction processed successfully.

{
    "status": 1,
    "statusCode": "AC0001",
    "message": "Success: Transaction processed successfully."
}

AC0002 · HTTP 422

Failed: Transaction failed downstream with Airtel Bank.

Failed: Transaction failed downstream with Airtel Bank.
```
{
    "status": 0,
    "statusCode": "AC0002",
    "message": "Failed: Transaction failed downstream with Airtel Bank."
}
```
AC0003 · HTTP 500

Error: System error or partner connectivity failure.

Error: System error or partner connectivity failure.
```
{
    "status": 0,
    "statusCode": "AC0003",
    "message": "Error: System error or partner connectivity failure."
}
```

APB_000 · HTTP 200

Success: Ideal success code in all scenarios.

{
    "status": 1,
    "statusCode": "APB_000",
    "message": "Success: Ideal success code in all scenarios."
}

APB_001 · HTTP 422

Form Data not found (Biller is not configured in the system).

Form Data not found (Biller is not configured in the system).
```
{
    "status": 0,
    "statusCode": "APB_001",
    "message": "Form Data not found (Biller is not configured in the system)."
}
```
APB_002 · HTTP 422

Insufficient balance in account, please add funds and try again.

Insufficient balance in account, please add funds and try again.
```
{
    "status": 0,
    "statusCode": "APB_002",
    "message": "Insufficient balance in account, please add funds and try again."
}
```
APB_004 · HTTP 422

Amount cannot be credited as account exceeds maximum balance limit.

Amount cannot be credited as account exceeds maximum balance limit.
```
{
    "status": 0,
    "statusCode": "APB_004",
    "message": "Amount cannot be credited as account exceeds maximum balance limit."
}
```
APB_006 · HTTP 422

Credit freeze on account, ask beneficiary to contact bank.

Credit freeze on account, ask beneficiary to contact bank.
```
{
    "status": 0,
    "statusCode": "APB_006",
    "message": "Credit freeze on account, ask beneficiary to contact bank."
}
```

APB_010 · HTTP 422

Either debit or credit account is closed.

{
    "status": 0,
    "statusCode": "APB_010",
    "message": "Either debit or credit account is closed."
}

APB_011 · HTTP 422

Transaction could not be processed as Credit account is blocked.

Transaction could not be processed as Credit account is blocked.
```
{
    "status": 0,
    "statusCode": "APB_011",
    "message": "Transaction could not be processed as Credit account is blocked."
}
```
APB_042 · HTTP 422

Permissible daily transaction amount has exceeded.

Permissible daily transaction amount has exceeded.
```
{
    "status": 0,
    "statusCode": "APB_042",
    "message": "Permissible daily transaction amount has exceeded."
}
```
APB_043 · HTTP 202

Transaction pending. Deposited amount will be credited against ID.

Transaction pending. Deposited amount will be credited against ID.
```
{
    "status": 1,
    "statusCode": "APB_043",
    "message": "Transaction pending. Deposited amount will be credited against ID."
}
```
APB_111 · HTTP 422

Default failure code: Partner Not Found or Partner status is inactive.

Default failure code: Partner Not Found or Partner status is inactive.
```
{
    "status": 0,
    "statusCode": "APB_111",
    "message": "Default failure code: Partner Not Found or Partner status is inactive."
}
```
APB_112 · HTTP 422

Txn failed due to duplicate request, please retry with fresh ID.

Txn failed due to duplicate request, please retry with fresh ID.
```
{
    "status": 0,
    "statusCode": "APB_112",
    "message": "Txn failed due to duplicate request, please retry with fresh ID."
}
```
APB_121 · HTTP 422

No such transaction exists in system, please retry.

No such transaction exists in system, please retry.
```
{
    "status": 0,
    "statusCode": "APB_121",
    "message": "No such transaction exists in system, please retry."
}
```

APB_182 · HTTP 422

Balance not found for corresponding COD account.

{
    "status": 0,
    "statusCode": "APB_182",
    "message": "Balance not found for corresponding COD account."
}

APB_183 · HTTP 422

Account details not found.

{
    "status": 0,
    "statusCode": "APB_183",
    "message": "Account details not found."
}

Notes

🔄 Airtel CMS 4-Step Transaction Flow

Start Transaction: Call /api/v1/cms/airtel/start with merchantId and transactionId to receive the official Airtel Bank Plugin redirection URL.
Enter Details & Generate OTP: Retailer opens the redirection URL and enters biller, depositor mobile, and cash amount.
OTP Verification & Balance Check: Retailer enters OTP; Airtel triggers balance_check and balance_check_debit webhook callbacks.
Transaction Posting: Once completed, Airtel sends transaction_post callback (delivered within 15 minutes) and retailer commission is credited.

💰 Real-Time Wallet Balance, Commission & Auto-Refund

Zero Surcharge: No fee or surcharge is charged to the retailer or customer on cash collections.
Retailer Commission: The retailer earns a commission on each successfully settled transaction, credited automatically to their primary wallet.
Atomic Debit: Your wallet is atomically debited for the exact collection amount when Airtel issues the balance_check_debit callback.
Instant Auto-Refund: If the transaction fails downstream (Status Failed or provider decline), your wallet is 100% automatically refunded.

🔔 Inbound Callback Contract

In every callback request and response, all fields must be strings.
The status field accepts only "1" (Success) or "0" (Fail).
Always maintain a stable HTTPS callback listener and respond promptly with valid JSON.

Rate Limits

60/min