Authorization Flow

Authorization flows can operate under different responsibility models.

The primary path described in this guide is integrator-managed decisioning, where FINCI requests a decision from the integrator and the integrator applies its own balance and policy logic. Some programs may use a different responsibility split where FINCI manages decisioning as part of the agreed program setup.

Decision sequence

When a card transaction occurs:

1. the merchant submits an authorization request
2. Mastercard routes the request to FINCI
3. FINCI sends an authorization webhook to the integrator to request a decision
4. the integrator approves or declines the transaction if it can respond within the timeout window
5. FINCI sends the resulting decision back to Mastercard
6. FINCI sends an authorization advice webhook to the integrator with the final decision outcome

In practice, the integrator should expect two steps in the authorization flow:

• a decision request, where FINCI asks the integrator to approve or decline
• a follow-up advice message, where FINCI shares the final decision outcome

If the integrator returns a valid decision in time, the advice reflects that returned decision.

If the integrator does not return a valid decision in time, FINCI applies the fallback decision and the advice reflects that FINCI-applied outcome.

The two message types can be distinguished through the webhook payload:

• decision request: advice = false and response_code is absent
• advice message: advice = true and response_code is populated with the final outcome

This guide defines the authorization message sequence and decision semantics. Use the Webhook Handling guide for delivery robustness, idempotency, retry behavior, and handler implementation patterns.

Final outcome codes

response_code should be interpreted only on advice messages.

It represents the final authorization outcome shared back by FINCI after the decision path has completed, including cases where FINCI had to apply the fallback decline outcome.

For implementation and support purposes, the integrator should persist the raw response_code value and also map it to a smaller internal outcome category.

The table below reflects the current webhook enum and the recommended default view for integrator-managed decisioning. The Integrator can return? column indicates whether the code is typically suitable as an integrator-originated decision reason in the authorization response path.

The raw enum value from the webhook should remain the source-of-truth value stored for audit, support, and troubleshooting.

Timeout behavior

The integrator must respond to authorization webhooks within 3 seconds.

If no valid response is received in that window, the transaction is declined.

The integrator should still expect a follow-up advice message after that timeout path, showing the final outcome that was applied.

This timeout should shape the design of the authorization handler and any supporting decision logic.

What the integrator should evaluate

Typical decision logic should evaluate both the financial meaning of the message and the operational state behind it.

At a minimum, the integrator should check:

• message intent and direction Confirm whether the webhook represents a debit authorization, credit authorization, reversal, or technical message, and interpret the amount, currency, and authtype accordingly.
• card and account state Confirm that the token exists, the card is in a usable status, the linked account is valid, and the transaction is consistent with the current cardholder and account setup.
• available funds and issuer-side controls For debit-side flows, evaluate available balance, remaining budget, hold model, and any configured daily, monthly, or program-specific limits.
• merchant, channel, and policy controls Apply MCC restrictions, geography restrictions, cardholder or employee policy, merchant controls, and any program-level spend rules.
• duplicate and suspicious behavior Detect likely duplicate authorization attempts, repeated retries, and patterns that should be treated as suspicious or high risk.
• flow-specific handling PaymentCredit and Return should be treated as credit-side flows, Reversal should unwind the earlier authorization effect where applicable, and GetContractInfo should be treated as a technical message.
• safe failure behavior If the required internal systems or data are unavailable, the handler should decline safely rather than risk an incorrect approval.

Authorization types and funds direction

Authorization is not limited to purchase-style debit flows.

The webhook authtype values should be interpreted as follows:

• Cash Debit authorization.
• Goods Debit authorization.
• PaymentDebit Debit authorization.
• QuasiCash Debit authorization.
• PaymentCredit Credit authorization.
• Return Credit authorization, typically representing a return or refund flow.
• Reversal Cancellation of a previous authorization rather than a new debit or credit authorization.
• GetContractInfo Technical message.

Reversal messages follow the same webhook decision pattern and are identified through authtype = Reversal.

The authorization decision logic should therefore evaluate not only whether a transaction is allowed, but also what financial direction and business effect the authorization represents.

Authorization handler design

The authorization handler should be designed for fast, consistent, and auditable decisioning.

At a minimum:

• keep processing within the 3-second response window
• avoid unnecessary synchronous dependencies in the decision path
• return a single clear approval or decline outcome for each request
• record the request, decision, and key identifiers for support and investigation
• treat timeout or decisioning failure as a decline path

Authorization is not final settlement

An approved authorization is not the final booked transaction.

Clearing can happen later and may confirm the same amount or a different final amount, depending on network behavior and merchant processing.