Pay with Self-Custodial Wallets - React

Pay with Self-Custodial Wallets lets users pay with their self-custodial wallets like MetaMask, Trust, Ledger, and more directly in-app.

Quickstart#

Here you can find a simplified process to integrate AppKit Pay:

Code Example#

Install the library#

npm install @reown/appkit-pay

There are two main ways to handle payments:

pay - Full Payment Flow#

This function handles the complete payment flow — it opens the payment UI and waits for the result (success, failure, cancel, timeout).

import { baseSepoliaETH, pay} from '@reown/appkit-pay'

In order to run the payment, use the function pay. This function receives three values: recipient, amount, and paymentAsset.

// pay function returns a PaymentResult objectconst result = await pay({     recipient: addressRecipient,    amount: 0.0001,    paymentAsset: baseSepoliaETH});if (result.success) {    console.log("Payment successful: "+ result.result);} else {    console.error("Payment error: "+ result.error);}

openPay - Open Payment UI Only#

This function opens or triggers the payment UI modal but doesn't return the result of the payment. Use the hook to handle the payment result.

import { baseSepoliaETH, openPay} from '@reown/appkit-pay'

Call the hook to open the payment modal.

    const { open: openPay, isPending, isSuccess, data, error } = usePay({      onSuccess: handleSuccess,       onError: handleError,    });

Open the payment modal, but onSuccess/onError handles the actual payment result:

      await openPay({         paymentAsset: baseSepoliaETH,        recipient: address,        amount: 1000000000000000000 // 1 ETH      });

Handle the payment result in the onSuccess/onError callbacks:

    const handleSuccess = (data: PaymentResult) => {      console.log("Payment successful:", data);    };    const handleError = (error: AppKitPayErrorMessage) => {      console.error("Payment error:", error);    };

Or handle the payment result in the UI by displaying the payment status:

    {isSuccess || isPending || error && (          <section>            <h2>Payment Status</h2>          {isSuccess && (            <p>Payment successful: {data}</p>          )}          {isPending && (            <p>Payment pending: {data}</p>          )}          {error && (            <p>Payment error: {error}</p>          )}          </section>    )}

Supported Networks and Assets#

For a complete list of supported networks and assets, please refer to the Networks and Assets Supported section in our Pay with Self-Custodial Wallets documentation.

Assets Configuration#

For the moment, AppKit Pay has pre-configured these assets:

• baseETH, baseSepoliaETH, and baseUSDC
• ethereumUSDC, optimismUSDC, arbitrumUSDC, polygonUSDC and solanaUSDC
• ethereumUSDT, optimismUSDT, arbitrumUSDT, polygonUSDT and solanaUSDT

import { baseETH } from '@reown/appkit-pay' 

For custom assets, you can create a paymentAsset object with all the information:

// Configure the paymentAssetconst paymentAssetDetails = {    network: 'eip155:8453', // Base Mainnet    asset: 'native', // Or USDC in Base: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'    metadata: {        name: 'Ethereum', // Or 'USD Coin'        symbol: 'ETH',    // Or 'USDC'        decimals: 18      // Or 6 for USDC    }};

Prerequisites#

Enable Payments Feature in Dashboard#

The "Payments" feature must be enabled in the Reown Dashboard before you can use AppKit Pay, even for local testing.

1. Go to your project in the Reown Dashboard
2. Navigate to the Payments section
3. Enable the Payments feature for your projectId

Test locally#

In order to test locally use localhost and port 3000. This is the only port available for local testing.

Add the following to your package.json file in order to run the development server on port 3000:

"scripts": {    "dev": "vite --port 3000",},

Hooks#

All the hooks must be imported from @reown/appkit-pay/react. For example:

import { useAvailableExchanges } from '@reown/appkit-pay/react';

useAvailableExchanges#

Fetches and manages the state for available exchanges.

useAvailableExchanges(options?: { isFetchOnInit?: boolean } & GetExchangesParams): UseAvailableExchangesReturn

• options: Control initial fetch behavior.
• returns: { data, isLoading, error, fetch }

type GetExchangesParams= { page?: number asset?: string amount?: number | string network?: CaipNetworkId }

usePayUrlActions#

Provides functions (getUrl, openUrl) to interact with specific exchange URLs, returning the sessionId needed for status tracking.

usePayUrlActions(): { getUrl, openUrl }

• getUrl(exchangeId, params): Promise<PayUrlResponse>
• openUrl(exchangeId, params, openInNewTab?): Promise<PayUrlResponse> (Returns { url, sessionId })

useExchangeBuyStatus#

Fetches and polls for the status of a headless payment transaction using exchangeId and sessionId.

useExchangeBuyStatus(params: UseExchangeBuyStatusParameters): UseExchangeBuyStatusReturn

• params: { exchangeId, sessionId, pollingInterval?, isEnabled?, onSuccess?, onError? }
• returns: { data, isLoading, error, refetch }