Skip to main content

​
Overview

The Checkout API allows you to create checkout sessions directly without using a cart. This is useful for one-click purchases or when you want to create a checkout session programmatically.
Checkout operations require a customer token for authentication.

​
Create Checkout Session

Creates a checkout session using a customer token. After creating the checkout session, redirect the customer to the returned URL. 
storefront.checkout.createCheckoutSession(config)

​
Parameters

​
config
object
required
Configuration object for the request

​
Returns

Returns a checkout session object:
​
id
string
The checkout session ID
​
token
string
The token for the checkout session
​
url
string
The URL to redirect the customer to complete checkout

​
Example

import { createStorefrontClient } from '@paynow-gg/sdk';

const storefront = createStorefrontClient('store-id', 'customer-token');

// Create a simple one-time checkout
const { data: checkout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1
      }
    ]
  }
});

console.log('Checkout URL:', checkout.url);
window.location.href = checkout.url;

// Create a subscription checkout
const { data: subscriptionCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1,
        subscription: true
      }
    ]
  }
});

// Create checkout with multiple products
const { data: multiCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 2
      },
      {
        product_id: '411486491630370817',
        quantity: 1,
        subscription: true
      }
    ]
  }
});

// Create checkout with custom variables
const { data: customCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1,
        custom_variables: {
          'player-name': 'JohnDoe',
          'server-region': 'us-east'
        }
      }
    ]
  }
});

// Create checkout with game server selection
const { data: gameserverCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1,
        selected_gameserver_id: '411486491630370820'
      }
    ]
  }
});

// Create checkout as a gift
const { data: giftCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1,
        gift_to: {
          platform: 'steam',
          id: '76561198152492642'
        }
      }
    ]
  }
});

// Create checkout with coupon
const { data: couponCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1
      }
    ],
    coupon_id: '411486491630370817'
  }
});

// Create checkout with return URLs
const { data: urlCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1
      }
    ],
    return_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
    auto_redirect: true
  }
});

// Create checkout with affiliate tracking
const { data: affiliateCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1
      }
    ],
    affiliate_code: 'PARTNER123'
  }
});

// Create checkout with trial period
const { data: trialCheckout } = await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: '411486491630370816',
        quantity: 1,
        subscription: true,
        trial: true
      }
    ]
  }
});

​
Use Cases

Create immediate checkout sessions for quick purchases:
async function buyNow(productId: string) {
  const { data } = await storefront.checkout.createCheckoutSession({
    data: {
      lines: [
        {
          product_id: productId,
          quantity: 1
        }
      ],
      return_url: window.location.href
    }
  });
  
  window.location.href = data.url;
}
Allow customers to purchase products as gifts:
async function purchaseAsGift(productId: string, recipientSteamId: string) {
  const { data } = await storefront.checkout.createCheckoutSession({
    data: {
      lines: [
        {
          product_id: productId,
          quantity: 1,
          gift_to: {
            platform: 'steam',
            id: recipientSteamId
          }
        }
      ]
    }
  });
  
  window.location.href = data.url;
}
Create checkouts with multiple products:
async function purchaseBundle(productIds: string[]) {
  const { data } = await storefront.checkout.createCheckoutSession({
    data: {
      lines: productIds.map(id => ({
        product_id: id,
        quantity: 1
      }))
    }
  });
  
  window.location.href = data.url;
}
Offer trial periods for subscription products:
async function startTrial(productId: string) {
  const { data } = await storefront.checkout.createCheckoutSession({
    data: {
      lines: [
        {
          product_id: productId,
          quantity: 1,
          subscription: true,
          trial: true
        }
      ],
      return_url: 'https://example.com/subscription-active'
    }
  });
  
  window.location.href = data.url;
}

​
Best Practices

When making server-side requests, always include the customer’s IP address to ensure accurate VAT calculation and regional pricing:
await storefront.checkout.createCheckoutSession({
  data: {
    lines: [/* ... */]
  },
  headers: {
    'x-paynow-customer-ip': customerIp,
    'x-paynow-customer-countrycode': customerCountry
  }
});
Always provide return and cancel URLs to guide customers after checkout:
await storefront.checkout.createCheckoutSession({
  data: {
    lines: [/* ... */],
    return_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cart',
    auto_redirect: true
  }
});
Ensure all required custom variables are provided before creating checkout:
// Fetch product first to check required variables
const { data: product } = await storefront.products.getStorefrontProductByIdOrSlug({
  path: { idOrSlug: productId }
});

const customVars: Record<string, string> = {};
product.custom_variables.forEach(cv => {
  // Collect required variables from user input
  customVars[cv.identifier] = userInputs[cv.identifier];
});

await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: productId,
        quantity: 1,
        custom_variables: customVars
      }
    ]
  }
});
When creating subscription checkouts with trials, ensure both flags are set:
await storefront.checkout.createCheckoutSession({
  data: {
    lines: [
      {
        product_id: productId,
        quantity: 1,
        subscription: true,  // Required for trials
        trial: true          // Enable trial period
      }
    ]
  }
});

​
Checkout vs Cart

Direct Checkout

Use when:
  • One-click purchases
  • Pre-configured bundles
  • Gift purchases
  • Programmatic checkouts
Benefits:
  • Faster checkout flow
  • No cart management needed
  • Better for simple purchases

Cart-based Checkout

Use when:
  • Multiple products
  • Customer wants to browse
  • Need to save items for later
  • Complex shopping experience
Benefits:
  • Familiar shopping experience
  • Easy quantity updates
  • Persistent across sessions

Build docs developers (and LLMs) love

Get started for freeTalk to us