Webhooks V2

Webhooks

The Business API provides a webhook publisher service that delivers real-time notifications to partner systems when entity state changes occur. Webhooks are delivered as HTTP POST requests to configured company webhook URLs.

Webhook Delivery

Delivery Model: Fire-and-forget HTTP POST requests with JSON payloads. No authentication headers are added to webhook requests. Partners are responsible for validating webhook origin through network-level controls or payload verification.

Timeout: 10 seconds per request. Failed deliveries are logged but not retried.

Content-Type: application/json

Webhook Endpoints

Path	Entity	Description
`/v2/webhooks/wallets`	Wallet	Wallet creation and status changes
`/v2/webhooks/balances`	Balance	Token balance updates
`/v2/webhooks/cards`	Card	Card status and data changes
`/v2/webhooks/card-limits`	Card Limit	Spending limit and usage updates
`/v2/webhooks/3ds`	3DS Confirmation	3D Secure transaction confirmations requiring user decision
`/v2/webhooks/activities`	Activity	Transaction and activity feed updates
`/v2/webhooks/recipients`	Recipient	Recipient creation and updates
`/v2/webhooks/erc-withdrawals`	ERC Withdrawal	Pending ERC20 withdrawal requests

Webhook Payloads

Wallet Webhook (`/v2/webhooks/wallets`)

Delivered when wallet state changes (creation, confirmation status).

{
  "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "wallet_name": "Main Wallet",
  "wallet_status": "Confirmed",
  "wallet_type": "Primary"
}

Field	Type	Description
`wallet_address`	string	Ethereum address of the wallet
`wallet_name`	string	Display name of the wallet
`wallet_status`	enum	`Unknown`, `Confirmed`, `Rejected`
`wallet_type`	enum	`Primary`, `Secondary`, `Global`, `Card`

Balance Webhook (`/v2/webhooks/balances`)

Delivered when token balance changes on a wallet.

{
  "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "token_symbol": "USDT",
  "token_address": "0x6b175474e89094c44da98b954eedeac495271d0f",
  "balance": 100.00056,
  "reference_balance": 100.00056,
  "reference_currency": "EUR"
}

Field	Type	Description
`wallet_address`	string	Wallet address this balance belongs to
`token_symbol`	string	Token symbol (e.g., USDT, USDC)
`token_address`	string	Contract address of the token
`balance`	float	Available token balance
`reference_balance`	float	Balance converted to reference currency
`reference_currency`	string	ISO 4217 currency code (default: EUR)

Card Webhook (`/v2/webhooks/cards`)

Delivered when card state changes (issuance, activation, blocking, status updates).

{
  "id": "00000000-0000-0000-0000-000000000001",
  "card_wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "status": "Active",
  "status_reason": "User",
  "previous_status": "NotActivated",
  "generation": "Gen2",
  "provider": "Wirex",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z",
  "card_data": {
    "name_on_card": "Alex Grey",
    "payment_system": "Visa",
    "card_number_last_4": "5678",
    "expiry_date": "01/2028",
    "format": "Virtual",
    "card_name": "MC ****5678"
  },
  "delivery_address": {
    "line1": "123 Main St",
    "line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zip_code": "94107"
  }
}

Field	Type	Description
`id`	string (UUID)	Unique card identifier
`card_wallet_address`	string	Linked wallet address
`status`	enum	`Requested`, `NotActivated`, `Active`, `Closed`, `Blocked`
`status_reason`	string	Reason for current status
`previous_status`	enum	Status before current state
`generation`	enum	`Gen1`, `Gen2`
`provider`	enum	`Wirex`, `Bridge`
`card_data`	object	Card display information
`delivery_address`	object	Physical card delivery address (optional)

Card Limit Webhook (`/v2/webhooks/card-limits`)

Delivered when card spending limits or usage changes.

{
  "card_id": "00000000-0000-0000-0000-000000000001",
  "transaction_limit": 500.00,
  "daily_limit": 1000.00,
  "daily_usage": 200.00,
  "monthly_limit": 5000.00,
  "monthly_usage": 1500.00,
  "lifetime_limit": 100000.00,
  "lifetime_usage": 25000.00
}

Field	Type	Description
`card_id`	string (UUID)	Card identifier
`owner`	address	Address of the user who owns the card
`transaction_limit`	float	Maximum single transaction amount
`daily_limit`	float	Daily spending limit
`daily_usage`	float	Amount spent today
`monthly_limit`	float	Monthly spending limit
`monthly_usage`	float	Amount spent this month
`lifetime_limit`	float	Lifetime spending limit
`lifetime_usage`	float	Total amount spent

3DS Confirmation Webhook (`/v2/webhooks/3ds`)

Delivered when a card transaction requires 3D Secure confirmation.

{
  "card_id": "00000000-0000-0000-0000-000000000001",
  "owner": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "transaction_id": "00000000000000000000000000000001",
  "merchant_name": "Amazon",
  "amount": "100.00",
  "currency": "USD",
  "card_last_4": "1234"
}

Field	Type	Description
`card_id`	string (UUID)	Card used for the transaction
`transaction_id`	string	Issuer transaction identifier
`merchant_name`	string	Merchant name
`amount`	string	Transaction amount
`currency`	string	ISO 4217 currency code
`card_last_4`	string	Last 4 digits of card number

Activity Webhook (`/v2/webhooks/activities`)

Delivered when transaction or activity state changes.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "user_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "type": "CardTransaction",
  "status": "Completed",
  "status_reason": null,
  "direction": "Outbound",
  "source": {
    "type": "Card",
    "card": {
      "id": "00000000-0000-0000-0000-000000000001",
      "pan_last": "1234",
      "payment_system": "Visa"
    }
  },
  "destination": {
    "type": "Merchant",
    "merchant": {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "Amazon"
    }
  },
  "source_amount": {
    "amount": 100.0,
    "token_symbol": "USDT",
    "token_address": "0x..."
  },
  "destination_amount": {
    "amount": 100.0,
    "currency": "USD"
  },
  "rate": {
    "ticker": "USD/USDT",
    "rate": 1.0
  },
  "created_at": "2024-01-01T00:00:00Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T00:00:00Z",
      "completed_at": "2024-01-01T00:00:01Z"
    }
  ]
}

Field	Type	Description
`id`	string (UUID)	Activity identifier
`user_address`	string	User wallet address
`type`	enum	`Deposit`, `Withdrawal`, `Exchange`, `Sepa`, `FasterPayment`, `AchPull`, `AchPush`, `Swift`, `Spei`, `CardTransaction`, `ExternalCardTransaction`, `Crypto`, `CardFeesPayment`, `YieldClaim`, `CardTransfer`
`status`	enum	`Pending`, `Completed`, `Failed`
`direction`	enum	`Inbound`, `Outbound`, `Internal`
`source`	object	Source subject (wallet, card, bank account)
`destination`	object	Destination subject (wallet, merchant, bank account)
`source_amount`	object	Amount debited from source
`destination_amount`	object	Amount credited to destination
`rate`	object	Exchange rate applied (optional)
`activity_steps`	array	Transaction processing steps

Recipient Webhook (`/v2/webhooks/recipients`)

Delivered when recipient is created or updated.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "personal_info": {
    "first_name": "Alex",
    "last_name": "Grey",
    "is_business": false
  },
  "payment_details": [
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "type": "Sepa",
      "currencies": ["EUR"],
      "sepa": {
        "iban": "DE89370400440532013000",
        "bic": "COBADEFF"
      }
    }
  ]
}

Field	Type	Description
`id`	string (UUID)	Recipient identifier
`personal_info`	object	Recipient name and type (person/business)
`payment_details`	array	Payment methods (Crypto, Sepa, FasterPayment, Ach, Swift, Spei, Card)

ERC Withdrawal Webhook (`/v2/webhooks/erc-withdrawals`)

Delivered when ERC20 withdrawal is requested and pending user signature.

{
  "account_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "token_address": "0x71C7656EC7AB88B098DEFB751B7401B5F6D8976F",
  "to_address": "0xF4D2A0E30C7983EF65DC0DD938BED82C7E3745DB",
  "amount": 100.0,
  "valid_after": "2024-01-01T00:00:00Z",
  "valid_before": "2024-01-02T00:00:00Z",
  "hash": "0x8A7B6C5D4E3F2A1B0C9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F4A3B2C1D0E9F817",
  "call_data": "3F7D9E1C5A2B804D6E93F7C1A0B5D8E29F4A3B7C6D5E0F1A2B3C4D5E6F7A8B9"
}

Field	Type	Description
`account_address`	string	Account Abstraction wallet address
`token_address`	string	ERC20 token contract address
`to_address`	string	Destination address for withdrawal
`amount`	float	Withdrawal amount
`valid_after`	string (ISO 8601)	Request validity start time
`valid_before`	string (ISO 8601)	Request expiry time
`hash`	string	Calldata and nonce hash
`call_data`	string	Encoded contract call data

Webhooks

Webhook Delivery

Webhook Endpoints

Webhook Payloads

Wallet Webhook (/v2/webhooks/wallets)

Balance Webhook (/v2/webhooks/balances)

Card Webhook (/v2/webhooks/cards)

Card Limit Webhook (/v2/webhooks/card-limits)

3DS Confirmation Webhook (/v2/webhooks/3ds)

Activity Webhook (/v2/webhooks/activities)

Recipient Webhook (/v2/webhooks/recipients)

ERC Withdrawal Webhook (/v2/webhooks/erc-withdrawals)