Transactions

One list across every kind of money movement (charges, payouts, deposits, withdrawals and refunds) for reconciliation.

The transaction object

{
  "id": "chg_01J9Z3K8Q4W6XK2M7N5P0R3T8V",
  "object": "transaction",
  "type": "CHARGE",
  "approval_status": "NOT_REQUIRED",
  "status": "SUCCESSFUL",
  "amount": "50000",
  "currency": "UGX",
  "country": "UG",
  "network": "MTN",
  "msisdn_masked": "+2567****456",
  "reference": "order-9001",
  "fee": "1250",
  "net": "48750",
  "provider": "…",
  "metadata": { "cart_id": "c_42" },
  "created_at": "2026-09-28T09:29:51.000Z",
  "updated_at": "2026-09-28T09:30:08.000Z"
}

Attributes

idstring: The underlying object's id: chg_, pyt_, dep_, wdl_ or ref_.
objectstring: Always "transaction".
typeenum: CHARGE, PAYOUT, DEPOSIT, WITHDRAWAL or REFUND.
approval_statusenum: NOT_REQUIRED, PENDING (waiting for a second team member), APPROVED or REJECTED.
statusenum: See Transaction statuses.
amountstring: Minor units, as a string.
currencyenum: UGX, KES or GHS.
countryenum: The wallet's country: UG, KE or GH.
networkenum: MTN or AIRTEL.
msisdn_maskedstring: The wallet number, masked (+2567****456). Full numbers are never returned.
referencestring: Your reference, unchanged.
feestring: SkanPay's fee booked so far ("0" until the transaction succeeds).
netstring: Money in (charges, deposits, refunds): amount − fee. Money out (payouts, withdrawals): amount + fee, the total debited.
providerstring | null: An identifier for the rail that carried the payment. Informational: don't build logic on it.
metadataobject | null: As sent.
created_atstring: ISO 8601, UTC.
updated_atstring: ISO 8601, UTC. Changes with the status.

It carries no failure_code or description; fetch the typed object (e.g. GET /v1/charges/:id) or the timeline below for those.

List transactions

GET/v1/transactions

Newest first, cursor-paginated.

Query parameters

typeenumOptional: CHARGE, PAYOUT, DEPOSIT, WITHDRAWAL, REFUND
statusenumOptional: Any status.
approval_statusenumOptional: NOT_REQUIRED, PENDING, APPROVED, REJECTED
referencestringOptional: Exact match.
currencyenumOptional: UGX, KES, GHS
limitintegerOptional: 1–100, default 25.
starting_afterstringOptional: The next_cursor of the previous page.

curl "https://api.skanpay.website/v1/transactions?type=CHARGE&status=SUCCESSFUL&currency=UGX&limit=100" \
  -H "Authorization: Bearer $SKANPAY_SECRET_KEY"

Retrieve a transaction, with its timeline

GET/v1/transactions/:id

Any transaction id works. Returns the transaction, every status event in order, and every ledger entry behind it. See Reconciliation for how to read the ledger.

{
  "transaction": { "id": "chg_…", "object": "transaction", "type": "CHARGE", ... },
  "events": [
    { "id": "evt_…", "status": "INITIATED", "source": "API", "provider_status": null, "message": null, "created_at": "…" },
    ...
  ],
  "ledger": [
    { "id": "…", "journal_id": "…", "account": "PROVIDER_FLOAT", "side": "DEBIT", "amount": "50000", "currency": "UGX", "reason": "CHARGE_SETTLED", "created_at": "…" },
    ...
  ]
}

curl

curl https://api.skanpay.website/v1/transactions/chg_01J9Z3K8Q4W6XK2M7N5P0R3T8V \
  -H "Authorization: Bearer $SKANPAY_SECRET_KEY"

Returns 404 transaction_not_found for an unknown id.