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:

Field	Type	Description
`transactionId`	String	Unique identifier of the transaction (same as returned in the initial response).
`requestId`	String	The original request ID provided when the transaction was initiated.
`mid`	String	Merchant ID that the transaction is associated with.
`transactionStatus`	String	Final status of the transaction (e.g., `SUCCEED`, `FAILED`, `PENDING`, `REFUNDED`).
`declineCode`	Integer	Decline code if the transaction failed (provides reason for failure), otherwise `null` for successful transactions.
`cardMask`	String	Masked card number used (e.g., `"4111********1111"`).
`cardHolder`	String	Cardholder name (if available).
`orderCurrency`	String	Currency of the original order (from the request).
`processedCurrency`	String	Currency in which the transaction was processed (may differ if conversion happened).
`orderAmount`	Double	The amount requested in the original order currency.
`processedAmount`	Double	The amount that was actually processed in the processed currency.
`conversionRate`	Double	The conversion rate applied if currency conversion occurred (otherwise `1.0`).
`callbackUrl`	String	The URL on your server that received this callback (echoed back for reference).
`billingDetails`	Object	A subset of billing details (e.g., name, country, email) associated with the transaction.
`order`	Object	A subset of order details (e.g., `orderId`, `title`) associated with the transaction.
`createdAt`	String	Timestamp when the transaction was created (ISO 8601 format).

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

All webhook callbacks from Exirom are sent via POST requests. Regardless of the original callbackUrl you provide during the transaction request, Exirom will append a paymentMethod query parameter to the callback URL to indicate the payment method used.

This ensures consistent webhook structures across different payment flows (e.g., Card and APM) and allows you to parse the callback body appropriately based on the payment type.

How It Works

If your original callback URL is:

https://merchant.com/payment-status

Exirom will call one of the following, depending on the payment method:

For Alternative Payment Methods (APM):

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

For Card Payments:

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