Payment Aggregators and Branch Settlement Methods

You are opening GS-KV-03 next month and the till has to accept cash, cards through the group’s card-acquiring bank, two e-wallets and DuitNow — and each of those has to land in the right cashbook so the branch balances at close of day. By the end of this page you will know what a “settlement method” is in BigLedger (an item, not a setting), how the cashier’s payment buttons are derived from a branch link table, how to build that link for a new branch in two minutes from a screen or a CSV, where the branch’s default methods live, and why a sale can be taken at the till and then refuse to post an hour later with MISSING_CASHBOOK: STL_MTHD. It also explains the table called payment aggregators that 87 of 90 tenants carry, because its name promises something the product does not do. Linking a new branch takes a few minutes; the settlement methods themselves are usually already there.

Meet GadgetSphere

GadgetSphere Sdn Bhd runs 22 branches and 28 cashbooks across a primary bank, a secondary bank and a card-acquiring bank. Every branch takes cash and cards; the Klang Valley branches also take two e-wallets and DuitNow QR; the Penang branches take a regional e-wallet the others do not. At close of day each branch’s cash goes to that branch’s cash-in-hand cashbook, the card takings to the card-acquiring bank’s cashbook, the e-wallet takings to the wallet operator’s cashbook. That is about a dozen settlement methods in the whole group and roughly six to eight linked to any one branch.

Three things with similar names

The developers’ comment on the aggregator table says it “is read only from the client side and is used in drop downs in apps like Payment Channel”. That drop-down does not exist in any applet as of 2026-09-16, which is why the table gets a section of its own at the end rather than a step.

Where the money goes — the chain behind every payment button

When a cashier presses Card on a RM 3,499 laptop sale, the POS writes a line on the cash bill with txn_type = STL_MTHD, the settlement method’s item guid, and amount signum −1 (money coming in against the sale). At FINAL, posting turns that line into a journal entry by walking a chain:

1. the line’s item — the settlement method;
2. the item’s cashbook (cashbook_guid on the item, set when the method is created or imported);
3. the cashbook’s GL code (glcode_guid on the cashbook);
4. a subledger for that GL code and company, created on the spot if missing — and that is the account the payment is debited to.

Two links in that chain can be missing, and the failure is delayed until posting, long after the customer has left: no cashbook on the method gives MISSING_CASHBOOK: STL_MTHD [method code]; a cashbook with no GL code gives MISSING_GL_CODE: STL_MTHD [method code]. Nothing checks either when the method is linked to the branch, so the button renders and the sale is taken. Check the chain before you link a method to a till (Step 1).

Step 1: Check the settlement methods you are going to link

Doc Item Maintenance › the item › Settlement tab — or POS General › Settings › Settlement Method

The outcome: each of GS-KV-03’s eight payment types exists as a settlement method with a cashbook and a settlement type, and the cashbook has a GL code.

Open each method and confirm three things: it is a settlement method (txn_class STL_MTHD — the POS settings listing shows only these); its cashbook is the one the branch’s takings should land in — for cash, the branch’s own cash-in-hand cashbook, so a new branch usually needs one new Cash method or a cashbook of its own; and its settlement type is set. The POS reads the settlement type from the item’s extension row SETTLEMENT_TYPE, not from the column of the same name on the item — a method without that extension row is invisible to the POS even if it is linked to the branch (see Common mistakes).

If you are creating many methods at once, the CSV import takes 22 columns (SETTLEMENT_METHOD_CODE, SETTLEMENT_METHOD_NAME, CASHBOOK_CODE, SETTLEMENT_TYPE, the bank-charge and customer-surcharge columns and so on). Use the template named MasterData_Upload_SettlementMethod.csv; the one with _Reviewed in its name uses different headings and is rejected by the parser.

Step 2: Link the methods to the branch

POS General › Settings › Branch Settings › the branch › Settlement › Add — or Settings › Settlement Method › the method › Branch › Add

The outcome: GS-KV-03 has one link row per method it accepts, and the till at that branch shows exactly those buttons.

The same link can be made from either side: pick a branch and add methods, or pick a method and add branches (useful when a new e-wallet goes live in all 22 branches at once). Each link is one row with the branch guid and the item guid. The row also has used_for_sales and used_for_purchases flags and a sort_code; the screens do not set them and nothing reads them — in the whole customer base the sales flag is set in exactly one tenant and the purchase flag in none. Button order in the POS is by name, not sort code, so name the methods in the order you want them (1 Cash, 2 Card…) if order matters.

For a batch of branches, the CSV import has three columns: SETTLEMENT_CODE, SORT_CODE, BRANCH_CODE (template MasterData_Upload_BranchSettlementMethod.csv), one line per branch-method pair.

The commonest failure here is the duplicate: linking a method to a branch that already has it. Nothing on the server refuses it except the “add many methods to many branches” endpoint, and the POS builds one button per link row — two links, two identical Card buttons. If you see doubles, list the branch’s links and delete the extra rows.

Step 3: Set the branch’s default methods

POS General › Settings › Branch Settings › the branch › Default Settlement Method

The outcome: when the cashier presses Cash the till already knows which of the branch’s methods is “the” cash one, and likewise for credit card, debit card, e-wallet, voucher, bank transfer, cheque, membership points and others.

This tab has nine drop-downs, one per settlement type, each offering the methods linked in Step 2. It saves them as a JSON block on the branch record (bl_fi_mst_branch.default_settlement_method_json). Two things to know: a default that points at a method you later delete is not cleaned up — the drop-down simply shows nothing until you pick again; and the database also contains a fully built table for the same purpose, bl_fi_mst_branch_default_settlement_method_hdr, with its own API — it holds no rows in any tenant and no screen writes it. The JSON on the branch is the one that works.

Step 4 (card terminals only): Tell the till which terminal takes which card method

POS General › Devices › the device › Settlement Method › Add

If a branch’s card terminals are driven from the POS (two tenants do this today), link each card-type method to the terminal that processes it. The picker offers the branch’s linked methods from Step 2; the POS copies the terminal’s IP address and code onto the payment button so the tap goes to the right machine. Skip this if cashiers key card payments after the terminal has approved them.

Step 5: Ring up one sale of each type and finalise it

Open the POS at GS-KV-03, start a session, and check the payment buttons: one per linked method, no doubles, in name order. Ring up a small sale and settle it with each method in turn — cash, card, each wallet, DuitNow — and finalise each bill. Every one should post; if one stops with MISSING_CASHBOOK or MISSING_GL_CODE, the chain in Where the money goes is broken for that method, and it was broken before you linked it.

Changing the method after the sale

A cashier who pressed Cash for a card payment does not edit the bill. The Settlement Adjustment screen (14 of 90 tenants use it) records the old and new payment lines as a request, refuses it unless the new lines add up to the bill’s payable amount (The total settlement amount must be the same as the PNS amount) and unless something actually changed, and then a background job reverses the cashbook entries and journal of the old method and posts the new one, recording the status of each stage on the request. Because the new line is a different item, the whole chain above runs again — so an adjustment to a method with no cashbook fails the same way a sale would.

About the payment aggregator list

bl_pgw_payment_aggregator is a reference list seeded into every tenant by the platform: 313 rows naming a payment company, a channel (FPX, a bank’s online banking, an e-wallet, an over-the-counter network), a category, a country and a currency, and it has no foreign key to or from anything. It is exposed read-only at GET core2/tnt/dm/pgw/aggregators (filters: currency, country, company — not category). As of 2026-09-16 no backend code joins it, no applet calls the endpoint, and the one column that could hold an aggregator code — payment_aggregator_code on a settlement-method’s payment-channel link — is filled from a disabled free-text box in Doc Item Maintenance, not from the list. Treat it as a catalogue for a future payment-channel screen, not as something to configure. If your integration needs a gateway record, that is the payment channel and payment provider tables under the same bl_pgw_ prefix, which the settlement-method import’s PAYMENT_GATEWAY_CODE and PAYMENT_PROVIDER_CODE columns point at.

Two data quirks in the seed are worth knowing if you ever read the list: 33 rows for one e-wallet operator and the two DuitNow rows have their currency and country columns swapped, and the two DuitNow rows carry the product name as their category.

What success looks like

At GS-KV-03, start a POS session and count the payment buttons: exactly the methods you linked, no doubles, in name order. Press each of the nine default-type buttons and confirm the right method is pre-selected. Finalise one bill per method and open the Journal for each: the debit is to the subledger of the cashbook you expected. That is a balanced till before the first real customer.

Common mistakes

1. A bill will not finalise: MISSING_CASHBOOK: STL_MTHD [code] or MISSING_GL_CODE: STL_MTHD [code]. The method has no cashbook, or its cashbook has no GL code. Fix the method (or the cashbook), then finalise again; the link to the branch was never the problem.
2. A linked method does not appear on the till. Its item has no SETTLEMENT_TYPE extension row — the POS joins on that row, not on the settlement-type column — or the link row’s status is not ACTIVE, or the branch has more than 200 linked methods (the POS asks for 200 and never asks for more).
3. Two identical buttons. Two link rows for the same branch and method. Delete one; the screens do not stop you creating the second.
4. A purchase-side method shows up as a sales button. The used_for_sales / used_for_purchases flags are not read by the POS. Do not link supplier-payment methods to a retail branch at all.
5. “Where is the payment aggregator drop-down?” There is none. The list is seeded, readable and unused; the payment-channel screen the table comment describes has not been built.

Related documentation

• Point of Sale Module — where the cash bill sits and what it posts
• POS General — the till, its settings screens and the Settlement Adjustment listing
• Doc Item Maintenance — the settlement method as an item and its settlement tab
• Cashbook — the cashbook and its GL code, the two links posting needs
• Organisation Applet — branches
• Internal Receipt Voucher — the same settlement lines on a back-office receipt