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.

The lookup is scoped to the organization the access token belongs to. You can only read orders that are your own.

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
  }
}

Failure responses

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"
}

Note

An order belonging to another organization returns this same 404, with an identical body — not a 403. A distinct status would confirm that the id exists, so the two cases are deliberately indistinguishable.

An orderId that is not a plausible order reference at all is rejected before the lookup with HTTP 400:

{
  "error": "Invalid request",
  "message": "Order ID is not a valid order reference"
}

An unexpected server-side failure returns HTTP 500 with the standard body — just an error label, and never an exception message, stack frame or database detail:

{
  "error": "Internal Server Error"
}

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