Introduction #
APG Merchant Cloud Notification Service enables merchants to receive real-time transaction notifications as they occur.
To integrate APG Merchant Cloud Notification, merchants must create a RESTful web service based on the specifications defined in this document. Once implemented, merchants must provide the URL of the created web service within the Amwal Pay Platform. This URL will be used to send transaction notifications directly to the endpoint hosted by the merchant.
Purpose of Document #
This document outlines the technical specifications, request and response parameters, and implementation guidelines required to integrate with Merchant Cloud Notification.
It assists merchants in developing a RESTful web service that can receive real-time APG transaction notifications, ensuring seamless communication and timely transaction updates.
Integration Overview #
Merchants must implement a RESTful web service that:
- Adheres to the request and response structure defined in this document.
- Supports secure communication using HTTPS.
- Can handle real-time transaction notifications sent by Amwal Pay.
Once implemented, merchants should:
- Host the service on a reliable and secure server.
- Provide the service URL within the APG Portal.
Technical Specifications #
Header #
| Parameter | Requirement | Value |
|---|---|---|
| Content-Type | Mandatory | application/json |
| Request Type | Mandatory | POST |
Request Message Format #
| Field Name | Mandatory | Type | Constraints | Description | Sample Value |
|---|---|---|---|---|---|
| MerchantId | Yes | Numeric | Max length: 19 | The APG Merchant ID that executed the transaction | 74417 |
| TerminalId | Yes | Numeric | Max length: 19 | The APG Terminal ID | 23556 |
| AuthorizationDateTime | Yes | String | 14 characters | The transaction execution date and time (yyyyMMddHHmmss) | "20241205132435" |
| SecureHash | Yes | String | Max length: 64 | A secure value generated from the merchant’s data and key | 3C0B51238933AB7A97504EFC43EF46AE37548CD8C91490D78192725FAC02E44D |
| DateTimeLocalTrxn | Yes | String | 14 characters | The local transaction date/time (yyyyMMddHHmmss) | "20241205135532" |
| ResponseCode | No | String | — | The transaction response code | "02" |
| TxnType | Yes | String | — | Transaction type | "Purchase" |
| PaidThrough | No | String | Optional | Source of transaction | "Card" |
| SystemReference | Yes | String | — | The APG Transaction ID | "bb618a47-45b3-458f-bf2f-c5dae8698bfa" |
| Message | Yes | String | — | Description of transaction status | "Connectivity Error" |
| MerchantReference | No | String | — | Merchant reference for the transaction | — |
| Amount | Yes | Numeric | 1–9 digits | Transaction amount | 1000.0 |
| CurrencyId | Yes | Numeric | 3 digits | ISO 4217 numeric code (e.g., 512 for OMR) | 512 |
| UDF | No | String | – | Merchant custom-defined fields | { “v1”: “test1”, “v2”: “test2” } |
Request Example #
{
"MerchantId": 0,
"TerminalId": 0,
"AuthorizationDateTime": "string",
"DateTimeLocalTrxn": "string",
"SecureHash": "string",
"Message": "string",
"TxnType": "string",
"PaidThrough": "string",
"SystemReference": "string",
"Amount": 0,
"CurrencyId": 0,
"ResponseCode": "string",
"MerchantReference": "string"
"UDF": "string"
}
Response Example #
{
"message": "success",
"success": true
}
