Skip to main content

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​

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.

FieldValue
BeneficiarySticitt
BankFNB (Cheque)
Account Number62719297922
Branch Code250655
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:

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

3. 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.

4. 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.

  1. The Merchant must be managed by you (the Partner).
  2. 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.

5. 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.

6. 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."

StateDescriptionSpend ScopePartner 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 WalletThe user has "claimed" this wallet by registering a full Sticitt profile.Global
(Any Sticitt Merchant)		⚠️ Shared
3. Linked WalletAn 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.

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