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 payout using one of your identifiers. This endpoint is useful for reconciliation or when webhooks are delayed.
Auth: Requires a Payout token (Authorization: Bearer <payout_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 payout.
request_uuidstringRequest UUID returned by the platform (if provided).
payment_uuidstringWaftpay payment UUID (numeric string).

​
Example (by transaction reference)

{
  "transaction_reference": "TXN213687756272200"
}

​
Example (by payment UUID)

{
  "payment_uuid": "8363546214883574601"
}

​
Example response

{
  "code": 102,
  "status": "SUCCESS",
  "description": "Transaction Was Successful",
  "results": {
    "result_code": "0",
    "result_description": "The service request is processed successfully.",
    "amount": 100.0,
    "total_charges": 10.0,
    "total_amount": 100.0,
    "service_code": "SAF_MOCK_PAYOUT",
    "account": "254708374149",
    "transaction_reference": "410823",
    "payment_uuid": "413377670969114276",
    "external_reference": "3C1HH12RIN",
    "time_processed": "2026-01-08T07:43:47.800432367Z",
    "validation_hash": "04213f90a36e1de7b8a7f49e13cd0bd7a1066d3d552ef9035e145cf6e7a8c160",
    "metadata": {}
  }
}

​
Notes

  • state can be processing, succeeded, failed, or canceled.
  • If the payout 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