Pay

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={({ intentId }) => markOrderPaid(intentId)}
/>

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. Fires before quoting, so no `intentId` yet
`onPaymentSuccess`	`({ sessionId, intentId }) => void`	Payment completes successfully
`onPaymentError`	`({ sessionId, intentId, error }) => void`	Payment encounters an error

intentId identifies the intent behind this flow and is what you pass to the Trails API or Trailscan to look it up. It is null for passthrough quotes. See Callback payloads.

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={({ intentId }) => {
    updateOrderStatus(orderId, "paid", intentId)
  }}
>
  <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={({ intentId }) => console.log("paid", intentId)}
/>

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={({ intentId }) => console.log("minted", intentId)}
>
  <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={({ intentId }) => markOrderPaid(intentId)}
  onPaymentError={({ error }) => console.error("failed", error)}
/>

SDK Documentation

Overview

Quick start

Props

Required

Source selection (optional)

Destination options

Shared options

Lifecycle callbacks

Examples

Stablecoin payment

Pre-select payment source

QR code / crypto transfer

Fiat on-ramp

Payment with contract execution

App branding and event handling

See also

​Overview

​Quick start

​Props

​Required

​Source selection (optional)

​Destination options

​Shared options

​Lifecycle callbacks

​Examples

​Stablecoin payment

​Pre-select payment source

​QR code / crypto transfer

​Fiat on-ramp

​Payment with contract execution

​App branding and event handling

​See also

Overview

Quick start

Props

Required

Source selection (optional)

Destination options

Shared options

Lifecycle callbacks

Examples

Stablecoin payment

Pre-select payment source

QR code / crypto transfer

Fiat on-ramp

Payment with contract execution

App branding and event handling

See also