# Integrate Apple Pay through QPay source: https://developer.mastercard.com/mastercard-gateway/documentation/build/mobile-integration/apple-pay/int-apple-pay-through-qpay/index.md ## Overview {#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](https://www.qcb.gov.qa/en/Pages/Retail-payment-systems.aspx). ## Supported features and limitations {#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 {#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. Tip: Contact your local product team for additional support. ## Merchant configuration {#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 {#integration-options} Mastercard Gateway currently supports only the Gateway API direct integration for Apple Pay transactions through QPay in Qatar ### Direct payment integration {#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 {#qpay-transaction-flow-diagrams} ### Payment transaction flow {#payment-transaction-flow} This diagram illustrates the end-to-end payment transaction flow to the QPay Payment Gateway through Mastercard Gateway. Diagram payflo-applepay-qpay ### Refund transaction flow {#refund-transaction-flow} This diagram illustrates the end-to-end refund transaction flow to the QPay Payment Gateway through Mastercard Gateway. Diagram refundflo-applepay-qpay ## Supported Gateway API operations {#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. Note: QPay debit transactions support only the PAY and REFUND model. They do not support the AUTHORIZATION and CAPTURE model. ### Purchase (Pay) {#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](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/imp-brow-pay-int/index.md) 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 {#sample} ```curl PUT https://{host}/api/rest/version/100/merchant/{merchantId}/order/{orderId}/transaction/{transactionId} ``` ```json { "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" } } ``` ```json { "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 {#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](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/imp-brow-pay-int/index.md) 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. | Note: QPay does not support standalone refunds. #### Sample {#sample-1} ```curl PUT https://{host}/api/rest/version/100/merchant/{merchantId}/order/{orderId}/transaction/{transactionId} ``` ```json { "apiOperation": "REFUND", "transaction": { "amount": "20.00", "currency": "QAR" } } ``` ```json { "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 {#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. | ```curl GET https://{host}/api/rest/version/100/merchant/{merchantId}/order/{orderId} ``` ```json { "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 {#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 {#settlement-disputes-and-chargebacks} Contact QPay service or acquirer for settlement, disputes, and chargebacks. ## Webhook notifications {#webhook-notifications} If you subscribe to Mastercard Gateway webhook notifications, you receive additional updates about **paymentStatus**.