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.

This guide focuses on transaction flows that begin with an authorization request.

For the end-to-end transaction map across both authorization-first and presentment-first cases, use Transaction lifecycle.

Some deferred-authorization or offline transactions do not pass through this stage and first appear only at presentment and clearing. Those cases are covered in Clearing and reconciliation.

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 returns success or error if it can respond within the timeout window
5. FINCI sends the resulting authorization response to Mastercard
6. FINCI sends the same authorization webhook again, using the same id, with the response_code that FINCI actually returned to Mastercard

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

• an initial authorization request, where FINCI asks the integrator for a fast success or error response
• a follow-up authorization advice message, where FINCI confirms the final Mastercard response outcome

If the integrator returns success within 3 seconds, FINCI normally sends Approved to Mastercard and then sends the integrator the same authorization webhook again with response_code = Approved.

If the integrator returns error, or does not return a valid response within 3 seconds, FINCI normally declines the Mastercard authorization with InsufficientFunds and then sends the integrator the same authorization webhook again with response_code = InsufficientFunds.

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

• initial authorization request: response_code is absent
• authorization advice confirmation: response_code is populated with the response FINCI sent to Mastercard

Do not use the advice field by itself to decide whether the message is the initial authorization request or FINCI's confirmation of the Mastercard response. The follow-up confirmation is identified by the repeated authorization id and populated response_code.

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.

Advice flag and amount changes

The advice flag is still relevant to authorization processing, but it should be understood in the context of partial and incremental authorization handling rather than as the confirmation marker.

Partial and incremental authorizations can create related authorization messages where the authorized amount or expected hold changes over the lifecycle. In those cases, the integrator should reconcile the message using the authorization identifiers, retrieval reference data, lifecycle identifiers where available, amount fields, and final response_code.

Use the repeated authorization id plus populated response_code to identify FINCI's confirmation of the response sent to Mastercard. Use advice together with the other transaction fields when interpreting partial or incremental authorization behavior.

Final outcome codes

response_code should be interpreted only on the follow-up authorization advice confirmation.

It represents the authorization outcome that FINCI actually returned to Mastercard, 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. These values are FINCI outcome values on the confirmation message. They are not currently a list of decline reasons that the integrator can return in the initial authorization webhook response.

Today, the integrator response contract is success or error. If the integrator returns error, FINCI normally sends InsufficientFunds to Mastercard and confirms that outcome back to the integrator. A future API version should allow the integrator to return more specific decline reasons that can be mapped to response_code.

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 the initial authorization webhook within 3 seconds.

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

The integrator should still expect the follow-up authorization advice confirmation after that timeout path. It uses the same authorization id and carries the final response_code that FINCI sent to Mastercard.

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

What the integrator should evaluate

Where integrator-managed decisioning is in scope, the relevant checks depend on the agreed program setup, responsibility model, and control framework.

The account entity still exists even where approval logic is not driven by an account-balance check. Depending on the agreed model, the integrator may evaluate a client-managed balance or budget during the webhook decision, or may ignore balance and apply other policy or control logic instead. The linked account record remains part of the required card and transaction structure in both cases.

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

Depending on the agreed program and operating model, the integrator may need to check:

• confirm whether the webhook represents a debit authorization, credit authorization, reversal, or technical message, and interpret the amount, currency, and authtype accordingly
• 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
• for debit-side flows, evaluate available balance, remaining budget, hold model, and any configured daily, monthly, or program-specific limits
• apply MCC restrictions, geography restrictions, cardholder or employee policy, merchant controls, and any program-level spend rules
• detect likely duplicate authorization attempts, repeated retries, and patterns that should be treated as suspicious or high risk
• treat PaymentCredit and Return (refund) as credit-side flows, treat Reversal as an unwind of the earlier authorization effect where applicable, and treat GetContractInfo as a technical message
• if the required internal systems or data are unavailable, 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 success or error outcome for each initial authorization 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.