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.

Card transaction events (`card.transaction`)

PayVessel also sends card.transaction to the webhook URL on your business. Use event_type to decide what to do.

`event_type`	When it fires	Suggested action
`settlement`	Spend settled on the card	Append to history; refresh card balance
`decline`	Spend declined (for example insufficient card balance)	Show the decline to your customer
`termination`	Card terminated	Mark the card terminated
`contactless_fee`	Miden billed a contactless payment fee that the card could not pay (usually insufficient balance). PayVessel debits your USD wallet instead.	Debit your customer for `amount`. `charged_from` is `merchant_wallet`.
`cross_border_fee`	Same recovery path for a cross-border / FX fee Miden could not take from the card	Debit your customer for `amount`

Contactless and cross-border fee recovery

Miden sometimes cannot collect contactless or cross-border fees from the card (the card is below the amount, or would drop under the $1 retain). They still bill PayVessel. PayVessel then:

Debits the issuing merchant USD wallet for the same fee amount
Sends you a card.transaction webhook so you can recover it from your customer

Treat reference as idempotent — the same event is not charged twice.

{
  "event": "card.transaction",
  "card_id": "7b231d95-9006-4e53-a08c-dbe3b4d3ab4d",
  "reference": "MIDEN_ISSUER_FEE_evt-contactless-1",
  "event_type": "contactless_fee",
  "status": "successful",
  "amount": "0.50",
  "currency": "USD",
  "balance_after": "1.20",
  "merchant_name": "Merchant",
  "description": "Contactless payment fee charged to merchant wallet — card had insufficient balance",
  "fee_type": "contactless_payment",
  "charged_from": "merchant_wallet",
  "reason": "insufficient_card_balance",
  "created_at": "2026-08-20T08:15:00.000000+00:00",
  "message": "Success",
  "code": "00"
}

Cross-border recovery uses event_type cross_border_fee and fee_type cross_border. If your USD wallet cannot cover the fee, status is failed. Fund the wallet and expect a retry of the same reference, or recover the amount from your customer.

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

Getting started

Use cases

API Basics

Accept Payment

Transfers

Wallets

Virtual Accounts

Issuing

Identity Verification

Value Added Services

Webhook

Virtual Card Webhooks

Transaction types

Card transaction events (`card.transaction`)

Contactless and cross-border fee recovery

What to do on each event

List transactions

​Transaction types

​Card transaction events (card.transaction)

​Contactless and cross-border fee recovery

​What to do on each event

List transactions

Transaction types

Card transaction events (`card.transaction`)

Contactless and cross-border fee recovery

What to do on each event