Environments

The PaymentKit SDK operates in two distinct modes: Live Mode for processing real transactions and Test Mode for development and testing. Every API request is executed in one of these environments. By default, the SDK is initialized in Live Mode.

It is crucial to use Test Mode during development to build and verify your integration without affecting your live data or incurring real charges.

Programmatic Configuration#

You can dynamically switch between Live and Test modes within your application using the methods provided on the payment.environments object. This is the recommended approach for managing environments.

Set Live Mode#

To explicitly activate Live Mode, use the setLivemode method. All subsequent API calls will be directed to the production environment.

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

// Activate Live Mode for production transactions
payment.environments.setLivemode(true);

Setting setLivemode(false) is equivalent to activating Test Mode.

Set Test Mode#

To activate Test Mode for development, use the setTestmode method. This ensures that all API calls are sandboxed and will not interact with your live data.

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

// Activate Test Mode for development and testing
payment.environments.setTestmode(true);

Setting setTestmode(false) is equivalent to activating Live Mode.

Checking the Active Mode#

You can programmatically check which mode the SDK is currently configured to use.

Check Live Mode#

The getLivemode method returns true if the SDK is currently in Live Mode.

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

const isLive = payment.environments.getLivemode();
console.log(`SDK is in Live Mode: ${isLive}`);
// Expected output: SDK is in Live Mode: true

Check Test Mode#

The getTestmode method returns true if the SDK is currently in Test Mode.

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

payment.environments.setTestmode(true);

const isTest = payment.environments.getTestmode();
console.log(`SDK is in Test Mode: ${isTest}`);
// Expected output: SDK is in Test Mode: true

How It Works#

Once you set an environment mode, all subsequent API calls made through the SDK will automatically include the necessary livemode parameter in the request. This ensures your requests are routed to the correct PaymentKit environment without needing to specify it in every call.

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

// Ensure the SDK is in Test Mode
payment.environments.setTestmode(true);

console.log(`Operating in Test Mode: ${payment.environments.getTestmode()}`);

async function listTestCustomers() {
  try {
    // This API call will be sent to the test environment
    const customers = await payment.customers.list({ pageSize: 5 });
    console.log('Fetched test customers:', customers.data);
  } catch (error) {
    console.error('Error fetching test customers:', error.message);
  }
}

listTestCustomers();

Properly managing your environments is a critical step for a safe and reliable integration. Now that you understand how to configure the SDK, you can proceed to implement payment flows.

Next, dive into practical guides for implementing common payment workflows.