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 seeded table called payment aggregators, 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 settlement line on the cash bill carrying the settlement method and amount signum −1 (money coming in against the sale). After FINAL, the posting job turns that line into a journal entry by walking a chain:

1. the line’s item — the settlement method;
2. the item’s cashbook (set when the method is created or imported);
3. the cashbook’s GL code;
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 (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 Settlement tab, not from the type shown on the item header — a method whose Settlement tab has no type 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 › 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.

Link from the method’s side: pick the method and add the branches that accept it (which also suits a new e-wallet going live in all 22 branches at once). Do not use the other door. Branch Settings › the branch › Settlement › Add looks like the same link made from the branch’s side, lets you tick methods and closes — and saves nothing. No error appears; the till simply shows no new button. The link also has used for sales and used for purchases flags and a sort code; the screens do not set them, and the only thing that looks at the two flags is the listing filter — no till, journal or document behaviour keys off either. 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, 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 on the branch record. Two of the nine never take effect: the Voucher default is saved and never read, and the E-Wallet default is looked up under a type name no e-wallet method carries, so neither pre-selects anything. Set them if you like; do not expect the till to show them. One thing 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.

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 rather than keyed in after the terminal has approved the payment, 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 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 replaces the old posting with a 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.

It replaces; it does not reverse. This is the part worth knowing before you reach for it, because reverse and replace leave very different evidence behind:

That last row is the one to plan around. Changing the settlement amount on a finalised document through the ordinary edit path is refused while its cash book line is matched in a reconciliation, with a message naming the reconciliation and its month. The Settlement Adjustment path performs the same amount change and never asks that question: the old cash book line is deleted, the amount it had matched is handed back to the bank statement line, the reconciliation link is marked deleted, and a new cash book line appears unmatched. The month you signed off moves, and the only sign is that the reconciliation no longer balances.

So unreconcile first. If the bill is inside a period you have already reconciled, undo the match on that cash book line in the Bank Reconciliation session before you adjust the settlement, then match the new line afterwards. See Everything is matched to zero and the reconciliation still won’t tally for what the symptom looks like from the other end.

About the payment aggregator list

The payment aggregator list is 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 nothing links to it. It is exposed read-only through the API (filters: currency, country, company — not category). Nothing in the product reads it, no applet calls it, and the one place that could hold an 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 records, which the settlement-method import’s PAYMENT_GATEWAY_CODE and PAYMENT_PROVIDER_CODE columns point at.

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 default-type button and confirm the right method is pre-selected — for seven of the nine; Voucher and E-Wallet never pre-select, and that is not your set-up (Step 3). 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. The bill finalised, but it has no journal and no cashbook line; Trace Document’s Resolve reports MISSING_CASHBOOK: STL_MTHD [code] or MISSING_GL_CODE: STL_MTHD [code]. The method has no cashbook, or its cashbook has no GL code. FINAL never checks this — the posting job does, after the customer has gone. Fix the method (or the cashbook), then press Resolve on each affected bill in Financial Report › Error Checking › Trace Document; 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