Check Collection Status

This endpoint allows you to check the current status of a payment collection transaction. Use this to verify whether a transaction has been completed, is still pending, or has failed.

Endpoint

GET /collections/status/{transactionId}

Path Parameters

Parameter	Type	Required	Description
transactionId	string	Yes	The unique ID of the transaction to check

Headers

Header	Value	Required	Description
Authorization	Bearer YOUR_API_KEY	Yes	Your API authorization token

Example Request

const checkStatus = async (transactionId) => {
  try {
    const response = await fetch(`https://pay.computerstore.ug/api/v1/collections/status/${transactionId}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error:', error);
  }
};

// Example usage
checkStatus('e870f17f-090b-40d6-9eb0-a1d683591917');

Response Parameters

The response includes the same structure as the create collection endpoint:

Parameter	Type	Description
success	boolean	Indicates if the request was processed successfully
message	string	Human-readable description of the result
payload	object	Contains all the transaction details
statusCode	number	HTTP status code of the response

Payload Object

Field	Type	Description
id	string	Unique transaction identifier
balanceId	string	Identifier for the merchant balance
amount	number	Transaction amount
currency	string	Currency code (currently only UGX supported)
payer	string	Phone number of the customer
payeeNote	string or null	Note for merchant reference
provider	string	Payment provider (AIRTEL_UG or MTN_UG)
externalId	string or null	Merchant-provided reference ID
status	string	Transaction status (PENDING, SUCCESS, FAILED, ROLLED_BACK)
message	string or null	Additional information about the transaction status
payerMessage	string or null	Message shown to the customer
payerName	string or null	Name of the customer if available
createdAt	string	ISO timestamp of when the transaction was created

Example Response

{
  "success": true,
  "message": "",
  "payload": {
    "id": "e870f17f-090b-40d6-9eb0-a1d683591917",
    "balanceId": "cm63k6vw50004sea47kkdv78s",
    "amount": 500,
    "currency": "UGX",
    "payer": "+256706859041",
    "payeeNote": "ZenFii Hotspot System",
    "provider": "AIRTEL_UG",
    "externalId": "order-20250520-001",
    "status": "FAILED",
    "message": "The Request ID is invalid/Already processed.",
    "payerMessage": "Payment for internet subscription",
    "payerName": "MUJUNI INNOCENT",
    "createdAt": "2025-05-20T18:55:51.336Z"
  },
  "statusCode": 200
}

Status Codes

Code	Description
200	Request successful
400	Bad request - invalid transaction ID format
401	Unauthorized - check your API key
404	Transaction not found
500	Server error occurred

Transaction Statuses

The transaction can have one of the following statuses:

Status	Description
PENDING	The transaction is awaiting customer authorization
SUCCESS	The transaction was successful and funds have been collected
FAILED	The transaction failed (customer rejected, insufficient funds, etc.)
ROLLED_BACK	The transaction was initially successful but has been reversed

Notes

• It's recommended to poll this endpoint periodically for transactions in PENDING status
• Alternatively, you can rely on webhook notifications to be informed of status changes
• If a transaction remains in PENDING status for too long, it will eventually time out and change to FAILED
• The status will never change from SUCCESS or FAILED to PENDING