Forge Payments JS SDK

Installation

Install the package using your favorite package manager:

npm

npm install @forgehq/payments-sdk

yarn

yarn add @forgehq/payments-sdk

pnpm

pnpm add @forgehq/payments-sdk

Usage

To initiate a checkout process, import and use the startCheckout function. This function takes a CheckoutDetails object as an argument, which includes campaign and payment information, as well as the products to be included in the checkout.

Here is an example of how to use it:

import { startCheckout, CheckoutDetails } from '@forgehq/payments-sdk';

const checkoutDetails: CheckoutDetails = {
  campaignId: 'your-campaign-id',
  paymentId: 'your-payment-id',
  email: '[email protected]',
  userId: 'user-123',
  entries: [
    {
      productId: 'product-a',
      quantity: 1,
    },
    {
      productId: 'product-b',
      quantity: 2,
    },
  ],
};

await startCheckout(checkoutDetails);

This will redirect the user to the checkout page to complete their payment.

CheckoutDetails

The CheckoutDetails object has the following fields:

• campaignId (string, required): The unique identifier of the campaign.
• paymentId (string, required): An arbitrary value that uniquely identifies the payment. This ID should not be repeated between different payments. It will be sent via webhook to communicate the completion of the operation to the backend.
• email (string, optional): The email address of the Forge user.
• userId (string, optional): The unique identifier of the Forge user.
• entries (CheckoutEntry[], required): An array of entries for the checkout.

CheckoutEntry

A CheckoutEntry represents a line in the checkout. Each CheckoutEntry object in the entries array has the following fields:

• productId (string, required): The unique identifier of the product.
• quantity (number, required): The quantity of the product.

Error Handling

Here is an example of how to handle the different error types to identify specific failure scenarios:

import {
  startCheckout,
  CheckoutDetails,
  ProductNotFoundError,
  InsufficientStockError,
  PaymentIdAlreadyUsedError,
  InvalidPaymentMethodError,
  PaymentsNotEnabledError,
  ForgeApiError,
} from '@forgehq/payments-sdk';

// ... checkoutDetails definition

try {
  await startCheckout(checkoutDetails);
} catch (error) {
  if (error instanceof ProductNotFoundError) {
    // This error is thrown when one or more product IDs do not exist.
    console.error('Products not found:', error.productIds);
    // You can update the UI to inform the user which products are invalid.
  } else if (error instanceof InsufficientStockError) {
    // This error is thrown when the requested quantity for one or more products
    // cannot be satisfied.
    console.error('Insufficient stock for products:', error.productIds);
    // You could inform the user about the stock issue.
  } else if (error instanceof PaymentIdAlreadyUsedError) {
    // This error is thrown when the payment ID has already been used.
    console.error('Payment ID already used:', error.paymentId);
  } else if (error instanceof InvalidPaymentMethodError) {
    // This error is thrown when a payment method is invalid for the requested products.
    console.error('Invalid payment method for products:', error.productIds);
  } else if (error instanceof PaymentsNotEnabledError) {
    // This error is thrown when payments are not enabled for a campaign.
    console.error('Payments not enabled for campaign:', error.campaignId);
  } else if (error instanceof ForgeApiError) {
    // This is a generic error for problems when communicating with the Forge API.
    console.error('A Forge API error occurred:', error.message);
    console.error('HTTP Status:', error.httpStatusCode);
    console.error('Forge Error Code:', error.errorCode);
    // This can be used to handle server-side issues or invalid requests.
  } else {
    // Handle any other unexpected errors.
    console.error('An unexpected error occurred:', error);
  }
}