CheckoutWithCard (JS SDK)

CheckoutWithCard element is an embeddable iframe that allows your buyers to purchase your NFT with credit card.

“Enter card information” page

“Review your purchase” page

The native Javascript offers you three composable pieces to create the CheckoutWithCard element:

createCheckoutWithCard
createCheckoutWithCardLink
createCheckoutWithCardMessageHandler

If you’re looking to use the native JS SDK and get started as soon as possible, you’ll start with the createCheckoutWithCard which uses both createCheckoutWithCardLink and createCheckoutWithCardMessageHandler under the hood to create the CheckoutWithCard element.

createCheckoutWithCard

Code Snippet

import {
  createCheckoutWithCardElement,
} from '@nftgate/js-client-sdk';

// Assuming a container exists:
createCheckoutWithCardElement({
  sdkClientSecret,
  elementOrId: 'nftgate-checkout',
  appName,  
  options,
  onLoad() {},
  onError(error) {
    console.log("error", error);
  },
  onPaymentSuccess({ id }) {
    console.log("transactionId", id);
  },
  onOpenKycModal({ iframeLink }) {
    // You should open the iframeLink in an iframe embedded in a modal of your choice
    console.log("iframeLink", iframeLink);
  },
  onCloseKycModal: () => {
    // you can close the modal that was opened from the KYC previously here
    console.log("close kyc modal");
  },
  onReview({ cardholderName, id }) {
    console.log("cardholderName, id", cardholderName, id);
  },
});

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

Props

Props	Type	Description
sdkClientSecret *	string	The client secret returned from the Checkout SDK intent API.
onOpenKycModal *	(props: { iframeLink: string }) => void	This callback provides a link which developers must load in an iframe to complete the purchase.Failing to do so would mean that the buyer’s purchase will not complete.
onCloseKycModal *	() => void	This callback allows you to close the iframe that was previously displaying the KYC details.
elementOrId	string \| HTMLElement	If 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
appName	string	If provided, the wallet card will display your If provided, the wallet card will display your appName.
option	ICustomizationOptions	See Customizing Checkout Elements.
onLoad	() => void	This callback will be called when the iframe loads.
onError	(error: (error: [NFTgateSDKError](ref:nftgatesdkerror)) => void	This callback will be called when an error occurs during the payment process.
onPaymentSuccess	(props : { id: string }) => void)	This callback will be called when the buyer has successfully paid.
onReview	(props: { cardholderName: string, id: string }) => void	This callback will be called after the user enters their card details.

createCheckoutWithCardLink

This is the core building block that builds up the iframe link required to display the CheckoutWithCard element.

Once you generate the link, you can proceed to display it in an iframe but you’d still need to listen for a couple of events on the document in order to know when a payment is successful or when the user has to KYC. We provide a handler which does most of the heavy lifting.

Code Snippet

const checkoutWithCardUrl = createCheckoutWithCardLink({
    sdkClientSecret,
    appName,
    options,
});

Props

Props	Type	Description
sdkClientSecret *	string	The client secret you get from create checkout SDK intent
appName	string	If provided, the wallet card will display your appName.
options	ICustomizationOptions	See Customizing Checkout Elements.

createCheckoutWithCardMessageHandler

This is the message handler that is to be registered.
Essentially, this listens to six main events:

checkoutWithCardError
paymentSuccess
reviewComplete
openModalWithUrl
completedSDKModal
sizing

Code Snippet

const iframe = document.createElement("iframe");

window.addEventListener(
    "message",
    createCheckoutWithCardMessageHandler({
      iframe,
      onCloseKycModal,
      onOpenKycModal,
      onError,
      onPaymentSuccess,
      onReview,
    })
);

Props

Props	Type	Description
iframe *	HTMLIFrameElement	The iframe that is displaying the link from createCheckoutWithCardLink
onOpenKycModal *	(props: { iframeLink: string }) => void	This callback provides a link which developers must load in an iframe to complete the purchase. Failing to do so would mean that the buyer’s purchase will not complete.
onCloseKycModal *	() => void	This callback allows you to close the iframe that was previously displaying the KYC details.
onError	(error: [NFTgateSDKError](ref:nftgatesdkerror)) => void	If provided, the callback will be called when anything wrong happens during the payment process.
onPaymentSuccess	(props : { id: string }) => void)	If provided, the callback will be called when the buyer has successfully paid.
onReview	(props: { cardholderName: string, id: string }) => void	If provided, the callback will be called when the user clicks the button after the enter their card details.

Writing your own handler

You can write your own handler if you wish, Here’s how:
The event object that is passed by default into the message event contains the data filed which has the following type

type event.data = {
    eventType: 'checkoutWithCardError',
  code: NFTgateSDKErrorCode,
  error: Error
}   | {
  eventType: 'paymentSuccess',
  id: string
} | {
    eventType: 'reviewComplete',
  id: string,
  cardholderName: string
} | {
    eventType: 'openModalWithUrl',
  iframeLink: string,
} | {
  eventType: 'completedSDKModal'
} | {
    eventType: 'sizing'
  height: string,
  width: string,
}

You simply create a function that handles or ignores either of the two events, exactly the way you want:

window.addEventListener('message', (event: MessageEvent) => {
    // we use this alternate domain to avoid certain firewalls blocking .xyz domains 
        if (!event.origin.startsWith("https://nftgatecheckout.com")) {
      return;
    }
    const data = event.data;
    switch(data.eventType): {
        case "checkoutWithCardError": {
        break;
      }
      case "paymentSuccess": {
        break;
      }
      case "reviewComplete": {
        break;
      }
      case "openModalWithUrl": {
        break;
      }
            case "completedSDKModal": {
        break;
      }
      case "sizing": {
        break;
      }
    }
});