After a transaction is processed (for any of the above endpoints that create a transaction), Exirom will send
a webhook callback to the URL you specified as callbackUrl in the request. This callback is a POST
request to your server containing a JSON body that describes the final state of the transaction. Your system
should listen for these callbacks to update transaction records and trigger any post-payment actions (like
fulfilling an order or notifying the customer).

Callback Payload Fields

The JSON payload of the callback (often called the Merchant Callback DTO) includes the following fields:

Example Callback Payload

{
"transactionId": "txn12345",
"requestId": "req67890",
"mid": "merchant001",
"transactionStatus": "SUCCEED",
"declineCode": null,
"cardMask": "411111******1111",
"cardHolder": "John Doe",
"orderCurrency": "USD",
"processedCurrency": "USD",
"orderAmount": 100.00,
"processedAmount": 100.00,
"conversionRate": 1.0,
"callbackUrl": "https://yourserver.com/callback",
"billingDetails": {
"firstName": "John",
"lastName": "Doe",
"country": "US",
"email": "[email protected]"
},
"order": {
"orderId": "order789",
"title": "Product Purchase"
},
"createdAt": "2024-01-01T12:00:00Z"
}

Your webhook endpoint should verify the authenticity of the callback (if signatures or tokens are provided
by Exirom) and then use this data to update your records. Typically, upon receiving a successful payment
callback ( transactionStatus: "SUCCEED" ), you would proceed to fulfill the order or service. If the
status is "FAILED", you might notify the customer or prompt them to retry with a different payment
method.

Webhook Callback Behavior - HPP, APM and Cards

Webhook Callback Method Identification

In some integrations, merchants use Hosted Payment Pages (HPP) instead of server-to-server (S2S) flows.

In these cases, Exirom does not know the final payment method at transaction creation time.
The end user selects the payment type later in the flow (Card or a specific APM).

As a result, the transaction lifecycle may involve different DTOs, and the final callback structure depends on the payment method chosen by the user.

To guarantee predictable webhook handling, Exirom explicitly identifies the resolved payment method in every callback.

Callback Identification Fields

Exirom provides explicit identifiers in webhook callbacks so merchants can determine which DTO to expect before parsing the body.

1) paymentMethod (Query Parameter)

All webhook callbacks are sent as HTTP POST requests.

Regardless of the original callbackUrl provided during transaction creation, Exirom appends the paymentMethod query parameter to the callback URL.

2) apmType (Query Parameter and Payload Field)

When paymentMethod=apm, Exirom appends apmType to the callback URL and includes it in the callback payload.

• Present only when paymentMethod=apm
• Value is taken from the Supported Payment Methods (PaymentMethod) enum
• Enables routing and parsing decisions before reading the callback body

Callback URL Examples

If the original callback URL is:

https://merchant.com/payment-status

Exirom will invoke one of the following:

Card Payment

POST https://merchant.com/payment-status?paymentMethod=card

APM Payment

POST https://merchant.com/payment-status?paymentMethod=apm&apmType={APM_METHOD}

Example:

POST https://merchant.com/payment-status?paymentMethod=apm&apmType=UPI_QR

Parsing APM Callbacks (apmResponseData)

When paymentMethod=apm, the callback payload contains:

The structure of apmResponseData varies by apmType. Merchants must use apmType to select the correct parser and flow handling logic.

⚠️

Important Do not assume apmResponseData has the same shape for all APMs. Always route parsing and UX behavior based on apmType.

Where to Find the Correct apmResponseData Schema

Each apmType has dedicated documentation describing:

• the expected apmResponseData fields
• redirect vs iframe behavior
• any required follow-up actions (polling, SDK steps, confirmations)
• provider-specific notes and edge cases

Use the apmType value (from the callback URL or payload) to navigate to the relevant APM documentation page and implement the correct parsing and user experience flow.

Processing Guidance

• Read paymentMethod from the callback URL to determine Card vs APM callback DTO
• When paymentMethod=apm, read apmType to determine which APM schema applies
• Parse apmResponseData according to the dedicated docs for that apmType
• For HPP flows, rely on callback identifiers rather than the original request intent

✅

Outcome A single webhook endpoint can reliably handle Card and all APM callbacks with deterministic parsing and flow control.