Transaction Status API

This endpoint allows you to check the current status of any transaction (pay-in or payout) using its reference ID. This is useful for verifying transaction states, reconciliation, and troubleshooting payment issues.

Endpoint

GET /payment/status/{reference}

Headers

Name	Description
X-API-Key	Your Zikopay API Key
X-API-Secret	Your Zikopay API Secret
Accept	Must be application/json

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	The unique transaction reference ID returned during transaction creation

Example Request

GET /payment/status/TXN174506674372585E

Success Response

{
  "success": true,
  "message": "Transaction found",
  "data": {
    "reference": "TXN174506674372585E",
    "external_transaction_id": "OP123456789",
    "amount": 100,
    "currency": "XAF",
    "type": "payin",
    "operator": "orange_cm",
    "status": "completed",
    "status_description": "Payment completed successfully",
    "fee": 3.5,
    "created_at": "2025-04-12T14:30:45Z",
    "updated_at": "2025-04-12T14:45:22Z",
    "payment_details": {
      "order_id": "12345"
    },
    "customer": {
      "name": "John Doe",
      "phone": "696447002",
      "email": "john.doe@example.com"
    }
  }
}

Error Response

{
  "success": false,
  "message": "Transaction not found",
  "errors": {
    "reference": ["No transaction exists with the provided reference"]
  }
}

Response Parameters

Parameter	Type	Description
reference	string	Unique transaction reference ID
external_transaction_id	string	Transaction ID from the payment provider
amount	number	Transaction amount
currency	string	Transaction currency
type	string	Transaction type: payin or payout
operator	string	Payment operator used
status	string	Current transaction status
status_description	string	Human-readable description of the current status
fee	number	Transaction fee amount
created_at	string	ISO8601 timestamp when the transaction was created
updated_at	string	ISO8601 timestamp when the transaction was last updated
payment_details	object	Additional metadata provided during transaction creation
customer	object	Customer information

Transaction Status Values

Status	Description
pending	Transaction has been initiated but not yet processed
processing	Transaction is being processed by the payment provider
completed	Transaction has been successfully completed
failed	Transaction has failed
cancelled	Transaction was cancelled
expired	Transaction expired before completion
refunded	Transaction was refunded

Notes

• Transactions histories are available for 90 days via the API
• Check status regularly for pending transactions rather than creating new ones
• This endpoint is subject to the same rate limits as other API endpoints
• For real-time updates, we recommend using webhooks rather than polling this endpoint

Code Examples

PHP

<?php
$transactionReference = "TXN174506674372585E";
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payment.zikopay.com/v1/payment/status/{$transactionReference}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "X-API-Key: your_api_key",
    "X-API-Secret: your_api_secret"
  ],
]);

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

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $data = json_decode($response, true);
  if ($data['success']) {
    echo "Transaction status: " . $data['data']['status'];
    echo "Description: " . $data['data']['status_description'];
  } else {
    echo "Error: " . $data['message'];
  }
}
?>

JavaScript

const checkTransactionStatus = async (reference) => {
  try {
    const response = await fetch(`https://api.payment.zikopay.com/v1/payment/status/${reference}`, {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'X-API-Key': 'your_api_key',
        'X-API-Secret': 'your_api_secret'
      }
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log(`Transaction status: ${data.data.status}`);
      console.log(`Description: ${data.data.status_description}`);
      
      // Handle different statuses
      switch(data.data.status) {
        case 'completed':
          // Handle successful transaction
          break;
        case 'pending':
        case 'processing':
          // Transaction still in progress
          break;
        case 'failed':
        case 'cancelled':
        case 'expired':
          // Transaction unsuccessful
          break;
        default:
          // Other status
          break;
      }
      
      return data.data;
    } else {
      console.error('Status check failed:', data.message);
      return null;
    }
  } catch (error) {
    console.error('Error:', error);
    return null;
  }
};

// Example usage
checkTransactionStatus('TXN174506674372585E');

Python

import requests

transaction_reference = "TXN174506674372585E"
url = f"https://api.payment.zikopay.com/v1/payment/status/{transaction_reference}"

headers = {
  'Accept': 'application/json',
  'X-API-Key': 'your_api_key',
  'X-API-Secret': 'your_api_secret'
}

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

if response.status_code == 200:
    data = response.json()
    if data['success']:
        print(f"Transaction status: {data['data']['status']}")
        print(f"Description: {data['data']['status_description']}")
        
        # Process based on status
        if data['data']['status'] == 'completed':
            # Handle completed transaction
            pass
        elif data['data']['status'] in ['pending', 'processing']:
            # Handle in-progress transaction
            pass
        else:
            # Handle failed or other statuses
            pass
    else:
        print(f"Error: {data['message']}")
else:
    print(f"HTTP Error: {response.status_code}")

Recommended Implementation Pattern

For the best user experience, we recommend implementing the following pattern:

1. After initiating a transaction, store the reference ID in your system
2. Implement webhook handlers to receive real-time updates (primary method)
3. Use this status API endpoint as a backup or for manual reconciliation
4. Display appropriate messages to users based on the current status
5. Set up automated retry or notification logic for failed transactions

This approach ensures your system stays synchronized with the actual transaction status while providing a good user experience.