# QPAY Gateway source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/cards/domestic-schemes/qpay-gateway/index.md QPAY is a domestic payment network in Qatar that acts as a payment gateway for online transactions, particularly for Qatari debit card users. It allows businesses to accept payments from customers in Qatar using their debit cards through a secure and convenient online payment process. For more information, refer to [QPAY](https://www.qnb.com/sites/qnb/qnbqatar/page/en/enqpaypayment.html). ## Prerequisites {#prerequisites} To offer the QPAY payment method through the Mastercard Gateway: 1. Establish a merchant account with one of the member banks that participate in the QPAY payment gateway and obtain a QPAY MID and credentials. These are required to register your domain and CNAME. 2. Register with your gateway service provider and share your QPAY MID and credentials, domain, and CNAME. 3. Ask your acquirer to configure your merchant profile on the Mastercard Gateway to enable QPAY gateway acceptance. Note: Contact your local product team for additional support. ## QPAY payer journey flow {#qpay-payer-journey-flow} This figure illustrates the QPAY payer journey flow. Figure: QPAY payer journey flow ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/qPaySwitch.png) ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/qPayGateway.png) These stages describe the QPAY payer journey: 1. **Consumers:** 1. Select products and services. 2. Complete the checkout process. 3. Provide basic customer information such as first name, last name, email address, telephone number, and address details. 4. Select **QPAY** as a payment option. 2. The browser redirects consumers to the QPAY page. 3. The consumer provides card details and authenticates the payment. 4. The browser redirects consumers to your page with the final payment status. If the payment process is unsuccessful, consumers can try another payment method. Note: QPAY does not support the AUTHORIZATION and CAPTURE model. It supports only the PAY model. ## QPAY integration {#qpay-integration} ### QPAY through Direct Payment {#qpay-through-direct-payment} * Direct Payment integration enables you to offer QPAY on your checkout page. * QPAY is supported from API version 100 and later. * Submit an [Initiate Browser Payment](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment) request where: * `sourceOfFunds.browserPayment.type = QPAY` * `browserPayment.operation = PAY` ### QPAY transactions {#qpay-transactions} | Transaction Details | Value | |----------------------|-------------------------------------------------------------------------------------------| | Payment type | Debit Switch Gateway | | Supported countries | Qatar | | Supported currencies | QAR | | Supported operations | Purchase (PAY), PARTIAL REFUND, REFUND | | Refund Validity | As per QPAY guidelines, refunds cannot be issued after 90 days from the date of purchase. | | Chargeback | Not applicable | ### Specific Parameter Fields {#specific-parameter-fields} In addition to the [standard fields](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/imp-brow-pay-int/index.md) required in a browser payment request, provide the following parameter fields in the [Initiate Browser Payment](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment) request for QPAY. | Parameter Name | Mandatory or Optional | Description | |-------------------------------------|-----------------------|------------------------------------------------------| | `order.amount` | Mandatory | Specifies that the amount is required. | | `order.currency` | Mandatory | Specifies that the currency is required. | | `order.notificationUrl` | Mandatory | Specifies that the notification URL is required. | | `sourceOfFunds.type` | Mandatory | Specifies that the source of funds is required. | | `sourceOfFunds.browserPayment.type` | Mandatory | Specifies that the browser payment type is required. | | `browserPayment.operation` | Mandatory | Specifies that the operation is required. | ### Initiate QPAY payment request {#initiate-qpay-payment-request} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "QAT", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive", "postcodeZip": "2000" } }, "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "QAT", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive", "postcodeZip": "2000" } }, "browserPayment": { "operation": "PAY", "returnUrl": "{{host}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "dateOfBirth": "xxxx-xx-xx", "email": "xxxx@mxxxx.com", "firstName": "Ganxxxh", "lastName": "Surxxxxxhi", "mobilePhone": "07xxxxxx5", "nationalId": "nationalId1", "phone": "98xxxxx98" }, "order": { "reference": "TEST-SUCCEED", "amount": "90.00", "currency": "QAR", "itemAmount": "90.00", "item": [ { "detail": { "unitTaxRate": "0" }, "name": "Spud", "quantity": "1", "unitPrice": "45", "unitTaxAmount": "0.02", "unitDiscountAmount": "0.03", "description": "item1 description", "sku": "item1" }, { "detail": { "unitTaxRate": "0" }, "name": "item2", "quantity": "1", "unitPrice": "45", "unitTaxAmount": "0.02", "unitDiscountAmount": "0.03", "description": "item2 description", "sku": "item2" } ], "shippingAndHandlingAmount": "0.02", "taxAmount": "0.04", "description": "apmspi test order", "notificationUrl": "{{host}}/callbackInterface/apmspinotification" }, "sourceOfFunds": { "browserPayment": { "type": "QPAY" }, "type": "BROWSER_PAYMENT" } } ``` ### Initiate Qpay payment response {#initiate-qpay-payment-response} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "QAT", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive", "postcodeZip": "2000" } }, "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "QAT", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive", "postcodeZip": "2000" } }, "browserPayment": { "operation": "PAY", "returnUrl": "{{host}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "dateOfBirth": "1999-12-31", "email": "gxxxx@mxxxx.com", "firstName": "Gaxxxxh", "lastName": "Suxxxxhi", "mobilePhone": "077xxxx55", "nationalId": "nationalId1", "phone": "98****8" }, "order": { "reference": "TEST-SUCCEED", "amount": "90.00", "currency": "QAR", "itemAmount": "90.00", "item": [ { "detail": { "unitTaxRate": "0" }, "name": "Spud", "quantity": "1", "unitPrice": "45", "unitTaxAmount": "0.02", "unitDiscountAmount": "0.03", "description": "item1 description", "sku": "item1" }, { "detail": { "unitTaxRate": "0" }, "name": "item2", "quantity": "1", "unitPrice": "45", "unitTaxAmount": "0.02", "unitDiscountAmount": "0.03", "description": "item2 description", "sku": "item2" } ], "shippingAndHandlingAmount": "0.02", "taxAmount": "0.04", "description": "apmspi test order", "notificationUrl": "{{host}}/callbackInterface/apmspinotification" }, "sourceOfFunds": { "browserPayment": { "type": "QPAY" }, "type": "BROWSER_PAYMENT" } } ``` ## Interpretation of the transaction result {#interpretation-of-the-transaction-result} This table shows the transaction response codes for the possible scenarios that you may encounter after initiating the QPAY payments. | Initiate Browser Payment Response | Result | What This Means | |------------------------------------|-----------|------------------------------------------------------------| | `response.gatewayCode = SUBMITTED` | `SUCCESS` | Redirect the payer using the URL provided in the response. | | 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 payment 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 that the transaction is not successful or will revert it. | ## QPAY through Hosted Checkout {#qpay-through-hosted-checkout} Hosted Checkout integration allows you to collect payment details from your payer through an interaction that the gateway hosts and displays. From the API version 100 and later, QPAY is automatically available as a payment method once your payment service provider enables and configures you for this payment method. For more information, see [Browser Payments through Hosted Checkout integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/imp-brow-pay-int/index.md#browser-payments-through-hosted-checkout-integration). ## Webhook notifications {#webhook-notifications} If you subscribe to payment gateway webhook notifications, you will receive additional updates about the `paymentStatus`.