Create Collection

This endpoint initiates a payment collection request to a customer's mobile money account. The transaction will initially be in a PENDING state until the customer authorizes the payment, the request is declined, or it times out.

Endpoint

POST /collections/collect

Request Parameters

Parameter	Type	Required	Description
phone	string	Yes	The phone number of the payer (must include country code)
amount	number	Yes	The amount to collect (must be greater than 0)
externalId	string	No	Your system's reference ID for this transaction
payerMessage	string	No	Message displayed to the payer during authorization
payeeNote	string	No	Note for your own records (not shown to payer)

Headers

Header	Value	Required	Description
Authorization	Bearer YOUR_API_KEY	Yes	Your API authorization token
Content-Type	application/json	Yes	The format of the request body

Example Request

const createCollection = async () => {
  try {
    const response = await fetch(
      "https://pay.computerstore.ug/api/v1/collections/collect",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          phone: "+256706859041",
          amount: 500,
          externalId: "order-20250520-001",
          payerMessage: "Payment for internet subscription",
          payeeNote: "ZenFii Hotspot System",
        }),
      }
    );

    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Error:", error);
  }
};

Response Parameters

The response will include information about the created transaction:

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": "Request sent to provider",
  "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": "PENDING",
    "message": "Request sent to provider",
    "payerMessage": "Payment for internet subscription",
    "payerName": "MUJUNI INNOCENT",
    "createdAt": "2025-05-20T18:55:51.336Z"
  },
  "statusCode": 201
}

Status Codes

Code	Description
201	Request created successfully
400	Bad request - check your parameters
401	Unauthorized - check your API key
500	Server error occurred

Notes

• The phone number must include the country code (e.g., +256 for Uganda)
• The transaction ID returned in the response should be stored for future reference
• You can use the transaction ID to check the status of the payment using the Check Status endpoint
• The customer will receive a prompt on their phone to authorize the payment
• You will receive a webhook notification when the transaction status changes