# Aani source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/a2a/aani/index.md Aani is the UAE's national instant payment platform operated by AI Etihad Payments (AEP). Aani enables fast, secure, and real time account-to-account (A2A) transfers in UAE Dirham (AED). Transactions are processed within seconds and are available 24 hours a day, 7 days a week, using simple payment identifiers such as mobile numbers or QR codes. Aani does not require traditional bank account identifiers, such as IBANs. Aani supports peer-to-merchant (PSM) transactions. Consumers initiate payments instantly, while merchants accept payments through QR code-based flows and Request to Pay services. Through Mastercard Gateway integration with Aani, merchants can accept Aani digital payments for online transactions. The payment process completes within seconds. Merchants receive instant confirmation of the transaction, and consumers experience a smooth checkout flow. Aani enables customers to perform these actions: * Pay online merchants by scanning an Aani QR code. * Pay online merchants using Request to Pay initiated through a registered mobile number. For more information, refer to [Aani](https://aep.ae/en/services/about-aani/). ## Prerequisites {#prerequisites} To offer the Aani payment method through the Mastercard Gateway: * Register with a supported payment method service provider to offer Aani payments. * Register as an online merchant for Aani payments through your payment service provider. * Configure your merchant profile in Mastercard Gateway Merchant Manager (MM) to enable Aani as an accepted payment method. ## Aani payer journey flow {#aani-payer-journey-flow} These stages describe the Aani payer journey: 1. The consumer selects the products or services and completes the checkout process. Basic customer information may be required, such as first name, last name, email address, telephone number, and address details. 2. The consumer selects Aani as the payment method from the available payment options. 3. The payment provider redirects the consumer to the Aani payment page, where the consumer signs in with their credentials or follows the instructions to continue the payment. 4. For Aani payments, the payment page displays a QR code. The consumer uses an Aani supported banking app to scan the QR code, review the payment details, and confirm the transaction. 5. For Aani RTP payments, the consumer enters the mobile number registered with their issuing bank on the payment page. The issuing bank sends a payment notification to the consumer's Aani supported banking app. The consumer can review and confirm the transaction. 6. After the transaction completes, the system redirects the consumer back to the merchant page and displays the final payment status. 7. If the transaction is unsuccessful, the merchant advises the consumer on the retry procedure. Figure: Aani payment payer journey flow This diagram illustrates the Aani payment payer journey flow. ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/aani.png) Figure: Aani QR Code This diagram illustrates the QR code used in an Aani payment. ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/aaniQr.png) Figure: Aani RTP This diagram illustrates the RTP used in an Aani payment. ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/aaniRtp.png) ## Aani payments integration {#aani-payments-integration} ### Aani payments through Direct Payment {#aani-payments-through-direct-payment} This section provides an overview of how to support Aani QR Code and Aani RTP payments using Direct Payment integration. * Direct Payment integration enables you to offer Aani QR Code and Aani RTP payments on your checkout page. * Aani payments are supported from WS API version 100 for Direct API and version 100 for HCO. * Submit an Initiate Browser Payment request where `sourceOfFunds.browserPayment.type = AANI_QR` and `browserPayment.operation = PAY`. * Submit an Initiate Browser Payment request where `sourceOfFunds.browserPayment.type = AANI_RTP` and `browserPayment.operation = PAY`. ### Aani QR payments transactions {#aani-qr-payments-transactions} This table describes the transaction characteristics for Aani QR payments. | Transaction details | Value | |-----------------------------|-----------------------------------| | Payment type | QR Code | | Supported countries | UAE | | Supported currencies | AED | | Supported operations | Purchase (PAY) | | Minimum transaction amount | Depends on merchant configuration | | Maximum transaction amount | Depends on merchant configuration | | Refund validity | Not applicable | | Chargeback | Not applicable | | Transaction validity period | 300 seconds | ### Aani RTP payments transactions {#aani-rtp-payments-transactions} This table describes the transaction characteristics for Aani RTP payments. | Transaction details | Value | |-----------------------------|-----------------------------------| | Payment type | Request to Pay | | Supported countries | UAE | | Supported currencies | AED | | Supported operations | Purchase (PAY) | | Minimum transaction amount | Depends on merchant configuration | | Maximum transaction amount | Depends on merchant configuration | | Refund validity | Not applicable | | Chargeback | Not applicable | | Transaction validity period | 120 seconds | Note: Aani does not support REFUND, AUTHORIZATION, and CAPTURE operations. It supports only PAY operation. ### Payment options inquiry {#payment-options-inquiry} Use the Payment Options Inquiry (POI) request to retrieve available payment methods and their attributes, including mandatory and optional fields, standard fields, and transaction limits. #### POI request {#poi-request} ```bash curl --request POST \ --url {{remotehost}}/api/rest/version/llaatteesstt/merchant/AANI_MTF/paymentOptionsInquiry \ --header 'Authorization: Basic bWVyY2hhbnQuQUFOSV9NVEY6MTRiOTBhMzYzMDNiNTRjYmIyMDJjZDQzY2QyYTYwMzU=' \ --header 'Content-Type: application/json' ``` #### POI response {#poi-response} ```json { "merchant": "AANI_MTF", "paymentTypes": { "browserPayment": [ { "additionalPayerData": [ { "display": [ { "errorMessageText": "Enter valid phone number", "fieldLabel": "Payer Phone Number", "helpText": "Enter UAE mobile number with 971", "locale": "en" } ], "id": "payerPhone", "validation": { "allowedCharacterSet": "ASCII", "maximumLength": 15, "minimumLength": 10, "presence": "MANDATORY", "regularExpression": "^(\\+971|0)?[- ]?5[0-9]{1}[- ]?[0-9]{7}$" } } ], "currencies": [{ "currency": "AED" }], "description": "Aani is an instant account-to-account payment method that enables Request to Pay (RTP) transactions ", "displayName": "Aani Request to Pay", "maxAmount": 10000, "minAmount": 1, "supportedCountries": [{ "country": "ARE" }], "type": "AANI_RTP" }, { "currencies": [{ "currency": "AED" }], "description": "Aani QR Code payment method", "displayName": "Aani QR Code", "maxAmount": 10000, "minAmount": 1, "supportedCountries": [{ "country": "ARE" }], "type": "AANI_QR" } ] }, "result": "SUCCESS" } ``` ### Sample code to Initiate Aani QR Payment request {#sample-code-to-initiate-aani-qr-payment-request} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "stateProvince": "Scotland", "postcodeZip": "2000", "street": "OceanPoint", "street2": "OceanDrive" } }, "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "stateProvince": "Scotland", "postcodeZip": "2000", "street": "OceanPoint", "street2": "OceanDrive" } }, "browserPayment": { "operation": "PAY", "returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "dateOfBirth": "1999-12-31", "email": "<Email ID>", "firstName": "Akash", "lastName": "Mali", "mobilePhone": "0779xxxx555", "nationalId": "nationalId1", "phone": "+998xxxx898" }, "order": { "reference": "TEST-SUCCEED", "amount": "3", "currency": "AED", "description": "apmspi test order" }, "sourceOfFunds": { "browserPayment": { "type": "AANI_QR" }, "type": "BROWSER_PAYMENT", "provided": { "browserPayment": { "additionalPayerData": [ { "id": "payerPhone", "value": "+971-58-5838078" } ] } } } } ``` ### Sample code to Initiate Aani RTP Payment request {#sample-code-to-initiate-aani-rtp-payment-request} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "stateProvince": "Scotland", "postcodeZip": "2000", "street": "OceanPoint", "street2": "OceanDrive" } }, "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "stateProvince": "Scotland", "postcodeZip": "2000", "street": "OceanPoint", "street2": "OceanDrive" } }, "browserPayment": { "operation": "PAY", "returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "dateOfBirth": "1999-12-31", "email": "<Email ID>", "firstName": "Akash", "lastName": "Mali", "mobilePhone": "0779xxxx555", "nationalId": "nationalId1", "phone": "+998xxxx9898" }, "order": { "reference": "TEST-SUCCEED", "amount": "3", "currency": "AED", "description": "apmspi test order" }, "sourceOfFunds": { "browserPayment": { "type": "AANI_RTP" }, "type": "BROWSER_PAYMENT", "provided": { "browserPayment": { "additionalPayerData": [ { "id": "payerPhone", "value": "+971-58-5838078" } ] } } } } ``` ### Sample Code to Initiate Aani QR Payment response {#sample-code-to-initiate-aani-qr-payment-response} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "postcodeZip": "2000", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive" } }, "browserPayment": { "interaction": { "status": "INITIATED", "timeInitiated": "2026-03-13T07:33:04.740Z" }, "operation": "PAY", "redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script type='application/javascript'>\nwindow.top.location.href='https://uatmpgs.testsvc.shukria.ae:14010/acquirer/1071f18da63400d110b4cd4e1ad8e07a';\n</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe></div>", "returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "email": "<Email ID>", "firstName": "Akash", "lastName": "Mali", "mobilePhone": "0779xxxx555", "nationalId": "nationalId1", "phone": "+998xxxx898" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "MERCURY_AANI_QR_MER", "order": { "amount": 3.00, "chargeback": { "amount": 0, "currency": "AED" }, "creationTime": "2026-03-13T07:33:04.675Z", "currency": "AED", "description": "apmspi test order", "id": "7114702941", "lastUpdatedTime": "2026-03-13T07:33:05.600Z", "merchantAmount": 3.00, "merchantCurrency": "AED", "reference": "TEST-SUCCEED", "status": "INITIATED", "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalDisbursedAmount": 0, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "ACCEPTED", "gatewayCode": "SUBMITTED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "postcodeZip": "2000", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive" } }, "sourceOfFunds": { "browserPayment": { "type": "AANI_QR" }, "provided": { "browserPayment": { "additionalPayerData": [ { "id": "payerPhone", "value": "+971-58-5838078" } ] } }, "type": "BROWSER_PAYMENT" }, "timeOfLastUpdate": "2026-03-13T07:33:05.600Z", "timeOfRecord": "2026-03-13T07:33:04.731Z", "transaction": { "acquirer": { "id": "MERCURY_AANI_QR", "merchantId": "Mercury_3C25752" }, "amount": 3.00, "currency": "AED", "id": "3349458173", "source": "INTERNET", "stan": "0", "type": "PAYMENT" }, "version": "100" } ``` ### Sample code to Initiate Aani RTP Payment response {#sample-code-to-initiate-aani-rtp-payment-response} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "postcodeZip": "2000", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive" } }, "browserPayment": { "interaction": { "status": "INITIATED", "timeInitiated": "2026-03-13T07:34:51.278Z" }, "operation": "PAY", "redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script type='application/javascript'>\window.top.location.href='https://uatmpgs.testsvc.shukria.ae:14010/acquirer-rtp/b2815d1b21ce26d851af50f55831705c';\n</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe></div>", "returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html" }, "customer": { "account": { "id": "customerAccount" }, "email": "<Email ID>", "firstName": "Akash", "lastName": "Mali", "mobilePhone": "0779xxxx555", "nationalId": "nationalId1", "phone": "+9989xxxx898" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "MERCURY_AANI_QR_MER", "order": { "amount": 3.00, "chargeback": { "amount": 0, "currency": "AED" }, "creationTime": "2026-03-13T07:34:51.209Z", "currency": "AED", "description": "apmspi test order", "id": "5261324021", "lastUpdatedTime": "2026-03-13T07:34:52.023Z", "merchantAmount": 3.00, "merchantCurrency": "AED", "reference": "TEST-SUCCEED", "status": "INITIATED", "totalAuthorizedAmount": 0, "totalCapturedAmount": 0, "totalDisbursedAmount": 0, "totalRefundedAmount": 0 }, "response": { "acquirerCode": "ACCEPTED", "gatewayCode": "SUBMITTED", "gatewayRecommendation": "NO_ACTION" }, "result": "SUCCESS", "shipping": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "GBR", "postcodeZip": "2000", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive" } }, "sourceOfFunds": { "browserPayment": { "type": "AANI_RTP" }, "provided": { "browserPayment": { "additionalPayerData": [ { "id": "payerPhone", "value": "+971-58-5838078" } ] } }, "type": "BROWSER_PAYMENT" }, "timeOfLastUpdate": "2026-03-13T07:34:52.023Z", "timeOfRecord": "2026-03-13T07:34:51.268Z", "transaction": { "acquirer": { "id": "MERCURY_AANI_RTP", "merchantId": "Mercury_3C25752" }, "amount": 3.00, "currency": "AED", "id": "3349458173", "source": "INTERNET", "stan": "0", "type": "PAYMENT" }, "version": "100" } ``` ## 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 transaction. | Initiate browser payment response | What this means | |-------------------------------------------------------|-------------------------------------------------------------------------------------| | `response.gatewayCode = SUBMITTED` `result = SUCCESS` | Redirect the payer using the URL provided in the Initiate Browser Payment response. | | Retrieve transaction or retrieve order response | What this means | |-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `response.gatewayCode = APPROVED` `result = SUCCESS` | The payment is successful. | | `response.gatewayCode = PENDING` `result = PENDING` | The \ is waiting for a confirmation from the acquirer. Retry `RETRIEVE_TRANSACTION` or listen to notifications from the \. | | `response.gatewayCode = CANCELLED` `result = FAILURE` | The payer cancelled the payment. Offer an alternative payment method. | | `response.gatewayCode = DECLINED or ACQUIRER_SYSTEM_ERROR` `result = FAILURE` | The payment was declined. Offer another payment method or retry `RETRIEVE_TRANSACTION`. | | `response.gatewayCode = TIMED_OUT` `result = FAILURE` | Treat as declined. The \ ensures the transaction is not successful or reverts the transaction. | ## Aani payment through Hosted Checkout {#aani-payment-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, Aani QR Code and Aani RTP payments are automatically available as a payment method once your payment service provider enables and configures you for this payment methods. For more information, see [Browser Payments through Hosted Checkout Integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/imp-brow-pay-int/index.md#browser-payments-through-hosted-checkout-integration). ## Webhook notifications {#webhook-notifications} If you subscribed to Mastercard Gateway webhook notifications, you receive additional notifications on the paymentStatus. To process webhooks, the service provider must: * Use the endpoint provided to the service provider as part of the `/initiate API` request. * Configure the required webhook events in the system and send webhook payloads accordingly. * Configure a webhook retry mechanism.