Integrate Apple Pay through QPay
Overview
To help merchants process Apple Pay debit payments in Qatar, Mastercard Gateway has integrated with the QPay Payment Gateway. This integration supports these payment use cases:
- Apple Pay transactions: Mastercard Gateway supports merchants that accept Apple Pay as a payment method using debit cards in Qatar.
- This solution applies only to customers that support merchant decryption and sends decrypted requests to QPAY for processing.
For more information about QPay, refer to QPay.
Supported features and limitations
This table describes the features that Mastercard Gateway supports for QPay transactions and the applicable limitations.
| Feature | Support |
|---|---|
| Region | Qatar |
| Payment method | Apple Pay debit cards |
| Supported card schemes | Mastercard and Visa |
| Supported operations | PAY, REFUND, and RETRIEVE |
| Authorization and capture | Not supported |
| Refund type | Full refunds only |
| Standalone refunds | Not supported |
Prerequisites
White label acquirers and MSOs must complete these tasks before they open a Mastercard Gateway implementation project for Apple Pay through QPay in Qatar. This table describes each task and the responsible party.
| Task | Responsible party |
|---|---|
| Sign the Mastercard Gateway contract addendum for QPay connectivity. | Merchant, acquirer, and Mastercard Gateway account manager |
| Submit the Mastercard Gateway enrollment form and specify the QPay transactions to enable. If a transaction type is not available, enter it in the notes. | Merchant or acquirer |
| Create QPay portal access for the merchant. | Acquirer |
| Upgrade to a Gateway API version that supports QPay. | Merchant |
Mastercard Gateway supports QPay from Gateway API version 40 onward. Merchants that use an earlier version must upgrade to version 100 to enable this integration.
Merchant configuration
This table describes the fields to configure on the Payment Configuration page for the QPay acquiring link in the Mastercard Gateway Merchant Administration portal.
| Field | Description |
|---|---|
| API Key | Specifies the API key that the QPay payment gateway provides. |
| Username | Specifies the username that the QPay payment gateway provides. |
| Password or Secret Key | Specifies the password that the QPay payment gateway provides. |
| ezConnect Secret Key | Specifies the secret key that the QPay payment gateway provides. |
| QPay Merchant ID | Specifies the merchant ID that the QPay payment gateway defines. |
Integration options
Mastercard Gateway currently supports only the Gateway API direct integration for Apple Pay transactions through QPay in Qatar.
Direct payment integration
With direct payment integration, merchants control transactions and manage their own payment pages or collect payment details. The merchant sends the payment details directly to Mastercard Gateway to process the transaction.
QPay transaction flow diagrams
Payment transaction flow
This diagram illustrates the end-to-end payment transaction flow to the QPay Payment Gateway through Mastercard Gateway.
Refund transaction flow
This diagram illustrates the end-to-end refund transaction flow to the QPay Payment Gateway through Mastercard Gateway.
Supported Gateway API operations
Merchants that have the Purchase, Refund, and Retrieve privileges can create orders, refund transactions, and retrieve order or transaction details. Merchants perform these operations through Gateway API operations or through merchant portals.
QPay transactions must meet these requirements:
- The wallet provider must be APPLE_PAY.
- The card country of issuance must be QAT.
- The transaction currency must be QAR.
- The input Device Primary Account Number (DPAN) must belong to a debit card.
- The card scheme must be Mastercard or Visa.
Purchase (Pay)
To process Apple Pay transactions through QPay, merchants must send the encrypted payment token received in the Apple Pay payment token and the card details shown in the sample request.
In addition to the standard fields that a Pay request requires, include these parameters for QPay. This table describes each parameter.
| Parameter name | Mandatory or optional | Description |
|---|---|---|
sourceOfFunds.provided.card.devicePayment.paymentToken |
Mandatory | Specifies the payment token that the payment SDK of the device returns. |
sourceOfFunds.provided.card.number |
Mandatory | Specifies the account number of the payer's account used for the payment. |
order.currency |
Mandatory | Specifies the transaction currency. |
order.walletProvider |
Mandatory | Specifies the source of the payment details used for digital payment methods. |
Sample request
PUT https://{host}/api/rest/version/100/merchant/{merchantId}/order/{orderId}/transaction/{transactionId}
{
"apiOperation": "PAY",
"order": {
"currency": "QAR",
"amount": "20.00",
"walletProvider": "APPLE_PAY"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5160760000073043",
"expiry": {
"month": "01",
"year": "39"
},
"devicePayment": {
"cryptogramFormat": "3DSECURE",
"onlinePaymentCryptogram": "IA/8pdiWftSsxpFT6wABoDABhgA",
"eciIndicator": "20",
"paymentToken": "{\"version\":\"EC_v1\",\"data\":\"UoGqXyIphPed5E1rFyAVWXgTyTg2iA+1vQ2lmJUqXzIqNEmPOiWH5sr9jeGocRz16rE9W7szszDEWG+OQ74oHc2eHaxYauon8ALhRLrA5ZDSdOQUfsbgRinNxe/KzVDq5IIy7paYixMpCvjL49zQfsgSCR/TNwVIih+Cq7rART6BxrvI9v68P6Z9rq719Re68qT4GJ2nO8wXz/1gXy9ogJq5fmVKxzb1fplOX3jEzyXQdNwyuwEylDeCcD++EDpdtR92dt2ngH5z6nNSnm3ru5uIJpnAkNG6yqd6CJ8FIc1IggNXhSaeKnQCgDgiFqJnsZk5P1gOv2tW+HpKZ7xk0RPJbDlb5gyaNAqFMP2sg4ytLMDJOoee2m7ZVf3i1fkIGuTCCElOoysLn/s\"}"
}
}
}
},
"transaction": {
"source": "INTERNET"
}
}
Sample response
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTQPAY_MERCH",
"order": {
"amount": 20,
"chargeback": {
"amount": 0,
"currency": "QAR"
},
"creationTime": "2026-05-08T17:50:29.829Z",
"currency": "QAR",
"id": "481477008",
"lastUpdatedTime": "2026-05-08T17:50:32.016Z",
"merchantAmount": 20,
"merchantCurrency": "QAR",
"status": "CAPTURED",
"totalAuthorizedAmount": 20,
"totalCapturedAmount": 20,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0,
"walletProvider": "APPLE_PAY"
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"fundingMethod": "DEBIT",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2026-05-08T17:50:32.016Z",
"timeOfRecord": "2026-05-08T17:50:29.874Z",
"transaction": {
"acquirer": {
"id": "QPAY_QNB",
"transactionId": "86d936ce-c371-4b90-9c78-2b839a465a14"
},
"amount": 20,
"currency": "QAR",
"id": "796408447",
"receipt": "260508527601",
"reference": "20260508175029527601",
"source": "INTERNET",
"stan": "527601",
"type": "PAYMENT"
},
"version": "100"
}
Refund
This integration supports only full refunds. The total refund amount must equal the amount of the original transaction.
In addition to the standard fields that a Refund request requires, include these parameters for QPay. This table describes each parameter.
| Parameter name | Mandatory or optional | Description |
|---|---|---|
transaction.amount |
Mandatory | Specifies the transaction amount. |
transaction.currency |
Mandatory | Specifies the transaction currency. |
Sample request
PUT https://{host}/api/rest/version/100/merchant/{merchantId}/order/{orderId}/transaction/{transactionId}
{
"apiOperation": "REFUND",
"transaction": {
"amount": "20.00",
"currency": "QAR"
}
}
Sample response
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTQPAY_MERCH",
"order": {
"amount": 20,
"chargeback": {
"amount": 0,
"currency": "QAR"
},
"creationTime": "2026-05-08T17:50:29.829Z",
"currency": "QAR",
"id": "481477008",
"lastUpdatedTime": "2026-05-08T17:52:05.730Z",
"merchantAmount": 20,
"merchantCurrency": "QAR",
"status": "REFUNDED",
"totalAuthorizedAmount": 20,
"totalCapturedAmount": 20,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 20
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"type": "CARD"
},
"timeOfLastUpdate": "2026-05-08T17:52:05.730Z",
"timeOfRecord": "2026-05-08T17:52:03.516Z",
"transaction": {
"acquirer": {
"id": "QPAY_QXX",
"transactionId": "24157bd6-df58-449e-83ae-eb53ef0684ea"
},
"amount": 20,
"currency": "QAR",
"id": "110319933",
"receipt": "260508529601",
"reference": "20260508175203529601",
"source": "INTERNET",
"stan": "529601",
"type": "REFUND"
},
"version": "100"
}
Retrieve
Use the Retrieve operation to get the final status of the order or transaction after a Pay or Refund operation.
The Retrieve operation requires these path parameters. This table describes each parameter.
| Parameter name | Mandatory or optional | Description |
|---|---|---|
merchantId |
Mandatory | Specifies your Mastercard Gateway merchant identifier. |
orderId |
Mandatory | Specifies the identifier of the order to retrieve. |
transactionId |
Optional | Specifies the identifier of the transaction to retrieve. Required only for transaction-level retrieval. |
Sample request
GET https://{host}/api/rest/version/100/merchant/{merchantId}/order/{orderId}
Sample response
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMK_QPAY-1",
"order": {
"amount": 1.97,
"chargeback": {
"amount": 0,
"currency": "QAR"
},
"creationTime": "2026-05-18T10:16:01.481Z",
"currency": "QAR",
"id": "18May260001",
"lastUpdatedTime": "2026-05-18T10:16:03.810Z",
"merchantAmount": 1.97,
"merchantCurrency": "QAR",
"status": "CAPTURED",
"totalAuthorizedAmount": 1.97,
"totalCapturedAmount": 1.97,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0,
"walletProvider": "APPLE_PAY"
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"fundingMethod": "DEBIT",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2026-05-18T10:16:03.810Z",
"timeOfRecord": "2026-05-18T10:16:01.562Z",
"transaction": {
"acquirer": {
"id": "QPAY_BANK",
"transactionId": "3f56cc08-3b80-48b7-9f49-a2199e996d5b"
},
"amount": 1.97,
"currency": "QAR",
"id": "01",
"receipt": "260518554471",
"reference": "20260518101601554471",
"source": "INTERNET",
"stan": "554471",
"type": "PAYMENT"
},
"version": "100"
}
Interpret transaction results
This table explains the possible retrieve transaction or retrieve order response codes.
| Retrieve transaction or Retrieve order response | Result | What this means |
|---|---|---|
response.gatewayCode = APPROVED |
SUCCESS |
The payment is successful. |
response.gatewayCode = PENDING |
PENDING |
The Mastercard Gateway is waiting for a notification from the acquirer about the payment result. Try RETRIEVE_TRANSACTION again later or listen for notifications from the Mastercard Gateway. |
response.gatewayCode = CANCELLED |
FAILURE |
The payer cancelled the interaction for this payment. |
response.gatewayCode = DECLINED or ACQUIRER_SYSTEM_ERROR |
FAILURE |
The payment was declined. Offer the payer another payment method. If the response is ACQUIRER_SYSTEM_ERROR, contact the acquirer for the reason or try RETRIEVE_TRANSACTION again. |
response.gatewayCode = TIMED_OUT |
FAILURE |
Treat this as a declined payment. The Mastercard Gateway ensures the transaction is not successful or will reverse it. |
Settlement, disputes, and chargebacks
Contact QPay service or acquirer for settlement, disputes, and chargebacks.
Webhook notifications
If you subscribe to Mastercard Gateway webhook notifications, you receive additional updates about paymentStatus.