Skip to main content
Version: v2.0.4 latest

Introduction

The QiCard Payment Gateway is a PCI-DSS–compliant payment platform that lets merchants accept digital payments — card payments, saved-card tokens, and the Pay with SuperQi wallet — across the web and inside native mobile apps. This documentation gives developers, technical teams, and stakeholders everything needed to integrate, test, and operate payments on the QiCard platform.

At its core the gateway sits between three parties: your application, the card schemes / SuperQi wallet, and the acquiring bank. You never handle raw card data yourself — the gateway takes on the sensitive parts of the flow (cardholder authentication, 3-D Secure, authorization, and settlement notifications), which dramatically reduces your compliance scope and lets you focus on your product.

New here?

Read this page end-to-end for the concepts, then jump to Integration Requirements and the API Authentication section to make your first call.

What the gateway does for you​

A payment gateway is more than a single API call — it is an orchestration layer. When a customer pays, a lot has to happen correctly and securely in a few seconds: the amount must be validated, the cardholder authenticated, the issuing bank asked to authorize the funds, the result recorded, and your system reliably notified. The QiCard Payment Gateway abstracts all of this behind a small, predictable surface so you can integrate quickly:

  • Security & compliance — card data is captured on QiCard-hosted surfaces (a hosted payment page or the native SDK screens), so raw PANs never touch your servers. The platform performs 3-D Secure authentication (the sandbox host is literally uat-sandbox-3ds-api.qi.iq) to reduce fraud and shift liability.
  • Authorization & processing — the gateway talks to the card schemes and the acquirer to authorize and capture the payment.
  • Reliable notifications — every meaningful state change is delivered to your backend through webhooks, so your systems stay in sync even if the customer closes their browser.
  • Lifecycle management — you can query a payment's status, refund it, or cancel it through the API at any time.

How a payment flows​

Conceptually, every payment follows the same lifecycle regardless of the channel (web or mobile):

  1. Create the payment. Your backend calls Create Payment with the amount, currency, and callback URLs. The gateway returns a Payment object containing a unique paymentId and a formUrl (a secure payment link).
  2. Collect the payment. The customer completes payment either on the hosted page (formUrl) for web flows, or inside your app through the Mobile Payment SDK for in-app flows.
  3. Authenticate. The gateway runs 3-D Secure and any method-specific step (for example, approving the charge in the SuperQi app).
  4. Authorize & finalize. The issuer authorizes the funds and the gateway settles the transaction, resolving it to a terminal status such as SUCCESS, FAILED, or AUTHENTICATION_FAILED.
  5. Get notified. The gateway sends a signed webhook to your notificationUrl. This is the source of truth for your backend — see Webhook Notifications.
  6. Confirm. For belt-and-suspenders reliability, your backend confirms the outcome with Get Payment Status before releasing goods or services.
Webhooks are the source of truth

Never rely on the customer being redirected back to your finishPaymentUrl to mark an order as paid. Browsers close, apps get backgrounded, networks drop. Treat the webhook (verified per Message Verification) as authoritative and reconcile with Get Payment Status.

Two ways to integrate​

The platform exposes the same payment engine through two complementary integration surfaces. Most merchants use one; larger merchants use both (server-to-server for orchestration, SDK for the in-app experience).

1. The REST API​

The REST API is the backbone of the integration. Your backend uses it to create and manage payments without ever rendering a card form itself. It is a small, resource-oriented HTTP API that speaks JSON.

The REST API is ideal for headless commerce, web checkouts (redirect the shopper to formUrl), server reconciliation, and back-office operations like refunds.

2. The Mobile Payment SDK — native in-app payments​

The Mobile Payment SDK embeds the entire payment experience directly inside your app, so customers never leave to a browser. It ships for Android (Kotlin), iOS (Swift), Flutter, and React Native, and — like the API — keeps card data inside PCI-DSS–compliant, QiCard-maintained screens.

Beyond simply rendering a payment form, the SDK provides capabilities that only make sense on-device:

  • Card tokenization — save a card as a reusable payment token so returning customers can pay with one tap, and manage those tokens (list, block, transfer) from within the app.
  • Deep customization — theme colors, light/dark, custom labels, and full RTL/LTR support with multiple languages (including Arabic and Kurdish).
  • Pay with SuperQi — from SDK 2.0.2+, customers can pay from their SuperQi wallet; 2.0.4+ adds same-device deep-link (URI redirect) support. See Pay with SuperQi.
App-channel payments

Payments initiated from a mobile app must be created with appChannel = true so the gateway tailors the authentication flow for an in-app context. See Mobile SDK Overview.

For teams that use a CMS instead of a custom backend, there are also drop-in WordPress & CMS plugins.

Key features at a glance​

CapabilityWhat it gives you
Card paymentsAccept card payments on the web (hosted page) or in-app (SDK).
Pay with SuperQiLet customers pay from the SuperQi wallet (SDK 2.0.2+, deep-link 2.0.4+).
TokenizationSave cards as tokens for fast, one-tap repeat purchases.
3-D SecureBuilt-in cardholder authentication and liability shift.
Webhooks & eventsReal-time, verifiable notifications to your notificationUrl.
Refunds & cancellationsReverse or void payments programmatically.
Multi-language & RTLLocalized payment surfaces, including Arabic and Kurdish.
PCI-DSS complianceSensitive card data stays off your servers.

Core concepts and terminology​

A few terms recur throughout the docs — it helps to know them up front:

  • Merchant Terminal — the payment configuration your acquirer provisions for you. Its identifier is sent as the X-Terminal-Id header on every API request and determines which payment methods and permissions are enabled.
  • Payment object — the record the gateway creates for each transaction. It carries the paymentId (the transaction reference), formUrl (payment link), status, and related metadata.
  • paymentId — the canonical reference for a transaction; use it to query status, refund, or cancel.
  • notificationUrl — your webhook endpoint where the gateway posts payment results.
  • finishPaymentUrl — the URL the shopper is redirected to after finishing on the hosted page (a UX convenience, not a payment confirmation).
  • Payment token — a saved-card reference issued by the SDK for repeat payments.

Environments​

Development and testing happen against the sandbox environment (https://uat-sandbox-3ds-api.qi.iq/api/v1), where you can exercise the full flow with test data before going live. Start with Sandbox & Testing to get set up.

Before you begin​

To integrate, you'll need:

  1. Merchant Terminal credentials (X-Terminal-Id and API credentials) provided by your acquirer.
  2. A backend able to make authenticated HTTPS requests and to receive webhook callbacks on a publicly reachable notificationUrl.
  3. For in-app payments, a supported mobile project (Android, iOS, Flutter, or React Native).

Review Integration Requirements and API Usage Guidelines for the full checklist.

Where to go next​