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

# Webhook Events

> Complete reference for all webhook event types

## Account Events

### us\_account.created

Triggered when a new US bank account is successfully created.

```json theme={null}
{
  "event_id": "evt_1234567895",
  "event_type": "us_account.created",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "account_id": "12345hgyd78yuyu9",
    "user_id": "12345",
    "account_status": "INACTIVE",
    "balance": 0,
    "numbers": {
      "ACH": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "RTP": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "WIRE": {
        "account_number": "0000",
        "routing_number": "021000021"
      }
    }
  }
}
```

### us\_account.ready

Triggered when a new US bank account is ready for use.

```json theme={null}
{
  "event_id": "evt_1234567895",
  "event_type": "us_account.ready",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "account_id": "12345hgyd78yuyu9",
    "user_id": "12345",
    "account_status": "ACTIVE",
    "balance": 0,
    "numbers": {
      "ACH": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "RTP": {
        "account_number": "0000",
        "routing_number": "021000021"
      },
      "WIRE": {
        "account_number": "0000",
        "routing_number": "021000021"
      }
    }
  }
}
```

***

## Funding Events

### zelle\_id.update

Triggered when a submitted zelle id validation has a new update.

```json theme={null}
{
  "event_id": "evt_1234567895",
  "event_type": "zelle_id.update",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "zelle_id": "user@example.com",
    "user_id": "12345",
    "status": "VERIFIED"
  }
}
```

### zelle.collections

Triggered when a merchant's customer funds their wallet via Zelle.

```json theme={null}
{
  "event_id": "evt_1234567895",
  "event_type": "zelle.collections",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "id": "txn_12345",
    "user_id": "12345",
    "zelle_id": "user@example.com",
    "amount": 0,
    "transaction_date": "2023-10-01T12:34:56Z"
  }
}
```

### us\_account.collections

Triggered when a merchant's customer funds their US bank account.

```json theme={null}
{
  "event_id": "evt_1234567895",
  "event_type": "us_account.collections",
  "timestamp": "2023-10-01T12:39:00Z",
  "data": {
    "id": "txn_12345",
    "user_id": "12345",
    "description": "Wallet FUnding",
    "amount": 0,
    "type": "ACH|WIRE",
    "transaction_date": "2023-10-01T12:34:56Z"
  }
}
```

***

## Card Events

### card.created

Triggered when a new virtual card is successfully created.

```json theme={null}
{
  "event_id": "evt_1234567892",
  "event_type": "card.created",
  "timestamp": "2023-10-01T12:36:00Z",
  "data": {
    "card_id": "card_12345",
    "user_id": "12345",
    "card_name": "John D. Card",
    "card_type": "Virtual",
    "card_brand": "Visa",
    "card_status": "Active",
    "card_balance": 1000,
    "currency": "USD",
    "last_four": "7890"
  }
}
```

### card.terminated

Triggered when a virtual card is terminated or deleted.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.terminated",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "card_id": "card_12345",
    "card_type": "Virtual",
    "card_brand": "Visa",
    "card_status": "Deleted",
    "balance_before_termination": 1,
    "currency": "USD",
    "last_four": "7890",
    "auth_message": "Card terminated due to multiple failed debits"
  }
}
```

### card.auth.approved

Triggered when a virtual card authorization has been successfully approved during a purchase transaction.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.approved",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Approved or completed successfully"
  }
}
```

### card.auth.settled

Triggered when a virtual card authorization has been settled successfully.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.settled",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Approved or completed successfully"
  }
}
```

### card.auth.declined

Triggered when a virtual card authorization has been declined.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.declined",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "No sufficient funds"
  }
}
```

### card.auth.reversal

Triggered when a virtual card previously authorized transaction is reversed.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.auth.reversal",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Reversal completed successfully"
  }
}
```

### card.cross-border.charge

Triggered when a virtual card is used to make a none USD payment.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.cross-border.charge",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 1.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Cross border charge for purchase @ Store Inc."
  }
}
```

### card.decline.charge

Triggered when a virtual card authorization is declined for a customer's transaction due to insufficient funds.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.decline.charge",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_id": "txn_12347",
    "card_id": "card_12345",
    "amount": 1.25,
    "availableBalance": 10,
    "currency": "USD",
    "merchant_name": "Store Inc.",
    "transaction_date": "2023-10-01T12:38:00Z",
    "description": "Purchase at Store",
    "auth_message": "Decline charge for purchase @ Store Inc."
  }
}
```

### card.topup

Triggered when a virtual card is topped up with a specified amount.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.topup",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_ref": "trf_12347",
    "card_id": "card_12345",
    "amount": 50.25,
    "oldBalance": 10.0,
    "newBalance": 60.25,
    "currency": "USD",
    "transaction_date": "2023-10-01T12:38:00Z"
  }
}
```

### card.withdrawal

Triggered when a withdrawal is made from a virtual card.

```json theme={null}
{
  "event_id": "evt_1234567893",
  "event_type": "card.withdrawal",
  "timestamp": "2023-10-01T12:37:00Z",
  "data": {
    "transaction_ref": "trf_12347",
    "card_id": "card_12345",
    "amount": 10.0,
    "oldBalance": 60.25,
    "newBalance": 50.25,
    "currency": "USD",
    "transaction_date": "2023-10-01T12:38:00Z"
  }
}
```

***

## Payments Events

### transaction.completed

Triggered when a pending/processing transaction (USD transfer, card push, or PayPal payout) completes successfully.

```json theme={null}
{
  "event_id": "evt_1234567890",
  "event_type": "transaction.completed",
  "timestamp": "2023-10-01T12:34:56Z",
  "data": {
    "transaction_id": "txn_12345",
    "transaction_type": "usd_transfer|push_to_card|paypal_payout",
    "amount": 100.5,
    "currency": "USD",
    "status": "successful",
    "account_id": "12345hgyd78yuyu9",
    "reference": "12345hgyd78yuyu9",
    "description": "Payment for services",
    "transaction_date": "2023-10-01T12:34:56Z"
  }
}
```

### transaction.failed

Triggered when a pending/processing transaction fails to process.

```json theme={null}
{
  "event_id": "evt_1234567891",
  "event_type": "transaction.failed",
  "timestamp": "2023-10-01T12:35:00Z",
  "data": {
    "transaction_id": "txn_12346",
    "transaction_type": "push_to_card",
    "amount": 50.0,
    "currency": "USD",
    "status": "failed",
    "account_id": "12345hgyd78yuyu9",
    "reference": "12345",
    "description": "Failed payment",
    "transaction_date": "2023-10-01T12:35:00Z",
    "failure_reason": "Insufficient funds"
  }
}
```

***

## Event Types Reference

| Event Type              | Description                        |
| ----------------------- | ---------------------------------- |
| `transaction.completed` | Transaction successfully processed |
| `transaction.failed`    | Transaction failed to process      |
| `card.created`          | Virtual card created               |
| `card.terminated`       | Virtual card deleted               |
| `card.transaction`      | Transaction made with virtual card |
| `account.created`       | US bank account created            |

## Handling Webhook Events

<CodeGroup>
  ```javascript Node.js theme={null}
  async function handleWebhook(event) {
    switch (event.event_type) {
      case 'transaction.completed':
        await handleTransactionCompleted(event.data);
        break;
      case 'transaction.failed':
        await handleTransactionFailed(event.data);
        break;
      case 'card.transaction':
        await handleCardTransaction(event.data);
        break;
      // Add more cases as needed
      default:
        console.log('Unhandled event type:', event.event_type);
    }
  }
  ```

  ```python Python theme={null}
  def handle_webhook(event):
      event_type = event['event_type']
      
      if event_type == 'transaction.completed':
          handle_transaction_completed(event['data'])
      elif event_type == 'transaction.failed':
          handle_transaction_failed(event['data'])
      elif event_type == 'card.transaction':
          handle_card_transaction(event['data'])
      else:
          print(f"Unhandled event type: {event_type}")
  ```

  ```php PHP theme={null}
  function handleWebhook($event) {
      switch ($event['event_type']) {
          case 'transaction.completed':
              handleTransactionCompleted($event['data']);
              break;
          case 'transaction.failed':
              handleTransactionFailed($event['data']);
              break;
          case 'card.transaction':
              handleCardTransaction($event['data']);
              break;
          default:
              error_log("Unhandled event type: " . $event['event_type']);
      }
  }
  ```
</CodeGroup>