airpay

View saved version →

---
name: airpay-workflows
description: Use when the user asks about their airpay merchant account - payment or order status, refunds, UPI QR codes, VPA validation, bank lists, subscriptions, POS transactions, or settlement status and reports - via the airpay MCP tools.
---

# airpay workflows

Use the airpay MCP tools as the source of truth. Only call tools that are actually exposed in the current session; never invent tool names, parameters, identifiers, or results.

## Identifiers

- `ap_transactionid` — airpay's internal numeric ID. Prefer it whenever available.
- `orderid` — merchant-generated order ID (alphanumeric, max 30 chars).
- `rrn` — bank Retrieval Reference Number.

Use identifiers exactly as the user supplied them or a previous tool returned them. Never substitute one kind for another.

## Workflows

1. **Check payment status** — call `airpay_order_confirmation` with exactly one of `ap_transactionid`, `orderid`, or `rrn`.
2. **Refund** — confirm the transaction with `airpay_order_confirmation`, show the user the order, amount, and refund amount, get explicit confirmation, then call `airpay_initiate_refund`. Follow up with `airpay_get_refund_status`. Refunds are irreversible.
3. **UPI QR payment** — optionally validate the payer VPA with `airpay_validate_vpa`, then `airpay_generate_qr`, then poll `airpay_order_confirmation` until a terminal state is returned.
4. **Split settlement** — call `airpay_order_confirmation` to get `rrn` and `ap_transactionid`, get explicit user confirmation, then call `airpay_split_settlement`. Irreversible.
5. **Consolidated settlement report** — call `airpay_settlement_report` with `from_date` and `to_date` (`page_no` defaults to 1).
6. **Transaction-wise settlement report** — first call `airpay_settlement_report` with `from_date` and `to_date` both set to the requested settlement date, pick the `version` for that date, then call `airpay_transactionwise_settlement_report` with `settlement_date` and `version`. Request further pages until no records are returned. Never ask the user for `api_type`; it is set internally.
7. **Other lookups** — `airpay_settlement_status`, `airpay_get_bank_list`, `airpay_pos_transaction_detail`, `airpay_check_subscription_status`, `airpay_create_invoice` as needed, following each tool's schema.

## Constraints

- Amounts are strings with exactly two decimals, e.g. `"100.00"`.
- `airpay_order_confirmation` and `airpay_get_refund_status` work only on LIVE merchant IDs, not sandbox.
- QR codes from `airpay_generate_qr` expire after a successful payment.
- Treat refunds, split settlements, QR generation, and invoice creation as consequential: confirm details with the user before calling.

## Reading results

`status_code` / `response_code` say whether the API call worked; `transaction_status` / `transaction_payment_status` say what happened to the payment.

| Code | Meaning |
| --- | --- |
| 200 | Success |
| 211 | In processing — poll again |
| 400 | Failed |
| 401 | Not registered properly |
| 402 | Not yet processed |
| 403 | No callback from bank |
| 405 | Bounced |
| 503 | No records found |

`transaction_payment_status` values: SUCCESS, FAIL, INPROCESS, INCOMPLETE, AUTHORIZE, CAPTURE, VOIDED, RISK, Mandate Approved.

- Never report success when any status field indicates failure, processing, incomplete, or no records.
- Preserve identifiers and monetary values exactly as returned.
- Distinguish authentication/connection errors from business declines or invalid input. Only ask the user to reconnect when a tool returns an authentication error.
- Never request or display passwords, tokens, keys, or other credentials.