Creating & Managing Payments
To initiate a transaction, your server must create a Payment Object via the API. This object acts as the "contract" for the transaction, defining how much is owed, who gets paid, and how it will appear on financial statements.
For the full list of parameters, data types, and example payloads, please see the Create Payment endpoint documentation.
Understanding the Fields
While the API Reference defines the schema, understanding the intent behind the fields ensures your reconciliation and user experience are seamless.
Financials
amount: The value of the transaction in Cents (ZAR).- Example: To charge R10.00, pass
1000.
- Example: To charge R10.00, pass
merchantId: The UUID of the Sticitt Merchant (e.g., the School or Shop) that will receive the funds.
If you are a payment integrator for your own store, you will be provided with a unique MerchantID when you get your API Credentials.
References & Descriptions
Sticitt provides multiple text fields to help you track and reconcile payments. Using these correctly is critical for reporting.
| Field | Mandatory? | Purpose | Best Practice |
|---|---|---|---|
reference | ✅ Yes | Primary Identifier. This is the "hard" link to your system (e.g., Invoice Number, Order ID). It is used by financial systems to match the payment. | Use your internal unique ID (e.g., INV-2024-001). |
description | ✅ Yes | Bank Statement Text. This text appears Sticitt Wallet history. | Keep recognizable (e.g., Tuckshop Lunch). Max 256 chars. |
project | ❌ No | Human Context. Describes the "campaign" or "event" tied to the payment. | Use for categorization (e.g., Grade 5 Camp or Matric Dance 2024). |
debtor | ❌ No | The Payer. A human-readable name of the person or family responsible for the payment. | Use the user's name or account name (e.g., Smith Family or John Doe). |
debtorReference | ❌ No | Tracking Code. A technical reference to track the user/session in your system. | Use a User ID or Session ID if you need to link the payment to a specific user profile programmatically. |
Control Flow (Redirects)
If you are using Payment Links or want the JS SDK to redirect the user after completion, you must populate these fields. If these fields are not populated, the SDK will call Javascript callbacks directly.
paymentSuccessfulReturnUrl: The user is redirected here immediately after a successful payment.paymentCancelReturnUrl: The user is redirected here if they actively cancel/abort the payment process.
When a user lands on your paymentSuccessfulReturnUrl, do not assume the payment is complete based solely on the URL visit. A user could manually type this URL. Always verify the status via Webhooks or a server-side GET request.
For payment Links, if you do not provide a paymentSuccessfulReturnUrl and paymentCancelReturnUrl, the user can get "stuck" on our payment completed page.
Filtering Payment Methods
By default, a payment object allows the user to pay using any method enabled for that merchant. You can restrict this using preferredPaymentMethods.
Common Mappings:
0: Sticitt Wallet1: Credit/Debit Card2: Ozow (EFT)3: Capitec Pay4: Stitch (EFT)5: eZAR (Crypto)6: Nedbank Pay
Leaving this array empty [] (default) will show all available options to the user.
Payment Methods could be updated from time to time. Please check the Create Payment API Reference for the latest list.
Retrieving Status
Once the payment is created, you will receive a paymentId. You can check the status of this payment at any time.
Endpoint: Get Payment
The API returns a generic status code (0-5).
0(Pending): Created, waiting for user action.1(Authorized): User has been redirected to the payment provider.2(Paid): Success. Funds are secured.3(Expired): The payment has not been paid within 4 days and is now expired.4(Canceled): The user or system aborted the transaction.5(Refunded): The payment was paid and then reversed/refunded.
Instead of polling this endpoint, we strongly recommend listening to Webhooks to get notified instantly when a payment status changes.