Overview
In order to keep your application up to date, and notify your users of changes to their card account, you should listen to webhooks originated by Bridge and sent to your servers.Webhook types
| Object | Event category | Description |
|---|---|---|
| Card account | card_account | Represents changes to a given card account. |
| Transaction | card_transaction | Represents a transaction arriving from the card network. This transaction may or may not be actionable or final depending on its state. |
| Posted Transaction | posted_card_account_transaction | Represents finalized transactions.. |
| Dispute | card_dispute | Represents state changes in disputes made on cards issued in your card program. |
| Card withdrawal | card_withdrawal | Reflects status changes for withdrawals from custodial card accounts. Only funds flows which use pre-funded balances will receive these notifications. |
Example webhooks
Thecard_transaction event category has the most complexity, as it represents the various stages that a card transaction could go through. Below, we’ve outlined several common scenarios that you could encounter for card transactions, and what the corresponding webhook events would look like
Scenario 1: Successful Transaction
In a normal, successful transaction, anapproved event will be published at the time of the initial purchase.
Event 1: Card transaction approved
settled event will be published for the full amount of the transaction.
Event 3: Card transaction settled
Scenario 2: Transaction Denied
In the case of a card transaction decline, a single event will be published with the transaction in adenied state. See a below section on a comprehensive listing of the possible status_reasons.
Event 1: Card transaction denied
Scenario 3: Authorization Reversal
A transaction may also be reversed before it gets settled. The original authorization event will look largely the same as scenario 1: Event 1: Card transaction approvedreversed, and the amount will change to reflect that no funds have been settled. The original authorization amount will still be available on the original_amount field.
Event 2: Card transaction reversed
Scenario 4: Refund After Settlement
If a card transaction gets refunded after settlement, our system will see an authorization and settlement for a positive amount. (Note that up until now, events for normal purchases have been denoted as negative amounts against the card account balance.) In the webhook event, the category of the transaction will be denoted asrefund.
Depending on various factors, Bridge may place a short risk hold (usually between 1 hour and 3 days) for the refund before crediting it to the card balance. If a risk hold is placed, the transaction will move into an intermediate state, merchant_credit_on_hold, before it becomes settled.
Event 1: Refund transaction approved (on risk hold)
settled event will be published when the refund transaction is settled with the risk hold released.
Event 2: Risk hold released
Scenario 5: Incremental Authorization
In many situations, the amount of a transaction will change after it has been authorized but before it has been settled. The original authorization event will look largely similar to the other scenarios outlined in this document, but after that, more events will be published to provide information about the additional amount. Event 1: Card transaction approvedincremental_auth_approved event will be published for the full amount of the transaction. Note that the authorized_at timestamp will still reflect the timestamp of the original authorization approval. The original authorization amount will still be available on the original_amount field.
Event 2a: Additional amount authorized
settled_amount reflects the full amount of the transaction after the incremental authorization.
Event 3: Total amount settled
Scenario 6: Authorization Expiration
Authorizations are not indefinite, and can expire. This is rare but not impossible in the real world. For example, if you check in at a hotel, the front desk might place a temporary hold on the balance for incidental charges, but the card authorization will expire after some period of time after checking out of the hotel. Event 1: Card transaction approvedexpired event will be published, with the amount changed.
Event 2: Card transaction expired
Crypto Transaction Details
If a card transaction is associated with an onchain transaction against a noncustodial wallet, the webhook event will contain the crypto transaction details. Since each authorization will generally be associated with a separate onchain pull, this object is exposed within eachauthorization_infos item.
Below is an example of a webhook event that involves a noncustodial wallet pull. You can use the tx_hash within the crypto_details to correlate the transaction with other onchain data sources.
Card Transaction Status Reasons
Below is a comprehensive listing of the possiblestatus_reason values you may receive in the card_transaction webhook event object.
Note that many of them are very uncommon. The most common reasons for denied transactions are the following:
insufficient_funds_or_delinquent_credittransaction_not_permitted_to_cardholdersuspected_fraudexceeds_amount_limit
Approval Related
approved: Transaction approved normallypartial_approval: Transaction approved for a partial amountpartial_approval_for_sales_amount_only: Transaction approved for sales amount onlyavs_success_or_mobile_wallet_provisioning_yellow_path: Address verification successful or mobile wallet provisioning in yellow path. This will not be present except on authorizations to link the card to a mobile wallet.
Card Status Related
card_inactive: Card is not activerestricted_or_frozen_card: Card has been restricted or frozencard_expired_or_expiry_date_mismatch: Card is expired or expiration date doesn’t matchclosed_account: Associated account has been closedlost_and_pick_up: Card reported as loststolen_and_pick_up: Card reported as stolencapture_card: Card should be captured/retained
Security Related
security_violation: Security violation detectedsuspected_fraud: Transaction has been flagged for suspected fraud by our risk systems. We are working on surfacing additional information in the webhook events. For now, please reach out in your shared Slack channel with Bridge for more information.invalid_pin: Incorrect PIN enteredpin_count_exceeded: Too many incorrect PIN attemptsinvalid_cvv1,invalid_cvv2: One of the security codes related to cards is invalid.cannot_verify_pin: Unable to verify PIN
Limit Related
exceeds_amount_limit: Transaction amount exceeds allowed limitexceeds_count_limit: Number of transactions exceeds allowed limitmaximum_system_amount_reached: System-wide maximum amount reached
Technical Issues
format_error: Transaction format errorsystem_error: General system errorissuer_error: Error on the issuer’s sideissuer_did_not_respond_in_time: Issuer timeoutdenied_by_timeout: Transaction denied due to timeouttrack_data_format_error: Error in card track data
Account Related
insufficient_funds_or_delinquent_credit: Insufficient funds or credit issuesinvalid_pan: Invalid card numberinvalid_from_account_for_atm_balance_inquiry: Invalid account for ATM balance checkno_checking_account_found_for_an_atm_balance_inquiry: No checking account foundno_savings_account_found_for_an_atm_balance_inquiry: No savings account foundno_credit_account_found_for_an_atm_balance_inquiry: No credit account found
Transaction Type Related
mcc_blocked: Merchant category code is blockedtransaction_not_permitted_to_cardholder: Usually indicates that there was an issue while creating a transaction with the crypto wallet associated with this card.cash_service_not_permitted: Cash services not allowedsettlement_without_authorization: Settlement attempted without prior authorizationno_support_for_msi_installments_or_loan_terms_invalid: Installment or loan terms not supported
Crypto Specific
crypto_wallet_spend_not_permitted_temporarily: Temporary restriction on crypto wallet spending — this is only applicable if your funding strategy is non-custodial and creating transactions on the wallet linked to the card account is blocked for a non-balance reason, such as pending proposals on the crypto wallet.
Other
other: Catch-all for unspecified or unmapped response codes