> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Payment Transaction Status

> Poll the current status of a payment collection or payout. Prefer webhooks; use this only when you cannot receive them.

## 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](/api-reference/endpoint/webhook) 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

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

### Path parameters

| Name            | Type   | Description                                           |
| --------------- | ------ | ----------------------------------------------------- |
| `transactionId` | string | Cartevo transaction ID (UUID) returned at initiation. |

### Query parameters

| Name                      | Type    | Default | Description                                                                                                                 |
| ------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `doubleCheck`             | boolean | `false` | If `true`, force a re-fetch from the upstream operator before returning. Slower; useful when local state seems stale.       |
| `includeUpstreamResponse` | boolean | `false` | If `true`, attach the raw upstream-operator payload as `upstream` in the response. For debugging.                           |
| `skipCompanyCheck`        | boolean | `false` | **Internal/ops use only.** Bypasses the company-ownership check. Requires elevated privileges; ordinary tokens are ignored. |

## Response

### 200 — Success

```json theme={null}
{
  "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
  }
}
```

| Field            | Type   | Description                                                                              |
| ---------------- | ------ | ---------------------------------------------------------------------------------------- |
| `transaction_id` | string | Echoes the path parameter.                                                               |
| `external_id`    | string | Your idempotency key (or auto-generated).                                                |
| `status`         | string | One of `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`. Both terminal: `SUCCESS`, `FAILED`. |
| `type`           | string | `COLLECTION` or `PAYOUT`.                                                                |
| `reason`         | string | Short human-readable reason.                                                             |
| `description`    | string | Free-form description (echoes the `purpose` field if you set one).                       |
| `error_message`  | string | Populated only when `status: FAILED`.                                                    |

### Error responses

| Status | Trigger                                                   |
| ------ | --------------------------------------------------------- |
| `404`  | Transaction does not exist or belongs to another company. |

## Code examples

```bash cURL theme={null}
curl https://api.cartevo.co/api/v1/payment/transactions/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer $TOKEN"
```

```js Node.js (axios) — polling pattern theme={null}
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");
}
```

## Related

* [Webhooks](/api-reference/endpoint/webhook) — preferred way to learn outcomes.
* [`POST /payment/collect`](/api-reference/endpoint/post-payment-collect)
* [`POST /payment/payout`](/api-reference/endpoint/post-payment-payout)


## OpenAPI

````yaml GET /payment/transactions/{transactionId}/status
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /payment/transactions/{transactionId}/status:
    get:
      summary: Get Transaction Status
      description: Check the status of a payment transaction using transaction ID.
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Transaction UUID
      responses:
        '200':
          description: Transaction status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Transaction status retrieved successfully
                  data:
                    $ref: '#/components/schemas/TransactionStatus'
        '404':
          description: Transaction not found
components:
  schemas:
    TransactionStatus:
      type: object
      properties:
        transaction_id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
            - PROCESSING
          example: SUCCESS
        amount:
          type: number
          example: 1000
        currency:
          type: string
          example: XAF
        phone_number:
          type: string
          example: '237670000000'
        country:
          type: string
          example: CM
        operator:
          type: string
          example: mtn
        type:
          type: string
          enum:
            - COLLECTION
            - PAYOUT
          example: COLLECTION
        external_id:
          type: string
          example: ORD-2024-001
        reason:
          type: string
          example: Invoice payment
        description:
          type: string
          example: Payment collection transaction
        created_at:
          type: string
          format: date-time
          example: '2025-01-08T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-01-08T12:05:00.000Z'
        error_message:
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````