Webhook handling

FINCI uses webhooks to notify the integrator about time-sensitive and operationally important events.

Webhooks are part of the platform event model for authorization and transaction processing. In integrator-managed decisioning setups, they are also part of the transaction decision path.

Use Transaction lifecycle for the high-level sequence between authorization, reversal, presentment, clearing, and refund. This guide focuses on delivery behavior and webhook consumer design.

Primary webhook responsibilities

The integrator should be prepared to:

• receive authorization requests in real time
• where integrator-managed decisioning is used, return success or error within the authorization timeout
• receive the authorization advice confirmation with the response FINCI sent to Mastercard
• process transaction lifecycle updates
• handle duplicate delivery safely

Authorization webhook expectations

In integrator-managed decisioning setups, the initial authorization webhook requires a fast response from the integrator.

In that model, the integrator must respond within 3 seconds. If FINCI does not receive a valid response within that timeout window, the transaction is normally declined with InsufficientFunds.

FINCI then sends the same authorization webhook again as an advice confirmation, using the same authorization id and including the response_code that FINCI actually returned to Mastercard.

If the integrator returns error, FINCI normally declines the Mastercard authorization with InsufficientFunds and confirms that response_code back to the integrator. More specific integrator-provided decline reasons are not mapped today; that is expected to be handled by a future API improvement.

The Authorization flow guide defines this initial-request versus advice-confirmation message pattern and the meaning of response_code.

That means the authorization handler should:

• avoid slow downstream dependencies where possible
• apply deterministic approval rules
• fail safely when balance or policy checks cannot complete in time

Webhook endpoint trust

FINCI sends webhooks only to endpoints that have been registered for the integration.

Webhook ingress should therefore enforce the expected environment and endpoint boundaries:

• only registered endpoints should receive webhook traffic
• sandbox and production endpoint configuration must remain separate
• source validation and network controls should reject unexpected traffic before business processing begins

Webhook endpoints should be dedicated, monitored, and protected as payment-critical interfaces.

Webhook consumer design

A practical implementation usually splits webhook handling into two layers:

1. a fast ingress layer that validates, records, and routes the event
2. business logic that decides or processes the event safely

For integrator-managed authorization decisions, those layers still need to fit within the 3-second timeout window.

For advice, presentment, reversal, and similar follow-up events, the integration should still persist the event durably and process it idempotently even when the business handling is asynchronous.

Idempotency and retries

Webhook consumers must be idempotent.

The same event may be delivered more than once, especially during retries or transient failures. The integrator should be able to identify duplicate processing attempts and avoid double booking or double state transitions.

The default delivery behavior reflected in this portal is:

• initial authorization requests require a valid response within 3 seconds
• follow-up authorization correction, reversal, and presentment deliveries may be retried every 60 seconds
• the maximum retry count is 10 attempts

Retry handling should be validated during onboarding and testing.

Use the Webhook events reference for the exact event payloads and response schemas.

Use API connectivity and authentication for outbound Card API request signing.