Skip to main content
POST
/
tsq
/
api
/
v1
/
query
/
payments
curl --request POST \
  --url https://dev.waftpay.io/tsq/api/v1/query/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_reference": "TXN213687756272200"
}
'
{
  "status": "<string>",
  "code": "<string>",
  "description": "<string>",
  "data": {
    "transaction_reference": "<string>",
    "payment_reference": "<string>",
    "time_received": "2023-11-07T05:31:56Z",
    "amount": 123,
    "total_charges": 123,
    "total_amount": 123,
    "payment_uuid": "<string>",
    "state": "<string>",
    "last_updated": "2023-11-07T05:31:56Z"
  }
}
{
  "error": "<string>",
  "message": "<string>",
  "param": "<string>",
  "request_id": "<string>"
}
{
  "code": "400.001.100",
  "status": "REJECTED",
  "description": "Invalid or expired token",
  "data": {}
}
{
  "error": "<string>",
  "message": "<string>",
  "param": "<string>",
  "request_id": "<string>"
}

​
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

POST {BASE_URL}/tsq/api/v1/query/payments

​
Request body

Provide one of the following fields:
FieldTypeNotes
transaction_referencestringYour client reference used when creating the remittance.
request_uuidstringRequest UUID returned by the platform (if provided).
payment_uuidstringWaftpay payment UUID (numeric string).

​
Example (by transaction reference)

{
  "transaction_reference": "TXN123654573"
}

​
Example (by payment UUID)

{
  "payment_uuid": "8363546214883574601"
}

​
Example response

{
  "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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
transaction_reference
string

This is the client-generated transaction reference

​
request_uuid
string

This is the request UUID.

​
payment_uuid
string

This is the payment UUID.

Response

Payment status

​
status
string
required
​
code
string
required

E.g., ACCEPTED, NOT_FOUND, FAILED.

​
description
string
required
​
data
object
required