Skip to main content
GET
/
payment
/
transactions
/
{transactionId}
/
status
Get Transaction Status
curl --request GET \
  --url https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "Transaction status retrieved successfully",
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SUCCESS",
    "amount": 1000,
    "currency": "XAF",
    "phone_number": "237670000000",
    "country": "CM",
    "operator": "mtn",
    "type": "COLLECTION",
    "external_id": "ORD-2024-001",
    "reason": "Invoice payment",
    "description": "Payment collection transaction",
    "created_at": "2025-01-08T12:00:00.000Z",
    "updated_at": "2025-01-08T12:05:00.000Z",
    "error_message": "<string>"
  }
}

​
Overview

GET /payment/transactions/{transactionId}/status returns the current status of a payment collection or payout. It is intended as a fallback when you cannot receive webhooks — for production traffic, the webhook flow is more reliable and lower-latency.

​
When to use it

  • Your webhook receiver was down and you need to reconcile what you missed.
  • You’re polling from a worker that doesn’t expose a public webhook endpoint.
  • You’re investigating a specific transaction during support.

​
Polling guidance

  • Cadence: Poll at most once every 5 seconds. After 30 seconds, switch to exponential backoff (10s, 20s, 40s, …).
  • Stop conditions: Stop polling once status is SUCCESS or FAILED. Both are terminal.
  • Timeout: If the status remains PENDING / PROCESSING for more than 15 minutes, treat the transaction as failed and reach out to support.

​
Prerequisites

  • The transaction must belong to your company (or you supply skipCompanyCheck=true and have the privilege — see below).

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>

​
Path parameters

NameTypeDescription
transactionIdstringCartevo transaction ID (UUID) returned at initiation.

​
Query parameters

NameTypeDefaultDescription
doubleCheckbooleanfalseIf true, force a re-fetch from the upstream operator before returning. Slower; useful when local state seems stale.
includeUpstreamResponsebooleanfalseIf true, attach the raw upstream-operator payload as upstream in the response. For debugging.
skipCompanyCheckbooleanfalseInternal/ops use only. Bypasses the company-ownership check. Requires elevated privileges; ordinary tokens are ignored.

​
Response

​
200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "ORD-2026-001",
    "status": "SUCCESS",
    "type": "COLLECTION",
    "amount": 1000,
    "currency": "XAF",
    "operator": "mtn",
    "country": "CM",
    "phone_number": "237670000000",
    "reason": "Payment completed",
    "description": "Invoice payment for May 2026",
    "created_at": "2026-05-09T10:15:00.000Z",
    "updated_at": "2026-05-09T10:15:42.000Z",
    "error_message": null
  }
}
FieldTypeDescription
transaction_idstringEchoes the path parameter.
external_idstringYour idempotency key (or auto-generated).
statusstringOne of PENDING, PROCESSING, SUCCESS, FAILED. Both terminal: SUCCESS, FAILED.
typestringCOLLECTION or PAYOUT.
reasonstringShort human-readable reason.
descriptionstringFree-form description (echoes the purpose field if you set one).
error_messagestringPopulated only when status: FAILED.

​
Error responses

StatusTrigger
404Transaction does not exist or belongs to another company.

​
Code examples

cURL
curl https://api.cartevo.co/api/v1/payment/transactions/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer $TOKEN"
Node.js (axios) — polling pattern
async function waitForStatus(token, transactionId) {
  const start = Date.now();
  let delay = 5000;

  while (Date.now() - start < 15 * 60 * 1000) {
    const { data } = await axios.get(
      `https://api.cartevo.co/api/v1/payment/transactions/${transactionId}/status`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    if (["SUCCESS", "FAILED"].includes(data.data.status)) {
      return data.data;
    }
    await new Promise((r) => setTimeout(r, delay));
    if (Date.now() - start > 30_000) delay = Math.min(delay * 2, 60_000);
  }
  throw new Error("Transaction did not finalize within 15 minutes");
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
transactionId
string<uuid>
required

Transaction UUID

Response

Transaction status retrieved successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Transaction status retrieved successfully"

​
data
object