Payment methods, providers, and bank accounts

A payment method describes how money is received. A bank account describes where external funds are held. A payment provider connects Makronexus to an external payment channel. Bank settings connect those records to school collection and reconciliation policy.

Audience: implementers, bursars, treasury/accounting users, integration owners, security reviewers, and support analysts
Learning time: 45 minutes
Navigation: Finance → Payments & Banking → Providers & Payment Methods → Bank Settings (finance/bank-settings)
Boundary: provider availability, certification, settlement timing, fees, retries, and country support are external/configuration-dependent.

Learning outcomes

You will be able to:

• distinguish payment method, bank account, provider, payment attempt, settlement, and reconciliation;
• configure school bank accounts with currency and optional GL linkage;
• register providers without exposing credentials;
• configure default accounts/providers and collection/reconciliation settings;
• identify exact bank-setting permissions;
• verify provider and settlement readiness without making a live charge;
• preserve secret and audit boundaries.

Object model

Object	Meaning
Payment method	user/business classification of how funds are received
Bank account	school-owned external account, currency, identity, active/default status
Payment provider	encrypted integration configuration for a gateway or channel
Bank settings	school singleton for default account/provider, collection/payout, and reconciliation preferences
Payment attempt	external initiation/callback/retry evidence
Payment	Makronexus incoming-funds record
Settlement	external transfer of provider value to bank
Reconciliation	evidence that external activity matches Makronexus activity

Bank-account fields

Field	Meaning	Control
Bank and branch name	external institution identity	verify official source
Account name/number	legal/operational account identity	account number unique per school
Currency	three-letter code, uppercased	must match approved design
SWIFT/BIC	optional international identifier	verify with bank
GL account ID	optional link to Chart of Accounts	use active posting account
Default flag	preferred account	only one default per school
Active flag	eligible for collections	inactive accounts are excluded
Metadata	approved contextual values	do not store secrets casually

Account numbers are sensitive operational data. Display masking where the product provides it and limit access.

Provider configuration and secret handling

Supported provider-type values include Stripe, Paynow, EcoCash, InnBucks, bank transfer, mobile money, cash, and custom. This enumeration does not guarantee that every type is implemented or certified for every deployment.

Credentials are encrypted at rest using AES-256-GCM. API consumers receive redacted summaries, never plaintext credentials. Provider mutation audit entries omit request bodies to prevent credential leakage.

Never copy provider secrets into documentation or tickets

Use approved secret-management and support procedures. Logs, screenshots, audit comments, and examples must use redacted values.

School bank settings

A school settings record can select:

• default bank account;
• default provider;
• reconciliation auto-match;
• tolerance amount and currency;
• payout enabled;
• collection enabled;
• metadata.

Auto-match tolerance is a control decision, not a convenience setting. Document who approved the threshold and which variance causes are acceptable.

Prerequisites

Requirement	Why it matters
Correct school selected	all resources are school-scoped
Approved bank evidence	prevents fraudulent or incorrect account setup
Currency design	account and tolerance currencies must be intentional
GL account structure	optional bank-account link should resolve correctly
Provider contract/certification	external channel must be approved
Settlement design	default destination must be known
Reconciliation policy	auto-match and tolerance need control ownership
Secret owner and rotation policy	credentials are high risk
Test/sandbox credentials	never test with production secrets unnecessarily

Roles and exact permissions

Action	Ability
Create bank account or provider	school_bank_setting:create
Read account/provider/settings	school_bank_setting:read
List accounts/providers	school_bank_setting:list
Update account/provider/settings	school_bank_setting:update
Soft-delete account/provider	school_bank_setting:delete
View statistics	school_bank_setting:statistics
View payments/attempts	relevant financial_payment:* abilities
Configure posting mappings	relevant finance_control:* abilities

The same create/update ability covers bank accounts and provider records. Operational ownership and secret access should still be separated through process controls.

Guided procedure: bank account

1. Select the school.
2. Open Bank Settings.
3. Choose Add bank account.
4. enter bank, branch, account name, account number, and currency;
5. add SWIFT/BIC when required;
6. select an eligible GL account where the design uses direct linkage;
7. decide active/default status;
8. save with authorised access;
9. verify masked display and audit evidence.

Control: if making an account default, confirm the previous default is intentionally replaced.

Guided procedure: provider

1. Confirm provider contract and sandbox environment.
2. choose the verified provider type;
3. enter display name and approved configuration;
4. supply credentials through the protected form only;
5. choose active/default status;
6. save;
7. verify the response is redacted;
8. perform the provider’s supported connectivity/test action where available;
9. record external certification separately.

Guided procedure: settlement and reconciliation defaults

1. select the default active bank account;
2. select the default active provider if used;
3. decide whether collections are enabled;
4. decide whether payouts are enabled;
5. configure auto-match only with approved policy;
6. set tolerance amount and currency;
7. save and review audit event;
8. open Controls Readiness and confirm bank/provider requirements.

Readiness verification

For reconciliation readiness:

• at least one active bank account;
• bank settings complete;
• open accounting period.

For gateway readiness:

• active provider;
• default settlement bank account;
• posting mappings.

For collection readiness, a cash book, receipt template, open period, and mappings are also required.

Worked scenario: Mupfure Learning Academy

The Harare school configures:

• CBZ USD collection account linked to school GL account 1110-HRE;
• a second local-currency bank account;
• Paynow sandbox provider;
• USD account as default settlement account;
• collections enabled;
• payouts disabled during initial rollout;
• auto-match disabled until reconciliation testing is complete.

The implementation team verifies that provider responses are redacted, no secret appears in audit logs, and gateway readiness passes only after posting mappings are active.

Failure modes

Symptom	Likely cause	Evidence to inspect	Safe action	Escalate when
Duplicate bank account error	account number already exists in school	active/soft-deleted account list	reuse or correct existing record	legitimate migration duplicate needs resolution
Account absent from collections	inactive flag or wrong school	account status/scope	activate correct account	active correct account remains absent
Provider saved but readiness fails	inactive provider, no default settlement account, or mappings missing	provider/settings/readiness	complete dependencies	all evidence is correct but gate fails
Credentials appear in response/log	security defect	response, audit, logging	stop use and rotate secret	any plaintext exposure occurs
Auto-match creates risky matches	tolerance too high or wrong currency	settings and matched lines	disable/reduce and review	historical incorrect matches require remediation
Default account changes unexpectedly	another account saved as default	audit history	confirm authorised change	unexplained actor/change
Provider type exists but integration fails	unsupported/certification/external outage	provider guide, external status	use verified fallback	contract says supported and sandbox still fails

Verification checklist

• Bank identity came from an approved source.
• Account number is unique and correctly masked.
• Currency and optional GL link are correct.
• Active/default flags are intentional.
• Provider contract and environment are confirmed.
• Credentials are encrypted/redacted and absent from audit payloads.
• Settlement account is active.
• Collection/payout settings match rollout scope.
• Reconciliation tolerance is approved.
• Posting mappings simulate correctly.
• Gateway and reconciliation readiness pass.
• Fallback method and escalation owner are documented.

Practice and knowledge check

Guided practice: configure one sandbox bank account and one provider in a test school, then inspect the redacted response.

Independent scenario: provider callbacks work, but gateway readiness is blocked. List the non-provider dependencies to inspect.

1. Why is a payment method not the same as a provider?
2. Why can a provider enum not prove availability?
3. What happens when an account becomes default?
4. Why are provider request bodies excluded from audit capture?
5. What is reconciliation tolerance?
6. Which dependencies gate online payments?
7. What should happen after suspected credential exposure?

Answer guide: methods classify collection while providers integrate externally; certification varies; previous default is unset; secrets must not leak; tolerance defines acceptable variance for matching; provider, settlement account, mappings, period/control dependencies matter; stop, rotate, investigate, and escalate.

Next lesson

Continue to Numbering, templates, and communications.