Overview

The AutoSKU system is an automated background engine built into the Celbux platform. It is designed to intelligently route and split funds from a merchant’s daily transactions into various beneficiary wallets based on pre-configured percentage rules (“SKUs”).

Instead of forcing your POS systems or integration layers to perform complex, real-time splits on every single payment, AutoSKU handles it mathematically in the background at the end of every day.

How It Works

1. Enroll the Merchant: You tell the platform to actively monitor a specific merchant’s daily payments by enrolling them via /createAutoSKU.
2. Define the Rules: You map product identifiers (SKUs) to specific beneficiary wallets and assign them percentage allocations. This is done using the Create SKU Split API.
3. Take Payments: Your integration continues processing normal /pay transactions throughout the day, ensuring you pass the relevant SKU data inside the transaction metadata.
4. Automated Settlement: At midnight, the AutoSKU engine reviews all transactions from the previous day, calculates the exact percentage splits, deducts any configured platform fees, and moves the funds out of the merchant’s wallet into the appropriate beneficiary wallets automatically.

Platform Commission & Allocation Limits

When a standard payment occurs, the Celbux platform deducts a real-time default commission (typically 3%) from the merchant’s received funds. Because this commission is deducted instantly and belongs to the platform, the AutoSKU engine can only allocate the remaining percentage of the funds.

Therefore, when creating your SKU split rules, the total sum of your beneficiary percentages cannot exceed 97% (or 100% - Default Commission). If you attempt to allocate more than the maximum allowed percentage to outside wallets, the API will return an error to prevent the merchant’s wallet from going into a negative balance.

Example

A customer buys a cup of coffee at a franchise using your app. The total transaction is R20.00.

The Create SKU Split API was used to define a rule for the SKU Coffee_SKU outlining where the funds should go:

• 3% (R0.60) is deducted instantly as the Celbux platform commission.
• 77% (R15.40) remains with the Merchant.
• 10% (R2.00) goes to the Franchise HQ Wallet.
• 10% (R2.00) goes to a Staff Tip Wallet.

    "RulesJSON": "[{\"Username\":\"franchiseHQWallet\",\"Percentage\":\"10.00\"},{\"Username\":\"staffTipsWallet\",\"Percentage\":\"10.00\"}]",

When you process the payment, the initial R19.40 (after the 3% commission) lands in the Merchant’s wallet instantly. At midnight, the AutoSKU engine kicks in, recognizes the Coffee_SKU tag on the transaction, and automatically routes the R2.00 to the HQ Wallet and R2.00 to the Tip Wallet out of the merchant’s balance, in batched transactions.

Triggering an AutoSKU Payment

For the AutoSKU engine to recognize a payment and calculate the splits, your integration must pass a Products array inside the transaction’s stringified Metadata parameter when executing a standard /pay call.

The Quantity * PricePerUnit inside the array must mathematically equate to the total root Amount of the transaction, otherwise the transaction will be rejected.

Here is an example of the exact Metadata string formatting required in your /pay payload:

{
    "VoucherNo": "168-25130-30290",
    "StoreID": "celbuxMerchantStore",
    "Amount": "2000",
    "Currency": "ZAR",
    "Reference": "TXN_12345",
    "Metadata": "{\"Products\":[{\"SKU\":\"Coffee_SKU\",\"PricePerUnit\":1000,\"Quantity\":2}]}"
}

Handling Failures (Dead Letters)

Because AutoSKU runs asynchronously in the background at midnight, it is designed to handle unexpected errors gracefully. If an automated split transfer fails, for example, if a beneficiary wallet has been locked, or if the merchant has insufficient funds because they manually withdrew the money too early, the system will safely intercept the failure to protect the ledger.

Instead of crashing or dropping the data, the failed transaction payload is written to the Dead Letters table. Integrators and platform admins can easily view these trapped failures using the View AutoSKU Dead Letters API, resolve the underlying issue, and manually retry the transfer safely.