Transaction use cases
Choose the case you need. Each link opens the relevant handling rules. Start with the first purchase, then add the cases your integration must support.
Twelve worked examples include complete FINCI webhook messages beside their diagrams. Identifiers, dates, locations and merchant names are fictional; amounts and reference relationships are preserved.
Download all masked webhook examples (JSON)
Use the Integration test plan to validate these cases. It identifies the checks required for every integration and those that depend on enabled features.
1. Start with a purchase
| Use case | What to implement |
|---|---|
Reserve once, keep that hold on confirmation, then post and release the full hold at clearing. Complete EUR 10.65 example. | |
Preserve the confirmed outcome and release any provisional hold for the declined request. | |
Respond within 3 seconds; use the later confirmation to record the resulting outcome. | |
Use the supplied local account amount. Avoid counting the fee twice. Complete USD 49.99 / EUR 45.00 example. | |
Reserve and post the local total including fees. Complete CHF 200.00 / EUR 223.18 example. | |
Parse IDs losslessly, preserve string references and use decimal arithmetic for money. |
2. Handle authorization changes
| Use case | What to implement |
|---|---|
Link the new ID to the earlier approval and apply the agreed amount-update rule once. Complete EUR 28.94 + EUR 0.40 example. | |
Keep the earlier approval; a declined addition does not cancel it. | |
Keep the estimate separate from the later charge. Confirm the flow's amount-update and hold-closing rules. | |
Link the advice and replace the hold with the advised total under the completion rule. Applies to supported estimated-amount flows, such as fuel or taxi fares. Complete amount-update example: EUR 125.00 → EUR 29.12; release EUR 95.88 once. | |
Distinguish a lower approval from partial clearing. The current webhook response cannot return a lower approved amount. | |
Use authtype to distinguish credits, debit authorizations, reversals and technical messages. |
3. Handle clearing and holds
| Use case | What to implement |
|---|---|
Usually one presentment; rarely several. The first releases the whole matched hold. Post every distinct presentment once without reopening the hold. Complete two-presentment example. | |
Release the entire matched hold and post the actual clearing. EUR 6.50 held / EUR 6.00 posted leaves EUR 0.00 held; EUR 0.50 becomes available again. | |
Account for any uncovered amount under the program funding policy. Assess dispute eligibility separately. | |
Post the supplied local movement once; compare components only in the same currency. | |
Match the approval and release its eligible unposted hold. A reversal is not a refund. | |
Release only the affected part. Complete EUR 10.00 approval → EUR 2.46 reversal → EUR 7.54 clearing example. | |
Release the remaining hold at the configured expiry and keep the authorization record. | |
Post each later distinct clearing once without reopening the hold. A reversal after clearing or expiry releases nothing and is not a refund. |
4. Match related records
| Use case | What to implement |
|---|---|
Match original_authorization_id to the exact authorization ID in the same program and card context. | |
Use the configured original-reference rule to match one qualifying earlier nrn; retain ambiguous or conflicting links for reconciliation. | |
Use a unique supported RRN match in the same card/account context. The partial-reversal example shows this case. | |
Prefer explicit FINCI references. Preserve network references as opaque strings; do not assume identical values across regions or processing routes. | |
Keep the explicit link pending and resolve it when the referenced record becomes available. | |
Keep the event for reconciliation. Do not guess from merchant, amount or time. | |
Post and retain the clearing without fabricating a link. Presentments do not carry RRN, NRN or TLID fields. |
5. Complete the integration
| Use case | What to implement |
|---|---|
Deduplicate the business effect. A request and confirmation sharing an ID are still different lifecycle steps. | |
Start the financial record at clearing; retain any supplied authorization reference for matching. | |
Post the credit as a new financial event and link it to the purchase where a reliable reference is available. | |
Reconcile through the agreed Payments API setup. A presentment webhook does not confirm completion of network cash settlement. |
For the overall flow, open Transaction lifecycle. For customer, account and card relationships, open Core data model.
Before go-live, agree the program's amount-update rules, hold expiry, permitted excesses and dispute procedures. The examples do not define universal limits for those rules.
A hold expiry is a change in your reservation records; it does not create a new FINCI presentment. Retry and matching rules apply to the complete messages linked above.