Virtual Card Webhooks

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 for signature checks, trusted IPs, and idempotent handling. These are example webhook responses for virtual card issuing.

{
  "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"
}

{
  "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
  }
}

{
  "event": "issuing.created.failed",
  "reference": "your-create-reference"
}

{
  "event": "issuing.terminated",
  "card_id": "700865ae-af75-4b6b-b09d-1ecb16753dee",
  "amount": 120,
  "reason": "Insufficient Funds",
  "reference": "61a85f53-6e67-434d-9b6d-fa1d4c7c2f68"
}

{
  "event": "issuing.charge",
  "card_id": "32244f-3ac0-431d-9fb0-43f72505",
  "amount": 30,
  "transaction_date": "2024-12-17T09:26:42.243416144Z"
}

{
  "event": "issuing.activation",
  "card_id": "fb2f92a8-cac2-4bae-91ee-f0e7c91c409c",
  "activation_code": "866026"
}

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.

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 or create-time prefund.
WITHDRAWAL: When funds are withdrawn from the card via Withdraw from 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 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 or Get Card Transactions.
`issuing.terminated`	Mark card `TERMINATED`; expect wallet credit for remaining balance where applicable.

List transactions

Query normalized transaction history from the API

​Transaction types

​What to do on each event

List transactions

Transaction types

What to do on each event