Card webhook events
Card webhook events inform you of activity on the cards of your customers. Learn how to start receiving webhooks in the webhooks guide.
We send the following card-related webhook events:
Card authorizations
We inform you in real-time via webhooks when someone makes a card authorization attempt. We send the outcome of the attempt via webhooks together with the details of the purchase. You can use these webhooks to notify customers in real-time that someone attempted or made a purchase using the card.
The information is sent to you using the ${WEBHOOK_URL}/managed_cards/authorisations/watch webhook URL.
The ${WEBHOOK_URL} is the URL configured in your application settings.
You receive card authorization webhooks both when the purchase is approved or rejected. You can find the outcome of the purchase authorization in the request body in the approved field, which has a boolean value. If the purchase was rejected, the request body also contains the declineReason field with the reason why the purchase was rejected.
In some situations purchases can be made up of multiple card authorizations, with these confirmed via a single (or multiple) settlements. In this case, a webhook is sent for every authorization, as it happens, and the related authorizations are recorded as they accumulate, in the relatedAuthorisationIds array. Although this behavior for card purchases is relatively less common, it can take place.
Example, a purchase is made up of three related authorizations
Auth1 id : 111901064818982920, relatedAuthorisationIds : [ ]
Auth2 id : 111901066454368264, relatedAuthorisationIds : [111901064818982920]
Auth3 id : 111901066927210504, relatedAuthorisationIds : [111901064818982920, 111901066454368264]
Card settlements
In most cases, a card settlement is a confirmation of a card authorization initiated earlier. You should expect to receive a settlement of a purchase after a purchase was initiated. Card authorizations can take up to 30 days to be settled, but in most cases you receive a settlement transaction in just a few hours.
The settlement information is sent to you using the ${WEBHOOK_URL}/managed_cards/settlements/watch webhook URL.
The webhook includes the following fields:
- The
transactionAmount, which is the amount that has been deducted from the card - The
sourceAmount, which is the original purchase amount; if the card was used to make a purchase in a currency that is different than the card's currency, this field shows the amount in the currency of the purchase.
In the same way as a purchase can be made up of multiple authorizations, authorizations can also be settled in multiple transactions. This can happen for single authorizations, or multiple authorizations. In the case of multiple settlements, a webhook is sent for every settlement, as it happens, and the related settlements are recorded as they accumulate, in the relatedSettlementIds array. If a settlement is made up of multiple authorizations, these are also specified in the webhook. Although multiple settlements are a relatively less common occurrence, they do happen.
Example, two related authorizations are settled in multiple transactions
Settlement1 id : 111901069025607688, relatedSettlementIds : [ ], relatedAuthorisationIds : [111901064818982920, 111901066454368264]
Settlement2 id : 111901069336772616, relatedSettlementIds : [111901069025607688], relatedAuthorisationIds : [111901064818982920, 111901066454368264]
Settlement3 id : 111901069647872008, relatedSettlementIds : [111901069025607688, 111901069336772616], relatedAuthorisationIds : [111901064818982920, 111901066454368264]
Card settlement types
This is a list of settlement types, indicating which ones are supported by our system and for which you can expect webhook.
| Value | Meaning | Supported |
|---|---|---|
| SALE_PURCHASE | Debits (goods and services)- A cardholder used their card to purchase goods or services, and the merchant received payment. | Y |
| CASH_WITHDRAWAL | Debits - A cardholder withdraws cash through an ATM. | Y |
| SALE_WITH_CASHBACK | Debits (goods with cash back)- A cardholder makes a purchase and receives cash back at the point of sale (e.g., during a purchase at a store). | Y (UK only) |
| ACCOUNT_FUNDING | Credits - Funds transferred to Account | N |
| MAIL_OR_TELEPHONE_ORDER | Debits - A cardholder places an order by mail or over the phone. | Y |
| PURCHASE_REFUND_REVERSAL | Debits - A reversal of a refund that was processed for a previous purchase, effectively canceling the refund. | Y |
| ORIGINAL_CREDIT_TRANSACTION_REVERSAL | Debits - A reversal of a previous original credit transaction, which was used to send money to the cardholder. | Y |
| CASH_WITHDRAWAL_REVERSAL | Credits - A reversal of a previously processed cash withdrawal, returning the funds to the managed accountManaged Account An account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr.. | Y |
| PURCHASE_REFUND | Credits - A transaction where a merchant refunds a cardholder for a purchase. | Y |
| PURCHASE_REVERSAL | Credits - A reversal of a purchase transaction, typically done when there is a problem with the original transaction. | Y |
| ORIGINAL_CREDIT_TRANSACTION | Credits - A transaction where funds are credited directly to a cardholder’s account, such as a refund or a payment from the merchant. | Y |
| FIRST_CHARGEBACK | Credits - A dispute initiated by the cardholder or their bank to reverse a transaction. | N |
| FIRST_CHARGEBACK_REVERSAL | Debits - A reversal of the first chargeback, where the original transaction is reinstated, often after the dispute is resolved in the merchant's favor. | N |
| FIRST_REPRESENTMENT | Debits - The merchant’s attempt to dispute a chargeback and represent the transaction to the cardholder’s bank. | N |
| FIRST_REPRESENTMENT_REVERSAL | Credits -A reversal of the first representment, typically when the merchant's challenge is unsuccessful and the chargeback stands. | N |
| SECOND_CHARGEBACK | Credits - A second chargeback in a series, typically occurring when a transaction is disputed again after the first chargeback. | N |
| SECOND_CHARGEBACK_REVERSAL | Debits - A reversal of the second chargeback, reinstating the original transaction after the dispute is resolved in the merchant's favor. | N |
| SECOND_REPRESENTMENT | Debits - The merchant’s second attempt to dispute a chargeback. | N |
| ARBITRATION_CHARGEBACK | A final dispute resolution process involving the card network, where the merchant and cardholder's bank cannot agree on a chargeback, and the network makes a decision. | N |
| BALANCE_INQUIRY | A transaction where the cardholder checks the available balance on their account, often at an ATM or your app. | N |
System balance adjustments
In some situations, the system updates the balance of the card. This means that the system either deducts funds or credits them to the card. For example, when you replace a lost or stolen physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. with a new one, the system automatically transfers funds from the old card to the new card.
Whenever the system performs a system balance adjustment, the transaction information is sent to you using the ${WEBHOOK_URL}/managed_cards/adjustments/watch webhook URL.
The webhook includes the following fields:
- The
adjustmentAmountcredited or deducted from the card - The
availableBalanceof the card after the adjustment