Card Notifications

There are three different webhook events that are dedicated for cards.

📘

Modulr Notifications

For more information on notifications from Modulr including what webhooks are and how to use them see our page on receiving notifications.

CARDAUTH

This sends a webhook notification in the event of:

• Approved card Authorisation
• Declined card Authorisation (Reason field will specify the decline reason)
• Subsequent Decline of previously Approved Authorisation (This happens in case of the network outage. Reason field will include Timeout information and PreviousActivityStatus will specify "APPROVED")
• Authorisation Reversal (When the transaction is partially or fully reversed, _OrderId _can be used to link any reversed amount with a previously approved Authorisation)

📘

Example context for approved authorisation

{
"MCC": "6011",
"CardId": "V110000009",
"FxRate": "1.000000",
"EventId": "cfb9931a-673f-43da-8a7c-6f83d90f6297",
"OrderId": "8",
"AccountId": "A1100003",
"EventName": "CARDAUTH",
"EventTime": "2020-11-03T15:11:44+0000",
"ActivityId": "X110000008",
"AuthCode": "987654321"
"ActivityType": "AUTHORISATION",
"MerchantID": "12345678"
"MerchantName": "CASHZONE",
"BillingAmount": "100.00",
"VerifiedBy3DS": "true",
"ActivityStatus": "APPROVED",
"BillingCurrency": "GBP",
"MerchantCountry": "GBR",
"TransactionAmount": "100.00",
"ActivityCreatedDate": "2020-11-03T15:11:44+0000",
"TransactionCurrency": "GBP",
"TransactionType": "ATM",
"InputMethod": "EMV_PIN"
}

Settlements and Refunds

When card authorisations settle we will record a transaction against the account, which will trigger PAYOUT Webhook

If a transaction has been refunded we will create a credit entry on the account, which will, in turn, trigger the PAYIN Webhook

Webhooks above are universal and trigger on most payment types (not just cards)

CARDCREATION

This sends a webhook notification that informs of the outcome of a successfully submitted create physical card request. Possible results are:

• Error
• Created

This is only supported for Physical Cards.

A successful outcome will provide details of the created card including the card ID, masked PAN and provides the original task ID & external ref for the create request so that the outcome can be reconciled with the request.

📘

Example content for successful physical card creation

{
"EventName": "CARDCREATION",
"EventId": "19ba6ad4-d260-40e1-b207-d0298429649f",
"EventTime": "2020-07-02T15:15:50+0100",
"Result": "CREATED",
"CardId": "V110000059",
"TaskId": "T110000029",
"ExternalRef": "GML-testsuite-TestPhysicalCard",
"CreatedDate": "2020-07-02T15:15:50+0100",
"MaxLimit": "1000000.00",
"MaskedPAN": "556993**6520"
}

An error result will provide the original task ID & external ref so that the outcome can be reconciled with the request.

In this event all internal retry attempts have been exhausted and no card has been created. You will need to try the create physical card request again.

📘

Example content for error result

{
"EventName": "CARDCREATION",
"EventId": "4460a90a-fb70-4b5f-9aa5-3c40f5b69db2",
"EventTime": "2020-07-02T15:17:19+0100",
"Result": "ERROR",
"TaskId": "T11000002A",
"ExternalRef": "GML-testsuite-PROVIDER_FAILURE"
}

📘

Webhook retry logic. In case we cannot reach your receiving endpoint, we will retry:

1st retry - after 1 minute
2nd retry - after 5 minutes
3rd retry - after 25 minutes
4th retry - after 2 hours 5 minutes
5th retry - after 10 hours 25 minutes

CARDSTATUSUPDATE

This sends a webhook notification in the event of a card changing status, regardless of what triggered/performed the status update. This can help clients be informed of card status changes that were not initiated by their API user e.g. card status change performed via the Customer Portal, or a card status initiated by an internal Modulr process e.g. card expiry.

📘

Example content for card status update notification

{
"EventName": "CARDSTATUSUPDATE",
"EventId": "357ca9dd-6809-4876-bf41-e3b6474fa46a",
"EventTime": "2021-04-09T10:18:25+0000",
"CardId": "V11000CW2G",
"Status": "ACTIVE"
}