# Webhook events

## Webhook authentication

We've taken some steps to secure webhook communications, so you can always verify that a webhook event came from us and not from a malicious party.

Below are the steps you need to follow to verify that a webhook event came from Bridgecard.

STEP 1:  Access your webhook secret from your dashboard (live\_webhook\_secret\_key or test\_webhook\_secret\_key depending on the environment)

<figure><img src="https://content.gitbook.com/content/qI17YRyYeAeRUYVag72N/blobs/7F99QvAJ1zm0l7IOmK0v/Screenshot%202023-05-15%20at%2013.11.46.png" alt=""><figcaption></figcaption></figure>

STEP 2:  Whenever you get a webhook event from Bridgecard, extract the x-webhook-signature header and decrypt it using your secret key (live\_secret\_key / test\_secret\_key depending on the environment)

{% tabs %}
{% tab title="Python" %}

```
$ pip install aes-everywhere

from AesEverywhere import aes256

# decryption
decrypted = aes256.decrypt('x-webhook-signature value', 'Bridgecard Secret Key')
decrypted = decrypted.decode()
print(decrypted)
```

{% endtab %}

{% tab title="NodeJS" %}

```
$ npm install aes-everywhere

var AES256  = require('aes-everywhere');
// or
// import AES256 from 'aes-everywhere';

// decryption
var decrypted = AES256.decrypt('webhook secret', 'Bridgecard Secret Key')
console.log(decrypted);
```

{% endtab %}

{% tab title="PHP" %}

```
$ composer require mervick/aes-everywhere

require '../../vendor/mervick/aes-everywhere/php/src/AES256.php';
use mervick\aesEverywhere\AES256;

$decrypt = AES256::decrypt('webhook secret', 'Bridgecard Secret Key')
```

{% endtab %}

{% tab title="Go" %}

```
import "github.com/mervick/aes-everywhere/go/aes256"

// decryption
decrypted := aes256.Decrypt("webhook secret", "Bridgecard Secret Key")
```

{% endtab %}
{% endtabs %}

STEP 3: Compare the decrypted string with your webhook secret key from STEP 1. If they are the same, then it is a valid webhook event sent from us.

## All webhook events

These are the list of webhook events triggered when you communicate with our APIs.

### cardholder\_verification.successful

This webhook event is sent when a user has passed the ID verification process

```
{
    "event": "cardholder_verification.successful",
    "data" : {
        "cardholder_id": "859505050505",
        "is_active": true, 
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke"
    }
}
```

### cardholder\_verification.failed

This webhook event is sent when a user has failed the ID verification process

```
{
    "event": "cardholder_verification.failed",
    "data" : {
        "cardholder_id": "859505050505",
        "is_active": true, 
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "error_description": "the user passed an invalid ID number"
    }
}
```

### card\_creation\_event.successful

We send this webhook event when a card is successfully created

```
{
    "event": "card_creation_event.successful",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True
        "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"}
    }
}
```

### card\_creation\_event.failed

This webhook event is sent when we can't complete your request to create a card.

```
{
    "event": "card_creation_event.failed",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True,
        "reason": "The user failed our second stage KYC verification for fraud detection, please contact admin."
    }
}
```

### card\_credit\_event.successful

We send this webhook event when a successful credit transaction happens on a USD card.

```
{
    "event": "card_credit_event.successful",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "amount": "100",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "CREDIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645",
        "settled_available_balance":"500",
        "settled_book_balance":"400"
    }
}
```

### card\_credit\_event.failed

We send this webhook event when a card funding transaction fails on a USD card.

```
{
    "event": "card_credit_event.failed",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "amount": "100",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "CREDIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}
```

### card\_unload\_event.successful

You get this webhook event when an unload transaction is successful on a USD card.

```
{
    "event": "card_unload_event.successful",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "amount": "100",
        "description": "Virtual dollar card unloading",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "DEBIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}
```

### card\_unload\_event.failed

You get this webhook event when an unload transaction on a USD card fails.

```
{
    "event": "card_unload_event.failed",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "amount": "100",
        "description": "Virtual dollar card unloading",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "DEBIT",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645"
    }
}
```

### card\_debit\_event.successful

You get this webhook event when a debit transaction happens on a USD card.

```
{
    "event": "card_debit_event.successful",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "amount": "100",
        "description": "Amazon US",
        "currency": "USD",
        "transaction_reference":"859505050505",
        "livemode": false, 
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "card_transaction_type": "DEBIT",
        "merchant_category_code": "12345 can be None",
        "transaction_date": "2022-09-28 23:10:45",
        "transaction_timestamp": "1664406645",
        "settled_available_balance":"500",
        "settled_book_balance":"400"
    }
}
```

### card\_debit\_event.declined

We send this webhook event whenever there's a declined transaction on the user's USD card.

```
{
  "data": {
    "amount": "100",
    "card_id": "06246484994004040404efcf",
    "cardholder_id": "06246484994004040404efcf",
    "currency": "USD",
    "decline_reason": "Transaction is not permitted. Please confirm that the billing address you're using is 256 Chapman Road STE 105-4, Newark, 19702, Delaware (DE) and try again. Also confirm from support if our cards work on this platform.",
    "description": "APPLE ECOM FBILL APPLE ECOM FBILL         866 D712 D7753",
    "issuing_app_id": "5b29cbe5b29cbe5b29cbe5b29cbe5b29cbe",
    "livemode": true,
    "transaction_date": "2024-02-27 19:54:51",
    "transaction_reference": "3cdee95e5e0c883cdee95e5e0c883cdee95e5e0c883cdee95e5e0c88",
    "transaction_timestamp": "1709063691"
  },
  "event": "card_debit_event.declined"
}
```

### card\_declined\_transaction\_fee\_charge\_event.successful(Deprecated)

We send this webhook event when the declined transaction fee on a user's card has been charged.

```
{
   
   'event': 'card_declined_transaction_fee_charge_event.successful, 
   'data': {
       'card_id': '8eedfssfee443rffd1cb5e', 
       'cardholder_id': 'bfgg8eedfssfee443rffd1cb5e', 
       'currency': 'USD', 
       'amount': '30',
       'transaction_date': '2021-11-15 17:13:19', 
       'transaction_timestamp': '1636996399',
       'transaction_reference': '859505050505',
       'livemode': True, 
       'issuing_app_id': 'c6424f3c-1708-4386-9406-b20da7f4d6b9',
       'transaction_date': '2022-09-28 23:10:45',
       'transaction_timestamp': '1664406645',
       'card_transaction_type': 'DEBIT'
    }

}
```

### card\_reversal\_event.successful

This webhook event is triggered whenever a user USD card gets a reversal from a merchant that they previously got debited from.&#x20;

```
{
  "event": "card_reversal_event.successful",
  "data": {
    "card_id": "a303fb8b7a0e476fbc910671ca952b74",
    "cardholder_id": "9b78a44ccdf848fd860f75fd5c117d9d",
    "amount": "100",
    "currency": "USD",
    "transaction_reference": "22597F3D-A7A5-4C9B-B9DF-B7D918EE8241_REVERSAL",
    "transaction_date": "2022-09-28 23:10:45",
    "transaction_timestamp": "1664406645",
    "livemode": true,
    "issuing_app_id": "c6424f3c-1708-4386-9406-b20da7f4d6b9",
    "card_transaction_type": "CREDIT"
  }
}
```

### card\_delete\_event.notification

This webhook event is triggered to notify a user that he doesn't have enough funds to pay the maintenance fee due in the subsequent month and his card will be automatically deleted in some days.

```
{
  "event": "card_delete_event.notification",
  "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "potential_delete_date": "2022-09-28 23:10:45",
        "livemode": True
    }
}
```

### card\_delete\_event.successful

This webhook event is triggered whenever a user's USD card gets deleted.\
Note: USD Mastercard gets deleted if a user doesn't have enough balance to pay for the next month's monthly maintenance fee.

```
{
  "event": "card_delete_event.successful",
  "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True,
        "balance": "400",
        "reason": "" // can be None.
    }
}
```

### **3d\_secure\_otp\_event.generated** \[Deprecated]

This webhook event is sent when a user attempts a transaction online and he's sent an OTP to confirm the transaction.

```
{
  "event": "3d_secure_otp_event.generated",
  "data": {
    "card_id": "86a19202202002020251i292",
    "cardholder_id": "86a19202202002020251i292",
    "otp": "430854",
    "merchant_name": "BRIDGECARD",
    "amount": "300",
    "currency": "USD",
    "last_four_digits": "4804",
    "issuing_app_id": "198286a192020251i292b01ab",
    "livemode": true,
    "transaction_date": "2023-02-02 23:49:00",
    "transaction_timestamp": "1675381740"
  }
}
```

Note:

This API is currently deprecated. To get OTP for transactions on the Mastercard kindly call the transaction history API to fetch the OTP for that current transaction.

Here is a sample. In this example, the OTP required for FACEBOOK is CB966S3VM2

<figure><img src="https://content.gitbook.com/content/qI17YRyYeAeRUYVag72N/blobs/zVB3jZYXlPmqKTy5KmIl/WhatsApp%20Image%202023-11-02%20at%2011.35.44.jpeg" alt="" width="563"><figcaption></figcaption></figure>

### **card\_maintenance\_fee\_debit\_event.successful**

We send this webhook event whenever when we deduct the monthly card maintenance fee from the card.

```
{
  "event": "card_maintenance_fee_debit_event.successful",
  "data": {
    "card_id": "38f155a93148",
    "cardholder_id": "08ceb6a9",
    "amount": "100",
    "currency": "USD",
    "transaction_date": "2023-04-30 11:21:18",
    "transaction_timestamp": "1682853678",
    "livemode": true,
    "issuing_app_id": "e9ab",
    "card_transaction_type": "DEBIT"
  }
}
```

### card\_freezed\_due\_to\_30\_days\_inactivity\_event.successful

This webhook event is sent when a user's card has been blocked because he hasn't done any transactions in the last 30 days.

```
{
  "event": "card_freezed_due_to_30_days_inactivity_event.successful",
  "data": {
    "card_id": "38f155a9314838f155a93148",
    "cardholder_id": "08ceb6a908ceb6a908ceb6a9",
    "livemode": true,
    "issuing_app_id": "e9ab08ceb6a908ceb6a908ceb6a9",
    "block_reason": "The user has not made any transactions in the last 30 days."
  }
}
```

### card\_flagged\_due\_to\_suspiscion\_of\_fraud.activated

This webhook event is sent when a user's card has been blocked due to suspicion of fraudulent activity. We'll have to manually review this case and make a final decision, you can reach out to support in this case.&#x20;

```
{
  "event": "card_flagged_due_to_suspiscion_of_fraud.activated",
  "data": {
    "card_id": "38f155a9314838f155a93148",
    "cardholder_id": "08ceb6a908ceb6a908ceb6a9",
    "livemode": true,
    "issuing_app_id": "e9ab08ceb6a908ceb6a908ceb6a9",
    "reason": "This card has been flagged due to suspicion of fraudulent transactions."
  }
}
```

### naira\_card\_credit\_event.successful

We send this webhook event when a successful credit transaction happens on a Naira card.

```

{   
   "event":"naira_card_credit_event.successful",
   "data":{
      "card_id":"1104776035",
      "transaction_reference":"190220249992843051",
      "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840",
      "currency":"NGN",
      "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab",
      "livemode":false,
      "amount":"500",
      "transaction_reference": "57b314d57aab3016ff9d57b314d57aa",
      "transaction_type":"CREDIT",
      "transaction_date": "2022-09-28 23:10:45",
      "transaction_timestamp": "1664406645"
   }
}
```

### naira\_card\_credit\_event.failed

We send this webhook event when a credit transaction fails on a Naira card.

```

{   
   "event":"naira_card_credit_event.failed",
   "data":{
      "card_id":"1104776035",
      "transaction_reference":"190220249992843051",
      "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840",
      "currency":"NGN",
      "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab",
      "livemode":false,
      "amount":"500",
      "transaction_reference": "57b314d57aab3016ff9d57b314d57aa",
      "transaction_type":"CREDIT",
      "transaction_date": "2022-09-28 23:10:45",
      "transaction_timestamp": "1664406645"
   }
}
```

### naira\_card\_unload\_event.successful

You get this webhook event when an unload transaction is successful on a Naira card.

```
{
   "event":"naira_card_unload_event.successful",
   "data":{
      "card_id":"1104776035",
      "transaction_reference":"190220249992843051",
      "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840",
      "currency":"NGN",
      "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab",
      "livemode":false,
      "amount":"500",
      "transaction_reference": "57b314d57aab3016ff9d57b314d57aa",
      "transaction_type":"DEBIT",
      "transaction_date": "2022-09-28 23:10:45",
      "transaction_timestamp": "1664406645"
   }
}
```

### naira\_card\_unload\_event.failed

You get this webhook event when an unload transaction failed on a Naira card.

```
{
   "event":"naira_card_unload_event.failed",
   "data":{
      "card_id":"1104776035",
      "transaction_reference":"190220249992843051",
      "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840",
      "currency":"NGN",
      "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab",
      "livemode":false,
      "amount":"500",
      "transaction_reference": "57b314d57aab3016ff9d57b314d57aa",
      "transaction_type":"DEBIT",
      "transaction_date": "2022-09-28 23:10:45",
      "transaction_timestamp": "1664406645"
   }
}
```

### naira\_card\_debit\_event.successful

You get this webhook event when an debit transaction is successful on a Naira card.

```
{
   "event":"naira_card_debit_event.successful",
   "data":{
      "cardholder_id":"30429e8efce74ad3a0b2df8bf9189136",
      "amount":"57272",
      "currency":"NGN",
      "is_successful":true,
      "transaction_type":"DEBIT",
      "transaction_reference":"0603202499930495",
      "issuing_app_id":"ef4ad945-e99b-4507-8609-709b144f77d4",
      "livemode":false,
      "description":"POINT OF SALE PURCHASE TRANSACTION POS@<99999999> <284118000200925> <APPLE.COM/BILL \\xa0 \\xa0 \\xa0 \\xa0 ITUNES.COM \\xa0 \\xa0 IE> <520360/129268> ",
      "transaction_timestamp":1709688060,
      "is_card":true,
      "transaction_date":"2024-03-06 02:21:00",
      "enriched_transaction":{
         "transaction_category":"Media",
         "transaction_group":"Non-Essential Expenses",
         "merchant_name":"Apple",
         "merchant_logo":"https://logos.ntropy.com/apple.com",
         "merchant_website":"apple.com",
         "merchant_city":"None",
         "is_recurring":true,
         "merchant_code":"None"
      }
   }
}
```

### naira\_card\_debit\_event.declined

You get this webhook event when a debit transaction is declined on a Naira card.

```
{
   "event":"naira_card_debit_event.declined",
   "data":{
      "cardholder_id":"30429e8efce74ad3a0b2df8bf9189136",
      "amount":"57272",
      "currency":"NGN",
      "is_successful":true,
      "transaction_type":"DEBIT",
      "transaction_reference":"0603202499930495",
      "issuing_app_id":"ef4ad945-e99b-4507-8609-709b144f77d4",
      "livemode":false,
      "description":"POINT OF SALE PURCHASE TRANSACTION POS@<99999999> <284118000200925> <APPLE.COM/BILL \\xa0 \\xa0 \\xa0 \\xa0 ITUNES.COM \\xa0 \\xa0 IE> <520360/129268> ",
      "transaction_timestamp":1709688060,
      "is_card":true,
      "transaction_date":"2024-03-06 02:21:00",
      "enriched_transaction":{
         "transaction_category":"Media",
         "transaction_group":"Non-Essential Expenses",
         "merchant_name":"Apple",
         "merchant_logo":"https://logos.ntropy.com/apple.com",
         "merchant_website":"apple.com",
         "merchant_city":"None",
         "is_recurring":true,
         "merchant_code":"None"
      }
   }
}
```

### naira\_account\_credit\_event.successful

This webhook event is sent when a user's naira account is credited

```
{
    'event': 'naira_account_credit_event.successful',
      'data': {
            'transaction_reference': '100720239194959', 
            'cardholder_id': '019349be694f4daea1a9b04c0', 
            'currency': 'NGN', 
            'issuing_app_id': 'e98260dc-sdfdsf-wewcw2-8b6c-4704a89b01ab', 
            'livemode': False, 
            'amount': '995000',
            'description': 'VPS TRANSFERS TRANSFER FROM JOHN DOE TO BRIDGECARD(Bridgecard) 99**92 Wallet fund ', 
            'transaction_type': 'CREDIT'
            }
}
```

### naira\_account\_transfer\_event.successful

This webhook event is sent when a user's naira account debit transaction is successful

```
{
    "event":"naira_account_transfer_event.successful", 
    "data":{
        "cardholder_id": "48499494",
        "amount": "995000",
        "currency":"NGN", 
        "is_successful": true,
        "transaction_type": "DEBIT",
        "recipient_account_number":"5403200440", 
        "recipient_bank_code":"0184",
        "transaction_reference":"100343243439991194959", 
        "livemode": true,
        "issuing_app_id":"e982-4fa8-8b6c-47b01ab",
        }
}
```

### naira\_account\_transfer\_event.failed

This webhook event is sent when a user's naira account debit transaction fails

```
{
    "event":"naira_account_transfer_event.failed", 
    "data":{
        "cardholder_id": "48499494",
        "amount": "995000",
        "currency":"NGN", 
        "is_successful": true,
        "transaction_type": "DEBIT",
        "recipient_account_number":"5403200440", 
        "recipient_bank_code":"0184",
        "transaction_reference":"100343243439991194959", 
        "livemode": true,
        "issuing_app_id":"e982-4fa8-8b6c-47b01ab",
        }
}
```

### rewards\_event.claimed

This webhook event is sent when a user claims a reward via the rewards service.

```
{
    "event": "rewards_event.claimed",
    "data": {
        "coupon_code": "25FY1SL4O9DI",
        "created_on": "19/08/2023",
        "description": "Women Leggings Black White",
        "downvotes": 0,
        "is_available": true,
        "merchant": "Aliexpress",
        "reward_id": "JDDDNDNDNDND",
        "reward_type": "PROMO_CODE",
        "success_record": 0,
        "upvotes": 0,
        "valid_till": 1694818799,
        "valid_till_date": "15/09/2023",
        "cardholder_id": "48499494",
    },
}

```

### card\_migration\_event.successful (Deprecated)

We send this webhook event when a card is successfully migrated

```
{
    "event": "card_migration_event.successful",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True
    }
}
```

### cardholder\_verification.manual\_review

This webhook event is sent when a cardholder KYC fails and is subject to manual review within 24 hours.

```
{
    "event": "cardholder_verification.manual_review",
    "data" : {
        "cardholder_id": "859505050505",
        "is_active": False,
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True,
    }
}
```

### card\_migration\_event.failed (Deprecated)

This webhook event is sent when we can't complete your request to migrate a card.

```
{
    "event": "card_creation_event.failed",
    "data" : {
        "card_id": "859505050505",
        "cardholder_id": "859505050505",
        "currency": "USD",
        "issuing_app_id": "9ujinoncpsni3943198393939930ke",
        "livemode": True,
        "reason": "You don't have sufficient funds to create a card with this limit, you need to fund with up to $3 to create a card with a $5,000 limit and up to $4 for a card with $10,000 limit."
    }
}
```

### Issuing\_account\_topup.successful

This webhook is sent after a successful top-up on your issuing wallet.

```
{
            "environment": “production”,
            "issuing_app_id": “9ujinoncpsni3943198393939930ke”,
            "data": {
                "event": "issuing_account_topup.successful",
                "data": {
                    "amount_topped_up_in_cents": 200
                },
            },
        }
```

### card\_negative\_balance\_event.notification

This webhook is sent when a card recieves a transaction update and the card balance goes into negative. Imagine your card has only a $10 balance. If you book an Uber ride with an estimated cost of $10, the ride cost is authorized and debited from your card right away. However, if an unforeseen event, like an accident, extends the ride and the cost increases to $15, the final amount will be adjusted during the settlement stage (typically within 0-3 days). In this case, the transaction amount will update to $15, resulting in a $5 negative balance on your card. Uber reserves the right to apply this negative balance to the card.

```
{
  "event": "card_negative_balance_event.notification",
  "data": {
    "card_id": "637387383939ee3003838033",
    "cardholder_id": "637387383939ee3003838033",
    "currency": "USD",
    "issuing_app_id": "637387383939ee3003838033",
    "livemode": true,
    "merchant_name": "FACEBK *HDB9XEQ9S2 Dublin "
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bridgecard.co/reference/api-reference/webhook-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.