Skip to content
Pipevest Developers

Get payment status

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

Returns the status of the collection (C2B, payment) and/or disbursement (B2C, disbursement) for an order. Poll this endpoint to learn a payment outcome — signed outbound webhooks are not available yet.

The lookup is scoped to the organization the access token belongs to: an order owned by another tenant is reported exactly as a nonexistent one, with the same 404 and an identical body.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
orderId
required
string
Example
clx0a1b2c3d4e5f6g7h8i9j0k

Order identifier (CUID string). Rejected with 400 before the lookup if it is not a plausible order reference.

Responses

Section titled “Responses”

200

Section titled “200”

Transaction status

Media typeapplication/json
object
message
string
data
object
orderId
string
payment
object
id
string
type

INCOMING = C2B collection, OUTGOING = B2C disbursement.

string
Allowed values: INCOMING OUTGOING
amount
string
currency
string
status
string
Allowed values: PENDING PROCESSING CONFIRMED FAILED EXPIRED
provider
string
Allowed values: ZAMTEL MTN AIRTEL
telcoTransactionId
string
nullable
telcoConversationId
string
nullable
confirmedAt
string format: date-time
nullable
failedAt
string format: date-time
nullable
failureReason
string
nullable
createdAt
string format: date-time
disbursement
object
id
string
type

INCOMING = C2B collection, OUTGOING = B2C disbursement.

string
Allowed values: INCOMING OUTGOING
amount
string
currency
string
status
string
Allowed values: PENDING PROCESSING CONFIRMED FAILED EXPIRED
provider
string
Allowed values: ZAMTEL MTN AIRTEL
telcoTransactionId
string
nullable
telcoConversationId
string
nullable
confirmedAt
string format: date-time
nullable
failedAt
string format: date-time
nullable
failureReason
string
nullable
createdAt
string format: date-time
Example
{
  "message": "Transaction status retrieved successfully",
  "data": {
    "orderId": "clx0a1b2c3d4e5f6g7h8i9j0k",
    "payment": {
      "id": "clpaya1b2c3d4e5f6g7h8i9j0",
      "type": "INCOMING",
      "amount": "150.00",
      "currency": "ZMW",
      "status": "PENDING",
      "provider": "ZAMTEL"
    },
    "disbursement": {
      "id": "clpaya1b2c3d4e5f6g7h8i9j0",
      "type": "INCOMING",
      "amount": "150.00",
      "currency": "ZMW",
      "status": "PENDING",
      "provider": "ZAMTEL"
    }
  }
}

400

Section titled “400”

The orderId is not a valid order reference

Media typeapplication/json
object
error
string
message
string
Example
{
  "error": "Invalid request",
  "message": "Order ID is not a valid order reference"
}

401

Section titled “401”

Authentication failed

Media typeapplication/json
object
error
string
message
string
Example
{
  "error": "Unauthorized",
  "message": "Invalid organization authentication token"
}

404

Section titled “404”

No payment or disbursement found for the order — including when the order belongs to another organization.

Media typeapplication/json
object
error
string
message
string
Example
{
  "error": "Transaction not found",
  "message": "No payment or disbursement transaction found for order clx0a1b2c3d4e5f6g7h8i9j0k"
}

500

Section titled “500”

Unexpected server error. The body is the error label alone — never an exception message, stack frame or database detail.

Media typeapplication/json
object
error
string
Example
{
  "error": "Internal Server Error"
}