Skip to main content

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 sends the following card-related webhook notifications:

Card Authorisations​

Weavr informs you in real-time via webhooks when someone makes a card authorisation attempt. Weavr sends 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.

ValueMeaningSupported
SALE_PURCHASEDebits (goods and services)- A cardholder used their card to purchase goods or services, and the merchant received payment.Y
CASH_WITHDRAWALDebits - A cardholder withdraws cash through an ATM.Y
SALE_WITH_CASHBACKDebits (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_FUNDINGCredits - Funds transferred to AccountN
MAIL_OR_TELEPHONE_ORDERDebits - A cardholder places an order by mail or over the phone.Y
PURCHASE_REFUND_REVERSALDebits - A reversal of a refund that was processed for a previous purchase, effectively cancelling the refund.Y
ORIGINAL_CREDIT_TRANSACTION_REVERSALDebits - A reversal of a previous original credit transaction, which was used to send money to the cardholder.Y
CASH_WITHDRAWAL_REVERSALCredits - A reversal of a previously processed cash withdrawal, returning the funds to the managed account.Y
PURCHASE_REFUNDCredits - A transaction where a merchant refunds a cardholder for a purchase.Y
PURCHASE_REVERSALCredits - A reversal of a purchase transaction, typically done when there is a problem with the original transaction.Y
ORIGINAL_CREDIT_TRANSACTIONCredits - A transaction where funds are credited directly to a cardholder’s account, such as a refund or a payment from the merchant.Y
FIRST_CHARGEBACKCredits - A dispute initiated by the cardholder or their bank to reverse a transaction.N
FIRST_CHARGEBACK_REVERSALDebits - 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_REPRESENTMENTDebits - The merchant’s attempt to dispute a chargeback and represent the transaction to the cardholder’s bank.N
FIRST_REPRESENTMENT_REVERSALCredits -A reversal of the first representment, typically when the merchant's challenge is unsuccessful and the chargeback stands.N
SECOND_CHARGEBACKCredits - A second chargeback in a series, typically occurring when a transaction is disputed again after the first chargeback.N
SECOND_CHARGEBACK_REVERSALDebits - A reversal of the second chargeback, reinstating the original transaction after the dispute is resolved in the merchant's favour.N
SECOND_REPRESENTMENTDebits - The merchant’s second attempt to dispute a chargeback.N
ARBITRATION_CHARGEBACKA 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_INQUIRYA transaction where the cardholder checks the available balance on their account, often at an ATM or the embedder 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 card 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 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