Managing Wallets

For Enterprise partners, the ability to issue and manage wallets is the core of the "Closed Loop" ecosystem. This allows you to create digital accounts for your users (students, parents, staff) and manage the funds within them.

1. Creating a Wallet

To issue a new wallet, make a request to the API. This creates a "Partner Wallet" which is owned by your organization but assigned to a specific user entity.

Endpoint: Create Wallet

Response & Mapping

The API will return a Wallet Object. The most critical field is the walletId.

Data Mapping

Sticitt does not store your user's personal details (Name, Email, ID) during this phase. You must store the walletId in your own database and map it to your internal User ID.

2. Funding Wallets

There are two ways to get money into a wallet:

EFT: The user (or your organization) deposits directly into the wallet using its unique accountReference.
From your partner account: You programmatically move funds out of your own partner account float into the wallet.

Option A: EFT

Every wallet created has a unique accountReference (e.g., SABCPXYZ). Funds are loaded into the wallet via standard EFT (Electronic Funds Transfer) using this reference.

Banking Details for EFT

To load funds, the user (or your organization) must make a bank transfer using the specific Account Reference found in the Wallet Object.

Field	Value
Beneficiary	`Sticitt`
Bank	`FNB (Cheque)`
Account Number	`62719297922`
Branch Code	`250655`
Reference	`<YOUR_WALLET_ACCOUNT_REFERENCE>`

Processing Times

Funds typically clear within 15min - 48hours depending on the bank.

Funding in Test Mode

Since real money cannot be used in the Sandbox:

Do not EFT to the live bank account using test references.
Contact Support: Email technology@sticitt.co.za with your Test Wallet ID or Account Reference to have test funds allocated.

Option B: From Your Partner Account

If your partner account already holds funds, you can push them into any wallet you manage without an EFT. This is the usual mechanism for distributing an allowance or a bulk allocation from a central pot.

Endpoint: Transfer partner account funds to wallet

Body:

{
  "amount": 50000,
  "walletReference": "March allowance",
  "partnerReference": "PAYRUN-2026-03"
}

Field	Requirement	Description
`amount`	Required	Amount in cents. `50000` = R500.00. Use a negative amount to sweep funds back out of the wallet into your partner account.
`walletReference`	Optional	Reference shown on the wallet's side of the transaction.
`partnerReference`	Optional	Your own reference, for reconciliation on the partner account side.

Returns: The updated Wallet Object.

Check your partner account balance before a funding run to confirm you have enough float to cover it.

3. Retrieving Your Partner Account Balance

Separate from the individual wallets, your partner account has its own account (the "float"). This is the pot that Option B funding draws from, so you will want to check it before any bulk allocation.

Endpoint: Get account balance

Request: No parameters or body. The account is resolved from the partner_id on your access token, so you always get the balance of your own partner account.

Response:

{
  "availableBalance": 1250000
}

Field	Type	Description
`availableBalance`	`integer`	Funds available to distribute, in cents (ZAR). `1250000` = R12 500.00.

Cached Value

availableBalance excludes funds already reserved by pending transactions. It is a cached figure, so a very recent EFT into your partner account may take a moment to reflect.

Wallet balances are separate

This endpoint returns your account balance only — it does not aggregate your wallets. To read an individual wallet's balance, use the wallet endpoints in the next section.

4. Retrieving Wallet Info

You can query the balance and status of wallets at any time.

List Wallets: Get list of wallets
- Returns: List of wallets linked to your partner account.
Wallet Details: Get wallet by ID
- Returns: Wallet Object with details such as balance and status.
Transaction History: Get wallet transactions
- Returns: Paged, date-filterable list of a wallet's transactions (detailed below).

Transaction History

Retrieve a wallet's ledger — funds in and out — as a paged, date-filterable list.

Endpoint: Get wallet transactions

GET /v3/wallets/{walletId}/transactions

Query Parameters

Parameter	Type	Default	Notes
`pageSize`	integer	`50`	Results per page. Must be between `1` and `200`.
`pageIndex`	integer	`0`	Zero-based page number.
`fromDate`	date-time	–	Optional. ISO-8601 UTC (e.g. `2026-01-01T00:00:00Z`). Inclusive lower bound.
`toDate`	date-time	–	Optional. Inclusive upper bound. Must be on or after `fromDate`.

Response

Returns a paged result; transactions are ordered newest first.

{
  "items": [
    {
      "transactionId": "0f8e1f2a-...",
      "dateTime": "2026-07-15T12:00:00Z",
      "amount": 7500,
      "accountCreditReference": "SGTDPNPS",
      "accountDebitReference": "SABCPXYZ",
      "creditReference": "Tuck shop",
      "debitReference": "Allowance"
    }
  ],
  "pagination": {
    "totalCount": 178,
    "totalPages": 4,
    "pageIndex": 0,
    "pageSize": 50
  }
}

Amounts are in cents

The amount field is an integer in cents (e.g. 7500 = R75.00), not rand.

Direction of a transaction

Each transaction references both sides of the ledger. When accountCreditReference matches your wallet's accountReference, funds moved in; when accountDebitReference matches, funds moved out.

Ownership required

You can only read transactions for a wallet your partner account owns or is linked to. Requesting a wallet outside your ecosystem — or one that does not exist — returns 404 Not Found; no transaction data is exposed.

Use pagination.totalCount to drive paging, and pass fromDate/toDate to scope a statement period.

5. Executing Payments (Closed Loop)

Unlike the Standard Payment Flow where the User authorizes the payment via the SDK, Enterprise partners can programmatically execute payments on behalf of the wallet.

Requirement: This functionality is only available for Closed Loop transactions.

The Merchant must be managed by you (the Partner).
The Wallet must be managed by you (the Partner).

The Execution Call

You perform this by updating a pending payment with the funding walletId.

Endpoint: Update Payment

Set the payment status to 2 (Execute payment) and include the walletId in the request body. Optionally add a walletHolderName to identify the user for reporting purposes.

Body:

{
  "status": 2,
  "walletId": "7f8e1f2a-...",
  "walletHolderName": "John Doe"
}

Permission Denied

If you attempt to use a Partner Wallet to pay a Public Merchant (one you do not own), this call will fail. Partner Wallets are restricted to your own merchant ecosystem until the user "Links" the wallet.

6. Transferring Funds

You can programmatically transfer funds between any two wallets that are linked to your partner account. This is useful for peer-to-peer flows, such as a parent transferring allowance to a child's wallet, or distributing funds from a central pot to user wallets.

Endpoint: Transfer wallet funds

Constraints

Same Ecosystem: Both the Source Wallet and the Destination Wallet must be linked to or created by your Partner account. You cannot transfer funds to a random Sticitt user who is not part of your integration.
Funds Availability: The source wallet must have a sufficient balance.

7. Claiming and Linking wallets

A wallet in your ecosystem can exist in one of three states. Understanding these states resolves the confusion around "who controls what."

State	Description	Spend Scope	Partner Control
1. Partner Wallet (Unclaimed)	A wallet you created via API. The user has no Sticitt account yet. It acts like a "Gift Card" specific to your platform.	Restricted (Your Merchants Only)	✅ Full
2. Claimed Wallet	The user has "claimed" this wallet by registering a full Sticitt profile.	Global (Any Sticitt Merchant)	⚠️ Shared
3. Linked Wallet	An existing Sticitt user (who already had an account) has authorized your platform to link to their wallet.	Global (Any Sticitt Merchant)	⚠️ Shared

Linking a Wallet

To gain access to an existing Sticitt user's wallet (State 3), you must perform a "Link" operation. This authorizes you as a partner to manage their wallet on their behalf.

Prerequisite: You must have obtained a User Access Token for the specific user you wish to link.

See User Authentication for details on how to get this token.

Endpoint: Link a wallet

Token Switch

For this specific call, do not use your standard Client Credentials token. You must use the access_token you received from the User Login flow in the Authorization header.

Request: Header: Authorization: Bearer <USER_ACCESS_TOKEN> Body: (Empty)

Response: The API returns the Wallet Object

1. Creating a Wallet​

Response & Mapping​

2. Funding Wallets​

Option A: EFT​

Banking Details for EFT​

Funding in Test Mode​

Option B: From Your Partner Account​

3. Retrieving Your Partner Account Balance​

4. Retrieving Wallet Info​

Transaction History​

Query Parameters​

Response​

5. Executing Payments (Closed Loop)​

The Execution Call​

6. Transferring Funds​

Constraints​

7. Claiming and Linking wallets​

Linking a Wallet​