payload/packages/plugin-stripe

Payload Stripe Plugin

A plugin for Payload CMS to manage Stripe through Payload.

Core features:

• Layers your Stripe account behind Payload access control
• Enables a two-way communication channel between Stripe and Payload
  • Proxies the Stripe REST API
  • Proxies Stripe webhooks

Installation

  yarn add @payloadcms/plugin-stripe
  # OR
  npm i @payloadcms/plugin-stripe

Basic Usage

In the plugins array of your Payload config, call the plugin with options:

import { buildConfig } from 'payload/config';
import stripe from '@payloadcms/plugin-stripe';

const config = buildConfig({
  plugins: [
    stripe({
      stripeSecretKey: process.env.STRIPE_SECRET_KEY,
    })
  ]
});

export default config;

Options

• stripeSecretKey

  Required. Your Stripe secret key.

• stripeWebhookEndpointSecret

  Optional. Your Stripe webhook endpoint secret. This is needed only if you wish to sync data from Stripe to Payload.

• webhooks

  Optional. An object of Stripe webhook handlers, keyed to the name of the event. See webhooks for more details or for a list of all available webhooks, see here.

Endpoints

One core functionality of this plugin is to enable a two-way communication channel between Stripe and Payload. To do this, the following custom endpoints are automatically opened for you.

NOTE: the /api part of these routes may be different based on the settings defined in your Payload config.

• POST /api/stripe/rest

  Proxies the Stripe REST API behind Payload access control and returns the result. If you need to proxy the API server-side, use the stripeProxy function.

    const res = await fetch(`/api/stripe/rest`, {
      method: 'POST',
      credentials: 'include',
      headers: {
        ContentType: 'application/json',
        // Authorization: `JWT ${token}` // NOTE: do this if not in a browser (i.e. curl or Postman)
      },
      body: JSON.stringify({
        stripeMethod: "stripe.subscriptions.list",
        stripeArgs: {
          customer: "abc"
        }
      })
    })
  

• POST /api/stripe/webhooks

  Returns an http status code. This is where all Stripe webhook events are sent to be handled. See webhooks.

Webhooks

Stripe webhooks are used to sync from Stripe to Payload. Webhooks listen for events on your Stripe account so you can trigger reactions to them. To enable webhooks:

1. Login and create a new webhook from the Stripe dashboard
2. Paste /api/stripe/webhooks as the "Webhook Endpoint URL"
3. Select which events to broadcast
4. Then, handle these events using the webhooks portion of this plugin's config:

import { buildConfig } from 'payload/config';
import stripe from '@payloadcms/plugin-stripe';

const config = buildConfig({
  plugins: [
    stripe({
      stripeSecretKey: process.env.STRIPE_SECRET_KEY,
      stripeWebhooksEndpointSecret: process.env.STRIPE_WEBHOOKS_ENDPOINT_SECRET,
      webhooks: {
        'customer.subscription.updated': () => {}
      }
    })
  ]
});

export default config;

For a full list of available webhooks, see here.

Node

You can also proxy the Stripe API server-side using the stripeProxy function exported by the plugin. This is exactly what the /api/stripe/rest endpoint does behind-the-scenes. Here's an example:

import { stripeProxy } from '@payloadcms/plugin-stripe';

export const MyFunction = async () => {
  try {
    const customer = await stripeProxy({
      stripeSecretKey: process.env.STRIPE_SECRET_KEY,
      stripeMethod: 'customers.create',
      stripeArgs: {
        email: data.email,
      }
    });

    if (customer.status === 200) {
      // DO SOMETHING
    }

    if (customer.status >= 400) {
      throw new Error(customer.message);
    }
  } catch (error) {
    console.error(error.message);
  }
}

TypeScript

All types can be directly imported:

import {
  StripeConfig,
  StripeWebhookHandler.
  StripeProxy
} from '@payloadcms/plugin-stripe/dist/types';

Development

For development purposes, there is a full working example of how this plugin might be used in the demo of this repo. This demo can be developed locally using any Stripe account, you just need a working API key. Then:

git clone git@github.com:payloadcms/plugin-stripe.git \
  cd plugin-stripe && yarn \
  cd demo && yarn \
  cp .env.example .env \
  vim .env \ # add your Stripe creds to this file
  yarn dev

Now you have a running Payload server with this plugin installed, so you can authenticate and begin hitting the routes. To do this, open Postman and import our config. First, login to retrieve your Payload access token. This token is automatically attached to the header of all other requests.

Screenshots