> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction Status and Complaint Response
> Use this API to poll the result of a previously submitted complaint or transaction status request.
Call this using `bill_fetch_ref_id`, `transaction_ref_id`, and optionally `msg_id` from the Complaint Request API.
Continue polling until `data.txn_status_complain_response` is present with a terminal `response_code`.
| `message` | Meaning |
|---|---|
| `"Transaction status fetched successfully"` | Completed. Check `txn_list` for details. |
| `"Request is still in progress"` | Still processing. Continue polling. |
## OpenAPI
````yaml /openapi/bbps/bbps-cou.yaml post /bbps/cou/v1/billers/response/complaint
openapi: 3.0.3
info:
title: BBPS for Customers (Customer Operating Unit)
version: 1.0.0
description: >
APIs for Agent Institutions to integrate with the Bharat Bill Payment System
(BBPS) as a Customer Operating Unit (COU). These APIs enable bill discovery,
bill fetch, bill payment, complaint management, and wallet operations.
servers:
- url: https://sandbox.cashfree.com
description: Sandbox (Testing) environment.
- url: https://api.cashfree.com
description: Production environment.
security:
- XClientID: []
XClientSecret: []
paths:
/bbps/cou/v1/billers/response/complaint:
post:
tags:
- Complaints
summary: Transaction Status & Complaint Response (Polling)
description: >-
Use this API to poll the result of a previously submitted complaint or
transaction status request.
Call this using `bill_fetch_ref_id`, `transaction_ref_id`, and
optionally `msg_id` from the Complaint Request API.
Continue polling until `data.txn_status_complain_response` is present
with a terminal `response_code`.
| `message` | Meaning |
|---|---|
| `"Transaction status fetched successfully"` | Completed. Check
`txn_list` for details. |
| `"Request is still in progress"` | Still processing. Continue polling.
|
operationId: getComplaintStatus
requestBody:
description: Request parameters to poll a complaint or transaction status request.
required: true
content:
application/json:
schema:
type: object
required:
- transaction_ref_id
- bill_fetch_ref_id
properties:
transaction_ref_id:
type: string
description: >-
Unique transaction reference ID from the original bill
payment
example: OU011010XTZVU2DAW9SO
msg_id:
type: string
description: >-
Message ID received from the Complaint Request API response
(data.msg_id)
example: 8ENSVVR4QOS7X1UGPY7JGUV444P10102202
bill_fetch_ref_id:
type: string
description: Unique reference ID generated during the Bill Fetch step
example: HENSVVR4QOS7X1UGPY7JGUV444P10102202
example:
transaction_ref_id: OU011010XTZVU2DAW9SO
msg_id: 8ENSVVR4QOS7X1UGPY7JGUV444P10102202
bill_fetch_ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
responses:
'200':
description: >-
Success response for polling a complaint or transaction status
request.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: HTTP status of the API call. This is always "OK".
example: OK
message:
type: string
description: Human-readable outcome indicator.
example: Transaction status fetched successfully
data:
type: object
properties:
txn_status_complain_response:
type: object
description: >-
Present when the request has been processed. Null
while still in progress.
properties:
msg_id:
type: string
description: Message ID echoed from the request.
example: 8ENSVVR4QOS7X1UGPY7JGUV444P10102202
response_code:
type: string
description: >-
"000" indicates success; any other value indicates
failure.
example: '000'
response_reason:
type: string
description: Human-readable description of the response code.
example: SUCCESS
txn_list:
type: array
description: List of transaction records matching the query.
items:
type: object
properties:
agent_id:
type: string
description: >-
ID of the Agent Institution that initiated
the transaction.
biller_id:
type: string
description: Biller ID for which the payment was made.
approval_ref_num:
type: string
nullable: true
description: >-
Approval reference number from the biller or
NPCI.
txn_reference_id:
type: string
description: Unique transaction reference ID.
mti:
type: string
description: >-
Message type indicator. Example value is
PAYMENT.
txn_date:
type: string
description: >-
Timestamp of the transaction in ISO 8601
format.
example: '2021-01-10T17:19:53+05:30'
amount:
type: string
description: Transaction amount in paise.
example: '100000'
txn_status:
type: string
description: Final status of the transaction.
enum:
- SUCCESS
- FAILED
- PENDING
compliance_resp_cd:
type: string
nullable: true
description: >-
Compliance response code returned by NPCI.
Present on failure.
compliance_reason:
type: string
nullable: true
description: >-
Human-readable reason for the compliance
response code.
dispute_id:
type: string
nullable: true
description: >-
Unique dispute ID if a dispute was raised
for this transaction.
dispute_date:
type: string
nullable: true
description: Date on which the dispute was raised.
dispute_type:
type: string
nullable: true
description: >-
Type of dispute raised. Example values are
chargeback and complaint.
dispute_status:
type: string
nullable: true
description: >-
Current status of the dispute. Example
values are ACCEPTED, REJECTED, and PENDING.
dispute_amount:
type: string
nullable: true
description: Amount under dispute in paise.
payment_ref_id:
type: string
nullable: true
description: >-
Internal payment reference ID assigned by
the COU platform.
customer_mobile:
type: string
nullable: true
description: >-
Mobile number of the customer who initiated
the payment.
transaction_ref_id:
type: string
description: >-
Present only in the PROCESSING response. This is the
transaction reference ID being polled.
nullable: true
msg_id:
type: string
description: >-
Present only in the PROCESSING response. This is the
message ID being polled.
nullable: true
status:
type: string
description: >-
Present only in the PROCESSING response. This is
always "PROCESSING".
nullable: true
examples:
success:
summary: Success
value:
status: OK
message: Transaction status fetched successfully
data:
txn_status_complain_response:
msg_id: 8ENSVVR4QOS7X1UGPY7JGUV444P10102202
response_code: '000'
response_reason: SUCCESS
txn_list:
- agent_id: OU01XXXXINT001123456
biller_id: ONNSTNS00NAT01
approval_ref_num: AB12345001
txn_reference_id: OU011010XTZVU2DAW9SO
mti: PAYMENT
txn_date: '2021-01-10T17:19:53+05:30'
amount: '100000'
txn_status: SUCCESS
dispute_id: OU012021021027717238
dispute_status: ACCEPTED
payment_ref_id: OU011010PUDQS23GR8MM70T7Z9E71L14JH3XBTVJ0RO
customer_mobile: '9123456079'
processing:
summary: Processing
value:
status: OK
message: Request is still in progress
data:
transaction_ref_id: HENSVVR4QOS7X1UGPY7JGUV444P10102202
msg_id: 8ENSVVR4QOS7X1UGPY7JGUV444P10102202
status: PROCESSING
'400':
description: Bad request error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication Error.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
'500':
description: API related Error.
components:
schemas:
ErrorResponse:
type: object
properties:
status:
type: string
example: BAD_REQUEST
message:
type: string
example: Validation error description
data:
nullable: true
example: null
UnauthorizedResponse:
type: object
properties:
message:
type: string
example: Unauthorized
securitySchemes:
XClientID:
type: apiKey
in: header
name: x-client-id
description: >-
Your unique client identifier issued by Cashfree. You can find this in
your [Merchant
Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).
XClientSecret:
type: apiKey
in: header
name: x-client-secret
description: >-
Your unique client secret issued by Cashfree. Keep this confidential and
never expose it in client-side code. You can find this in your [Merchant
Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).
````