Connecting a mobile financial service to a business system looks like a developer task and behaves like an operations project. The API call is the small part. The difficult parts are the reference that ties a payment to one order, the state model that survives timeouts, the settlement report that proves the money arrived, and the person who owns the exception queue on a Friday evening.
This guide is a delivery sequence for a Bangladeshi business connecting bKash, Nagad, Rocket or another provider to its order register, ERP or custom application. It assumes a commercial account is already open or under approval. It does not assume a particular vendor API, because provider details change and the provider's own documentation is authoritative.
Decide what the integration must achieve
Before choosing an endpoint, write four outcomes in plain language and have finance and operations sign them.
- Collection: a customer can pay a specific amount against a specific order, and the system records which attempt succeeded.
- Status: staff can see pending, paid, failed, expired and refunded states without opening the provider's merchant portal.
- Reversal: a refund or failed delivery can be traced back to the original payment and approved by the right person.
- Proof: at the end of each day, the order ledger, the provider statement and the settlement account can be matched and exceptions listed.
An integration that only does the first item is a checkout button, not a payment operation. Most support complaints come from the other three.
What must be true before phase one
- An approved merchant or agent account, with the commercial owner named and their contact details recorded.
- Sandbox or test credentials, the current API documentation, and the provider's rules on callback retries and settlement reporting.
- A written rule for order references, including what happens when a customer retries payment for the same order.
- A finance owner who will reconcile, and a technical owner who will maintain the integration after launch.
- Test identities and a small-value test plan approved by the account holder.
- A data review covering what customer information is sent to the provider, where it is stored, and who can read it.
The eight delivery phases
- Map the money path. Draw one line from order creation to the provider, then to the settlement account and the accounting ledger. Mark every manual step. Inputs: current order sources, merchant account details, chart of accounts. Output: a one-page swimlane. Role: operations lead with finance. Acceptance: finance agrees where the word "paid" is recorded and what evidence supports it.
- Choose the integration surface. Compare a hosted payment page, a direct server-to-server API and an aggregator that already connects several providers. Weigh refund support, settlement reporting, approval effort and who carries support when a call fails. Inputs: provider options, expected volumes and refund requirements. Output: a short decision note with the rejected options. Role: technical lead and finance. Acceptance: the person who owns the merchant relationship approves the route.
- Fix the payment reference. Give every payment attempt its own merchant reference and idempotency key. Never reuse an order number across a retry, because two attempts for one order must remain distinguishable in the provider statement. Inputs: order schema and provider reference rules. Role: technical lead with support. Output: a reference specification. Acceptance: support can move from an order to a payment and back without guessing.
- Design the state model. Separate payment from settlement. A payment can be initiated, pending, paid, failed, expired or reversed; settlement is a later event with its own reference. Draw the allowed transitions and forbid shortcuts. Inputs: payment and settlement events. Role: technical lead with finance. Output: a state diagram with an owner for every transition. Acceptance: no path marks an order paid before provider confirmation.
- Build the callback and the fallback poll. Verify the callback signature, reject replays, and make the handler idempotent so a duplicate message produces one ledger entry. Add a scheduled status poll for callbacks that never arrive. Inputs: callback specification and retry rules. Role: integration developer. Output: endpoint specification, retry policy and failure alert. Acceptance: a duplicated and an out-of-order callback both leave the ledger consistent.
- Implement refunds and partial adjustments. Require a reason code, an approver and a link to the original payment. Decide how delivery charges and partial returns are treated before the first refund is requested. Inputs: refund policy and approval limits. Role: finance manager. Output: a refund procedure and approval limits. Acceptance: a refund cannot exceed the captured amount, and every refund has a provider reference.
- Test a scripted matrix. Cover success, customer cancellation, timeout, wrong PIN, insufficient balance, duplicate callback, delayed callback, refund after settlement and a manual status check. Record the expected end state and ledger effect for each. Inputs: test identities and case matrix. Role: QA with finance. Output: a signed test log. Acceptance: every case reaches a named state, with no orphaned record.
- Pilot, then close daily. Run a limited-value pilot for two weeks. Each working day, match provider statement, system ledger and settlement account; assign every unmatched item to a person. Inputs: pilot cohort and close checklist. Role: operations manager. Output: a pilot report with open issues and fixes. Acceptance: five consecutive clean closes at the threshold finance agreed before the pilot began.
Evidence to keep after launch
- The reference specification and state diagram, versioned with the integration code.
- Callback signature and replay test results, including the date and tester.
- Refund approval limits and a sample audit trail.
- Daily reconciliation report with the name of the person who closed it.
- Provider contact escalation path and the date it was last tested.
- A runbook for disabling the payment option without taking the store offline.
Mistakes that cost a quarter
- Treating the provider's "success" page as proof of payment instead of verifying the transaction status.
- Using the order number as the only payment reference, then losing the ability to separate two attempts.
- Building only the callback and discovering weeks later that some callbacks are never delivered.
- Letting the support team reconcile from screenshots rather than an exported statement.
- Launching without a switch that can stop new MFS payments while card or cash-on-delivery keeps working.
Metrics for the operations dashboard
- Payments stuck in pending for longer than the provider's stated window.
- Unmatched settlement lines at each daily close, and their age.
- Refunds awaiting approval, measured in hours.
- Callback failures and fallback polls that had to correct a status.
- Share of orders where the customer had to contact support about payment.
Where our commerce team fits
We design MFS and gateway connections as part of the order, payment and reconciliation work under Commerce Systems. Fees for integration, reconciliation setup and support are set out on the pricing page. For the longer view of how these integrations change as a business grows, read the year-by-year guide to MFS integration.
Sources
- Bangladesh Bank, Mobile Financial Services statistics, accessed 17 November 2026.
- bKash Developer Portal, accessed 17 November 2026.
- PCI Security Standards Council, accessed 17 November 2026.
- RFC 9457, Problem Details for HTTP APIs, accessed 17 November 2026.
Responses (0)
No comments yet. Add the first one below.
Leave a response
Your email address will not be published. Required fields are marked *.