Setting up the platform

Every other console page answers “what does this screen do”. This one answers “what do I configure first”, and it is the only page here written as a sequence.

It is in two halves. The first is bringing up a platform: the configuration without which nothing a merchant does can succeed. The second is onboarding one merchant, which is the repeated job.

The order is not a preference

Each step is a precondition for the next, and several of them fail in the safe-looking direction — a partner with no credentials, a plan with no fee rules and a merchant with no plan all look configured and refuse every transaction. The sequence below is the order in which those refusals stop being possible.

Part one — bringing up a platform

1. Staff, and at least two of them

Staff first, because almost everything after this is dual controlled and the approver may not be the requester. A platform with one administrator cannot complete ten of its own actions.

Do	Why
Create accounts and grant roles	A staff account with MFA enabled: no cannot sign in at all.
Make sure two people hold the super-administrator role	approval.policy.write and role.write are granted to no role by migration; in practice both maker and checker are super admins.
Each person enrols an authenticator and stores recovery codes	Signing in. Step-up verification asks for a current code at the point of deciding, and a recovery code is not accepted there.

2. Reference data

Reference data is the vocabulary everything else is expressed in, and three of its tables are prerequisites rather than lookups.

Table	What depends on it
Banks	A merchant cannot add a settlement destination for a bank that is not here: the portal’s bank list shows only active banks that can be paid out to. A bank missing here is a merchant who cannot be paid.
Mobile money networks	The same for wallet destinations, and the network id a charge must carry. The prefix inference is never authoritative — Ghana has had number portability since 2011.
FX rates, Locales, Dispute reason codes	Cross-currency pricing, portal presentation, and the dispute vocabulary.

3. Partners, per environment

Partners. The same vendor is two rows, one per environment, with separate credentials, health and routing.

1. Check the adapter exists in the running build. A partner whose adapter the deployment does not carry gets a banner, and every capability, credential and routing rule on it is decoration.
2. Declare capabilities — collections, payouts, refunds, name enquiry, balance check. The routing resolver reads these.
3. Set credentials, and record the vendor’s expiry even approximately. After an expiry, every dispatch to that partner fails; it is an outage with a known date.
4. Check float. A rail with no float fails payouts regardless of health.

4. Routing

Routing decides which partner carries which traffic, and there is no shadow mode — a rule in force routes matching payments immediately.

Two things to get right before you write the first rule:

• Priority is lower-is-first; weight is higher-is-more-often. They run in opposite directions, and that is the most common misconfiguration on the page.
• A banded rule needs something unbanded below it. A payment outside every matching band routes to nothing, which is a refusal rather than a fallback.

Then use the lookup to prove where traffic actually resolves, before and after every change.

5. Pricing

Pricing, in the order the tabs are in, because a plan holds no prices.

Step	Consequence of skipping it
Create plans, and mark exactly one default	A merchant created with no plan has every transaction refused as unpriced.
Write platform fee rules against each plan	The only thing that makes a transaction priced. A gap in direction, channel, currency or amount band refuses the transaction.
Record partner fee rules — what the vendor charges us	A cost recorded too low fails nothing and makes every margin figure optimistic. It is discovered at reconciliation, or at the invoice.
Set margin floors	A platform rule with enforce margin on and no active floor to check against refuses its payments as unpriced. Set one global floor per currency and direction before taking traffic. See Margin floors.
Set commissions if agents are paid	What an agent earns out of the spread.

Fee rules are closed, never edited — a repricing is a close plus a create, and the new rule links to the one it replaced.

6. Limits and risk

Set	Page	The trap
Platform-floor and KYC-level limits	Limits	Zero means prohibited; blank means no ceiling. They are opposites, and zero is the one that reads as a formatting bug.
Risk rules	Risk	Rules can run in shadow mode first — unlike routing, you can watch what a rule would have done before it does it.

Limit precedence is most-specific-wins: a merchant-scoped row beats a KYC-level row, which beats the platform floor. A global limit that appears not to work is usually explained by a merchant row further down the same table.

7. Approval policies

Approval policies is where “how many people must agree” is set, by environment and amount band. The thresholds the platform ships with were seeded by a migration; review them against your own risk appetite before live traffic rather than after an incident.

Changing one is itself approval-gated, so this is the step that most needs step 1 to have been done properly.

8. Workers, and the shortest fuse

Workers is not configuration, but it is a bring-up check that cannot wait for a quiet week.

Partition cover is a dated outage, not a warning

There is no default partition in this schema. A partitioned table with no partition covering a date does not degrade on that date — every insert fails. On the transactions table that is the platform refusing payments at midnight on the first of a month. The panel checks the first of next month, and a non-empty list also means the sweeper job itself is broken.

Check the outbox, stuck claims and the run table at the same time. A platform that is configured correctly and whose jobs are not running is a platform that settles nothing.

9. Money machinery

Before the first settlement run, know where these live: the Ledger and its Periods (locking and reopening are both dual controlled), Settlements and withdrawals (releasing a settlement is dual controlled), Commissions and Reconciliation.

Bring-up checklist

✓	Before any merchant can take a live payment
	Two staff who can approve each other’s requests, both with authenticators
	Banks and mobile money networks loaded
	A partner per environment, with an adapter in the build, credentials, and float
	Routing rules that resolve — proven with the lookup — with an unbanded fallback
	A default plan, platform fee rules, partner cost rules, margin floors
	Limits set with blank-versus-zero checked
	Approval policies reviewed
	Partition cover clear and workers running

Part two — onboarding one merchant

1. Create the account

Accounts → Merchants → New merchant (Merchants) is the operator-led half of onboarding, and it creates a business and its first user.

Agree the account code before you open the form: it is globally unique, permanent, printed on reconciliation files, and a clash is refused on submit. The country and settlement currency are immutable too.

Set the pricing plan on this form or immediately after. Leaving it empty means every transaction is refused as unpriced.

The primary contact becomes the account owner, and a code is emailed to them.

2. Let the merchant do their half

Most of what follows is the merchant’s own work, and the console’s job is to approve rather than to do. Point them at Setting up, end to end.

They do	You do
Invite their team, turn on 2FA	Nothing
Build against test keys and endpoints	Nothing — test is never gated by KYC
Add a settlement destination	Verify it — see below
File a KYC submission	Review it — KYC

Assisted onboarding is the norm, and it is recorded differently

Where a field agent sits with a merchant, Open a case on the KYC queue files the submission on the merchant’s behalf. A merchant’s own submission names them as the filer; one you open cannot, so the audit entry is the only record of who actually did it. Write the reason for somebody reading it cold.

3. Verify the settlement destination

Usually done for you: an automatic name enquiry verifies a destination whose account holder matches the merchant’s registered name — see Settlement destinations. This step is for the rest. On the merchant’s Settlement destinations tab, Review or Verify the row and use the name the partner’s enquiry returned, exactly, including spacing and initials.

Do not retype the merchant’s claimed name

The whole value of a name enquiry is that it is independent of what the merchant told us. Retyping their version turns the control into a formality, and the money goes to whatever account the number actually belongs to.

4. Review KYC

The dossier renders the gate first — whether this submission can be decided at all against the level applied for — with the approve action disabled behind it. Approving a submission and granting a level are two different acts; read KYC before your first decision.

5. Request go-live

Request go-live on the merchant page raises an approval request that a second member of staff decides. Before raising it, check all four:

1. KYC level adequate and current — not lapsed;
2. a pricing plan set;
3. a settlement destination that exists and is verified;
4. fee settings, if they differ from the plan — themselves dual controlled.

A merchant enabled for live with no verified destination cannot be paid, and collections are refused anyway.

6. Hand over, and watch the first day

Watch Transactions and the partner’s Performance tab through their first live payments. A new merchant’s first failures are normally routing, pricing or a destination — in that order of likelihood.

The philosophy underlying a record

Six rules explain nearly every apparent limitation in this console. They are worth learning once, because they are why the screens are shaped the way they are.

A record that governed something is never edited in place. Fee rules are closed and replaced; routing rules are retired, not deleted; approval policies are superseded by a replacement band. A pending request snapshots the terms that governed it, so a row whose terms moved underneath it would make the register lie about what was agreed.

History is a separate question from what applies now, and often a separate table. “What is in force” and “what applied, and when it stopped” are different questions, and a reader who mistook the second for the first would act on a superseded threshold.

Nothing is deleted, because something downstream names it. Transactions carry the id of the routing rule that moved them and the policy that approved them. “Which rule sent this payment there” is the first question asked when a payment goes somewhere surprising, and it has to stay answerable.

A reason is a field of the record, and there is often more than one. A rejection can carry a reason the merchant sees, a reason for the audit log, and internal reviewer notes — three audiences, three fields, never interchangeable.

Every privileged act names a person, not a service. That is what makes the console trustable with the powers it has, and it is also what protects you when somebody asks six months later why a limit was raised.

Blank, zero and absent are distinguished deliberately. A blank partner field means “leave alone” rather than “clear”; a zero limit means prohibited while a blank one means unlimited; a list field replaces rather than appends. Where the distinction can cost money, the form says which is which — read it rather than inferring from the shape of the input.