Skip to content
On this page



npm install @candypay/checkout-sdk


The entrypoint to the Node.js SDK is CandyPay instance that will give you access to its API. It accepts an configuration object with the following fields:

  • private_api_key - The private API key which is been issued to the developer while generating an API key

  • network - The Solana cluster on which the payment checkout would take place i.e either mainnet or devnet

  • collect_shipping_address - A boolean to configure whether to show a shipping address form on the checkout page

    import { CandyPay } from "@candypay/checkout-sdk";
    import dotenv from "dotenv";
    const candypay = new CandyPay({
      api_keys: {
        private_api_key: process.env.CANDYPAY_PRIVATE_API_KEY!,
        public_api_key: process.env.CANDYPAY_PUBLIC_API_KEY!,
      network: "mainnet",
      config: {
        collect_shipping_address: false,

Session module

The session module can be accessed via candypay.session() and provides the following methods:


The create method creates and creates a new checkout session with the required configuration. It takes in the following parameters and returns session_id:

  • items - An array of items which would be displayed on the checkout page. Each element of the items array is an object which would contain the name, price, image, quantity and size of the product

  • shipping_fees - An optional param which takes shipping fees (value in $USD) and add it on total cart value to charge users (we currently only support static value for shipping fees, please charge accordingly)

  • tokens - An array of SPL tokens in which the customer could pay. By default, SOL and USDC (USDC-DEV on devnet) would be shown to the customer on the checkout page. Currently the following SPL tokens are supported on mainnet:

It returns session_id, order_id and payment_url for the corresponding checkout session.

const session = await candypay.session.create({
  success_url: "",
  cancel_url: "",
  tokens: ["dust", "samo", "shdw"],
  items: [
      name: "Throwback Hip Bag",
      price: 43.57, // value in USD
      image: "",
      quantity: 1,
      size: "M", // optional
  shipping_fees: 0.43, // optional | value in USD


The metadata method returns the metadata of a specified checkout session. It takes in session_id as a parameter.

const metadata = await candypay.session.metadata({
  session_id: "cp_pay_34059991-d572-46db-bd1c-225e467ee414",


The generatePaymentURL method returns the checkout URL. It takes in session_id as a parameter. The generatePaymentURL doesn't create a new checkout session rather it returns the URL via which the payment can be completed.

const paymentURL = candypay.session.generatePaymentURL({