Webhook amounts

Keep the original transaction amount and currency for purchase display. Use the local account total and currency for holds and postings. Keep settlement values and the fee breakdown to explain how the amounts relate.

This reference covers every amount, currency and rate field in the authorization, presentment and 3D Secure code payloads. Start with the action table, then look up the exact JSON path or open a worked example.

Which value to use

The purchase reservation rule applies to debit transaction types. Return, Reversal and technical messages have different actions; see authorization types. This guide assumes the client ledger owns the reservation under your program setup.

Sign note: in these purchase examples, the initial request has positive local amounts and the approval confirmation has negative amounts. The confirmation does not post a debit. A positive reversal amount releases the eligible hold; a credit presentment posts a credit. Read the phase and authtype before using the sign.

Authorization fields

These fields are at the top level of the authorization webhook, beside accounts_local.

Local account fields

accounts_local is an array on both authorization and presentment messages. The full path matters: accounts_local[].account_amount is the local total; amount_transaction is the original transaction amount.

Presentment fields

A presentment supplies the local movement to post and a settlement_details breakdown. It has no top-level amount_transaction, amount_settlement, transaction/settlement currency pair or rate field.

The complete examples below demonstrate Transaction, Fee and Markup. Interchange is a supported schema value; none of these selected messages contains it.

3D Secure amount fields

The POST /v1/3ds2code callback carries authentication context separately from the authorization webhook.

Purchase in one currency

Merchant 1 charges EUR 10.65. Request and confirmation share the authorization id; the presentment has a separate id and refers to that authorization.

FX purchase with markup

Merchant 2 charges USD 49.99 against a EUR account. The fee is included in the EUR 45.00 local total.

At presentment, Transaction is EUR +44.78 and Markup is EUR -0.22. The EUR 45.00 local total includes EUR 44.78 principal and EUR 0.22 markup. The settlement and local account currencies are both EUR, with local rate 1. Reserve EUR 45.00, then post EUR -45.00 once. Adding 0.22 again would double-count the markup.

ATM withdrawal with FX and a fee

Merchant 12 dispenses CHF 200.00. Reserve EUR 223.18, including EUR 7.96 in fee components. Approved confirmation keeps that hold; cash presentment posts EUR -223.18 once.

The two fee components are shown separately in settlement_details:

• ATM fee: entryType: "Fee", EUR -6.88.
• Markup: entryType: "Markup", EUR -1.08.
• Combined local fees: accounts_local[0].fee_amount: -7.96, equal to -6.88 + -1.08 in this same-currency example.

The local debit of EUR -223.18 already includes both fees. Its magnitudes are 215.22 + 6.88 + 1.08 = 223.18; do not post another EUR 7.96. The principal's positive component sign does not change the supplied negative posting sign. Use the complete ATM messages below to check the whole sequence.

Declined purchase

Merchant 8 requests EUR 135.60. The request has local amount 135.60 and top-level rate: 0; a zero rate does not make this a zero-value request. The confirmation reports Insufficient funds and local amount 0, although the top-level transaction amount is -135.6.

Record the decline, release any provisional hold and post EUR 0.00. The outcome and lifecycle phase determine the action; the negative transaction amount does not prove approval.

Full reversal including the fee

Merchant 9 authorizes GEL 7.30. The initial local total is EUR 2.55 and includes a EUR 0.01 fee. Approved confirmation has local amount -2.55 and fee -0.01; the matched reversal has local amount 2.55 and fee 0.01.

Release up to EUR 2.55 of the eligible remaining hold. The positive reversal amount releases a reservation; it does not post a credit. The request's rate: 0.01 is conversion metadata, not the hold amount.

Smaller presentment

Merchant 7 authorizes EUR 6.50 and clears EUR 6.00. Release the full EUR 6.50 hold and post EUR -6.00 once. The unused EUR 0.50 becomes available again; EUR 0.00 remains held. A later distinct presentment is posted separately without reopening this hold.

Refund

Merchant 10 sends authtype: "Return" with local amount +177.17. Record the return authorization and its approval. There is no purchase hold and no posted refund yet.

When the credit presentment arrives, post EUR +177.17 once. Its authorization_id identifies the return authorization, which need not identify the original purchase.

Implementation checks

Read the full path, currency, transaction type and phase together. Use decimal arithmetic or currency-aware minor units, preserve rates exactly, and process every local account entry independently.

Keep the first decision response for retries. A confirmation with the same id is a later lifecycle phase; each distinct presentment id is a distinct financial event. Confirmations, reversals and presentments must each apply their effect once.

For further cases, use amount changes and matching, multiple and late clearings, or the complete use-case index.