> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saalal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Lorsque des événements se produisent sur nos systèmes, vous serez notifiés sur vos urls ipn.

## Webhook List

Il est nécessaire de vérifier que les événements proviennent bien de ALAL afin d'éviter de créer des transactions dues à un événement frauduleux.

Pour vérifier les événements, validez l'en-tête x-alal-signature envoyé avec l'événement. La signature HMAC SHA512 est la charge utile `payload` de l'événement signée avec votre clé secrète `ALAL_API_KEY`.

<CodeGroup>
  ```javascript Javascript theme={null}
  const crypto = require('crypto');
  const webhookSecret = process.env.ALAL_API_KEY;
  // Using Express
  app.post("/webhook_url", function(req, res) {
  //validate event
  const hash = crypto.createHmac('sha512', webhookSecret).update(JSON.stringify(req.body)).digest('hex');
  if (hash == req.headers['x-alal-signature']) {
  // Retrieve the request's body
  const event = req.body;
  // Do something with event  
  }
  res.send(200);
  });
  ```

  ```python Python theme={null}
  import hmac
  from hashlib import sha512

  def webhook_verification(request):
  secret = os.environ.get("ALAL_API_KEY")
  signature = request.headers.get('x-alal-signature')
  computed_sig = hmac.new(
  key=webhook_secret.encode("utf-8"), msg=request.body, digestmod=sha512
  ).hexdigest()
  #Bitnob generated events will return True
  return signature == computed_sig

  ```

  ```php PHP theme={null}
  $webhookSecret = env('ALAL_API_KEY');
  $data = json_encode($_POST);
  $hash = hash_hmac('sha512', $data, $webhookSecret);
  if ($hash == $_SERVER['x-alal-signature']) {
  // Do something with event
  }
  ```
</CodeGroup>

## Card Users Events

### CardUser Verification Successful

```json theme={null}
{
  "event": "card_user_verification.successful",
  "data": {
    "reference": "88c2f29c-2fba-40f1-a303-b33008e42fe9",
    "first_name": "Testeur",
    "last_name": "glock",
    "address": "Pikine Texaco 11",
    "id_no": "17521999133211635",
    "phone": "221776854872",
    "email": "testingboy@gmail.com",
    "status": "passed"
  }
}
```

### CardUser Verification Failed

```json theme={null}
{
  "event": "card_user_verification.failed",
  "data": {
    "reference": "88c2f29c-2fba-40f1-a303-b33008e42fe9",
    "first_name": "Testeur",
    "last_name": "glock",
    "address": "Pikine Texaco 11",
    "id_no": "17521999133211635",
    "phone": "221776854872",
    "email": "testingboy@gmail.com",
    "status": "failed"
  }
}
```

## Cards Events

### Card Creation Successful

```json theme={null}
{
  "event": "card_creation.successful",
  "data": {
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_number": "4634716555196705",
    "card_brand": "Visa",
    "card_type": "virtual",
    "cvv2": "363",
    "expiry": "2027-06",
    "balance": "0",
    "status": "issued"
  }
}
```

### Card Creation Failed

```json theme={null}
{
  "event": "card_creation.failed",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "virtual",
    "last_four": "XXXX",
    "balance": "0",
    "status": "unissued",
    "created_at": "2024-01-25"
  }
}
```

### Card Link Successful

```json theme={null}
{
  "event": "card_link.successful",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "physical",
    "last_four": "XXXX",
    "balance": "0",
    "status": "issued",
    "created_at": "2024-01-25"
  }
}
```

### Card Link Failed

```json theme={null}
{
  "event": "card_link.failed",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "physical",
    "last_four": "XXXX",
    "balance": "0",
    "status": "issued",
    "created_at": "2024-01-25"
  }
}
```

### Card Freeze Successful

```json theme={null}
{
  "event": "card_freeze.successful",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "physical",
    "last_four": "XXXX",
    "balance": "0",
    "status": "issued",
    "created_at": "2024-01-25"
  }
}
```

### Card Freeze Failed

```json theme={null}
{
  "event": "card_freeze.failed",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "physical",
    "last_four": "XXXX",
    "balance": "0",
    "status": "issued",
    "created_at": "2024-01-25"
  }
}
```

### Card Unfreeze Successful

```json theme={null}
{
  "event": "card_unfreeze.successful",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "physical",
    "last_four": "XXXX",
    "balance": "0",
    "status": "issued",
    "created_at": "2024-01-25"
  }
}
```

### Card Unfreeze Failed

```json theme={null}
{
  "event": "card_unfreeze.failed",
  "data": {
    "identifier": "02584796325414",
    "reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_user_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "card_brand": "mastercard",
    "card_type": "physical",
    "last_four": "XXXX",
    "balance": "0",
    "status": "issued",
    "created_at": "2024-01-25"
  }
}
```

## Card Transaction Events

### Recharge Successful

```json theme={null}
{
  "event": "card_recharge.successful",
  "data": {
    "reference": "b60f55b1-922a-406a-8417-g54atb0849ttb22c",
    "card_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "status": "success",
    "kind": "recharge",
    "merchant": "",
    "amount": 2000,
    "created_at": "2023-06-22T10:40:17.000000Z"
  }
}
```

### Recharge Failed

```json theme={null}
{
  "event": "card_recharge.failed",
  "data": {
    "reference": "b60f55b1-922a-406a-8417-g54atb0849ttb22c",
    "card_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "status": "failed",
    "kind": "recharge",
    "merchant": "",
    "amount": 2000,
    "created_at": "2023-06-22T10:40:17.000000Z"
  }
}
```

### Withdraw Successful

```json theme={null}
{
  "event": "card_withdraw.successful",
  "data": {
    "reference": "b60f55b1-922a-406a-8417-g54atb0849ttb22c",
    "card_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "status": "success",
    "kind": "withdraw",
    "merchant": "Netflix SA",
    "amount": 2000,
    "created_at": "2023-06-22T10:40:17.000000Z"
  }
}
```

### Withdraw Failed

```json theme={null}
{
  "event": "card_withdraw.failed",
  "data": {
    "reference": "b60f55b1-922a-406a-8417-g54atb0849ttb22c",
    "card_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "status": "failed",
    "kind": "withdraw",
    "merchant": "Netflix SA",
    "amount": 2000,
    "created_at": "2023-06-22T10:40:17.000000Z"
  }
}
```

### Reverse Successful

```json theme={null}
{
  "event": "card_reverse.successful",
  "data": {
    "reference": "b60f55b1-922a-406a-8417-g54atb0849ttb22c",
    "card_reference": "9c54515e-7890-44f9-8cc2-a85b80322b98",
    "status": "success",
    "kind": "reversed",
    "merchant": "Netflix SA",
    "amount": 2000,
    "created_at": "2023-06-22T10:40:17.000000Z"
  }
}
```

### Card Sale Successful

```json theme={null}
{
  "event": "card_sale.successful",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "success",
    "kind": "card-sale",
    "merchant": "Alal",
    "amount": 4000,
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Card To Bank Successful

```json theme={null}
{
  "event": "card_to_bank.successful",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "success",
    "kind": "card_to_bank",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "bank_name": "YOUR_BANK_NAME",
    "bank_id": "YOUR_BANK_IDENTIFIER",
    "bank_account_name": "YOUR_BANK_ACCOUNT_NAME",
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Card To Bank Failed

```json theme={null}
{
  "event": "card_to_bank.failed",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "failed",
    "kind": "card_to_bank",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "bank_name": "YOUR_BANK_NAME",
    "bank_id": "YOUR_BANK_IDENTIFIER",
    "bank_account_name": "YOUR_BANK_ACCOUNT_NAME",
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Card To Wallet Successful

```json theme={null}
{
  "event": "card_to_wallet.successful",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "success",
    "kind": "card_to_wallet",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Card To Wallet Failed

```json theme={null}
{
  "event": "card_to_wallet.failed",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "failed",
    "kind": "card_to_wallet",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Wallet to Card Successful

```json theme={null}
{
  "event": "wallet_to_card.successful",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "success",
    "kind": "wallet_to_card",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Wallet to Card Failed

```json theme={null}
{
  "event": "wallet_to_card.failed",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "failed",
    "kind": "wallet_to_card",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

### Card Transaction Cancelled

```json theme={null}
{
  "event": "card_transaction.cancelled",
  "data": {
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "card_reference": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "status": "cancelled",
    "kind": "wallet_to_card",
    "merchant": "Alal",
    "amount": 4000,
    "card_balance": 8000,
    "meta": null,
    "created_at": "2023-10-10T13:29:45.000000Z"
  }
}
```

## Business Transactions Events

### Disburse Successful

```json theme={null}
{
  "event": "disburse.successful",
  "data": {
    "business": "YOUR_BUSINESS_NAME",
    "customer": {
        "full_name":  "capone bege",
        "email":  "capone@bege.com",
        "phone": "XXXXXXXX"
    },
    "slug": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "kind": "disburse",
    "network": "orange-money-sn",
    "amount": 5000,
    "status": "success",
    "expired_at" : null,
    "meta": null
  }
}
```

### Disburse Failed

```json theme={null}
{
  "event": "disburse.failed",
  "data": {
    "business": "YOUR_BUSINESS_NAME",
    "customer": {
        "full_name":  "capone bege",
        "email":  "capone@bege.com",
        "phone": "XXXXXXXX"
    },
    "slug": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "kind": "disburse",
    "network": "orange-money-sn",
    "amount": 5000,
    "status": "failed",
    "expired_at" : null,
    "meta": null
  }
}
```

### Payment Successful

```json theme={null}
{
  "event": "payment.successful",
  "data": {
    "business": "YOUR_BUSINESS_NAME",
    "customer": {
        "full_name":  "capone bege",
        "email":  "capone@bege.com",
        "phone": "XXXXXXXX"
    },
    "slug": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "kind": "payment",
    "network": "orange-money-sn",
    "amount": 5000,
    "status": "success",
    "expired_at" : null,
    "meta": null
  }
}
```

### Payment Failed

```json theme={null}
{
  "event": "payment.failed",
  "data": {
    "business": "YOUR_BUSINESS_NAME",
    "customer": {
        "full_name":  "capone bege",
        "email":  "capone@bege.com",
        "phone": "XXXXXXXX"
    },
    "slug": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "kind": "payment",
    "network": "orange-money-sn",
    "amount": 5000,
    "status": "failed",
    "expired_at" : null,
    "meta": null
  }
}
```

### Payment Expired

```json theme={null}
{
  "event": "payment.expired",
  "data": {
    "business": "YOUR_BUSINESS_NAME",
    "customer": {
        "full_name":  "capone bege",
        "email":  "capone@bege.com",
        "phone": "XXXXXXXX"
    },
    "slug": "a7517090-79b9-4af5-8c56-861ae221ae8c",
    "reference": "222d9c54-1aa4-4a14-a099-7d6e4d80063f",
    "kind": "payment",
    "network": "orange-money-sn",
    "amount": 5000,
    "status": "expired",
    "expired_at" : "2023-10-10T13:29:45.000000Z",
    "meta": null
  }
}
```