Card Notifications

Card webhook notifications inform you of events that happen and that apply to the cards of your customers. Learn how you can start receiving webhook notifications in the webhooks guide.

Weavr sendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary. the following card-related webhook notifications:

• Card Authorisations
• Card Settlements
  • Card Settlement Types
• System Balance Adjustments

Card Authorisations

Weavr informs you in real-time via webhooks when someone makes a card authorisation attempt. Weavr sendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary. the outcome of the attempt via webhooks together with the details of the purchase. You can use these notifications to notify customers in real-time that someone attempted or made a purchase using the card.

The information will be sent to you using the ${WEBHOOK_URL}/managed_cards/authorisations/watch webhook URL.

info

The ${WEBHOOK_URL} is the URL configured in your application settings.

You will receive card authorisation notifications both when the purchase is approved or rejected. You can find the outcome of the purchase authorisation in the request body of the notification in the approved field, which has a boolean value. If the purchase was rejected, the request body will also contain the declineReason field containing the reason why the purchase was rejected.

In some situations purchases can be made up of multiple card authorisations, with these confirmed via a single (or multiple) settlements. In this case, a notification is sent for every authorisation, as it happens, and the related authorisations are recorded as they accumulate, in the relatedAuthorisationIds array. Although this behaviour for card purchases is relatively less common, it can take place.

Example, a purchase is made up of three related authorisations

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 authorisation initiated earlier. You should expect to receive a settlement of a purchase after a purchase was initiated. Card authorisations 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 will be sent to you using the ${WEBHOOK_URL}/managed_cards​/settlements​/watch webhook URL.

The notification 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 will show the amount in the currency of the purchase.

In the same way as a purchase can be made up of multiple authorisations, authorisations can also be settled in multiple transactions. This can happen for single authorisations, or multiple authorisations. In the case of multiple settlements, a notification 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 authorisations, these are also specified in the notification. Although multiple settlements are a relatively less common occurrence, they do happen.

Example, two related authorisations 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 cancelling the refund.	Y
ORIGINAL_CREDIT_TRANSACTION_REVERSAL	Debits - A reversal of a previous original credit transaction, which was used to sendSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary. 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 favour.	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 favour.	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 the embedderEmbedder A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers. 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 transfersTransfer A transaction that moves funds between instruments managed by Weavr. The source and destination instruments of a transfer transaction must be owned by the same identity. Transfers can be scheduled for future execution and can be performed in bulk operations. funds from the old card to the new card.

Whenever the system performs a system balance adjustment, the transaction information will be sent to you using the ${WEBHOOK_URL}/managed_cards/adjustments/watch webhook URL.

The notification includes the following fields:

• The adjustmentAmount credited or deducted from the card
• The availableBalance of the card after the adjustment