Webhook Events

The Card issuing API sends different types of webhooks to your_webhook_endpoint to notify you of important events.

The types of events that the card issuing supports are categorized on this page.

Event categories:

Transaction - final transaction outcomes & balance-impacting operations
Notification - user authentication & alert messages (OTP, OOB)
Reconciliation - clearing file matching and manual adjustments
Settlement - settlement summaries, top-ups and offsets
Card & Token - card delivery, token provisioning, status changes, limits, balance issues
Dispute – dispute financial records received via Visa clearing system

See Webhook for the complete guidance

See Body Params for more details explanation

Transaction Related Events

transaction

Sent after every card authorization attempt processed by the network, reporting whether it was approved or declined along with amounts, merchant details, and authorization code, etc.

Fields	Types	Description
event_type	string	`transaction`
idempotency_key	string	key used to keep the request idempotent
acquirer_amount	string	the transaction amount in the currency used by the merchant's acquiring bank
acquirer_currency	string	the currency used by the merchant's acquiring bank
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
cbs_transaction_id	string	card system internal reference ID for this transaction record
currency	string	the currency used at the account level for the transaction
transaction_id	string	Visa's transaction ID assigned by the Visa network
transaction_amount	string	the amount charged to the cardholder
transaction_date	string	the date and time when the transaction was initiated
transaction_type	string	`oct`: original credit transaction. `balance_inquiry`: happens when card is used at an ATM. `deduction` : authorization where a deduction is requested. `debit_verify`: when the acquiring merchant attempts to validate card before online transactions. `hold`: pre authorization request. `completion`: pre authorization completion. `partial_reversal`: partial reversal. `reversal`: when a transaction is reversed before being cleared.
transaction_status	string	transaction status. Allowed:`approved`,`rejected`
merchant_name	string	merchant name for current transaction
merchant_location	string	location of the merchant for the specific transaction
authorization_code	string	an authorization code is a six-digit number that is used to confirm that a payment card transaction is approved.
retrieval_reference_number	string	an RRN is a 12-character identifier to a card transaction based on the ISO 8583 standard

example:

{
  "event_type": "transaction",
  "idempotency_key": "502bf964-6d96-4cfa-9484-7b38c56c72f1",
  "acquirer_amount": "35.67",
  "acquirer_currency": "SGD",
  "card_opaque_id": "01D6ZH4G40G0AMJ6YXD6J9HEVF",
  "cbs_transaction_id": "102bf964-6d96-4cfa-9484-7b38c56c72f1",
  "currency": "SGD",
  "transaction_id": "304082137918123",
  "transaction_amount": "35.67",
  "transaction_date": "1675848435000",
  "transaction_type": "deduction",
  "transaction_status": "approved",
  "merchant_location": "SINGAPORE SG",
  "merchant_name": "McDonald's",
  "authorization_code": "82A111",
  "retrieval_reference_number": "123456789012"
}

pre_authorization_release

Sent when a pre-authorization hold is released and the reserved funds are returned to the cardholder's available balance.

Fields	Types	Description
event_type	string	`pre_authorization_release`
idempotency_key	string	key used to keep the request idempotent
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
customer_opaque_id	string	customer unique identifier, combination of 26 digits and letters
transaction_id	string	Visa's transaction ID assigned by the Visa network
currency	string	the currency used at the account level for the transaction
transaction_amount	string	the final amount charged to the cardholder
transaction_date	string	the date and time when the transaction was initiated
merchant_name	string	merchant name for current transaction
authorization_code	string	An authorization code is a six-digit number that is used to confirm that a payment card transaction is approved.

example:

{
  "event_type": "pre_authorization_release",
  "idempotency_key": "39416a72-a1bb-449f-af98-693dd0d436d4",
  "card_opaque_id": "01H6DPZQ7XVAZ85D4C28GRTPBE",
  "customer_opaque_id": "01H6DPXE5TJKE398G0C31W1RMJ",
  "transaction_id": "304129478180286",
  "currency": "SGD",
  "transaction_amount": "30.00",
  "transaction_date": "230829161616",
  "merchant_name": "McDonald's",
  "authorization_code": "82A111"
}

Notification Related Events

otp_notification

Sent when a 3DS authentication flow requires a one-time password to be delivered to the cardholder via SMS or email.

Fields	Types	Description
event_type	string	`otp_notification`
idempotency_key	string	key used to keep the request idempotent
customer_opaque_id	string	customer opaque id
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
type	string	`OTP`
method	string	`SMS` or `EMAIL`
otp	string	otp code
destination	string	destination of webhook notification
masked_card_number	string	masked card number
merchant	string	merchant name
amount	string	the transaction amount at the account level
currency	string	the currency used at the account level for the transaction

{
  "event_type": "otp_notification",
  "idempotency_key": "fcf5dcbb-3c14-4a1e-b306-12e213180d94",
  "customer_opaque_id": "01D6ZH4G40G0AMJ6YXD6J9HEVF",
  "card_opaque_id": "01D6ZASLKHH12HJKBN2BB",
  "method": "SMS",
  "destination": "+62123456789",
  "type": "OTP",
  "otp": "767321",
  "masked_card_number": "4640********0000",
  "merchant": "APPLE",
  "amount": "2.00",
  "currency": "USD"
}

oob_notification

Sent during a 3DS out-of-band challenge to provide the authentication session details so the merchant can facilitate cardholder verification.

Fields	Types	Description
event_type	string	`oob_notification`
idempotency_key	string	key used to keep the request idempotent
acquirer_amount	string	the transaction amount in the currency used by the merchant's acquiring bank
acquirer_currency	string	the currency used by the merchant's acquiring bank
authentication_id	string	identifier for the 3DS transaction
contract_opaque_id	string	contract unique identifier, combination of 26 digits and letters
customer_opaque_id	string	customer unique identifier, combination of 26 digits and letters
merchant_name	string	merchant name for current transaction
transaction_id	string	identifier for the 3DS transaction

example:

{
  "event_type": "oob_notification",
  "idempotency_key": "4885a619-5b42-4523-afb4-1a18a7e1b489",
  "acquirer_amount": "2.00",
  "acquirer_currency": "USD",
  "authentication_id": "476f9387-93fa-4923-83b5-50f3b83a4ecb",
  "contract_opaque_id": "01J1CA74WV4ZCN4JM18QAS13RA",
  "customer_opaque_id": "01J1C9YG1PTWSRPBED8650GTEB",
  "merchant_name": "Shopee",
  "transaction_id": "9ef617c1-4d28-4144-ac87-322d2c3c3038"
}

Reconciliation Related Events

reconciliation_manual_adjustment

Sent when a balance correction is applied to a cardholder's account — either due to a manual transaction reversal (BASE_1_ADJUSTMENT) or a discrepancy found during Visa clearing file processing (BASE_2_ADJUSTMENT / FX_RATES_ADJUSTMENT) — along with a recommended action (refund or deduction) for the merchant to act on.

Fields	Types	Description
event_type	string	`reconciliation_manual_adjustment`
recommended_action	object	recommend action
-> type	string	`deduction` or `refund`
-> amount	string	amount to deduct/refund
-> currency	string	currency of recommended action
idempotency_key	string	key used to keep the request idempotent
auth_code	string	authentication code (usually 6 digits)
amount	string	the transaction amount at the account level
currency	string	the currency used at the account level for the transaction
account_amount	string	an amount that following card currency, if card currency is SGD, it will be populated by SGD amount. If card currency is USD, it will be populated by USD amount
account_currency	string	the currency used at the account level for the transaction
acquirer_amount	string	the transaction amount in the currency used by the merchant's acquiring bank
acquirer_currency	string	the currency used by the merchant's acquiring bank
issuer_amount	string	the transaction amount at the account level
issuer_currency	string	the currency used at the issuer level for the transaction
transaction_type	string	`ADDITION` - original credit transaction `DEDUCTION` - authorization where a deduction is requested `REFUND` - offline refund For more explanation, please check here
transaction_date	string	the date and time when the transaction was initiated
visa_transaction_id	string	Visa's transaction ID assigned by the Visa network
terminal_id	string	merchant terminal id
customer_opaque_id	string	customer unique identifier, combination of 26 digits and letters
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
merchant_category_code	string	an MCC is a four-digit number corresponds to the type of business or service the company offers
merchant_name	string	merchant name for current transaction
merchant_location	string	merchant's location
token_requestor_id	string	token requestor data for card token transaction. Well know token requestor data can be found the possibles values can be found here
pos_entry_mode	string	POS entry mode data, the possibles values can be found here
reason	string	`BASE_1_ADJUSTMENT`, `BASE_2_ADJUSTMENT`, `FX_RATES_ADJUSTMENT`
settlement_amount	string	the net settlement amount based on the settlement currency.
settlement_currency	string	the currency used for the settlement. Allowed: `SGD`,`USD`
interchange_fee_amount	string	Interchange fee amount
interchange_fee_currency	string	Interchange fee currency
interchange_fee_type	string	Interchange Fee Type. Allowed: `DEBIT`,`CREDIT`
acquirer_reference_number	string	23-digit string

example:

{
  "event_type": "reconciliation_manual_adjustment",
  "recommended_action": {
    "type": "refund",
    "amount": "50.00",
    "currency": "SGD"
  },
  "idempotency_key": "05505e38-b844-488b-b77a-07f9cd052ab4",
  "auth_code": "7YA02Z",
  "amount": "50.00",
  "currency": "SGD",
  "account_amount": "50.00",
  "account_currency": "SGD",
  "acquirer_amount": "50.00",
  "acquirer_currency": "SGD",
  "issuer_amount": "50.00",
  "issuer_currency": "SGD",
  "transaction_type": "REFUND",
  "transaction_date": "2023-12-23",
  "visa_transaction_id": "303360220344393",
  "terminal_id": "02034461",
  "customer_opaque_id": "01HFDKJZYSPJ63EWG3M8H1NDRD",
  "card_opaque_id": "01HFDNCH60SY65K9TTE5F4EWP9",
  "merchant_category_code": "5972",
  "merchant_name": "INDO VCMS",
  "merchant_location": "SG",
  "token_requestor_id": "400012345",
  "pos_entry_mode": "02",
  "reason": "BASE_2_ADJUSTMENT", 
  "settlement_amount": "50.00",
  "settlement_currency": "SGD",
  "interchange_fee_amount": "0.0875",
  "interchange_fee_currency": "SGD",
  "interchange_fee_type": "CREDIT",
  "acquirer_reference_number": "74761353167000395099887"
}

reconciliation_success

Sent when a card transaction is successfully matched against the Visa Base 2 clearing file, providing final settled amounts including interchange fees and settlement currency details.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
transactions	object[]	reconciliation transactions
-> amount	string	the transaction amount at the account level
-> currency	string	the currency used at the account level for the transaction
-> markup_amount	string	markup fee amount
-> account_amount	string	the transaction amount at the account level
-> account_currency	string	the cardholder's account currency
-> acquirer_amount	string	the transaction amount in the currency used by the merchant's acquiring bank
-> acquirer_currency	string	the currency used by the merchant's acquiring bank
-> acquirer_markup_amount	string	markup fee for acquirer amount
-> issuer_amount	string	the transaction amount at the issuer level
-> issuer_currency	string	the currency used at the issuer level for the transaction
-> issuer_markup_amount	string	markup fee for issuer amount
->transaction_id	string	Visa's transaction ID assigned by the Visa network
-> auth_code	string	authorization code
-> token_requestor_id	string	token requestor data for card token transaction.possibles values can be found here
-> pos_entry_mode	string	POS entry mode data, the possibles values can be found here
-> settlement_amount	string	the net settlement amount based on the settlement currency
-> settlement_currency	string	the currency used for the settlement. Allowed: `SGD`,`USD`
-> interchange_fee_amount	string	Interchange fee amount
-> interchange_fee_currency	string	Interchange fee currency
-> interchange_fee_type	string	Interchange Fee Type. Allowed: `DEBIT` ,`CREDIT`
-> card_opaque_id	string	card unique identifier, combination of 26 digits and letters
-> acquirer_reference_number	string	23-digit string

example:

{
  "event_type": "reconciliation_success",
  "idempotency_key": "9c6cae39-388d-4051-8eba-d02926f09d83",
  "transactions": [
    {
      "amount": "10.00",
      "currency": "SGD",
      "markup_amount": "0.00",
      "account_amount": "10.00",
      "account_currency": "SGD",
      "acquirer_amount": "10.00",
      "acquirer_currency": "SGD",
      "acquirer_markup_amount": "0.00",
      "issuer_amount": "10.00",
      "issuer_currency": "SGD",
      "issuer_markup_amount": "0.00",
      "transaction_id": "123456789012345",
      "auth_code": "123ABC",
      "token_requestor_id": "400012345",
      "pos_entry_mode": "02",
      "settlement_amount": "10.00",
      "settlement_currency": "SGD",
      "interchange_fee_amount": "0.0875",
      "interchange_fee_currency": "SGD",
      "interchange_fee_type": "CREDIT",
      "card_opaque_id": "GADPIOJIKAWENKKSPOIEKWRKBCUKJHBDFN",
      "acquirer_reference_number": "74761353167000395099887"
    },
    {
      "amount": "50.50",
      "currency": "SGD",
      "markup_amount": "1.00",
      "account_amount": "50.50",
      "account_currency": "SGD",
      "acquirer_amount": "50.50",
      "acquirer_currency": "SGD",
      "acquirer_markup_amount": "1.00",
      "issuer_amount": "50.50",
      "issuer_currency": "SGD",
      "issuer_markup_amount": "1.00",
      "transaction_id": "987605432112345",
      "auth_code": "HW4I27",
      "pos_entry_mode": "02",
      "settlement_amount": "50.00",
      "settlement_currency": "SGD",
      "interchange_fee_amount": "0.0875",
      "interchange_fee_currency": "SGD",
      "interchange_fee_type": "CREDIT",
      "card_opaque_id": "GWERODIFSGJNSKDFRGAOPKKSPOIEKWRN",
      "acquirer_reference_number": "74761353167000395099887"
    },
    {
      "amount": "0.01",
      "currency": "SGD",
      "markup_amount": "0.00",
      "account_amount": "0.01",
      "account_currency": "USD",
      "acquirer_amount": "0.01",
      "acquirer_currency": "SGD",
      "acquirer_markup_amount": "0.00",
      "issuer_amount": "0.01",
      "issuer_currency": "SGD",
      "issuer_markup_amount": "0.00",
      "transaction_id": "223456789912345",
      "auth_code": "234ABC",
      "central_processing_date": "5022",
      "conversion_date": "5007",
      "conversion_rate": "0.728439",
      "pos_entry_mode": "10",
      "settlement_amount": "0.01",
      "settlement_currency": "USD",
      "interchange_fee_amount": "0.0875",
      "interchange_fee_currency": "SGD",
      "interchange_fee_type": "CREDIT",
      "card_opaque_id": "GADDRFGERGAOPKJRIHINNKKSPOIEKWRN",
      "acquirer_reference_number": "74761353167000395099887"
    },
    {
      "amount": "0.01",
      "currency": "USD",
      "markup_amount": "0.00",
      "acquirer_amount": "200.00",
      "acquirer_currency": "IDR",
      "acquirer_markup_amount": "0.00",
      "issuer_amount": "0.02",
      "issuer_currency": "SGD",
      "issuer_markup_amount": "0.00",
      "transaction_id": "323456789912345",
      "auth_code": "345ABC",
      "central_processing_date": "5022",
      "conversion_date": "5008",
      "conversion_rate": "0.0000617742",
      "rate_table_id": "A0964",
      "pos_entry_mode": "03",
      "settlement_amount": "0.01",
      "settlement_currency": "USD",
      "card_opaque_id": "GADDRFGERGAOPKJRIHINNKKSPOIEKWRN",
      "acquirer_reference_number": "74761353167000395099887"
    },
    {
      "amount": "0.03",
      "currency": "USD",
      "markup_amount": "0.00",
      "acquirer_amount": "500.00",
      "acquirer_currency": "IDR",
      "acquirer_markup_amount": "0.00",
      "issuer_amount": "0.05",
      "issuer_currency": "SGD",
      "issuer_markup_amount": "0.00",
      "transaction_id": "423456789912345",
      "auth_code": "456ABC",
      "central_processing_date": "5022",
      "conversion_date": "5007",
      "conversion_rate": "0.0000616979",
      "rate_table_id": "A0963",
      "pos_entry_mode": "01",
      "settlement_amount": "0.03",
      "settlement_currency": "USD",
      "card_opaque_id": "GADDRFGERGAOPKJRIHINNKKSPOIEKWRN",
      "acquirer_reference_number": "74761353167000395099887"
    },
    {
      "amount": "0.05",
      "currency": "USD",
      "markup_amount": "0.00",
      "acquirer_amount": "0.05",
      "acquirer_currency": "USD",
      "acquirer_markup_amount": "0.00",
      "issuer_amount": "0.07",
      "issuer_currency": "SGD",
      "issuer_markup_amount": "0.00",
      "transaction_id": "523456789912345",
      "auth_code": "567ABC",
      "central_processing_date": "5022",
      "conversion_date": "5008",
      "rate_table_id": "A0964",
      "pos_entry_mode": "01",
      "settlement_amount": "0.05",
      "settlement_currency": "USD",
      "card_opaque_id": "GADDRFGERHISDFGDSFWERTNNKKSPOIEKWRN",
      "acquirer_reference_number": "74761353167000395099887"
    }
  ]
}

Settlement Related Events

settlement_account_topup

Sent when the merchant's settlement account receives a top-up, either from a blockchain transfer or a bank transfer.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
source_type	string	source type. Allowed: `Blockchain` ,`BANK_TRANSFER`
source	string	top-up source account or address
destination	string	destination blockchain address or bank account
amount	string	top-up amount
currency	string	top-up currency
transaction_id	string	top-up transaction id
updated_spendable_balance	string	updated spendable balance after top-up

example:

{
  "event_type": "settlement_account_topup",
  "idempotency_key": "c3963c4f-acbf-4655-88ca-a58a01a1f19a",
  "source_type": "BANK_TRANSFER",
  "source": "123456789",
  "destination": "3373049221415",
  "amount": "50.00",
  "currency": "SGD",
  "transaction_id": "bba230f2-300a-40ed-ba66-700c5261cb8c",
  "updated_spendable_balance": "4261.23"
}

settlement_summary

Sent after daily settlement processing is complete, providing a breakdown of net settlement amount, Visa charges, and reimbursement fees for the settlement period.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
net_settlement	object[]	net settlement amount
-> total_amount	string	net settlement total amount
-> amount_type	string	`DEBIT` or `CREDIT`
visa_charges	object	visa charges amount
-> total_amount	string	visa charge total amount
-> amount_type	string	`DEBIT` or `CREDIT`
reimbursement_fee	object	reimbursement fee object
-> total_amount	string	total reimbursement fee
-> amount_type	string	`DEBIT` or `CREDIT`
report_date	string	settlement summary report date
processing_date	string	this field indicates the date that the settlement was processed.
settlement_type	string	`DOMESTIC` or `INTERNATIONAL`
settlement_currency	string	the currency used for the settlement. Allowed: `SGD`,`USD`
settlement_purpose	string	settlement purpose description
total_atm_decline	string	the total monetary value of ATM transactions that were declined during the settlement period

example:

{
  "event_type": "settlement_summary",
  "net_settlement": {
    "total_amount": "6.95",
    "amount_type": "DEBIT"
  },
  "visa_charges": {
    "total_amount": "0.07",
    "amount_type": "DEBIT"
  },
  "reimbursement_fee": {
    "total_amount": "0.11",
    "amount_type": "CREDIT"
  },
  "idempotency_key": "e529f80f-001e-41e1-8af1-73d9079f25f7",
  "report_date": "2024-10-30T00:00:00Z",
  "processing_date": "2024-10-30T00:00:00Z",
  "settlement_type": "INTERNATIONAL",
  "settlement_currency": "USD",
  "settlement_purpose": "MERCHANT_SETTLEMENT",
  "total_atm_decline": "3.30"
}

settlement_offset

Sent when a settlement offset is applied — either a source credit or an applied debit, reporting the offset amount and any outstanding deduction balance remaining.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
report_date	string	settlement offset report date
processing_date	string	this field indicates the date that the settlement was processed
settlement_type	string	`DOMESTIC` or `INTERNATIONAL`
settlement_currency	string	the currency used for the settlement `SGD` or `USD`
offset_type	string	`SOURCE_CREDIT` or `APPLIED_DEBIT`
offset_amount	string	the monetary value applied during this offset event. This is a signed value (e.g., positive for credits, negative for debits).
remaining_deduction	string	the outstanding deduction amount remaining for the settlement record after this offset has been applied.

this example is for offset_type = SOURCE_CREDIT:

{
  "event_type": "settlement_offset",
  "idempotency_key": "191f6480-dffc-4a32-91f8-4bc8a93cffee",
  "report_date": "2024-10-30T00:00:00Z",
  "processing_date": "2024-10-30T00:00:00Z",
  "settlement_type": "DOMESTIC",
  "settlement_currency": "SGD",
  "offset_type": "SOURCE_CREDIT",
  "offset_amount": "88.29",
  "remaining_deduction": "0.00"
}

this example is for offset_type = APPLIED_DEBIT:

{
  "event_type": "settlement_offset",
  "idempotency_key": "191f6480-dffc-4a32-91f8-4bc8a93cffee",
  "report_date": "2024-10-30T00:00:00Z",
  "processing_date": "2024-10-30T00:00:00Z",
  "settlement_type": "DOMESTIC",
  "settlement_currency": "SGD",
  "offset_type": "APPLIED_DEBIT",
  "offset_amount": "-123.45",
  "remaining_deduction": "987.82"
}

Card and Token Related Events

card_spend_limit

Sent when a transaction is declined because it would exceed the cardholder's configured spend limit for the current period (e.g., daily, weekly, or monthly).

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
attempted_spend	string	the amount the user attempted to spend
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
current_spend	string	amount already spent
limit_amount	string	user spend limit amount
limit_type	string	`PURCHASE` ,`LIFETIME`,`DAILY`,`WEEKLY`,`MONTHLY`,`YEARLY`
transaction_date	string	the date and time when the transaction was initiated
transaction_id	string	Visa's transaction ID assigned by the Visa network

example:

{
  "event_type": "card_spend_limit",
  "idempotency_key": "99f8c4b7-8d7f-4eaa-abbd-df75e3032196",
  "attempted_spend": "35.24",
  "card_opaque_id": "01D6ZH4G3XVVZJHBFJRRFVZ5S5",
  "current_spend": "8.00",
  "limit_amount": "40.00",
  "limit_type": "LIFETIME",
  "transaction_date": "230329171223",
  "transaction_id": "345612345678901"
}

card_token_passcode

Sent during Visa Token Service provisioning when the Yellow Path flow requires the cardholder to verify identity via an OTP delivered to their registered SMS or email.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
method	string	`SMS` or `EMAIL`
destination	string	destination of webhook notification
otp	string	otp code
token_requestor	string	Well know token requestor data can be found the possibles values can be found here
token_type	string	`UNKNOWN`, `HCE`, `SECURE_ELEMENT`, `CARD_ON_FILE`, `ECOMMERCE` more details see here
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
token_opaque_id	string	the unique masked identifier for the digital wallet token
customer_opaque_id	string	customer unique identifier, combination of 26 digits and letters

example:

{
  "event_type": "card_token_passcode",
  "idempotency_key": "3bdd046f-5342-43cc-a431-378928f0449c",
  "method": "SMS",
  "destination": "+62123456789",
  "otp": "123456",
  "token_requestor": "Google Pay",
  "token_type": "HCE",
  "card_opaque_id": "01ABGCDA12DFFC1992",
  "token_opaque_id": "01LMKJJ912CD9231",
  "customer_opaque_id": "01J48HNMX7VQXYM9VH953B46SV"
}

card_token_provisioned

Sent when a card token is successfully provisioned to a mobile wallet (e.g., Apple Pay or Google Pay), including token type, device, and delivery method details.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
contract_opaque_id	string	contract unique identifier, combination of 26 digits and letters
customer_opaque_id	string	customer card unique identifier, combination of 26 digits and letters
last_four_digits	string	card last four digits
token_requestor	string	the possibles values of token requestor can be found here
token_requestor_id	string	the possibles values of token requestor id can be found here
token_type	string	the possibles values of token type can be found here
token_opaque_id	string	token opaque id
destination	string	destination for sms or email
device_id	string	token provisioning device id
method	string	`SMS`,`EMAIL`

example:

{
  "event_type": "card_token_provisioned",
  "idempotency_key": "0a014ba4-de94-41b6-acba-e63671b0e5f5",
  "contract_opaque_id": "01GNV08V5FREZ57RZAF4RQB607",
  "customer_opaque_id": "01GNV08THSHPTEW42837MR1AFW",
  "last_four_digits": "1234",
  "token_requestor": "Google Pay",
  "token_requestor_id": "40010075001",
  "token_type": "HCE",
  "token_opaque_id": "<token opaque id>",
  "destination": "+6588888888",
  "device_id": "0330548690FB0822",
  "method": "SMS"
}

card_token_provisioning_failed

Sent when a mobile wallet token provisioning attempt fails, indicating the failure reason (e.g., card not active, suspected fraud, or invalid CVV).

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
contract_opaque_id	string	contract unique identifier, combination of 26 digits and letters
customer_opaque_id	string	customer unique identifier, combination of 26 digits and letters
last_four_digits	string	card last four digits
token_requestor	string	Well know token requestor data can be found the possibles values can be found here
token_requestor_id	string	Well know token requestor data can be found the possibles values can be found here
token_opaque_id	string	the unique masked identifier for the digital wallet token
token_type	string	token type can be found here
failed_provision_reason	string	`CARD_STATUS_IS_NOT_ACTIVE`, `INVALID_EXPIRY_DATE`, `INVALID_CVV`, `KNOWN_FRAUD_DEVICE`, `HIGH_RISK_DEVICE_PROVISIONING`, `MULTIPLE_DECLINED_REASON_CODES`, `APPLE_PAY_SECURE_ELEMENT_NOT_SUPPORTED`, `MAXIMUM_TOKENS_REACHED`, `TOO_MANY_PROVISIONING_ATTEMPTS`, `VISA_TOKEN_RISK_SCORE_TOO_HIGH`, `CONSECUTIVE_CVV_FAILURES`

example:

{
  "event_type": "card_token_provisioning_failed",
  "idempotency_key": "393409c5-5dfe-4f44-8058-4373cecff0ca",
  "contract_opaque_id": "01K7GNG05B10A6437TEH7FZBTK",
  "customer_opaque_id": "01K7GNG05BNGXKYRMHA0HHNH6C",
  "last_four_digits": "1234",
  "token_requestor": "Google Pay",
  "token_requestor_id": "40010075001",
  "token_opaque_id": "01K7GNG05BB94WCPFQF0XG334Y",
  "token_type": "HCE",
  "failed_provision_reason": "INVALID_CVV"
}

card_token_status_changed

Sent whenever a token's lifecycle status transitions (e.g., from ACTIVE to SUSPENDED, or INACTIVE to ACTIVE).

Fields	Types	Description
event_type	string	`card_token_status_changed`
idempotency_key	string	key used to keep the request idempotent
contract_opaque_id	string	contract unique identifier, combination of 26 digits and letters
customer_opaque_id	string	customer unique identifier, combination of 26 digits and letters
token_requestor_id	string	Well know token requestor data can be found the possibles values can be found here
token_opaque_id	string	the unique masked identifier for the digital wallet token
previous_status	string	`ACTIVE`: The token is currently active and can be used for transactions. `SUSPENDED`: The token has been temporarily suspended (for example, due to suspected fraud or user request) and cannot be used until reactivated. `DEACTIVATED`: The token has been permanently unlinked from the card or device and cannot be reactivated. However, if the same card is bound again to the same device, a new token may be issued and become active. `INACTIVE`: The token is currently not active and can't be used for transactions. `ACTIVE`,`SUSPENDED`,`DEACTIVATED`,`INACTIVE`
current_status	string	`ACTIVE`: The token is currently active and can be used for transactions. `SUSPENDED`: The token has been temporarily suspended (for example, due to suspected fraud or user request) and cannot be used until reactivated. `DEACTIVATED`: The token has been permanently unlinked from the card or device and cannot be reactivated. However, if the same card is bound again to the same device, a new token may be issued and become active. `INACTIVE`: The token is currently not active and can't be used for transactions. `ACTIVE`,`SUSPENDED`,`DEACTIVATED`,`INACTIVE`

example:

{
  "event_type": "card_token_status_changed",
  "idempotency_key": "191f6480-dffc-4a32-91f8-4bc8a93cffee",
  "contract_opaque_id": "01K1D10B8SCRN5DR0G1V28B2SY",
  "customer_opaque_id": "01K1D10B8S2FT3CBJ4ZM8EY60G",
  "token_requestor_id": "40010075001",
  "token_opaque_id": "01K1D10B8SF69E1GJBE5M7SGP5",
  "previous_status": "INACTIVE",
  "currenct_status": "ACTIVE"
}

card_status_transition

Sent when a card's status changes. This includes activations, suspensions, blocks, closures, and reissues. This event requires the "Card Status Transition Webhook" feature to be enabled for the issuing group.

Fields	Types	Description
event_type	string	`card_status_transition`
idempotency_key	string	key used to keep the request idempotent
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
customer_opaque_id	string	the opaque ID of the customer who owns the card
previous_status	string	the card status before the change. Allowed: `INACTIVE`, `ACTIVE`, `SUSPENDED`, `BLOCKED_BY_FRAUD`, `LOST`, `STOLEN`, `PERM_BLOCK`
current_status	string	the card status after the change. Allowed: `INACTIVE`, `ACTIVE`, `SUSPENDED`, `BLOCKED_BY_FRAUD`, `LOST`, `STOLEN`, `PERM_BLOCK`

example:

{
  "event_type": "card_status_transition",
  "idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "card_opaque_id": "card_abc123",
  "customer_opaque_id": "cust_xyz789",
  "previous_status": "INACTIVE",
  "current_status": "ACTIVE"
}

card_pin_set

Sent when a customer successfully set their card PIN. This event requires the "Card PIN Action Webhook" feature to be enabled for the issuing group.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
event_timestamp	string	ISO 8601 UTC timestamp

example:

{
  "event_type": "card_pin_set",
  "idempotency_key": "99f8c4b7-8d7f-4eaa-abbd-df75e3032196",
  "card_opaque_id": "01D6ZH4G3XVVZJHBFJRRFVZ5S5",
  "event_timestamp": "2026-03-30T07:54:51Z"
}

card_pin_changed

Sent when a customer successfully changed their card PIN. This event requires the "Card PIN Action Webhook" feature to be enabled for the issuing group.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
event_timestamp	string	ISO 8601 UTC timestamp

example:

{
  "event_type": "card_pin_changed",
  "idempotency_key": "99f8c4b7-8d7f-4eaa-abbd-df75e3032196",
  "card_opaque_id": "01D6ZH4G3XVVZJHBFJRRFVZ5S5",
  "event_timestamp": "2026-03-30T07:54:51Z"
}

card_pin_reset

Sent when a customer successfully reset their card PIN. This event requires the "Card PIN Action Webhook" feature to be enabled for the issuing group.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
event_timestamp	string	ISO 8601 UTC timestamp

example:

{
  "event_type": "card_pin_reset",
  "idempotency_key": "99f8c4b7-8d7f-4eaa-abbd-df75e3032196",
  "card_opaque_id": "01D6ZH4G3XVVZJHBFJRRFVZ5S5",
  "event_timestamp": "2026-03-30T07:54:51Z"
}

card_custom_per_transaction_limit_revoked

Sent when a custom per-transaction limit on a card is revoked.

Fields	Types	Description
event_type	string	webhook event type
idempotency_key	string	key used to keep the request idempotent
card_opaque_id	string	card unique identifier, combination of 26 digits and letters
limit_amount	string	the revoked limit amount (e.g. "50000.00")
currency	string	the currency of the limit (e.g. "SGD")
revoke_reason	string	the reason provided for revoking the limit

example:

{
    "event_type": "card_custom_per_transaction_limit_revoked",
    "idempotency_key": "3926dd22-7614-494e-a742-5b57220f25f5",
    "card_opaque_id": "01KRJ9KYKV3F3MF7YGHFXS331M",
    "limit_amount": "50000.00",
    "currency": "SGD",
    "revoke_reason": "Compliance review required"
}

dispute_financial_advice

Sent when a transaction-level dispute financial record is received via the Visa clearing system.

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

example:

{
  "event_type": "dispute_financial_advice",
  "idempotency_key": "4f312914-9a33-490a-9757-14e543da52da",
  "card_number_opaque_id": "01HNFQPVKKZFN1X0SY4W2NS1NZ",
  "card_opaque_id": "01HNFQPVK67VTE9NB7E2N8988Y",
  "acquirer_reference_number": "74761356138000325630452",
  "authorization_code": "8MB7ZU",
  "central_processing_date": "6142",
  "dispute_financial_reason_code": "FRAUD",
  "dispute_status": "FINANCIAL",
  "merchant_category_code": "5999",
  "merchant_city": "CITY NAME",
  "merchant_country_code": "US",
  "merchant_name": "ACQUIRER NAME",
  "merchant_state_province_code": "CA",
  "merchant_zip_code": "92705",
  "original_transaction_amount": "40.00",
  "original_transaction_currency": "USD",
  "originator_recipient_indicator": "ORIGINATOR",
  "pos_entry_mode": "01",
  "purchase_date": "0518",
  "rate_table_id": "",
  "settlement_amount": "40.00",
  "settlement_amount_type": "CREDIT",
  "settlement_currency": "USD",
  "settlement_type": "INTERNATIONAL",
  "source_amount": "51.27",
  "source_currency": "SGD",
  "special_chargeback_indicator": "NOT_APPLICABLE",
  "transaction_identifier": "306138275153906"
}