Putting payments inside your product looks like a two-week integration. A provider, an SDK, a checkout component, done. That estimate holds right up until the first refund, the first chargeback, the first payout to a third party, and the first month-end where finance asks why the platform’s numbers do not match the provider’s settlement file.
The payment itself is the straightforward part. What takes the time is everything that happens around it: the money model, the reconciliation, the failure handling and the regulatory position on whose money you are holding and when.
Key Takeaways
- Decide the money flow model first. Whether funds touch your accounts determines your regulatory position and most of your architecture.
- Build your own ledger. The provider’s balance is their view of your position, not your record of your customers’ positions.
- Idempotency and reconciliation are not optional extras. They are the difference between a payment integration and a payment system.
- Design the failure paths explicitly. Timeouts, partial captures, refunds and chargebacks are where most production incidents come from.
- In the UAE, payment service activity is licensed under the Central Bank’s Retail Payment Services and Card Schemes Regulation, so settle the position before you build.
Choose the money flow model first
There are three broad shapes, and they carry very different obligations.
In a pass-through model, funds move directly from the payer to the end merchant and never touch accounts you control. You facilitate, you may take a fee, but you are not holding anyone’s money. This is the lightest position and the one most platforms should start from.
In a collect-and-remit model, funds land in an account you control and you pay out to sellers or providers afterwards. This gives control over timing, netting and holdbacks, and it means you are holding funds belonging to others, which changes your regulatory obligations substantially.
In a wallet or stored value model, customers hold a balance with you and spend from it. This is the heaviest position, with obligations around safeguarding, redemption and reporting.
Safeguarding: holding customer funds separately from the business’s own money, typically in a designated account, so that customer balances are protected and identifiable if the business fails.
Pick deliberately. Teams routinely drift from pass-through into collect-and-remit because a product requirement made it convenient, without anyone recognising that the regulatory position changed with it.
Build your own ledger
The most common architectural mistake in embedded payments is treating the provider as the source of truth. Their dashboard shows a balance, so the balance must be right, so why duplicate it.
Because their balance answers a different question. It tells you how much money the provider holds for you. It does not tell you how that decomposes across your customers, what is settled versus pending, what is held back against disputes, or what you owe out tomorrow. And when a customer disputes a figure, you need your own record, not a screenshot of someone else’s.
A double-entry ledger with immutable, append-only entries, where every movement has a corresponding entry and balances are derived rather than stored, is the standard answer and it is not difficult to build. Reconcile it daily against the provider’s settlement file, alert on any break, and never adjust a balance by editing it. Corrections are new entries. Finance and audit both need that property, and so do you when reconstructing what happened during an incident.
Idempotency, or duplicate payments
Networks fail mid-request. A client sends a payment, the connection drops, and the client does not know whether it succeeded. If it retries and the system treats that as a new payment, the customer is charged twice.
Every payment operation needs an idempotency key generated by the caller, stored with the result, and used to return the original outcome on any retry rather than performing the action again. Providers generally support this on their side; your own layer needs it too, because the same failure can occur between your client and your API.
The related discipline is that payment state must be driven by the provider’s webhooks and reconciliation, not by the response to your original request. A response that never arrived does not mean the payment failed. Systems that assume it does are the ones that produce customers who were charged for an order the platform believes was never placed.
Design the failure paths
Most payment incidents come from the paths nobody drew. Work through them explicitly.
Authorization succeeded but capture failed, so the customer has a hold and no order. Partial capture, where the order shipped incomplete. Refunds after settlement has already been paid out to a seller, so the money must come back from somewhere. Chargebacks arriving weeks later, with evidence deadlines and a decision about who bears the loss. Payouts failing because a seller’s bank details are wrong, which needs a defined retry and notification path rather than a silent failure. Currency conversion, where the rate at authorization differs from the rate at settlement and someone absorbs the difference.
Each of these needs an owner, a defined behaviour and a customer communication. Discovering them in production means deciding under pressure, usually inconsistently, and then reconciling the inconsistency afterwards.
The UAE picture
Payment service activity on the UAE mainland falls under the Central Bank of the UAE, with the Retail Payment Services and Card Schemes Regulation governing payment service provider licensing and card scheme requirements. The DIFC and ADGM operate separately under their own regulators, so the applicable regime depends on where you are established and who you serve.
Two pieces of national infrastructure matter for design. Al Etihad Payments, established as a Central Bank subsidiary in 2023, operates Aani, the domestic instant payments platform launched in October 2023, and Jaywan, the domestic card scheme launched in 2024. Instant rails change what is possible on payout timing and refund experience, and a domestic scheme changes the cost picture on card acceptance. Both are worth designing for rather than retrofitting.
Where the model involves stablecoins or payment tokens, the Central Bank’s Payment Token Services Regulation applies, in force since 6 July 2024, under which dirham payment tokens require a full licence and foreign payment tokens require registration. The choice between a partner licence and your own is covered in Banking as a Service or your own licence.
Frequently asked questions
How long does an embedded payments build take?
A pass-through integration with a single provider and a defined checkout is usually eight to twelve weeks including reconciliation and failure handling. Collect-and-remit with payouts to third parties is typically four to six months, because the ledger, payout scheduling and dispute handling are all additional systems rather than additional endpoints.
Do we need a payment licence?
It depends on your money flow model and jurisdiction, and it is a question for regulatory counsel. As a rule of thumb, pure pass-through where funds never touch accounts you control is the lightest position, and anything where you hold funds belonging to others requires a considered answer before you build.
Should we use one provider or several?
Start with one. Multi-provider routing adds meaningful complexity in reconciliation, refunds and reporting, and the benefits, meaning redundancy and rate optimisation, only justify it at volume. If you expect to add providers later, keep provider-specific logic behind your own interface so the second one is an addition rather than a rewrite.
What is the most common production failure?
Reconciliation breaks that go unnoticed. A small daily discrepancy that nobody alerts on becomes a large unexplained gap over a quarter, and by then reconstructing the cause is genuinely difficult. Automated daily reconciliation with alerting on any break is the highest-value control in the whole system.
Can we handle payments without holding funds?
Usually yes, and it is often the better design. Pass-through with a direct provider relationship for each merchant keeps you out of the funds-holding position entirely, at the cost of less control over timing and netting. Whether that trade is worth it depends on whether your product actually needs holdbacks or split settlement.
Putting payments inside your product?
Kentro builds embedded payment systems for platforms in the UAE and GCC, including the ledger, reconciliation and dispute handling that decide whether it holds up at volume.
