Pay

Accept exact-output payments with the focused Pay component

Overview

Pay mode implements exact-output payment flows where you specify the precise amount the recipient receives. The user pays whatever is required from their available tokens across all chains.

Trade type: EXACT_OUTPUT — fixed destination amount, variable input amount.

Quick start

import { Pay } from '0xtrails/widget'

<Pay
  apiKey="YOUR_API_KEY"
  to={{
    recipient: "0xYourAddress",
    token: "USDC",
    chain: "base",
    amount: "50",
  }}
  onPaymentSuccess={({ sessionId }) => markOrderPaid(sessionId)}
/>

That is the minimum. Every other prop is optional.

Props

Required

Prop	Type	Description
apiKey	string	Trails API key
to.recipient	string	Wallet or contract address that receives the payment
to.currency	string	Token symbol or address (e.g. "USDC", "ETH")
to.chain	ChainIdentifier	Destination chain — name ("base"), chain ID, or viem Chain
to.amount	string | number	Exact amount recipient receives in human-readable units

Source selection (optional)

Pre-select where the user pays from by adding a from object. Omit to let the user choose.

<Pay
  apiKey="YOUR_API_KEY"
  to={{ recipient: "0x...", token: "USDC", chain: "base", amount: "50" }}
  from={{ token: "ETH", chain: "ethereum" }}
/>

To control the payment method, set paymentMethod:

Value	Method
"CONNECTED_WALLET"	Connected wallet (default)
"CRYPTO_TRANSFER"	QR code / address deposit
"CREDIT_DEBIT_CARD"	Fiat on-ramp
"EXCHANGE"	CEX transfer (Coinbase, Binance, etc.)

Destination options

Prop	Type	Description
to.calldata	string	ABI-encoded calldata to execute on the destination chain after payment
to.defaultChain	ChainIdentifier	Default chain — user can change
to.defaultToken	string	Default token — user can change

Shared options

All focused components share these optional props:

Prop	Type	Description
payMessage	string	Custom message shown during the payment flow
appMetadata	AppMetadata	App name, URL, and logo for wallet connection dialogs
dev	DevConfig	Debug flags and internal URL overrides
theme	"light" | "dark" | "auto"	Widget color theme
renderInline	boolean	Render inline instead of as a modal
buttonText	string	Custom CTA text
slippageTolerance	number | string	Slippage tolerance (e.g. 0.005 for 0.5%)
swapProvider	RouteProvider	Preferred same-chain swap provider
bridgeProvider	RouteProvider	Preferred bridge provider

Lifecycle callbacks

Callback	Signature	When it fires
onPaymentStart	({ sessionId }) => void	User initiates the payment flow
onPaymentSuccess	({ sessionId }) => void	Payment completes successfully
onPaymentError	({ sessionId, error }) => void	Payment encounters an error

Examples

Stablecoin payment

Accept 25 USDC on Polygon from any token on any chain:

import { Pay } from '0xtrails/widget'

<Pay
  apiKey="YOUR_API_KEY"
  to={{
    recipient: "0xYourMerchantAddress",
    token: "USDC",
    chain: "polygon",
    amount: "25",
  }}
  onPaymentSuccess={({ sessionId }) => {
    updateOrderStatus(orderId, "paid", sessionId)
  }}
>
  <button>Pay $25</button>
</Pay>

Pre-select payment source

Lock the user to pay from ETH on Ethereum:

<Pay
  apiKey="YOUR_API_KEY"
  to={{
    recipient: "0x...",
    token: "USDC",
    chain: "base",
    amount: "50",
  }}
  from={{
    token: "ETH",
    chain: "ethereum",
  }}
  onPaymentSuccess={({ sessionId }) => console.log("paid", sessionId)}
/>

QR code / crypto transfer

Let the user pay by sending to an address directly:

<Pay
  apiKey="YOUR_API_KEY"
  paymentMethod="CRYPTO_TRANSFER"
  to={{
    recipient: "0x...",
    token: "USDC",
    chain: "base",
    amount: "50",
  }}
/>

Fiat on-ramp

Let the user pay with a credit card:

<Pay
  apiKey="YOUR_API_KEY"
  paymentMethod="CREDIT_DEBIT_CARD"
  to={{
    recipient: "0x...",
    token: "USDC",
    chain: "base",
    amount: "50",
  }}
/>

Payment with contract execution

Execute a function on the destination chain with the payment:

import { Pay } from '0xtrails/widget'
import { encodeFunctionData } from 'viem'

const mintCalldata = encodeFunctionData({
  abi: [{
    name: 'mint',
    type: 'function',
    stateMutability: 'payable',
    inputs: [{ name: 'to', type: 'address' }],
    outputs: [],
  }],
  functionName: 'mint',
  args: ['0xRecipientAddress'],
})

<Pay
  apiKey="YOUR_API_KEY"
  to={{
    recipient: "0xNFT_CONTRACT",
    token: "ETH",
    chain: "arbitrum",
    amount: "0.00002",
    calldata: mintCalldata,
  }}
  onPaymentSuccess={({ sessionId }) => console.log("minted", sessionId)}
>
  <button>Mint NFT</button>
</Pay>

App branding and event handling

<Pay
  apiKey="YOUR_API_KEY"
  to={{
    recipient: "0x...",
    token: "USDC",
    chain: "base",
    amount: "50",
  }}
  payMessage="Payment for Order #4821"
  appMetadata={{
    name: "My Store",
    url: "https://mystore.com",
    imageUrl: "https://mystore.com/logo.png",
  }}
  onPaymentStart={({ sessionId }) => console.log("started", sessionId)}
  onPaymentSuccess={({ sessionId }) => markOrderPaid(sessionId)}
  onPaymentError={({ error }) => console.error("failed", error)}
/>

See also

• Pay use cases — merchant integration, NFT purchases, x402
• Configuration reference — full prop list
• Quote providers — CCTP, Relay, and more