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

# Virtual Card Webhooks

> Virtual card API webhooks for card creation, transactions, funding, withdrawal, termination, and issuing events.

PayVessel sends webhooks when virtual cards are created, used at merchants, funded, withdrawn, or terminated. Configure your webhook URL in the PayVessel Dashboard and verify every payload before updating balances or order status in your system.

See [Verifying Webhooks](/api-reference/webhook/verifying-webhooks) for signature checks, trusted IPs, and idempotent handling.

These are example webhook responses for virtual card issuing.

<Tabs>
  <Tab title="Transaction Event">
    ```json theme={null}
    {
      "event": "issuing.transaction",
      "card_id": "7b231d95-9006-4e53-a08c-dbe3b4d3ab4d",
      "reference": "dd7412f3-aa14-4a77-94b5-a26f3cfb-56c",
      "amount": 80,
      "currency": "USD",
      "mode": "DEBIT",
      "status": "SUCCESS",
      "type": "AUTHORIZATION",
      "description": "Approved or completed successfully",
      "fee": 0,
      "settled": false,
      "merchant": {
        "city": "Lagos",
        "country": "NG",
        "name": "DLO*GOOGLE TikTok Liv"
      },
      "created_at": "2023-12-11T21:22:32.312347102Z",
      "updated_at": "2023-12-11T21:22:32.312350944Z"
    }
    ```
  </Tab>

  <Tab title="Successful Card Creation Event">
    ```json theme={null}
    {
      "event": "issuing.created.successful",
      "reference": "your-create-reference",
      "card": {
        "id": "fe796aef-5dca-47d5-a542-16d403b464d1",
        "name": "JOHN DOE",
        "masked_pan": "536898******1914",
        "type": "VIRTUAL",
        "brand": "VISA",
        "currency": "USD",
        "status": "ACTIVE",
        "balance": 0,
        "auto_approve": true
      }
    }
    ```
  </Tab>

  <Tab title="Failed Card Creation Event">
    ```json theme={null}
    {
      "event": "issuing.created.failed",
      "reference": "your-create-reference"
    }
    ```
  </Tab>

  <Tab title="Termination Event">
    ```json theme={null}
    {
      "event": "issuing.terminated",
      "card_id": "700865ae-af75-4b6b-b09d-1ecb16753dee",
      "amount": 120,
      "reason": "Insufficient Funds",
      "reference": "61a85f53-6e67-434d-9b6d-fa1d4c7c2f68"
    }
    ```
  </Tab>

  <Tab title="Card Charge Event">
    ```json theme={null}
    {
      "event": "issuing.charge",
      "card_id": "32244f-3ac0-431d-9fb0-43f72505",
      "amount": 30,
      "transaction_date": "2024-12-17T09:26:42.243416144Z"
    }
    ```
  </Tab>

  <Tab title="Activation Event">
    ```json theme={null}
    {
      "event": "issuing.activation",
      "card_id": "fb2f92a8-cac2-4bae-91ee-f0e7c91c409c",
      "activation_code": "866026"
    }
    ```
  </Tab>
</Tabs>

<Note>
  Match cards using `reference` from create (lifecycle events) or `card_id` in the payload (transaction and termination events). Store PayVessel `card_id` from the API for your own lookups.
</Note>

***

## Transaction types

These are the possible transaction types on `issuing.transaction`:

* **AUTHORIZATION**: When a card is successfully used at a merchant site.
* **SETTLEMENT**: When a card is successfully used and settlement is completed at a merchant site.
* **FUNDING**: When the card is funded via [Fund a Card](/virtual-cards/fund-card) or create-time prefund.
* **WITHDRAWAL**: When funds are withdrawn from the card via [Withdraw from Card](/virtual-cards/withdraw-card).
* **TERMINATION**: When a card is terminated (also available from the PayVessel Dashboard).
* **DECLINE**: When an attempt to use the card at a merchant site is rejected (for example insufficient balance).
* **REVERSAL**: When a merchant charges a card but immediately returns that amount to the card.
* **REFUND**: When a reversal does not complete as expected and funds erroneously debited are returned.
* **CROSS-BORDER**: Cross-border use at merchants outside the US or when authorization currency is not USD.

`mode` can only be **`CREDIT`** or **`DEBIT`**.

***

## What to do on each event

| Event                                    | Suggested action                                                                                                                                       |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issuing.created.successful`             | Mark card active; show masked PAN; poll [Get a Card](/virtual-cards/get-card) if you need full credentials.                                            |
| `issuing.created.failed`                 | Mark card `FAILED`; surface error to customer or retry create.                                                                                         |
| `issuing.transaction` / `issuing.charge` | Append to transaction history; refresh balance via [Get a Card](/virtual-cards/get-card) or [Get Card Transactions](/virtual-cards/list-transactions). |
| `issuing.terminated`                     | Mark card `TERMINATED`; expect wallet credit for remaining balance where applicable.                                                                   |

<Card title="List transactions" icon="list" href="/virtual-cards/list-transactions">
  Query normalized transaction history from the API
</Card>