CheckoutWithCard

CheckoutWithCard embeds a component on your page that accepts credit/debit card, Apple Pay, and Google Pay.

This component also handles:

  • Apple Pay and Google Pay options, if supported
  • Bot and anti-fraud detection
  • 3D Secure prompted by the issuing bank, if necessary
  • KYC of the buyer, if necessary

Example

👍

Try a demo!

First the buyer is prompted for basic card information.

Then they'll be asked 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
    • yarn add @paperxyz/react-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 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 CheckoutWithCard component to render this component. Pass the SDK Client Secret to this component.

NOTE: The SDK Client Secret encodes the parameters you provide. It can be decoded to plaintext but cannot be modified by buyers.

Example code

import { CheckoutWithCard, PaperSDKProvider } from "@paperxyz/react-client-sdk";
  
<PaperSDKProvider appName='My Web3 App' chainName="Polygon">
  <CheckoutWithCard
    sdkClientSecret='MY_SDK_CLIENT_SECRET'
    onPaymentSuccess={(result) => {
      console.log("Payment successful.");
    }}
    onError={(error) => {
      console.error("Payment error:", error);
    }}
    options={{
      colorBackground: '#121212',
      colorPrimary: '#19A8D6',
      colorText: '#f0f0f0',
      borderRadius: 24,
    }}
  />
</PaperSDKProvider>

PaperSDKProvider props

NameTypeDescription
appNamestringThe application name that will be shown on the wallet, if provided.
chainNameenum
Valid values:
- Polygon
- Mumbai
- Ethereum
- Goerli
- Solana
- SolanaDevnet
The chain matching the registered contract for this checkout.

CheckoutWithCard props

NameTypeDescription
sdkClientSecret *stringThe SDK Client Secret returned from the Create Checkout Elements Client Secret API.
onPaymentSuccess *(result: { id: string; }) => voidThis method is called after the payment has been initiated.

This payment is pending and may be rejected by the cardholder's bank.
onReview(result: { id: string; cardholderName: string; }) => voidThis method is called once the buyer presses the "Review" button with valid card details.
onError(error: PaperSDKError) => voidThis method is called when an error is encountered.
optionsobjectCustomize component styling. See Customization.

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 createCheckoutWithCardElement 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.

Example code

import { createCheckoutWithCardElement } from "@paperxyz/js-client-sdk";

// Assume a container exists:
//
//      <div id="paper-checkout-container" />
//
createCheckoutWithCardElement({
  sdkClientSecret: "MY_SDK_CLIENT_SECRET",
  elementOrId: "paper-checkout-container",
  appName: "My Web3 App",
  options,
  onError(error) {
    console.error("Payment error:", error);
  },
  onPaymentSuccess({ id }) {
    console.log("Payment successful.");
  },
});

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

Props

NameTypeDescription
sdkClientSecret *stringThe client secret returned from the Checkout SDK intent API.
elementOrIdstring | HTMLElementIf provided, the iframe will be appended this element.

Note that you can either pass in a reference to the containing element or the id associated with the containing element
appNamestringIf provided, the wallet card will display your appName.
optionobjectCustomize component styling. See Customization.
onLoad() => voidThis method is called when the iframe loads.
onError(error: PaperSDKError) => voidThis method is called when an error occurs during the payment process.
onPaymentSuccess(props : { id: string }) => voidThis method is called when the buyer has successfully paid.
onReview(props: { cardholderName: string, id: string }) => voidThis method is called after the user enters their card details.

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.

Examples

Here's an example component with the following props:

  • colorPrimary='#cce3de'
  • colorBackground='#264653'
  • colorText='#f0f0f0'
  • borderRadius={0}

FAQ

How do I prevent the 3D Secure or KYC modal from popping up behind my other frontend components?

The SDK uses a z-index of 10000 for these modals. If they are appearing behind other components, please lower your component's z-index values.