Developer API

Kollectar AR exposes a small server-to-server API for approved payment and collection partners. Use it to confirm a customer account, show the amount due, and post a successful payment back to Kollectar AR.

This page is the quickstart for going live.

What This API Does#

The payment flow is intentionally simple:

1. Validate the customer account.
2. Check the outstanding balance.
3. Collect payment in your channel.
4. Record the successful payment in Kollectar AR.

Kollectar AR then allocates the payment to open invoices, writes the audit trail, and queues downstream accounting sync where enabled.

Base URL#

https://kollectar-ar.com

All endpoints are under:

/api/public/v1/payments

Use HTTPS and send JSON:

Content-Type: application/json; charset=utf-8

Authentication#

Production requests require three headers issued by Kollectar AR:

Sign the exact raw JSON bytes you send. If your client signs one JSON string and sends another, the signature will fail.

Signing examples#

import { createHmac } from "node:crypto";

const body = {
  account_number: "BIN-100045",
  provider: "pegasus",
  channel: "ussd",
  request_reference: "PEG-REQ-20260605-0001",
};

const raw = JSON.stringify(body);
const timestamp = Date.now().toString();
const signature = createHmac("sha256", process.env.KOLLECTAR_API_SECRET)
  .update(`${timestamp}.${raw}`)
  .digest("hex");

await fetch("https://kollectar-ar.com/api/public/v1/payments/validate-account", {
  method: "POST",
  headers: {
    "content-type": "application/json; charset=utf-8",
    "x-api-key": process.env.KOLLECTAR_API_KEY,
    "x-timestamp": timestamp,
    "x-signature": signature,
  },
  body: raw,
});

1. Validate Account#

Use this before showing a customer balance or payment prompt.

POST /api/public/v1/payments/validate-account

Request:

{
  "account_number": "BIN-100045",
  "provider": "pegasus",
  "channel": "ussd",
  "request_reference": "PEG-REQ-20260605-0001"
}

Success response:

{
  "success": true,
  "code": "OK",
  "message": "Account is valid",
  "account_number": "BIN-100045",
  "customer_name": "Sample Customer Ltd",
  "customer_status": "active"
}

Common failures:

2. Check Balance#

Use this to show the amount currently due.

POST /api/public/v1/payments/balance-inquiry

Request:

{
  "account_number": "BIN-100045",
  "provider": "pegasus",
  "channel": "ussd",
  "request_reference": "PEG-REQ-20260605-0002"
}

Success response:

{
  "success": true,
  "code": "OK",
  "message": "Outstanding balance retrieved",
  "account_number": "BIN-100045",
  "customer_name": "Sample Customer Ltd",
  "customer_status": "active",
  "outstanding_amount": 125000,
  "currency": "UGX",
  "invoice_number": "INV-2026-00045",
  "billing_period": "2026-06",
  "allow_partial_payment": true,
  "minimum_payment_amount": 1,
  "payment_reference": "KAR-BIN-100045-1780500000000"
}

If the customer has no outstanding balance, the response is still successful but returns:

{
  "success": true,
  "code": "ZERO_BALANCE",
  "outstanding_amount": 0
}

3. Record Payment#

Call this only after your channel has successfully collected the money.

POST /api/public/v1/payments/record

Request:

{
  "transaction_id": "PEG-TXN-20260605-000123",
  "account_number": "BIN-100045",
  "invoice_number": "INV-2026-00045",
  "amount_paid": 50000,
  "currency": "UGX",
  "payment_date": "2026-06-05T09:30:00Z",
  "payment_method": "mobile_money",
  "status": "successful",
  "payer_phone": "+256700000000",
  "provider": "pegasus",
  "channel": "ussd",
  "request_reference": "PEG-REQ-20260605-0003",
  "provider_payload": {
    "receipt_number": "PEG-000123"
  }
}

Success response:

{
  "success": true,
  "code": "PROCESSED",
  "message": "Payment processed",
  "transaction_id": "PEG-TXN-20260605-000123",
  "payment_id": "9b1c5b3e-1a2c-4d8e-b3e7-77e3b1c2e0a1",
  "allocations_count": 1,
  "credit_amount": 0
}

transaction_id is the idempotency key. If you retry the same successful transaction, Kollectar AR returns HTTP 200 with:

{
  "success": true,
  "code": "DUPLICATE_IGNORED",
  "message": "Duplicate transaction ignored - original payment kept intact",
  "transaction_id": "PEG-TXN-20260605-000123",
  "payment_id": "9b1c5b3e-1a2c-4d8e-b3e7-77e3b1c2e0a1"
}

Treat DUPLICATE_IGNORED as success in your retry logic.

Field Summary#

Retries#

Retry safely when you receive a network timeout or a transient server error.

Do not create a new transaction_id for the same collected payment. Reuse the original transaction_id so Kollectar AR can deduplicate the callback.

Recommended retry behavior:

Optional: Reverse Payment#

Payment reversal is available for approved partners, but it is not required for the first integration unless agreed during go-live.

POST /api/public/v1/payments/reverse

Use it for chargebacks, refunds, or mistaken payment postings.

Go-Live Checklist#

Before production traffic starts, confirm:

• API key and HMAC secret have been issued through a secure channel.
• Your server clock is synchronized.
• You can call validate-account, balance-inquiry, and record.
• You have tested retrying the same transaction_id.
• Your support team knows what account number the customer will enter.
• Your reconciliation report includes transaction_id, account_number, amount_paid, currency, payment_date, and provider receipt number.

Support#

For credentials, test accounts, failed signatures, or production cutover, contact the Kollectar AR integration owner provided during onboarding.