Settlement and provider reconciliation

Provider reconciliation compares Makronexus payment-channel evidence with the provider’s external transaction evidence. Settlement reconciliation continues that comparison to the amount that actually reaches the school’s bank account, including provider fees, timing differences, reversals, refunds and chargebacks.

Makronexus verifies Payment Attempts, Payments, webhook events, reconciliation batches/items and bank statement transactions. The current repository does not verify one universal standalone merchant-settlement or payout object. Therefore, this chapter teaches a controlled evidence model using a payment_gateway reconciliation batch, provider exports/webhook evidence and the eventual bank statement credit. Provider-specific settlement formats and timing remain external-policy and configuration dependent.

Audience: bursars, treasury officers, payment operations staff, accountants, controllers, auditors, implementers and support analysts
Learning time: 60 minutes
Navigation: Finance → Payment attempts / provider workspace → Reconciliation → Bank statements
Control objective: prove the complete chain from customer authorisation to saved Payment to provider evidence to bank payout, without duplicating or hiding fees and reversals.

Learning outcomes

You will be able to:

• distinguish a Payment Attempt, Payment, webhook event, provider transaction and bank payout;
• explain why succeeded does not prove bank settlement;
• build a provider reconciliation batch from controlled external evidence;
• reconcile gross collections, provider fees, refunds, chargebacks and net payout;
• use exact provider, attempt, webhook and reconciliation permissions;
• identify timing differences without prematurely closing them;
• trace settlement differences to Payments, bank statement lines and journals;
• design a repeatable provider evidence pack;
• escalate missing or contradictory provider evidence safely.

Exact definition and boundaries

Evidence	What it proves	What it does not prove
Payment Attempt	initiation and provider-channel lifecycle	that a Payment exists or funds settled
Attempt status succeeded	provider workflow reported success and should link to a Payment	that the provider paid the school’s bank
Payment	Makronexus recorded incoming funds	that bank settlement occurred
Allocation	Payment value was applied to invoices	that provider payout is complete
Receipt	Makronexus issued proof for the Payment	bank or provider settlement
Webhook event	Makronexus received and processed a provider message	that the message is economically correct or final
Provider transaction/report	provider’s external activity evidence	that Makronexus matched it correctly
Reconciliation item	one controlled comparison amount	final bank match unless linked
Bank statement credit	bank reported a deposit	exact underlying provider transactions
Journal	internal accounting classification	external settlement
Chargeback/refund record	correction/return workflow	that provider and bank effects are fully reflected

A provider callback can arrive before or after polling, be duplicated, be delayed, or describe a reversal. The operational truth is the reconciled chain of identifiers and amounts, not a single notification.

Evidence chain

Provider-to-bank conservation

A common settlement relationship is:

gross successful provider collections
- provider fees
- refunds
- chargebacks
- reversals or reserves
+ released reserves or adjustments
= expected net payout

Then:

expected net payout
+/- timing and bank adjustments
= observed bank statement credit

These formulas are teaching controls, not a claim that every provider uses the same report structure. Some providers settle per transaction, per day, per merchant account, per currency or across multiple schools. Always follow the approved provider contract.

Attempt and webhook status boundaries

The verified Payment Attempt flow includes states such as processing, succeeded, failed and expired. Webhook processing statuses are:

• received;
• processing;
• completed;
• failed;
• duplicate;
• ignored.

Webhook event types include:

• transaction.received;
• transaction.reversed;
• transaction.failed;
• notification.

Each transition is independent. A system can have an attempt that succeeded but no saved Payment, a Payment with no provider match, a provider match waiting for payout, or a payout with an unexplained difference.

Prerequisites

Requirement	Why it matters
Approved provider configuration	identifies merchant/school ownership and channel
Correct school bank settings	defines where settlement should arrive
Provider credentials and webhook configuration controlled	prevents unauthorised or unverifiable events
Attempt and Payment access	permits tracing internal identifiers
Provider export/report access	supplies external transaction and fee evidence
Bank statement import	supplies final payout evidence
Currency and settlement-calendar design	separates currency and timing differences
Reconciliation permissions	controls match, resolution, review and close
Posting mappings for fees/refunds/chargebacks	prevents unexplained GL differences
Independent reviewer	settlement preparer should not be sole closer

Roles and exact permissions

Action	Exact ability	Control
Create a Payment Attempt	payment_attempt:create	use idempotency and correct school
List attempts	payment_attempt:list	search before retry
Read one attempt	payment_attempt:read	inspect provider IDs and linked Payment
Cancel an attempt	payment_attempt:cancel	cancellation is not refund
Confirm an attempt administratively	payment_attempt:confirm	exceptional maker-checker control
List provider/webhook evidence	bank_webhook:list	current provider and event scope
Read provider or event detail	bank_webhook:read	inspect normalized and raw evidence securely
Create provider configuration	bank_webhook:create	separate from day-to-day reconciliation
Update provider configuration	bank_webhook:update	reason, test and approval required
Delete provider configuration	bank_webhook:delete	prefer disable/retention where policy requires
View provider statistics	bank_webhook:statistics	KPI is not transaction proof
List school bank/provider settings	school_bank_setting:list	prove merchant and destination setup
Read bank/provider settings	school_bank_setting:read	verify account and currency
Update bank/provider settings	school_bank_setting:update	controlled configuration change
Create provider reconciliation batch	reconciliation_batch:create	use batch type payment_gateway
Auto-match provider items	reconciliation:auto_match	approved thresholds
Manually match provider items	reconciliation:manual_match	inspect complete evidence
Resolve settlement discrepancies	reconciliation:resolve_discrepancy	substantive notes required
Review batch	reconciliation_batch:review	independent reviewer
Close batch	reconciliation_batch:close	only after review

The Bank Webhooks API has exact bank_webhook:* permissions. The current frontend workspace also contains legacy/generic financial_payment:* gates. Treat that mismatch as an implementation constraint: successful page access does not prove the exact webhook API operation is authorised.

Provider reconciliation design

Create one reconciliation scope that is understandable and repeatable. Examples:

• provider, merchant account, currency and settlement date;
• provider, batch reference and payout ID;
• provider transaction date range and one bank payout;
• one gateway report file and one payment_gateway batch.

Do not combine different currencies or merchant accounts merely to reduce batch count.

End-to-end workflow

Guided procedure

1. Freeze the provider population

Obtain the provider report or controlled export for one defined settlement scope. Record provider, merchant account, school, currency, period, report ID, generation time and checksum.

Expected result: the external population cannot silently change during reconciliation.

2. Identify Makronexus attempts

List attempts for the same provider, date range, currency and school. Capture attempt ID, provider reference, status, amount, Payment ID and failure/expiry evidence.

Expected result: every provider transaction has a possible internal lineage or an exception.

3. Prove the Payment link

For each provider-success transaction, verify that the attempt is succeeded and links to one saved Payment. Compare amount, currency, student/payer, invoice/allocation context and provider reference.

Expected result: provider success and Makronexus Payment are one-to-one or an approved split/aggregate model is documented.
Control: do not create a second Payment because a callback was retried.

4. Create a provider reconciliation batch

Create a payment_gateway batch using the provider report identity and currency. Add or generate one item per approved comparison unit.

Expected result: batch total and item count equal the frozen provider population.

5. Match provider transactions

Use exact reference, amount, currency and Payment ID where possible. Fuzzy matches require additional party/date evidence.

Expected result: each match is reproducible.

6. Classify non-collection lines

Classify:

• provider fee;
• refund;
• chargeback;
• reversal;
• reserve/hold;
• reserve release;
• transfer adjustment;
• tax/withholding where externally applicable;
• unknown provider adjustment.

Expected result: every line contributes to gross-to-net arithmetic or remains an owned exception.

7. Calculate expected payout

Reproduce the provider’s gross-to-net settlement and compare to any payout identifier/report total.

Expected result: expected net payout is supported by transaction-level detail.

8. Match the bank credit

Import the bank statement and match the expected payout to the correct bank transaction. Compare value date, amount, currency, bank reference and merchant/payout reference.

Expected result: provider settlement and bank movement are linked.
Control: a bank credit with the same amount is not sufficient when multiple payouts exist.

9. Verify accounting

Check that:

• Payments and refunds/chargebacks have correct source journals;
• provider fees or bank charges have governed postings;
• settlement clearing accounts, if configured, clear as designed;
• no gross collection is posted twice;
• cross-currency differences are controlled;
• unresolved timing items remain open.

10. Review and close

An independent reviewer confirms report provenance, population completeness, match evidence, gross-to-net arithmetic, bank match, journals and exceptions before batch review and close.

Settlement field reference

Field	Meaning	Evidence source
Provider transaction ID	provider’s transaction identity	API/report/webhook
Attempt ID	Makronexus pre-Payment workflow	Payment Attempt
Payment ID	saved incoming-funds record	Payment
Provider status	provider transaction state	provider evidence
Gross amount	customer-facing collected amount	provider and Payment
Fee	provider deduction	settlement report
Refund/chargeback	value returned or forcibly reversed	provider report and Makronexus correction
Net payout	amount provider expects to transfer	settlement report
Payout/batch reference	provider settlement identity	provider report
Bank transaction ID/reference	bank’s external movement	statement line
Settlement/value date	external clearing timing	provider/bank
Currency	transaction/payout currency	all evidence layers
Journal IDs	internal accounting effects	General Ledger

Accounting patterns

The exact accounts are configuration-derived. Typical conceptual patterns include:

Event	Conceptual debit	Conceptual credit	Control
Gross provider collection	provider clearing/cash receivable	student receivable or income route	source Payment journal must be unique
Provider fee	fee expense	provider clearing	provider evidence and mapping required
Net payout	bank	provider clearing	bank line and payout reference required
Refund	refund/receivable reversal route	bank/provider clearing	trace original Payment
Chargeback	chargeback/receivable route	bank/provider clearing	preserve dispute evidence
Timing difference	no forced journal solely to make reconciliation balance	no forced journal	retain open reconciling item

These are illustrative. Use the school’s effective posting policy and backend resolver.

Worked scenario: Mupfure Learning Academy

Mupfure’s mobile-money provider report shows 480 successful customer transactions totalling USD 26,400. It also shows USD 396 in provider fees, two refunds totalling USD 180 and one chargeback of USD 75. The expected payout is USD 25,749.

The provider report contains 480 provider transaction IDs. Makronexus has 479 succeeded attempts with linked Payments and one succeeded attempt without a Payment ID. The missing-Payment case becomes a blocking exception; staff do not manually create a Payment until they determine whether provider confirmation processing failed or the report contains a duplicate.

The bank statement contains a USD 25,749 credit two days later with the provider payout reference. The batch links the payout and bank line. Fee, refund and chargeback journals are verified. The batch remains in processing until the missing-Payment exception is corrected and the provider population again reconciles to Makronexus.

Failure modes

Symptom	Likely cause	Evidence to inspect	Safe action	Escalate when
Provider success has no Payment	callback/polling failure or duplicate report row	attempt, webhook, provider ID and Payment search	investigate idempotently; do not create blindly	funds exist but no safe recovery path
Two Payments share one provider ID	duplicate confirmation or manual capture	attempt/payment audit and idempotency keys	quarantine and determine authoritative record	allocations/receipts/journals exist on both
Gross total differs	missing provider row, failed attempt included or currency issue	report population and attempt filters	reconcile row by row	provider cannot supply complete evidence
Net payout differs by fee amount	fees omitted from model	settlement fee lines and postings	record/match governed fee evidence	fee basis is unexplained
Bank credit is delayed	settlement calendar/timing	provider payout status and bank value date	retain timing exception	provider says paid but bank cannot trace
Bank credit is aggregated	provider combines multiple batches	payout references and batch scope	create controlled aggregate bridge	composition cannot be proven
Webhook marked completed but provider report excludes it	event was non-final, reversed or wrong merchant	raw/normalized webhook and provider report	follow provider authority and investigate	Makronexus Payment exists without economic support
Chargeback appears after batch close	later external correction	original batch, Payment and provider case	create linked correction batch	no append-only correction path
Currency differs	provider converted settlement or wrong merchant setup	provider report, bank account, FX evidence	use approved cross-currency process	rate/fees cannot be reproduced

Verification checklist

• Provider, merchant account, school and currency scope are fixed.
• Provider report checksum and generation time are retained.
• Provider rows reconcile to attempt population.
• Every succeeded attempt has exactly one appropriate Payment or an exception.
• Payment amount, currency and provider reference are verified.
• Fees, refunds, reversals, chargebacks and reserves are separately classified.
• Gross-to-net arithmetic is reproduced.
• Expected payout is tied to a provider payout reference.
• Bank statement credit is linked using amount, date and reference evidence.
• Payment, fee, refund and chargeback journals are verified.
• Timing differences remain open until evidence arrives.
• No duplicate Payment or journal was created during recovery.
• Independent review and close evidence are recorded.

Practice and knowledge check

Guided practice: reconcile a provider report with twenty successful transactions, one fee line, one refund and one delayed payout. Produce gross-to-net and bank-match evidence.

Independent scenario: a webhook is completed, an attempt is succeeded, and a Receipt exists, but no payout appears after the provider’s normal settlement window. List what is proven, what is not proven and the next controls.

1. Why is a succeeded attempt not settlement?
2. What evidence links a provider transaction to a Payment?
3. Why does this chapter not claim one universal settlement object?
4. Which batch type represents provider reconciliation?
5. What explains gross-to-net differences?
6. Why should timing differences remain open?
7. Which exact permissions govern webhook evidence?
8. What is the danger of creating a manual Payment during callback uncertainty?
9. What must be verified before settlement batch close?

Answer guide: success precedes external payout; identifiers, amount, currency, party/date and Payment linkage prove the relationship; the repository has no universal settlement record and providers vary; use payment_gateway; fees/refunds/chargebacks/reserves/adjustments explain differences; open timing items preserve truth; use bank_webhook:list/read and related exact permissions; manual creation can duplicate economic effects; population, gross-to-net, bank line, journals, exceptions and independent review must be complete.

Next lesson

Continue to Reconciliation exceptions.