<PayWithCard> is a React component that renders the card payment flow:

This component will automatically render the card checkout experience. onSuccess is called when the user's payment is complete. Once the transaction is fully complete on-chain, Paper sends a transfer:succeeded webhook associated with the transaction.

Optional event callback functions can be passed to handle events associated with this step.

Code Snippet

function PayWithCardExample() {
  const [paperCheckoutId, setPaperCheckoutId] = useState<string>();  
  const [message, setMessage] = useState<string>();
  useEffect(() => {
    (async () => {
      // Fetch the Paper checkout ID from your backend
      const checkoutFetch = await fetch('/you-backend', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        body: JSON.stringify({
          // Potentially some params you want to pass to tell
          // your backend which Paper checkout you want to get.
      const { checkoutId } = await checkoutFetch.json();
  }, []);

  const onPayWithCardTransferSuccess = (result: TransferSuccessResult) => {
    setMessage(`Transaction succeeded!`);
  const onPayWithCardError = (paperSDKerror: PaperSDKError) => {
    setMessage(`Something went wrong! ${paperSDKerror.code}: ${paperSDKerror.error}`);

  return (
    <PaperSDKProvider chainName='Polygon'>
          emailAddress='[email protected]'


checkoutId: string

The ID of the Paper checkout created for the NFT you're selling.
See the Checkout API for more information about creating or fetching a checkout.

recipientWalletAddress: string

The public address of where the NFT will ultimately be received. If the user is using a Paper wallet, you may use the component to create a wallet for them, or if you already know the user has previously registered a Paper wallet, you may use /api/v1/wallet/:emailAddress to get the public wallet address associated with an email address.

emailAddress: string

The email address of the user. We require this email to send useful information regarding the purchase (e.g. receipts).

quantity: number

Optional, defaults to 1
The quantity of NFTs to purchase.

metadata: object

A map of custom metadata for this purchase. This metadata will be provided in all webhooks emitted for this purchase.

Please only provide serializable data as values (i.e. JSON.stringify(metadata) is readable).

onPaymentSuccess: (result: PaymentSuccessResult) => void

This callback is invoked after Paper has successfully received payment from the buyer.

The NFT may not yet be transferred to the user. Use onTransferSuccess if you expect the NFT to be in the buyer's wallet.

onTransferSuccess: (result: TransferSuccessResult) => void

This callback is invoked after the NFT is successfully transferred to the buyer's wallet.

onReview: (result: ReviewResult) => void

This callback is invoked once the buyer presses the "Review" button with valid card details.

onClose: () => void

This callback is invoked once the card payment confirmation popup is closed. (Either closed by the user or closed automatically)

onError: (error: PaperSDKError) => void

This callback is invoked if an error occurs during payment.


type PaymentSuccessResult {
  // A unique ID for this purchase.
  id: string;

type ReviewResult {
  // A unique ID for this purchase.
  id: string;

type TransferSuccessResult = {
  // A unique ID for this purchase.
  id: string;
  // A list of tokens claimed.
  claimedTokens: ClaimedToken[];

type PaperSDKError = {
  code: PaperSDKErrorCode;
  error: Error;

enum PaperSDKErrorCode {
  UserLoginFailed = 'User login failed',
  InvalidProps = 'The props you passed in to this component are not valid.',
  InvalidCard = 'The card information is invalid. Please double check that the Card, CVC, and Zip code are all correct.',
  EmailNotVerified = 'The email was unable to be verified.',
  NotEnoughSupply = 'There is not enough supply to claim.',
  AddressNotAllowed = 'This address is not on the allowlist.',
  NoActiveClaimPhase = 'There is no active claim phase at the moment.',