Get Payment Transaction Status

Get Transaction Status

curl --request GET \
  --url https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

import requests

url = "https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/payment/transactions/{transactionId}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

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

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

Webhooks — preferred way to learn outcomes.
POST /payment/collect
POST /payment/payout

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

Show child attributes

Initiate Payout List Payment Transactions

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Polling guidance

Prerequisites

Request

Headers

Path parameters

Query parameters

Response

200 — Success

Error responses

Code examples

Authorizations

Path Parameters

Response

​Overview

​When to use it

​Polling guidance

​Prerequisites

​Request

​Headers

​Path parameters

​Query parameters

​Response

​200 — Success

​Error responses

​Code examples

​Related

Authorizations

Path Parameters

Response

Overview

When to use it

Polling guidance

Prerequisites

Request

Headers

Path parameters

Query parameters

Response

200 — Success

Error responses

Code examples

Related