🕒 This guide takes 60 minutes to embed a "Pay with ETH" checkout on your app.

CheckoutWithEth embeds a component on your page that accepts ETH payments on Ethereum (or Goerli).

This component also handles:

  • Connecting the payment wallet
  • Prompting the payment wallet to switch chain, if necessary
  • Informing the payment wallet they have insufficient funds

Paper requests the precise amount of funds on the correct chain for the easiest buying experience.

Competing alternatives often require the user to send funds to an arbitrary address, resulting in buyers sending insufficient funds or sending on the wrong blockchain.

Example

👍

Try a demo!

The user is prompted to connect their payment wallet. This step is skipped if they've already connected their wallet to your app since this connection is established on your domain.

The user is then prompted to review their purchase, accept the Terms of Service, and complete their payment.

📘

This SDK is available in ReactJS and JavaScript.

Integration: ReactJS

  1. Install the ReactJS SDK with your preferred package manager.
    • npm install @paperxyz/react-client-sdk-checkout-with-eth
    • yarn add @paperxyz/react-client-sdk-checkout-with-eth
  2. Copy your API key from the Developer Dashboard: Developers page.
  3. When a buyer wants to make a purchase, create a Checkout Elements Client Secret (API reference) to generate an SDK Client Secret. You will provide some buyer information and configure behavior via this API.
  4. Instantiate a PaperSDKProvider provider to store Paper-specific properties.
  5. Within the provider, instantiate the CheckoutWithEth component to render this component. Pass the SDK Client Secret to this component.

Example code

import { CheckoutWithEth } from "@paperxyz/react-client-sdk-checkout-with-eth";

<CheckoutWithEth
    sdkClientSecret="MY_SDK_CLIENT_SECRET"
    onSuccess={(result) => {
    console.log("Payment successful.");
  }}
/>

CheckoutWithEth props

NameTypeDescription
sdkClientSecret *stringThe SDK Client Scret returned from the Create Checkout Elements Client Secret API.
onSuccess *(props : { transactionResponse: TransactionResponse; transactionId: string; }) => voidThis method is called after the payment has been initiated.

This payment is pending and may still fail off-chain.
localeenum
Valid values: en, fr, es, it, de, ja, ko, zh
The language to show text in.
Defaults to en.
optionsobjectCustomize component styling. See Customization.
receivingWalletTypeenum
Valid values:
- WalletConnect
- MetaMask
- Coinbase Wallet
- Phantom
- Preset
Defaults to Preset.

The wallet type of the user wallet receiving the NFT to render the appropriate wallet icon in the component.
suppressErrorToastbooleanDefaults to false.

If false, there will be a toast (within the iFrame) that pops up informing the user of what went wrong.

This can include cancelling transaction, pending transactions etc.
showConnectWalletOptionsbooleanDefaults to true.

If true a connect wallet screen will be displayed allowing users to connect their wallet.
payingWalletSignerethers.SignerIf provided, the component will request funds from this signer.
onWalletConnected(props: { userAddress: string, chainId: number }) => voidThis method is called when a payment wallet is connected.
onPageChange(currentPage: CheckoutWithEthPage) => voidThis method is called when the buyer transitions between pages.
onError(error: PaperSDKError) => voidThis method is called when an error is encountered.
setUpUserPayingWalletSigner(args: { chainId: number }) => voidThis method is called before the payingWalletSigner is asked to pay with the chainId that the payingWalletSigner is supposed to be on.

Integration: JavaScript

  1. Install the JavaScript SDK with your preferred package manager.
    • npm install @paperxyz/js-client-sdk
    • yarn add @paperxyz/js-client-sdk
  2. Copy your API key from the Developer Dashboard: Developers page.
  3. When a buyer wants to make a purchase, create a Checkout Elements Client Secret (API reference) to generate an SDK Client Secret. You will provide some buyer information and configure behavior via this API.
  4. Call createCheckoutWithEthElement to insert the iframe on your page. Pass the SDK Client Secret to this component.
    1. If you don't provide elementOrId, this call returns an iframe element for you to insert into your page.

Code example

import type { createCheckoutWithEthElement } from "@paperxyz/js-client-sdk-checkout-with-eth";

// Assume a container exists:
//
//      <div id="paper-checkout-container" w="380px" />
//
const iframe = await createCheckoutWithEthElement({
  sdkClientSecret: "MY_SDK_CLIENT_SECRET",
  elementOrId: "paper-checkout-container",
  payingWalletSigner,
  setUpUserPayingWalletSigner,
  receivingWalletType,
  onError(error) {
    console.log("Payment error:", error);
  },
  onSuccess({ transactionId }) {
    console.log("Payment successful.");
  },
});

// Alternatively, insert the iframe programmatically:
//
//      const iframe = createCheckoutWithEthElement(...)
//      document.getElementById('paper-checkout-container').appendChild(iframe);

Props

NameTypeDescription
sdkClientSecret *stringThe client secret returned from the Checkout SDK intent API.
payingWalletSigner *ethers.SignerThe connected wallet who is going to be paying the ETH required for the checkout
localeenum
Valid values: en, fr, es, it, de, ja, ko, zh
The language to show text in.
Defaults to en.
optionsobjectCustomize component styling. See Customization.
setUpUserPayingWalletSigner(args: {
chainId: number;
}) => void | Promise
If provided, the callback will be called before asking buyers to pay with the chainId that they are expected to be on.

Developers must make sure that users are on the right chain (Goerli for testnets, Eth for mainnets) or risk buyers sending funds into the void.
receivingWalletTypeenum
Valid values:
- WalletConnect
- MetaMask
- Coinbase Wallet
- Phantom
- Preset
Defaults to Preset.

The wallet type of the user wallet receiving the NFT to render the appropriate wallet icon in the component.
onError(error: PaperSDKError) => voidThis method is called when anything wrong happens during the checkout process
onSuccess(props : { transactionResponse: TransactionResponse; transactionId: string; }) => void)This method is called when the transaction is successfully sent to the blockchain
suppressErrorToastbooleanDefaults to true.

If false, any error thrown will be displayed in a toast.
onLoad() => voidThis method is called when the iframe loads
elementOrIdstring | HTMLElementIf provided, the iframe will be appended this element.

You can pass in the DOM element or the id associated with the element.

A minimum width of 380px is recommended.

Customization

The optional options argument allows you to customize the component's styling. All customization fields are optional.

options object

NameTypeDescription
colorPrimarystring
In hex, e.g. #cf3781
The primary brand color for buttons and links.
colorBackgroundstring
In hex, e.g. #cf3781
The background color of the page.
colorTextstring
In hex, e.g. #cf3781
The color for text on the page and UI elements.
borderRadiusnumber
In px, e.g. 0 for sharp corners, 12 for rounded corners, 24 for pill shape
The roundness of buttons and input elements.