> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trails.build/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```tsx theme={null}
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.

```tsx theme={null}
<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. Defaults to `"light"` when omitted and the user has no stored preference; pass `"auto"` to follow the OS preference |
| `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 |
| `onPaymentCreated` | `({ sessionId, settlement }) => void` | A quote armed an external payment (Stripe PaymentIntent). Fires once per payment reference, before execution; carries no `intentId` |
| `onPaymentSuccess` | `({ sessionId, intentId, settlement? }) => void` | Payment completes successfully. With a settlement armed, the widget holds success until the processor confirms settlement, and `settlement` carries the `IntentSettlement` |
| `onPaymentError` | `({ sessionId, intentId, error }) => void` | Payment encounters an error |

### Stripe checkout

Added in `0xtrails@0.19.0`. Set the `stripe` prop to charge a fiat price and settle in USDC instead of specifying `to.amount`/`to.token`:

```tsx theme={null}
<Pay
  apiKey="YOUR_API_KEY"
  to={{ recipient: "0xYourMerchantAddress" }}
  stripe={{ amountCents: 2500, orderRef: "order-123" }}
  onPaymentCreated={({ settlement }) => console.log("payment armed", settlement)}
  onPaymentSuccess={({ intentId, settlement }) => fulfillOrder(intentId, settlement)}
/>
```

`stripe` takes `TrailsStripeCheckoutProps`:

| Field | Type | Description |
| - | - | - |
| `amountCents` | `number` | Required. Price in USD cents (e.g. `500` for \$5.00). The browser declares this value under a public key — verify the settled amount and order reference server-side before fulfilling |
| `orderRef` | `string` | Merchant order label attached to the PaymentIntent metadata, and the checkout-identity key: changing it mints a fresh checkout reference. Prefer supplying it; when omitted, one checkout reference spans the prop's lifetime (set `stripe` to `undefined` between purchases on a long-lived mount) |
| `chainId` | `number` | Settlement chain. Live merchant keys accept Base (8453, default), Polygon (137) and Ethereum (1); test keys settle on Base Sepolia (84532) only. An unsupported `chainId` throws at render — validate with `getStripeSettlementChainIds()` |
| `testMode` | `boolean` | Set when the project's merchant key is a Stripe test-mode key |

The `stripe` prop is mutually exclusive with `toAddress`/`toAmount`/`toChainId`/`toToken`/`toCalldata`/`actions`/`settlement`, and forces
`mode: "pay"`. See [Stripe Onramp](https://docs.trails.build/sdk/onramp/stripe.md) and the settlement hooks under [Hooks](https://docs.trails.build/sdk/hooks.md#settlement).

`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](https://docs.trails.build/sdk/configuration.md#callback-payloads).

## Examples

### Stablecoin payment

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

```tsx theme={null}
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:

```tsx theme={null}
<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:

```tsx theme={null}
<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:

```tsx theme={null}
<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:

```tsx theme={null}
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

```tsx theme={null}
<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)}
/>
```

## See also

* [Pay use cases](https://docs.trails.build/use-cases/pay.md) — merchant integration, NFT purchases, x402
* [Configuration reference](https://docs.trails.build/sdk/configuration.md) — full prop list
* [Quote providers](https://docs.trails.build/sdk/quote-providers.md) — CCTP, Relay, and more
