Merchant Webhooks

Enterprise Only

These webhooks are only available to partners who manage their own merchants. If you are a standard payment integrator, use the Payment Status Update instead.

These webhooks provide a real-time feed of the General Ledger for your merchants. They fire for every single financial movement, including:

• Incoming Payments (Principal).
• Transaction Fee deductions.
• Manual account adjustments.
• Settlement payouts.

---

1. MerchantTransactionInsert

This event triggers whenever a new financial entry is written to the merchant's account history.

Common Use Case: Building a shadow ledger or real-time statement for your merchants.

The Payload

The payload contains the transaction object. If the transaction originated from a Sticitt Payment (e.g., a user scanned a QR code), the full payment object is also included for context.

Example Payload:

{
  "webhookID": "1a2bfc86-e69b-4acf-b839-cfbd1a0bee00",
  "clientID": "cabbage",
  "body": {
    "merchantID": "dbba47d7-0776-4a05-a945-9040c0e0e2f3",
    "merchantAccountReference": "SZVEPQQL",
    "transaction": {
      "transactionID": "68e13345-6f71-4caa-95a3-800457716db4",
      "accountCreditReference": "SMASPNDB",
      "accountDebitReference": "SZVEPQQL",
      "dateTime": "2025-09-22T07:39:49.104272",
      "statementYear": null,
      "statementMonth": null,
      "amount": 100.0,
      "type": 2,
      "debitReference": "EFT Topup",
      "creditReference": "SZVEPQQL",
      "creditDisplayReference": "SZVEPQQL",
      "debitDisplayReference": "EFT Topup",
      "accountDebit": null,
      "accountCredit": null,
      "debitStatement": null,
      "creditStatement": null
    }
  },
  "type": "MerchantTransactionInsert"
}

Determining Direction

Sticitt treats the Merchant Account as an Asset Account. This means the standard accounting rules apply:

• Money IN (Debit): If transaction.accountDebitReference matches your merchantAccountReference.

• Money OUT (Credit): If transaction.accountCreditReference matches your merchantAccountReference.

Example: A customer payment (income) will show your merchant reference in the accountDebitReference field. A fee deduction (expense) will show your merchant reference in the accountCreditReference field.

Key Fields

• transaction.amount: The value of the movement in cents/base units.
• transaction.type: Integer representing the transaction category. See Transaction Types below for more details.
• transaction.creditReference: The account receiving the money.
• transaction.debitReference: The account losing the money.
• transaction.dateTime: The exact timestamp of the ledger entry.

Fee Reconciliation

You will often see two webhooks for a single sale:

1. Income: R100.00 (The customer payment).
2. Expense: R2.50 (The Sticitt transaction fee).

---

2. MerchantTransactionReversal

This event indicates that a specific accounting entry has been reversed at a system level.

Trigger: This typically happens during system corrections or rigorous accounting adjustments.

Important Distinction

• Payment Refund: A business logic event where you decide to give money back to a customer. This creates a new transaction (negative amount).
• Transaction Reversal: An accounting correction where an original entry is nullified.

Payload

The payload structure is similar to the Insert event but includes pointers to the Original Transaction Type that is being reversed.

{
    "webhookID": "3ea49e55-06d5-4a13-8e88-d2b23a23a28a",
    "clientID": "cabbage",
    "body": {
        "originalType": 9,
        "merchantID": "2a0ed44b-b928-4bfe-bad0-116fa360ba59",
        "merchantAccountReference": "SAUHPTXA",
        "transaction": {
            "transactionID": "33f5d56f-5a74-4dd5-9459-da706e58cb60",
            "accountCreditReference": "SMASPREV",
            "accountDebitReference": "SAUHPTXA",
            "dateTime": "2025-11-26T13:33:44.24375+00:00",
            "amount": 0.79,
            "type": 19,
            "debitReference": "Reversal",
            "creditReference": "Transaction Fee - SAUHPTXA",
            "creditDisplayReference": "Refund Cobus Greyling fee",
            "debitDisplayReference": "Refund Fee Sticitt Shop Dev"
        },
        "reversedAt": "2025-11-26T13:33:44.24375+00:00"
    },
    "type": "MerchantTransactionReversal"
}

---

3. MerchantTransactionsFinalized

This event is a "Daily Closing" signal. Unlike the real-time transaction webhooks, this event is fired once per day (usually early morning) for every merchant linked to your partner account.

It provides the definitive Closing Balance for the previous day.

Purpose: Reconciliation (Recon)

This webhook is your safety net. You should use it to verify that your internal ledger matches Sticitt's records.

• If the balance matches: Your real-time processing of MerchantTransactionInsert events was 100% accurate.
• If the balance differs: You likely missed a webhook or had a processing error during the day. You should trigger a re-sync.

The Payload

{
    "webhookID": "9ec69dbe-4390-49f2-b65a-e44424f5cf2c",
    "clientID": "cabbage",
    "body": {
        "merchantID": "0c8a4f88-43e0-4ce1-ac12-41a7b07c254c",
        "actualBalance": "4.64",
        "finalizationDate": "2025-09-26T00:00:00"
    },
    "type": "MerchantTransactionsFinalized"
}

The payload contains the snapshot of the account at the end of the finalized period.

• merchantID: The merchant this balance belongs to.
• actualBalance: The total closing balance of the merchant account (e.g., "4.64").
• finalizationDate: The specific date that was finalized.
  • Note: This will point to the previous day (the 24-hour period that just closed).

Recommended Recon Workflow

1. Listen for this webhook every morning.
2. Read the finalizationDate (e.g., 2025-09-26).
3. Sum all the MerchantTransactionInsert events you recorded for that specific date in your database.
4. Compare your calculated total against the actualBalance in this payload.
5. Recovery: If they do not match, use the API to query GET /v3/merchants/{id}/transactions filtering by the finalizationDate to download the official history and correct your local records.

---

Reference: Transaction Types

The transaction.type field is an integer that classifies the nature of the financial movement. Use this table to map the ID to its business meaning.

Core Payments & Transfers

ID	Name	Description
0	Purchase	Standard purchase transaction.
1	EftDebit	Electronic Funds Transfer (Debit).
2	EftCredit	Electronic Funds Transfer (Credit).
6	CpDebit	Credit/Debit card payment (Debit).
7	CpCredit	Credit/Debit card payment (Credit).
11	InstantEft	Instant EFT transaction.
13	Transfer	Internal transfer between accounts.
21	FlexpayPurchase	Flexpay purchase transaction.
32	EftCorpQrPayment	EftCorp QR payment.

Fees

ID	Name	Description
9	Fee	Standard fee charge.
10	CpFee	CapitecPay specific fee.
12	InstantFee	Fee for instant EFT.
14	DFee	Cash deposit fee.
15	RFee	Terminal Rental fee.
16	ReverseFee	Fee for processing a reversal.
17	InvoiceFee	Fee for invoice processing.
18	SubscriptionFee	Subscription service fee.
20	CardAccountFee	Fee for card account maintenance.
22	ReplaceCardFee	Fee for replacing a card.
31	SticittRewardActivationFee	Activation fee associated with a Sticitt reward.
33	EftCorpQrPaymentFee	Fee for EftCorp QR payment.

Refunds & Reversals

ID	Name	Description
3	Refund	Refund of a previous transaction.
19	Reverse	Reversal of a previous transaction (System correction).
23	FlexpayReversal	Reversal of a Flexpay transaction.

Rewards & Loyalty

ID	Name	Description
5	Loyalty	Loyalty points or rewards transaction.
24	LessonsEarnReward	Sticitt Lessons: Earn reward.
25	LessonsBudgetReward	Sticitt Lessons: Budget reward.
26	LessonsSavingsReward	Sticitt Lessons: Savings reward.
27	LessonsValueReward	Sticitt Lessons: Value reward.
28	LessonsShareReward	Sticitt Lessons: Share reward.
29	LessonsInvestReward	Sticitt Lessons: Investment reward.
30	SticittReward	General Sticitt platform reward.