Payment&BankIntegrations

The rails, and what each one actually requires

### FIB The best-documented rail in the market, and the one to start with because it is a bank rather than a telco — no network lock on the customer side.

How the flow works: you authenticate with OAuth2 `client_credentials` to get a bearer token, then POST a payment request with the amount, currency, callback URL and description. The response gives you back a payment ID, a base64-encoded QR code, a short human-readable code, and a deep link into the FIB app, plus an expiry timestamp. Your customer pays by scanning the QR, typing the readable code, or tapping the link. You then either poll the status endpoint — which returns `PAID`, `UNPAID` or `DECLINED` — or receive a webhook callback. Unpaid payments can be cancelled; paid ones can be refunded inside a configurable window (the default is seven days).

Official SDKs exist for PHP, Laravel, Python, Flutter, Android and iOS, plus a WooCommerce plugin. For Node and TypeScript the widely-used package is community-maintained. The full API is published as a Postman collection, and there is a sandbox separate from the live banking network.

The catch: the online gateway settles in IQD only. If you price in USD, that is a reconciliation problem you have to solve deliberately — see below.

### ZainCash Public, genuinely good documentation. OAuth2 `client_credentials` for the token, then a transaction-init call that returns a redirect, with the redirect payload and the webhooks signed as JWTs (HS256) — so you must verify the signature server-side rather than trusting the redirect. There is a UAT sandbox with test wallets. Webhooks are configured after you go live, by a business representative, not self-serve. IQD only. Customer must be on Zain.

### FastPay REST plus a QR-generation API, with iOS and Android SDKs, a Flutter package, a React Native package, and an OpenCart extension. Strongly Kurdistan-branded and widely held locally. IQD only.

### AsiaPay / AsiaHawala Token obtained with an App Key and App Secret, JWT-signed, then `preOrder` to create, `queryOrder` to check and `refund` to reverse, with a redirect plus webhook callback. You will need a Domain URL, App Key, App Secret, Private Key, Merchant Code and App ID from them. IQD only. Customer must be on Asiacell.

### Qi Card Mobile SDKs for Android, iOS, Flutter and React Native, covering cards, the SuperQi wallet and saved tokens, with PCI-compliant card handling. Notably, its payment UI ships with Kurdish alongside Arabic and English — one of the few that does.

### NassWallet Contract-gated. No public developer documentation. Korek customers only. Plan for a longer commercial conversation before any code gets written.

### Your checkout, in your customer's Kurdish The providers give you what they give you. Your checkout — the part your customer reads before deciding to pay — is yours, and it should be in the dialect they actually read: Bahdini for Duhok, Zakho, Amedi and Akre; Sorani for Hawler and Sulaymaniyah. I build both as separate, complete translations, with payment-method names, error messages, confirmation screens and emailed receipts correct in each. An error message in the wrong dialect at the moment someone is handing over money is precisely where you lose the sale.

### Cards and international Visa and Mastercard acceptance is thin and cash-on-delivery still dominates. If you sell outside the region, Stripe handles the international side — that is what runs billing on MotelSystem today. Locally, an Erbil-based aggregator (Rasedi) offers a unified API across most of the above, which is sometimes the right call and sometimes an unnecessary layer. I will tell you which, for your volume.

The part everyone gets wrong: IQD settlement against USD prices

Every local gateway above settles in IQD. A great many businesses in Hawler and Duhok price in USD. That mismatch is where the money quietly goes missing, and it is not solved by a currency dropdown.

What has to happen instead:

• The house exchange rate is owner-controlled and versioned, with a change log
• The rate in force is snapshotted onto the transaction record at the moment of sale — never looked up later
• The gateway's IQD settlement amount is stored alongside your USD ledger amount, as two separate fields, not one converted one
• Rounding rules are defined once and applied everywhere, because IQD has no practical sub-unit and USD does
• Settlement reports reconcile the gateway's IQD payout against your books without a human doing arithmetic

Get this wrong and your reports drift a little every month, and you will not notice until year-end. This is the same dual-currency discipline that runs in MotelSystem and eMed Store in production.

Reconciliation and webhooks — the unglamorous half

An integration is not finished when the payment succeeds. It is finished when it survives the payment that *half* succeeded.

• Idempotency keys on every create call, so a retry does not double-charge
• Webhook signature verification on every inbound callback — never trust a redirect
• A polling fallback for when a webhook is silently dropped, because they are
• A state machine, not a boolean: pending, paid, expired, cancelled, refunded, disputed
• An immutable payment event log, so you can prove what happened three months later
• Daily settlement reconciliation against what the provider actually paid out
• Retry and dead-letter handling, so a provider's bad afternoon is not your bad afternoon

Where AI earns its place in payments

I build AI automation too, and payments is one of the few areas where it does unglamorous work with a hard return:

• Reconciliation matching — matching a provider's settlement payout against dozens of individual transactions, across two currencies, when references are missing or mistyped. This is fuzzy matching that a human does slowly and badly, and it is the single best AI use case in this whole service
• Payment-proof reading — customers here routinely send a screenshot of a transfer on WhatsApp. Reading it, extracting the amount and reference, and matching it to an open invoice removes a real daily chore
• Anomaly and duplicate detection — the same payment recorded twice, a refund pattern that does not look right, a settlement that came in short
• A payment assistant for your customers — answering "did my payment go through" and "which wallets do you accept" in Bahdini, Sorani, Arabic or English, wired to real transaction status

Where AI does *not* belong: in the payment path itself. Authorisation, verification and state transitions are deterministic code with tests. AI reads, matches and explains — it never decides whether you got paid.

What I deliver

• Multi-wallet checkout, so the customer picks the rail they are on
• Server-side integration with signature verification and idempotency
• Webhook endpoints plus polling fallback and a reconciliation job
• Dual-currency ledger handling as described above
• Sandbox testing before go-live, and a documented go-live checklist
• Written technical documentation for your team — you own it, not me
• Plugged into whatever you run: a custom system, a POS, WooCommerce, or a Next.js site

How pricing works

Priced by scope, not by a rate card. What moves it:

• How many rails — the first one carries most of the setup cost; each additional wallet is cheaper than the first
• Whether reconciliation is included — a payment button is a small job; daily settlement reconciliation against your books is the real work
• Whether dual-currency handling is needed — if you price in USD and settle in dinar, this is where the effort goes
• What it plugs into — a clean modern codebase is fast; an old system with no API is slower
• Refunds, partial payments and subscriptions — each adds states to the machine

Bundled into a POS or ERP build, it costs meaningfully less than commissioning it standalone, because the ledger work is already being done.

You get a fixed-scope, fixed-price written proposal after a free scoping call.

Honest limits

I write the integration. I cannot get you the merchant account — each provider has its own onboarding, its own paperwork and its own commercial terms, and those are between you and them. I will tell you exactly what to ask for and review what they send back, but the contract is yours.

I also do not publish other people's fee schedules. Ask each provider directly; the numbers circulating online are stale.

Book a free 15-minute call →