> ## Documentation Index > Fetch the complete documentation index at: https://docs.waftpay.io/llms.txt > Use this file to discover all available pages before exploring further. # Refund/Reversal Status > Query the latest status of a refund or reversal request. ## Overview Use this endpoint to check the status of a refund or reversal request that was previously initiated in the platform. > **Auth**: Requires a **Collection token** (`Authorization: Bearer `). Need to initiate a refund or reversal? See [Initiate Refund/Reversal](/api-reference/collections/collections-refund-initiate). *** ## Endpoint ```http theme={null} POST {BASE_URL}/tsq/api/v1/query/refund-reversal ``` *** ## Request body Provide the `request_uuid` you received when the refund/reversal was created. ```json theme={null} { "request_uuid": "A333RTYUT" } ``` *** ## Example response ```json theme={null} { "code": 102, "status": "SUCCESS", "description": "Transaction success", "results": { "result_code": "21", "result_description": "The service request is processed successfully", "amount": "1015.00", "total_charges": "0.00", "total_amount": "1015.00", "account": "254792452002", "original_payment_uuid": "882231418121042119", "original_transaction_reference": "TNC0009886898418", "original_external_reference": "1V1OPZZGHQ", "external_reference": "1V33UUE1IR", "time_processed": "2025-08-26T05:20:27Z" } } ``` *** ## Notes * If the refund/reversal is not found, the response body will include a `NOT FOUND` status. * Errors follow the standard error shape. See [Errors](/errors). ## OpenAPI ````yaml POST /tsq/api/v1/query/refund-reversal openapi: 3.1.0 info: title: Waftpay Payments API description: >- Process payments, collect funds, and remit payouts with Waftpay. Includes Authentication Token, idempotency, webhooks, and sandbox support. license: name: MIT version: 1.0.0 servers: - url: https://dev.waftpay.io description: Sandbox (dev) security: - bearerAuth: [] tags: - name: Authentication description: Obtain and manage access tokens - name: Payments description: Charge a customer and track status - name: Collections description: Customer-initiated payments and hosted checkouts - name: Checkout description: >- Hosted checkout flow for customer payments. Flow: 1. Ensure the Collections service is enabled for your account. 2. Use `consumer_key` and `consumer_secret` to generate a Bearer token via **Get Authentication Token**. 3. Cache the token and refresh only on expiry. 4. Call **Create Checkout Request** with customer details, amount, and redirect URLs. 5. Use the returned `checkout_url` for redirect or iframe. 6. The `callback_url` receives a payload matching the `CheckoutCallback` schema. - name: Remittance description: Send payouts to mobile wallets and bank accounts - name: Webhooks description: Receive asynchronous notifications - name: Utilities description: Common utilities (idempotency, health) paths: /tsq/api/v1/query/refund-reversal: post: tags: - Refunds summary: Query Refund Reversal description: >- Query the status of a refund reversal by request_uuid. Returns a standardized APIResponse with status and transaction details when found. If not found, a NOT FOUND-style response is returned in the payload. This endpoint requires a Bearer token. operationId: queryRefundReversal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundReversalTsqRequest' examples: default: value: request_uuid: A333RTYUT responses: '200': description: Refund reversal status payload content: application/json: schema: $ref: '#/components/schemas/RefundReversalQueryResponse' examples: success: value: code: 102 status: SUCCESS description: Transaction success data: {} failed: value: code: 400 status: REJECTED description: Invalid payment reversal request data: {} unauthorizedInBody: summary: Authorization failure represented in body (tenant style) value: code: 401 status: FAILED AUTHORIZATION description: Unauthorized results: {} notFoundInBody: summary: Not found represented in body (tenant style) value: code: 404 status: NOT FOUND description: Transaction not found results: {} '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: RefundReversalTsqRequest: type: object required: - request_uuid properties: request_uuid: type: string description: >- Refund/reversal request UUID returned when the refund/reversal was created. example: A333RTYUT RefundReversalQueryResponse: type: object required: - code - status - description - results properties: code: type: integer description: >- Application code for the query result (e.g., 102=SUCCESS, 103=FAILED, 401/404 represented in body where applicable). status: type: string description: >- Outcome label (e.g., SUCCESS, FAILED, FAILED AUTHORIZATION, NOT FOUND). description: type: string description: Human-readable description of the outcome. results: oneOf: - $ref: '#/components/schemas/RefundReversalResults' - type: object description: Empty results object for non-success outcomes. additionalProperties: false examples: success: value: code: 102 status: SUCCESS description: Transaction success results: {} failed: value: code: 103 status: FAILED description: Transaction Failed results: {} unauthorizedInBody: value: code: 401 status: FAILED AUTHORIZATION description: Unauthorized results: {} notFoundInBody: value: code: 404 status: NOT FOUND description: Transaction not found results: {} RefundReversalResults: type: object description: >- Provider/platform response fields for a refund reversal query. Fields are optional and may vary by provider. properties: result_code: type: string result_description: type: string amount: type: number total_charges: type: number total_amount: oneOf: - type: number - type: string description: >- Total amount; some providers return labeled strings (e.g., MPESA_KE_MOCK). service_code: type: string account: type: string transaction_reference: type: string payment_uuid: type: string original_payment_uuid: type: string original_transaction_reference: type: string original_external_reference: type: string external_reference: type: - string - 'null' time_processed: type: string format: date-time description: ISO 8601 timestamp; may include fractional seconds. validation_hash: type: string metadata: type: object additionalProperties: type: - string - number - boolean - 'null' description: Arbitrary key-value metadata echoed back by the platform/provider. additionalProperties: true WaftpayErrorEnvelope: type: object required: - code - status - description properties: code: type: string description: >- Application code. Can be a top-level code (e.g., 400.600) or a granular code (e.g., 404.001.000). status: type: string description: >- Semantic status, e.g., REJECTED, FAILED, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, ACCEPTED. description: type: string description: Human-readable description. data: type: object description: Additional details (may be empty). additionalProperties: true nullable: true examples: notFoundGranular: summary: 404 with granular code value: code: 404.001.000 status: REJECTED description: Requested resource not found data: {} validationFailed: summary: 400 validation failed value: code: '400.100' status: REJECTED description: Validation failed data: field_errors: - field: recipient.account message: Invalid account unauthorized: summary: 401 failed authentication value: code: '400.200' status: REJECTED description: Failed Authentication data: null forbidden: summary: 403 failed authorization value: code: '403.300' status: REJECTED description: Failed Authorization data: null internal: summary: 500 internal server error value: code: '400.500' status: FAILED description: Internal server error data: null Error: type: object required: - error - message properties: error: type: string description: Machine readable error code message: type: string description: Human readable message param: type: string request_id: type: string responses: Unauthorized: description: Missing or invalid token content: application/json: schema: $ref: '#/components/schemas/WaftpayErrorEnvelope' examples: unauthorized: value: code: 400.001.100 status: REJECTED description: Invalid or expired token data: {} NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/Error' examples: error: value: error: internal_error message: An unexpected error occurred request_id: req_456 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````