jannikwempe / nodejs-paddle-sdk

A fully typed Node.js library for integration with Paddle.

Node Paddle SDK

A NodeJS library for integrating with Paddle.

The library provides full TypeScript definitions for the Paddle API & Webhook events.

Installation

npm install @invertase/node-paddle-sdk --save

Usage

import { PaddleSDK } from '@invertase/node-paddle-sdk';

const paddle = new PaddleSDK(
  12345, // Required: Vendor ID
  'xxxx', // Required: Vendor Auth Code
  'xxxx', // Optional: Public Key
);

The Public Key is optional, but required if using the verifyWebhook method.

API

The library provides integration with the Paddle API endpoints.

The vendor_id and vendor_auth_code parameters are not required and are automatically provided by the library.

Example usage:

try {
  const coupons = await paddle.listCoupons({
    product_id: 123,
  });
} catch (e) {
  console.error(e.code, e.message);
}

Product API

Coupons

• listCoupons
• createCoupon
• deleteCoupon
• deleteCoupon
• updateCoupon

Products

• listProducts

Licenses

• generateLicense

Pay Links

• generatePayLink

Transactions

• listTransactions

Payments

• refundPayment

Subscription API

Plans

• listPlans
• createPlan

Users

• listUsers
• updateUser
• cancelUser

Modifiers

• listModifiers
• createModifier
• deleteModifier

Payments

• listPayments
• reschedulePayment

One-off Charges

• createOneOffCharge

Alert API

Webhooks

• getWebhookHistory

Webhooks

The library provides useful helpers for handling Webhooks, along with type definitions for events for TypeScript users.

Verifying a webhook

To verify a webhook, you must have provided a public key whilst creating a PaddleSDK instance otherwise an error will be thrown. If the provided body does not conform to a Paddle Webhook request (JSON response containing both a alert_name and p_signature), an error will also be thrown.

Pass the request body to the verifyWebhook method to verify the signature:

// Express example

// Ensure you accept a JSON request body.
app.use(express.json());

app.post('/your-webhook-endpoint', (req, res) => {
  const verified = paddle.verifyWebhook(req.body);

  if (!verified) {
    return res.status(403).send('Invalid webhook request.');
  }

  ...
});

TypeScript

The library provides type definitions for the various Paddle Webhook events. Using the alert_name, you can discover the type of the event:

import { PaddleWebhook } from '@invertase/node-paddle-sdk';

app.post('/your-webhook-endpoint', (req, res) => {
  const verified = paddle.verifyWebhook(req.body);

  if (!verified) {
    return res.status(403).send('Invalid webhook request.');
  }

  const event = req.body as PaddleWebhook;

  if (event.alert_name === 'subscription_created') {
    // `event` is now cast as a `SubscriptionCreatedWebhook`
    console.log(event.subscription_id);
  }
});

Sandbox Environment

If using the Paddle Sandbox Environment, you can set the library to use a custom server endpoint:

import { PaddleSDK } from '@invertase/node-paddle-sdk';

const paddle = new PaddleSDK(
  12345, // Required: Vendor ID
  'xxxx', // Required: Vendor Auth Code
  'xxxx', // Optional: Public Key
  'https://sandbox-vendors.paddle.com/api/2.0', // Optional: Custom Server Endpoint
);

License

• See LICENSE

---

Built and maintained by Invertase.