Payment Status

GET /v1/payment/status/{orderId} returns the current status of the mobile-money collection (money in, C2B) and/or disbursement (money out, B2C) associated with an order.

Caution

This endpoint is currently the only way a partner learns the outcome of a payment or disbursement. Signed outbound webhooks are on the roadmap but are not available yet, so you must poll this endpoint to confirm whether funds were collected or paid out.

Request

Authenticated with your bearer token and x-client-id. Returns HTTP 200 when a payment and/or disbursement exists for the order.

  curl --request GET \
    --url https://api.staging.pipevest.com/v1/payment/status/clx0a1b2c3d4e5f6g7h8i9j0k \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>'

Note

orderId is a CUID string (e.g. clx0a1b2c3d4e5f6g7h8i9j0k), not an integer.

Response

The data object always contains both a payment (incoming C2B) and a disbursement (outgoing B2C) field. Either may be null if that leg does not exist for the order.

{
  "message": "Transaction status retrieved successfully",
  "data": {
    "orderId": "clx0a1b2c3d4e5f6g7h8i9j0k",
    "payment": {
      "id": "clpaya1b2c3d4e5f6g7h8i9j0",
      "type": "INCOMING",
      "amount": "150.00",
      "currency": "ZMW",
      "status": "CONFIRMED",
      "provider": "ZAMTEL",
      "telcoTransactionId": "QR12ABCD34",
      "telcoConversationId": "AG_20260715_00007a1b2c3d",
      "confirmedAt": "2026-07-15T08:01:12.000Z",
      "failedAt": null,
      "failureReason": null,
      "createdAt": "2026-07-15T08:00:44.000Z"
    },
    "disbursement": null
  }
}

If neither a payment nor a disbursement exists for the order, the endpoint returns HTTP 404:

{
  "error": "Transaction not found",
  "message": "No payment or disbursement transaction found for order clx0a1b2c3d4e5f6g7h8i9j0k"
}

Field reference

Field	Description
type	INCOMING (C2B collection) or OUTGOING (B2C disbursement)
amount	Transaction amount as a decimal string
currency	ISO currency code (e.g. ZMW)
status	One of PENDING, PROCESSING, CONFIRMED, FAILED, EXPIRED
provider	Telco provider — ZAMTEL, MTN or AIRTEL
telcoTransactionId	Provider transaction ID (present once confirmed)
telcoConversationId	Provider conversation ID for the request
confirmedAt	Timestamp the transaction was confirmed, or null
failedAt	Timestamp the transaction failed, or null
failureReason	Human-readable failure reason, or null
createdAt	When the transaction record was created

Polling guidance

Tip

A collection or disbursement is asynchronous. After you initiate it, poll GET /v1/payment/status/{orderId} until status reaches a terminal state: CONFIRMED (success), FAILED or EXPIRED. Poll with a modest backoff (for example every few seconds) rather than in a tight loop.

Error Reference

Status codes and error shapes returned across the API