Visa Dispute Financial Advice for Program Partners

StraitsX sends a dispute_financial_advice webhook when it receives a transaction-level dispute financial record through Visa clearing. Program partners use these notifications for reconciliation, dispute tracking, and cardholder communication. Notifications arrive by HTTP POST at your configured StraitsX webhook endpoint.
A financial event is not the complete case outcome. A recovery may later be reversed. Keep the financial history separate from the case status, and use StraitsX's case updates to confirm whether a dispute is open, won, lost, or cancelled.

1.Purpose and scope

Use these notifications to track the recovery or return of disputed funds, connect financial records to the original transaction, and reconcile the amounts affected at each dispute stage.
Notifications do not submit a dispute, provide the merchant's evidence, or request your acceptance of a case outcome. Continue submitting cases and supporting documents through the process in the Card Dispute Guidelines. Respond to case requests within the deadline communicated by StraitsX.

2.Dispute categories

The dispute_financial_reason_code identifies a category, rather than a detailed dispute condition such as 10.4 or 13.1.

Value	Visa category	Dispute process
FRAUD	10 Fraud	Allocation
AUTHORIZATION	11 Authorization	Allocation
PROCESSING_ERROR	12 Processing errors	Collaboration
CONSUMER_DISPUTE	13 Consumer disputes	Collaboration

In allocation cases, the acquirer can challenge the dispute through pre-arbitration. In collaboration cases, the acquirer can first submit a financial response, also called representment; pre-arbitration may follow. Receiving a pre-arbitration request does not move funds. Funds only move when the pre-arbitration is accepted or decided by arbitration.

3.All supported financial statuses

Issuer means StraitsX; acquirer means the merchant's acquiring institution. The directions below describe the effect between those institutions for the amount covered by the record. They do not specify an automatic posting to the partner's or cardholder's balance.
A REVERSAL_... record undoes the issuer's original recovery. A RESPONSEREVERSAL... record undoes the acquirer's take-back, restoring that recovery.

dispute_status	Meaning and case interpretation	Network funds direction
FINANCIAL	StraitsX raises the dispute financial and recovers the disputed amount. Treat this as dispute raised and funds recovered, with the outcome still subject to the case lifecycle. It does not by itself mean the dispute is won.	Acquirer → Issuer
REVERSAL_RECALL	StraitsX recalls the original dispute financial, undoing the earlier recovery. Check the case update for the reason for withdrawal or correction. A recalled financial record alone does not explain the whole case outcome.	Issuer → Acquirer
REVERSAL_PRE_ARB_ACCEPTANCE	StraitsX accepts the acquirer's pre-arbitration in a fraud or authorization case. The earlier recovery is reversed: liability is accepted on the issuer side for the affected amount.	Issuer → Acquirer
REVERSAL_ARB_DECISION	An arbitration decision requires the original dispute financial to be reversed. The earlier recovery is undone in line with the decision.	Issuer → Acquirer
RESPONSE_FINANCIAL	The acquirer submits a financial response in a processing or consumer case and takes back the disputed amount. Treat this as acquirer response received. Further case review or pre-arbitration may follow; this is not automatically a final loss.	Issuer → Acquirer
RESPONSE_REVERSAL_RECALL	The acquirer recalls its financial response. This restores the issuer's recovery for the affected amount. Check the case update before treating the case as closed.	Acquirer → Issuer
RESPONSE_REVERSAL_PRE_ARB_ACCEPT	The acquirer accepts StraitsX's pre-arbitration in a processing or consumer case. Its earlier financial response is reversed, restoring recovery for the accepted amount.	Acquirer → Issuer
RESPONSE_REVERSAL_ARB_DECISION	An arbitration decision requires the acquirer's financial response to be reversed. This restores the issuer's recovery in line with the decision.	Acquirer → Issuer

Do not map FINANCIAL directly to “Won” or RESPONSE_FINANCIAL directly to “Pre-arbitration received.” The first records an initial recovery; the second records the acquirer's financial response. A pre-arbitration acceptance or arbitration decision may affect only part of the claim.

4.Payload reference

All fields below are strings. Exact definitions and the full JSON example are in the dispute financial advice API reference.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
card_number_opaque_id	string	the opaque ID of the specific card number
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
acquirer_reference_number	string	the Acquirer Reference Number (ARN) used to track the dispute lifecycle
authorization_code	string	the original transaction authorization code
central_processing_date	string	the date Visa processed the dispute into the clearing system. Format: YDDD
dispute_financial_reason_code	string	Visa's reason code. Values: FRAUD, AUTHORIZATION, PROCESSING_ERROR, CONSUMER_DISPUTE
dispute_status	string	the status or stage of the dispute record. Values: FINANCIAL, REVERSAL_RECALL, REVERSAL_PRE_ARB_ACCEPTANCE, REVERSAL_ARB_DECISION, RESPONSE_FINANCIAL, RESPONSE_REVERSAL_RECALL, RESPONSE_REVERSAL_PRE_ARB_ACCEPT, RESPONSE_REVERSAL_ARB_DECISION
merchant_category_code	string	the Merchant Category Code (MCC)
merchant_city	string	the city where the merchant is located
merchant_country_code	string	the country code of the merchant location
merchant_name	string	name of the merchant
merchant_state_province_code	string	the state or province code of the merchant location
merchant_zip_code	string	the ZIP or postal code of the merchant location
original_transaction_amount	string	the initial transaction amount prior to the dispute
original_transaction_currency	string	the initial transaction currency code
originator_recipient_indicator	string	Visa indicator. Values: ORIGINATOR, RECIPIENT
pos_entry_mode	string	POS entry mode used during the original transaction
purchase_date	string	the original purchase date. Format: MMDD
rate_table_id	string	Visa exchange rate table ID for international currency conversions. Empty for domestic.
settlement_amount	string	the final amount settled for the record
settlement_amount_type	string	financial direction. Values: CREDIT, DEBIT
settlement_currency	string	the currency of the settlement
settlement_type	string	settlement routing type. Values: INTERNATIONAL, DOMESTIC, CLEARING_ONLY, DEFAULT_ROUTING
source_amount	string	the source dispute clearing amount
source_currency	string	the source dispute clearing currency
special_chargeback_indicator	string	special processing flag. Values: NOT_APPLICABLE, PARTIAL
transaction_identifier	string	the Visa Transaction ID linking for the lifecycle records

5.Example of a collaboration dispute

Illustrative example: a USD 100 consumer dispute, with every financial record also settled in USD. The running total below measures net issuer recovery, excluding fees and separate cardholder postings.

Step	Financial record	Amount and direction	Net issuer recovery	Partner interpretation
1	FINANCIAL	USD 100 credit	USD 100	Initial recovery recorded; monitor the case.
2	RESPONSE_FINANCIAL	USD 100 debit	USD 0	Acquirer challenges the dispute; review the evidence and next steps provided by StraitsX.
3	RESPONSE_REVERSAL_PRE_ARB_ACCEPT	USD 100 credit	USD 100	Acquirer accepts the issuer's pre-arbitration; reconcile the restored recovery with the case outcome.

If an arbitration decision instead restored the same amount, step 3 would be RESPONSE_REVERSAL_ARB_DECISION. These are alternative outcomes, not events that must both occur. If only USD 60 were restored, the net recovery would be USD 60; the remaining USD 40 would require its own outcome confirmation.