AppKit Pay with Self-Custodial Wallets - Next.js

AppKit Pay with Self-Custodial Wallets enables end users to make crypto payments directly from non-custodial wallets. This includes mobile wallets connected via WalletConnect as well as many browser wallets, giving users full control of their assets throughout the payment process.

Quickstart

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

Projects first need to install and set up Reown AppKit before integrating AppKit Pay. If you haven’t done so, please refer to the Reown AppKit docs.

Code Example

AppKit Pay Example

Check the React example

Install the library

Projects currently using Reown AppKit, or planning to use it to build custom payment flows with self-custodial wallets, should use AppKit Pay for a streamlined integration and significantly improved user experience out of the box. AppKit Pay can be found in @reown/appkit-pay npm package.

npm

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 object
const 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

AppKit Pay with Self-Custodial Wallets supports a wide range of networks and assets. For a complete list, please refer to the Networks and Assets Supported section.

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 paymentAsset
const 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 payment hooks must be imported from @reown/appkit-pay/react. For example:

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

usePay

Handles the payment flow including opening the modal and tracking payment status.

usePay(options?: { onSuccess?: (data: PaymentResult) => void, onError?: (error: AppKitPayErrorMessage) => void }): UsePayReturn

• options: Callbacks for success and error handling.
• returns: { open, isPending, isSuccess, data, error }