Deposits

A deposit tops up your own available balance from a mobile money wallet. No fee, available immediately.

Method	Path
POST	`/v1/deposits`	Create a deposit
GET	`/v1/deposits/:id`	Retrieve a deposit

To list deposits, use GET /v1/transactions?type=DEPOSIT.

The deposit object

{
  "id": "dep_01J9Z5B2C3D4E5F6G7H8J9K0M1",
  "object": "deposit",
  "status": "SUCCESSFUL",
  "amount": "500000",
  "currency": "UGX",
  "country": "UG",
  "network": "MTN",
  "msisdn_masked": "+2567****000",
  "reference": "topup-2026-09-28",
  "description": "Float for payouts",
  "provider": "…",
  "failure_code": null,
  "failure_message": null,
  "metadata": null,
  "created_at": "2026-09-28T08:00:00.000Z",
  "updated_at": "2026-09-28T08:00:40.000Z"
}

Attributes

idstring: Unique id, prefixed dep_.
objectstring: Always "deposit".
statusenum: See Transaction statuses.
amountstring: Credited to your available balance in full when it succeeds.
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.
descriptionstring | null: As sent.
providerstring | null: An identifier for the rail that carried the payment. Informational: don't build logic on it.
failure_codestring | null: Why it failed. See failure codes.
failure_messagestring | null: Human-readable reason. Don't parse it.
metadataobject | null: As sent.
created_atstring: ISO 8601, UTC.
updated_atstring: ISO 8601, UTC. Changes with the status.

Create a deposit

POST/v1/deposits

Sends a prompt to the wallet's phone, like a charge. The outcome arrives as deposit.successful or deposit.failed.

Headers

Idempotency-KeyheaderRequired: 8–255 characters. Same key and body returns the original response. See Idempotency.

Body parameters

amountstringRequired: Integer minor units as a string, e.g. "50000". See Amounts.
currencyenumRequired: UGX, KES or GHS. Must be the currency of the wallet's country.
msisdnstringRequired: The paying wallet's phone number. International format (+256772123456) is safest; local formats are read against country or your account's country. See Phone numbers.
referencestringRequired: Your own id for this payment, e.g. your order id. 1–128 characters from A–Z a–z 0–9 . _ : -. Returned unchanged everywhere.
networkenumOptional: MTN or AIRTEL. Worked out from the number; send it only when you get network_required, or when you already know it. It always wins over the prefix table.
countryenumOptional: UG, KE or GH. Read from the number's dialing code; used only to interpret a number in local format. Defaults to your account's country.
descriptionstringOptional: Up to 255 characters, for your own records.
metadataobjectOptional: Up to 20 keys of your own data. Values are strings (≤ 512 characters), numbers, booleans or null.

curl -X POST https://api.skanpay.website/v1/deposits \
  -H "Authorization: Bearer $SKANPAY_SECRET_KEY" \
  -H "Idempotency-Key: topup-2026-09-28" \
  -H "Content-Type: application/json" \
  -d '{"amount":"500000","currency":"UGX","msisdn":"+256772123000","reference":"topup-2026-09-28"}'

Retrieve a deposit

GET/v1/deposits/:id

curl

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

Returns the deposit, or 404 deposit_not_found.