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);
  }

See all 3 lines

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:

Overview
SDK Structure