Airtel CMS · Airtel CMS Services

Status Check

Retrieve real-time transaction status, bank UTR, and posting details

POST request

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

Body

{
    "transactionId": "NCMS428F49XXX"
}

Include a valid Bearer token with every request

Code sample

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

<?php

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

echo $response->getBody();

import requests

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

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/status', {"transactionId":"NCMS428F49XXX"}, {
  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": "",
    "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"
        }
    ]
}

Failure response

{
    "status": 0,
    "statusCode": "AC0002",
    "message": "Failed",
    "description": "Failure Message",
    "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": "",
            "commission": "0",
            "otherFields": "",
            "description": "APB_002: Insufficient balance in account",
            "tranStatus": "Failed"
        }
    ]
}

Overview

Airtel CMS Status Check

This API endpoint is used to retrieve the status of a transaction. Successful authentication will yield a response containing relevant status of the transaction or an error message if the query fails.

Request Parameters (JSON Body)

Parameter	Required	Data Type	Description	Example
`transactionId`	YES	`string`	Unique transaction ID between 12 to 25 characters long.	`NCMS428F49XXX`

Response Fields (`responseData[]`)

Field	Data Type	Description
`merchantId`	`string`	Merchant phone / ID
`amount`	`string`	Collected cash amount
`transactionId`	`string`	Unique transaction identifier
`billerId`	`string`	Biller ID selected by customer
`billerName`	`string`	Biller organization name
`mobile`	`string`	Customer mobile number
`tranDateTime`	`string`	Bank transaction date & time (`dd-MM-yyyy HH:mm:ss`)
`utr`	`string`	Unique bank reference number (UTR)
`commission`	`string`	Retailer commission earned on transaction
`tranStatus`	`string`	Transaction status: `Success`, `Failed`, or `Pending`
`description`	`string`	Bank remarks or error description

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 Status Check

Schema

{
    "type": "object",
    "required": [
        "transactionId"
    ],
    "properties": {
        "transactionId": {
            "type": "string",
            "description": "Unique transaction identifier between 12 to 25 characters long.",
            "example": "NCMS428F49XXX"
        }
    }
}

Example

{
    "transactionId": "NCMS428F49XXX"
}

Responses

200 · application/json default

Real-time transaction status and bank settlement details retrieved successfully.

Example

{
    "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"
        }
    ]
}

422 · application/json

Failure Response (AC0002)

Example

{
    "status": 0,
    "statusCode": "AC0002",
    "message": "Failed",
    "description": "Failure Message",
    "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": "",
            "commission": "0",
            "otherFields": "",
            "description": "APB_002: Insufficient balance in account",
            "tranStatus": "Failed"
        }
    ]
}

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

Status Check

Overview

Airtel CMS Status Check

Request Parameters (JSON Body)

Response Fields (responseData[])

Headers

Body

Responses

Errors

Notes

🔄 Airtel CMS 4-Step Transaction Flow

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

🔔 Inbound Callback Contract

Rate Limits

Response Fields (`responseData[]`)