Card Payments

Card checkout is now a widget mode, not a separate public component. Use declarative methods and default-pay-method on <tokenflight-widget>.

Should you read this?

Read this page if users can pay by card, or if your checkout offers both crypto and card tabs.

Card-only payment does not need a wallet adapter for the card path. Mixed crypto/card checkout still needs a wallet adapter for the crypto tab.

Mixed Crypto + Card

<tokenflight-widget
  api-endpoint="https://api.hyperstream.dev"
  fiat-api-endpoint="https://fiat.hyperstream.dev"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  methods='["crypto","card"]'
  theme="dark"
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';

  registerWidgetElement();
</script>

Card-Related Attributes

Attribute	Type	Default	Description
methods	string	["crypto"]	JSON array: ["crypto"], ["card"], or ["crypto","card"]
default-pay-method	string	--	Used by EXACT_INPUT swap mode to skip the picker; mixed receive/card checkout opens with the picker
fiat-currency	string	USD	Default fiat currency for card payments
fiat-api-endpoint	string	https://fiat.hyperstream.dev when omitted	Fiat API base URL

The card flow always opens the provider (e.g. Transak) in a new browser window via window.open, and the widget polls order status until the transaction settles.

Payment Modes

Crypto Only (Default)

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="50"
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';

  registerWidgetElement();
</script>

Card Only

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="50"
  methods='["card"]'
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';

  registerWidgetElement();
</script>

Both Methods

<tokenflight-widget
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
  methods='["crypto","card"]'
  theme="dark"
></tokenflight-widget>

<script type="module">
  import { registerWidgetElement } from '@tokenflight/swap/widget';

  registerWidgetElement();
</script>

Callbacks

Card and mixed-method flows use standard widget callbacks plus fiat-specific lifecycle callbacks:

Callback	Payload	Description
onFiatOrderCreated	{ orderId, widgetUrl }	Called when the card provider widget URL is ready
onFiatOrderCompleted	{ orderId, status, txHash? }	Called when a card order reaches a terminal status
onDepositSuccess	SwapSuccessData	Called on successful fixed-output crypto completion
onDepositError	SwapErrorData	Called on fixed-output crypto or card execution error
onQuoteReceived	QuoteResponse	Called when a new quote is received
onAmountChanged	AmountChangedData	Called when the user changes an editable amount
onWalletConnected	WalletConnectedData	Called on wallet connection

Next step

• Need wallet signing for the crypto tab? Read AppKit, wagmi, or ethers.
• Need payment proof? Read Backend Verification.
• Card provider popup blocked? Read Troubleshooting.