PaymentsApps

Online payments in Iraq: options for apps and online stores

By Al-Arjan26 September 2026Updated: 25 October 20269 min read

The available options

Terms, fees and integration methods change; confirm them directly with each provider before final planning.

Mobile e-wallets (such as ZainCash and FastPay).
Local cards (such as Qi Card) via payment gateways.
Cash on delivery — still essential for many customers.
Advance transfer for large or wholesale orders.

Qi Card, FastPay, cards and cash on delivery: what to know

Each payment method has its own audience and integration path, and a project in Iraq usually needs more than one. Start with the methods your customers actually use: if most of them pay cash, don’t delay launch for a complex gateway — launch with cash on delivery and one wallet, then add the rest. That is a direct application of the minimum viable product (MVP) idea.

Qi Card: a card held by a wide segment of people; accepting it in your store requires a merchant account and an agreement with the payment-gateway provider. Ask the provider whether the payment page is hosted on their side — that spares your server from handling card data directly.
Visa and Mastercard: Iraqi banks issue them too, and accepting them needs a gateway or payment provider that supports these cards. Enable extra verification such as 3-D Secure if the provider offers it, to reduce fraud.
FastPay: a mobile e-wallet through which merchants can receive payments. The collection methods and merchant-account terms are set by the company, so request its current documentation before planning the integration.
Cash on delivery: needs no technical integration with a provider, but it does need a system: confirm the order before dispatch by phone or WhatsApp, track cash with the courier or delivery company, settle daily, and log orders refused at the door to learn why.
Advance transfer: suits wholesale and large orders. Add an “awaiting transfer confirmation” status to the system and a way to upload proof of payment and review it manually before fulfilling the order.

Want the cost and timeline for your specific project?

Get a quote in two minutes

Activation steps

Open a merchant account in the company’s name and submit documents
Obtain API keys and a sandbox
Implement payment and confirm transactions on the server, not only the phone
Test success, failure, cancellation and refunds
Go live and monitor transactions

ZainCash API integration: what you need, the payment flow and common errors

If your customers use the ZainCash wallet, integrating it directly into your app or website lets them pay without a card. What follows is a general description of the integration according to ZainCash’s current documentation; field names and endpoints can differ between API versions, so always rely on the latest documentation the provider gives you.

Before writing any code you need: an active ZainCash merchant account in your company’s name, your merchant credentials (such as the merchant ID and secret key), a separate test environment with test data to try things before going live, and your own backend server. The secret stays on the server only — never put it inside the mobile app or the website’s front-end code, because anyone can extract it from there.

The typical payment flow goes through these stages:

Your server creates a transaction request signed with the secret key, containing the amount in Iraqi dinars, a unique order reference and a redirect URL back to your site.
Your server sends the request to ZainCash and receives a transaction ID, which it stores with the order in the database with a “pending payment” status.
The customer is redirected to the ZainCash payment page, enters their wallet number and PIN, then the one-time code (OTP) they receive to confirm.
After payment or cancellation, ZainCash sends the customer back to the redirect URL with a signed token carrying the result.
Your server verifies the token’s signature with the secret key, reads the status and order reference, and marks the order “paid” only if the status is successful and the amount and reference match what it created.
For reconciliation, your server can query the transaction status later, as the API allows, especially for orders left pending.

The ZainCash request and response flow, as a diagram

The diagram below shows who sends what to whom, and in which order, during one ZainCash payment. Read each line as a message between two parties: the customer’s app or browser, your server, and ZainCash. We deliberately don’t name specific fields or endpoints, because they differ between API versions; when we updated this section on 2026-10-14, ZainCash’s developer documentation site was not accessible to us for review, so take the technical details from the latest documentation the provider gives you with your merchant credentials.

Step 1 — customer’s app → your server: “I want to pay order number X.” The app sends only the order number; no amount coming from the front end is trusted.
Step 2 — your server: reads the amount from the database, creates a unique reference for this payment attempt, and signs the transaction request with the secret key.
Step 3 — your server → ZainCash: a create-transaction request carrying the amount in dinars, the reference and the redirect URL.
Step 4 — ZainCash → your server: a transaction ID on success, or an error response. Your server stores the ID with the order as “pending payment” and logs any error without the secret key.
Step 5 — your server → customer’s browser: a redirect to the ZainCash payment page for this transaction.
Step 6 — customer ↔ ZainCash: the customer enters their wallet number and PIN, then the verification code they receive, or cancels.
Step 7 — ZainCash → customer’s browser → your server: the customer returns to the redirect URL with a signed token carrying the result.
Step 8 — your server: verifies the token’s signature with the secret key, then matches the reference, amount and status with what it created. If any check fails it rejects the result and keeps the order pending.
Step 9 — your server → ZainCash, when needed: a transaction-status query for orders whose customers never returned, as the API allows.
Step 10 — your server → customer: a confirmation page or failure message and an order notification; fulfilment starts for paid orders only.

Common ZainCash API integration errors and how to avoid them

Many ZainCash integration problems don’t show up in the test environment but only after going live with real customers. If you’re working on e-commerce store development in Iraq or a delivery or booking app, review these errors before launch:

Verifying payment in the customer’s app or browser instead of the server: any result that reaches the front end can be forged, so the final decision belongs to your server after checking the signature.
Wrong or expired credentials, or mixing test-environment and production credentials: keep each environment’s settings separate, in the server’s environment variables rather than in the code.
Redirect URL mismatches: a wrong or incomplete URL, or one that differs between test and production, means the customer pays and then never reaches the order-confirmation page.
Ignoring pending and cancelled payments: the customer may close the page before returning, cancel, or let the OTP expire. Keep the order in a clear status and check it later instead of assuming success or failure.
Duplicate order references: use a unique reference for each payment attempt, and prevent recording a payment twice for the same order if the result arrives more than once.
Amount and currency format: send the amount in dinars in the numeric format the documentation specifies, without currency symbols or text separators; check whether a minimum amount applies; and be careful when converting prices stored in dollars.
No logging: store ZainCash responses and error codes in server logs, without the secret key, to make follow-up with technical support and reconciliation easier.

Common ZainCash integration errors: symptom, cause and fix (general integration errors, not official provider error codes)

Create-transaction request rejected for credentials
Likely cause:
Wrong merchant ID or secret, or test credentials used in production or vice versa
Fix:
Keep each environment’s settings in server variables and confirm them with the provider before launch
Signature check on the returned token fails
Likely cause:
A key that isn’t the right one for the environment, or a tampered token
Fix:
Reject and log the result; don’t mark the order paid
Customer paid but the order is still “pending payment”
Likely cause:
The customer closed the page or lost connection before returning to your site
Fix:
Query the transaction status from your server as the API allows, and review pending orders regularly
Customer never reaches the confirmation page
Likely cause:
A wrong or incomplete redirect URL, or one that differs between test and production
Fix:
Set the redirect URL per environment and test it in both
Payment recorded twice for the same order
Likely cause:
The same result processed more than once
Fix:
Make processing safe to repeat: if the order is already paid, don’t record the payment again
Amount rejected
Likely cause:
A non-numeric format or currency symbols, or an amount below a provider minimum
Fix:
Send the amount in dinars in the format the documentation specifies, and check any minimum
Reconciliation gap at the end of the day
Likely cause:
The transaction ID or reference wasn’t stored with the order
Fix:
Store the ID and reference for every attempt and match them daily against the provider’s statement

Common ZainCash integration errors: symptom, cause and fix (general integration errors, not official provider error codes)
Error or symptom	Likely cause	Fix
Create-transaction request rejected for credentials	Wrong merchant ID or secret, or test credentials used in production or vice versa	Keep each environment’s settings in server variables and confirm them with the provider before launch
Signature check on the returned token fails	A key that isn’t the right one for the environment, or a tampered token	Reject and log the result; don’t mark the order paid
Customer paid but the order is still “pending payment”	The customer closed the page or lost connection before returning to your site	Query the transaction status from your server as the API allows, and review pending orders regularly
Customer never reaches the confirmation page	A wrong or incomplete redirect URL, or one that differs between test and production	Set the redirect URL per environment and test it in both
Payment recorded twice for the same order	The same result processed more than once	Make processing safe to repeat: if the order is already paid, don’t record the payment again
Amount rejected	A non-numeric format or currency symbols, or an amount below a provider minimum	Send the amount in dinars in the format the documentation specifies, and check any minimum
Reconciliation gap at the end of the day	The transaction ID or reference wasn’t stored with the order	Store the ID and reference for every attempt and match them daily against the provider’s statement

An important security tip

Never rely on a “paid” message coming from the customer’s app. Your server must verify the transaction directly with the provider before fulfilling the order — this blocks most fraud attempts.

Get your store or app ready for online payments

Payment is part of a bigger system: order management, inventory, notifications, delivery and reporting. What the Al-Arjan team builds is that system: an online store for Iraqi businesses or a mobile app with order, stock and cash-on-delivery management. Activating and integrating the payment gateway itself is done with the gateway provider or a team that specialises in gateway integration. If you are looking for PayPal specifically, read does PayPal work in Iraq? Practical alternatives. Request a quote for your store or app.

Frequently asked questions

Can I enable several payment methods?

Yes, and it’s best — customers pick what suits them.

How long does gateway integration take?

The technical part is usually a few days; merchant onboarding depends on the provider and your documents.

Does the ZainCash API need a server?

Yes. Creating the transaction request and verifying its result must happen on a server that holds the secret key; the key must never be placed inside the app or the website front end.

How long does a ZainCash integration take?

It depends on how ready your merchant account is, how clear the documentation is, and whether you have a suitable server. The coding itself is usually not long, but allow enough time for testing in the test environment and then in production before opening payment to customers.

Can I test ZainCash without real payments?

Yes, the provider offers a test environment with test data according to its current documentation; test success, failure and cancellation there before switching to production credentials.

Is cash on delivery still necessary in Iraq?

For many stores and apps, yes; offer it alongside online payment and let customers choose, with a clear system for confirming orders and settling cash.