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, Facilero 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, Facilero explicitly identifies the resolved payment method in every callback.

Callback Identification Fields

Facilero 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, Facilero appends the paymentMethod query parameter to the callback URL.

2) apmType (Query Parameter and Payload Field)

When paymentMethod=apm, Facilero 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

Facilero 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 vs qr 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.