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.
Route each message to the right handler
Implement the authorization and presentment receivers on the backend URLs registered with FINCI. The Webhook reference defines their payloads and responses. Verify the incoming request, parse numeric IDs losslessly and preserve the complete payload.
Identify the message
The receiver identifies authorization versus presentment. For an authorization, read the fields below separately:
| Field | What it tells you |
|---|---|
authtype | The transaction type: purchase or cash debit, credit, reversal or technical message. Use the type mapping. |
response_code | Whether a decision is requested or an outcome is supplied: an empty value is the decision phase; a populated value is the reported outcome. It does not identify a refund or post money. |
id | This authorization record. Request and outcome confirmation share the same ID; a related authorization or reversal has its own ID. |
advice | true identifies an authorization advice message. It does not identify approval or specify how to update the hold. |
Original references | Which earlier authorization a related record refers to. Follow the matching rules. |
Apply the right action
| Received message | Your handler |
|---|---|
Initial debit decision | Check controls and available funds. Where your ledger owns holds, atomically reserve the required local amount once. Approve with HTTP 200 + {"status":"success"} or decline with HTTP 403 + {"status":"error"}, within 3 seconds. |
Outcome confirmation | Save the exact outcome on that authorization ID. Keep an open hold for approval; release any provisional hold on decline. A hold already closed by presentment stays closed. No debit is posted. |
Additional authorization | Keep its own ID and link the earlier authorization. A decision request needs the decision response; an approved outcome applies the configured amount-update rule once. A declined addition leaves the earlier approval in place. |
Authorization advice ( advice: true) | Record the advice and reported outcome, then use the automatic linking procedure. For supported completion of an estimated amount, replace the eligible hold with the advised local total; apply the update once. Other advice flows use their agreed amount-update rule. |
Reversal | Match the earlier authorization and release only its eligible unposted hold, once. Do not refund a posted debit. |
Credit authorization | PaymentCredit or Return identifies the credit flow. Record its outcome; no purchase hold or credit posting is created from authorization alone. A refund is posted at credit presentment. |
Presentment | Post every supplied signed local account movement once; release the full remaining matched hold. A smaller presentment leaves no residual hold; later distinct presentments post separately without reopening it. |
Technical authorization | Handle GetContractInfo under the agreed technical flow; do not apply purchase accounting. |
Keep amounts for display and accounting
Do not discard the original amount when you use the local amount for a hold. They serve different purposes:
| Purpose | Exact fields to keep |
|---|---|
Display the original purchase or withdrawal | amount_transaction with currency_transaction on the authorization. |
Reserve and later post in the account currency | Every accounts_local[].account_amount with its account_currency, using the message phase. |
Explain FX and fees | Settlement amount/currency, both rate fields and local fee_amount; presentment supplies settlement_details[]. See Webhook amounts. |
Link the activity to your records | id, token_id, local account mapping and all supplied authorization references. |
In the FX purchase, display the original USD 49.99 purchase and reserve EUR 45.00. The EUR total includes the markup; converting or adding the fee again would double-count it.
Use the HTTP response examples for decisions. Acknowledge outcome confirmations and presentments after durable receipt; their replies do not make a new purchase decision. Retry the processing safely and deduplicate each business effect.
Published webhook events
The Webhook API reference currently publishes these event endpoints:
- authorization requests, outcome confirmations, advices and reversals
- presentment events
- 3D Secure authentication code events
- tokenization verification code events
- tokenization events
The 3D Secure and tokenization payloads contain the event-specific card, timestamp, code, and context fields defined in the API reference. The 3D Secure code can contain up to 8 characters, and the tokenization verification code can contain up to 6 characters. Use the tokenization outcome mapping agreed for your program.
Authorization webhook expectations
For integrator-managed decisions, return the correct HTTP status and JSON body within 3 seconds. Keep this path free of slow dependencies; balance and policy checks must finish within that window.
FINCI confirms the result under the same authorization id. Preserve the exact response_code: the schema enum includes InsufficientFunds, while received messages can contain Insufficient funds. The webhook reply has no field for supplying a custom network response code.
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:
- a fast ingress layer that validates, records, and routes the event
- 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 outcome confirmations, approved advice or reversal updates, and presentments, persist receipt and apply the business effect once. A decision request still needs its valid response within the decision window; queueing later work does not replace that response.
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.
Deduplicate the effect, not the whole lifecycle
An initial authorization request and its outcome confirmation share an id; the confirmation must still update the outcome. Replay the saved response for repeated initial requests, and apply each confirmed state change once.
Each presentment has its own id. Several presentments can share authorization_id and amount, so neither is a deduplication key. Store identifiers without numeric rounding and scope processing to the environment, program and webhook type.
Keep references to authorizations that have not arrived yet. An out-of-order event must not create a second hold or financial posting when its related event arrives later.
Delivery timings:
- initial authorization requests require a valid response within 3 seconds
- follow-up authorization correction, reversal, and presentment deliveries may be retried every 60 seconds
- 3D Secure and tokenization deliveries use the same 60-second retry interval
- 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.
A changed payload with the same message ID and lifecycle phase is a conflict to retain, not another financial event. Do not use changes in accounts_local to create a second posting.