Getting Started

This guide will walk you through the essential steps to get the PaymentKit Node.js SDK up and running in your project. In just a few minutes, you'll install the SDK, configure it for the test environment, and make your first API call.

1. Installation

First, add the PaymentKit SDK to your project using npm. Open your terminal and run the following command:

Installation Command

npm install @blocklet/payment-js

2. Configuration

Before making any API calls, you need to configure the SDK. At a minimum, you must import the library and set the environment. For development and testing, it's highly recommended to use the test environment to avoid processing real transactions.

Create a new file, for example index.js, and add the following code to initialize the SDK in test mode:

Initialize the SDK

import payment from '@blocklet/payment-js';

// Use the test environment to avoid real charges during development
payment.environments.setTestMode(true);

console.log('PaymentKit SDK configured for test mode.');

For more details on managing different environments, see the Environments documentation.

3. Make Your First API Call

Now that the SDK is configured, you're ready to interact with the PaymentKit API. Let's try a simple, read-only operation: listing all subscriptions. This is a great way to verify that your configuration is correct.

Add the following asynchronous function to your index.js file and call it:

List Subscriptions

import payment from '@blocklet/payment-js';

// Use the test environment
payment.environments.setTestMode(true);

async function listSubscriptions() {
  try {
    console.log('Fetching subscriptions...');
    const subscriptions = await payment.subscriptions.list({
      order: 'updated_at:ASC', // Sort by update time
      pageSize: 5,           // Limit to 5 results
    });

    if (subscriptions.data.length > 0) {
      console.log(`Successfully retrieved ${subscriptions.data.length} subscriptions:`);
      subscriptions.data.forEach(sub => {
        console.log(`- ID: ${sub.id}, Status: ${sub.status}`);
      });
    } else {
      console.log('No subscriptions found. This is expected if you have not created any yet.');
    }

  } catch (error) {
    console.error('An error occurred:', error.message);
  }
}

listSubscriptions();

Run the file from your terminal:

node index.js

You should see a list of your test subscriptions or a message indicating that none were found. Congratulations, you've successfully integrated the PaymentKit SDK!

Next Steps

You are now ready to explore the core features of the PaymentKit SDK. Here are some suggestions for what to learn next: