> ## 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.

# Check Remittance Status

> Retrieve the latest status of a remittance using your reference or UUID.

## Overview

Query the current status of a remittance using one of your identifiers. This endpoint is useful for reconciliation or when webhooks are delayed.

> **Auth**: Requires a **Remittance token** (`Authorization: Bearer <remittance_token>`).

***

## Endpoint

```http theme={null}
POST {BASE_URL}/tsq/api/v1/query/payments
```

***

## Request body

Provide **one** of the following fields:

| Field                   | Type   | Notes                                                    |
| ----------------------- | ------ | -------------------------------------------------------- |
| `transaction_reference` | string | Your client reference used when creating the remittance. |
| `request_uuid`          | string | Request UUID returned by the platform (if provided).     |
| `payment_uuid`          | string | Waftpay payment UUID (numeric string).                   |

### Example (by transaction reference)

```json theme={null}
{
  "transaction_reference": "TXN123654573"
}
```

### Example (by payment UUID)

```json theme={null}
{
  "payment_uuid": "8363546214883574601"
}
```

***

## Example response

```json theme={null}
{
  "status": "200.100",
  "code": "ACCEPTED",
  "description": "Accepted for processing",
  "data": {
    "amount": 100,
    "total_charges": 0,
    "total_amount": 100,
    "transaction_reference": "TXN123654573",
    "payment_uuid": "8363546214883574601",
    "payment_reference": "1RJITP5HLL",
    "state": "processing",
    "time_received": "2025-04-04T06:13:52.585619Z",
    "last_updated": "2025-04-04T06:15:10.102993Z"
  }
}
```

***

## Notes

* `state` can be `processing`, `succeeded`, `failed`, or `canceled`.
* If the remittance is not found, you will receive a `NOT_FOUND` response.
* `payment_reference` is a separate Waftpay reference; do not send it as `payment_uuid`.
* Errors follow the standard error shape. See [Errors](/errors).


## OpenAPI

````yaml POST /tsq/api/v1/query/payments
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/payments:
    post:
      tags:
        - Payouts
        - Collections
      summary: Check Payment Status
      operationId: queryPaymentStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentStatusQueryRequest'
            examples:
              byTransactionReference:
                value:
                  transaction_reference: TXN213687756272200
              byPaymentUuid:
                value:
                  payment_uuid: '8363546214883574601'
              byRequestUuid:
                value:
                  request_uuid: 2BDHAJ8PWR
      responses:
        '200':
          description: Payment status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PaymentStatusQueryRequest:
      type: object
      properties:
        transaction_reference:
          type: string
          description: This is the client-generated transaction reference
        request_uuid:
          type: string
          description: This is the request UUID.
        payment_uuid:
          type: string
          description: This is the payment UUID.
      examples:
        - transaction_reference: TXN213687756272200
        - request_uuid: 2BDHAJ8PWR
        - payment_uuid: 1RJITP5HLL
    PayoutStatusResponse:
      type: object
      required:
        - status
        - code
        - description
        - data
      properties:
        status:
          type: string
        code:
          type: string
          description: E.g., ACCEPTED, NOT_FOUND, FAILED.
        description:
          type: string
        data:
          type: object
          required:
            - transaction_reference
            - payment_reference
            - time_received
          properties:
            amount:
              type: number
            total_charges:
              type: number
            total_amount:
              type: number
            transaction_reference:
              type: string
            payment_uuid:
              type: string
            payment_reference:
              type: string
            state:
              type: string
              description: processing | succeeded | failed | canceled
            time_received:
              type: string
              format: date-time
              description: ISO 8601 UTC timestamp. **Always ends with 'Z'**.
            last_updated:
              type: string
              format: date-time
              description: ISO 8601 UTC timestamp. **Always ends with 'Z'**.
          additionalProperties: true
      examples:
        processing:
          summary: Processing
          value:
            status: '200.100'
            code: ACCEPTED
            description: Accepted for processing
            data: {}
        notFound:
          summary: Not found
          value:
            status: '400.600'
            code: NOT_FOUND
            description: Payout with reference TXN213687756272200 was not found
            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
    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
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````