AANI
Available soon
This feature is only available in Middle East region and limited to certain acquirers.
Introduction
This page describes the neccessary steps to use the alternative payment method AANI via the Gateway's RESTful payment API. There two ways to use AANI for ECOM transactions - via QR code flow and via push notification flow.
Sale Transaction Request (QR code flow)
In the first step you need to send a request to the Gateway with requestType 'ApmSaleTransaction' and 'AANI' as paymentMethod.type. Please note that the QR code will automatically expire after 5 mins and cannot be used by the customer anymore.
Mandatory Elements
| Field name | Description |
|---|---|
paymentMethod.type | `'AANI' is the only value for this payment method |
integrationData.value | For QR code flow use 'QR' |
integrationData.item | Use value 'CHANNEL' |
Example
The following JSON document represents an example of an initial request and the related response with the transactionStatus 'WAITING'. In the API response you will receive the ipgTransactionId what you must use in the inquiry request to confirm the transaction processing status as well as the QR code in requiredIntegrationData.hint.
POST .../payments-gateway/v2/payments
{
"requestType": "ApmSaleTransaction",
"transactionAmount": {
"total": 200.20,
"currency": "AED",
"components": {
"subtotal": 200.20
}
},
"paymentMethod": {
"type": "AANI"
},
"integrationData": [
{
"value": "QR",
"item": "CHANNEL"
}
],
"storeId": "8116000004",
"merchantTransactionId": "AB-1234",
"transactionOrigin": "ECOM"
}
{
"type": "transactionResponse",
"clientRequestId": "2838649",
"ipgTransactionId": "84441734933",
"orderId": "R17549138502523270512766872436",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"type": "PAYMENT_CARD"
},
"paymentMethodDetails": {
"paymentMethodType": "APM"
},
"transactionTime": 1754913850,
"transactionAmount": {
"total": 200.20,
"currency": "AED",
"components": {
"subtotal": 200.20
}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting AANI",
"processor": {
"referenceNumber": "DYN84441734933",
"responseCode": "200",
"responseMessage": "SUCCESS",
"taxRefundData": {}
},
"additionalDetails": {
"additionalResponseData": {}
},
"requiredActions": {
"requiredIntegrationData": [
{
"hint": "00020101021226110007UP951VL5204123453037845406200.205802AE5908ADCB e2e6005Dubai62420132UP951VL#QR#400#00200#EFF##10001#0802036304F085",
"key": "QR_CODE"
}
]
}
}
Sale Transaction Request (push notification flow)
In the first step you need to send a request to the Gateway with requestType 'ApmSaleTransaction' and 'AANI' as paymentMethod.type. Besides, you will need to provide the phone number of the customer's mobile device. This request will trigger the push notification to the customer's mobile device.
Mandatory Elements
| Field name | Description |
|---|---|
paymentMethod.type | 'AANI' is the only value for this payment method |
integrationData.value | For push notification flow use 'PUSH' |
integrationData.item | Use value 'CHANNEL' |
order.billing.contact.mobilePhone | Customer's mobile phone number including '+' and country prefix. E.g. "+971528361234" |
Example
The following JSON document represents an example of an initial request and the related response with the transactionStatus 'WAITING'. In the API response you will receive the ipgTransactionId what you must use in the inquiry request to confirm the transaction processing status.
POST .../v2/payments
{
"requestType": "ApmSaleTransaction",
"transactionAmount": {
"total": 22.00,
"currency": "AED",
"components": {
"subtotal": 20,
"vatAmount": 2
}
},
"paymentMethod": {
"type": "AANI"
},
"integrationData": [
{
"value": "PUSH",
"item": "CHANNEL"
}
],
"order": {
"billing": {
"name": "John Walters",
"contact": {
"mobilePhone": "+971528361234"
}
}
},
"storeId": "8116000004",
"merchantTransactionId": "AB-1234",
"transactionOrigin": "ECOM"
}
{
"type": "transactionResponse",
"clientRequestId": "2838649",
"ipgTransactionId": "84441746491",
"orderId": "R17549827557172565372112443503",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"type": "PAYMENT_CARD"
},
"paymentMethodDetails": {
"paymentMethodType": "APM"
},
"transactionTime": 1754982755,
"transactionAmount": {
"total": 22.00,
"currency": "AED",
"components": {
"subtotal": 20.00,
"vatAmount": 2.00
}
},
"transactionStatus": "WAITING",
"approvalCode": "?:waiting AANI",
"processor": {
"referenceNumber": "DYNE84441746491",
"responseCode": "200",
"responseMessage": "SUCCESS",
"taxRefundData": {}
},
"additionalDetails": {
"additionalResponseData": {}
},
"requiredActions": {}
}
Payment Status Inquiry
In the next step you need to submit an inquiry request using the ipgTransactionId you have received in the first API response from the Gateway to check the transaction status.
Example
GET .../payments/{IPG Transaction ID}
{
"requestType": "RefreshOrder"
}
The following JSON document represents an example of an inquiry request with transactionResult 'APPROVED' in the response:
{
"type": "transactionResponse",
"clientRequestId": "2838649",
"ipgTransactionId": "84441746491",
"orderId": "R17549827557172565372112443503",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"type": "PAYMENT_CARD"
},
"paymentMethodDetails": {
"paymentMethodType": "APM",
"paymentMethodBrand": "AANI_PUSH"
},
"transactionTime": 1754982755,
"approvedAmount": {
"total": 22,
"currency": "AED",
"components": {
"subtotal": 20,
"vatAmount": 2
}
},
"transactionAmount": {
"total": 22,
"currency": "AED",
"components": {
"subtotal": 20,
"vatAmount": 2
}
},
"transactionResult": "APPROVED",
"approvalCode": "Y:000000:4441746491:PP X:12345",
"transactionState": "CAPTURED",
"processor": {
"referenceNumber": "12345",
"responseCode": "200",
"responseMessage": "SUCCESS",
"taxRefundData": {}
},
"additionalDetails": {
"additionalResponseData": {}
}
}
Reversal (Void)
To perform a reversal you need to refer to the original sale transaction.
The structure of the reversal can be used for both use cases - QR code flow and push notification flow.
Example
The following JSON document represents an example of a reversal using ipgTransactionId in the URL path:
POST .../payments/{transaction-id}
{
"requestType": "VoidTransaction"
}
Return (Linked refund)
To perform a return (linked refund) you need to refer to the original sale transaction.
The structure of the linked can be used for both use cases - QR code flow and push notification flow.
Mandatory Elements
| Field name | Description |
|---|---|
order.billing.contact.mobilePhone | Customer's mobile phone number including '+' and country prefix. E.g. "+971528361234" |
Example
The following JSON document represents an example of a return using ipgTransactionId in the URL path:
POST .../payments/{transaction-id}
{
"requestType": "ReturnTransaction",
"transactionAmount": {
"total": "33.00",
"currency": "AED"
},
"order": {
"billing": {
"name": "John Walters",
"contact": {
"mobilePhone": "+971503738089"
}
}
}
}
Updated about 9 hours ago
