payload/packages/plugin-stripe

Payload Stripe Plugin

A plugin for Payload CMS to manage a Stripe account through Payload.

Core features:

• Layers your Stripe account with Payload access control
• Opens custom routes to interface with the Stripe REST API
• Handles Stripe webhooks to allow for a two-way data sync

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.

Routes

The following routes are automatically opened to allow you to interact with the Stripe API behind Payload access control. This allows you to read and make updates to your account.

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

• POST /api/stripe/rest

  Calls the given Stripe REST API method and returns the result.

    const res = await fetch(`/api/stripe/rest`, {
      body: JSON.stringify({
        stripeMethod: "stripe.subscriptions.list",
        stripeMethodArgs: {
          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

This plugin also allows for a two-way data sync from Stripe to Payload using Stripe webhooks. 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.

TypeScript

All types can be directly imported:

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

Development

This plugin can be developed locally using any Stripe account that you have access to. 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