Payment Adapters

A deeper look into the payment adapter pattern used by the Ecommerce Plugin, and how to create your own.

The current list of supported payment adapters are:

Stripe

REST API

The plugin will create REST API endpoints for each payment adapter you add to your configuration. The endpoints will be available at /api/payments/{provider_name}/{action} where provider_name is the name of the payment adapter and action is one of the following:

Action	Method	Description
`initiate`	POST	Initiate a payment for an order. See initiatePayment for more details.
`confirm-order`	POST	Confirm an order after a payment has been made. See confirmOrder for more details.

Stripe

Out of the box we integrate with Stripe to handle one-off purchases. To use Stripe, you will need to install the Stripe package:

pnpm add stripe

We recommend at least 18.5.0 to ensure compatibility with the plugin.

Then, in your plugins array of your Payload Config, call the plugin with:

1import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
2import { stripeAdapter } from '@payloadcms/plugin-ecommerce/payments/stripe'
3import { buildConfig } from 'payload'
4
5export default buildConfig({
// Payload config...
plugins: [
  ecommercePlugin({
    // rest of config...
    payments: {
      paymentMethods: [
        stripeAdapter({
          secretKey: process.env.STRIPE_SECRET_KEY,
          publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
          // Optional - only required if you want to use webhooks
          webhookSecret: process.env.STRIPE_WEBHOOKS_SIGNING_SECRET,
        }),
      ],
    },
  }),
],
22})

Configuration

The Stripe payment adapter takes the following configuration options:

Option	Type	Description
secretKey	`string`	Your Stripe Secret Key, found in the Stripe Dashboard.
publishableKey	`string`	Your Stripe Publishable Key, found in the Stripe Dashboard.
webhookSecret	`string`	(Optional) Your Stripe Webhooks Signing Secret, found in the Stripe Dashboard. Required if you want to use webhooks.
appInfo	`object`	(Optional) An object containing `name` and `version` properties to identify your application to Stripe.
webhooks	`object`	(Optional) An object where the keys are Stripe event types and the values are functions that will be called when that event is received. See Webhooks for more details.
groupOverrides	`object`	(Optional) An object to override the default fields of the payment group. See Payment Fields for more details.

Stripe Webhooks

You can also add your own webhooks to handle events from Stripe. This is optional and the plugin internally does not use webhooks for any core functionality. It receives the following arguments:

Argument	Type	Description
event	`Stripe.Event`	The Stripe event object
req	`PayloadRequest`	The Payload request object
stripe	`Stripe`	The initialized Stripe instance

You can add a webhook like so:

1import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
2import { stripeAdapter } from '@payloadcms/plugin-ecommerce/payments/stripe'
3import { buildConfig } from 'payload'
4
5export default buildConfig({
// Payload config...
plugins: [
  ecommercePlugin({
    // rest of config...
    payments: {
      paymentMethods: [
        stripeAdapter({
          secretKey: process.env.STRIPE_SECRET_KEY,
          publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
          // Required
          webhookSecret: process.env.STRIPE_WEBHOOKS_SIGNING_SECRET,
          webhooks: {
            'payment_intent.succeeded': ({ event, req }) => {
              console.log({ event, data: event.data.object })
              req.payload.logger.info('Payment succeeded')
            },
          },
        }),
      ],
    },
  }),
],
28})

To use webhooks you also need to have them configured in your Stripe Dashboard.

You can use the Stripe CLI to forward webhooks to your local development environment.

Frontend usage

The most straightforward way to use Stripe on the frontend is with the EcommerceProvider component and the stripeAdapterClient function. Wrap your application in the provider and pass in the Stripe adapter with your publishable key:

1import { EcommerceProvider } from '@payloadcms/plugin-ecommerce/client/react'
2import { stripeAdapterClient } from '@payloadcms/plugin-ecommerce/payments/stripe'
3
4<EcommerceProvider
5  paymentMethods={[
6    stripeAdapterClient({
7      publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY || '',
8    }),
9  ]}
10>
11  {children}
12</EcommerceProvider>

Then you can use the usePayments hook to access the initiatePayment and confirmOrder functions, see the Frontend docs for more details.

Making your own Payment Adapter

You can make your own payment adapter by implementing the PaymentAdapter interface. This interface requires you to implement the following methods:

Property	Type	Description
`name`	`string`	The name of the payment method. This will be used to identify the payment method in the API and on the frontend.
`label`	`string`	(Optional) A human-readable label for the payment method. This will be used in the admin panel and on the frontend.
`initiatePayment`	`(args: InitiatePaymentArgs) => Promise<InitiatePaymentResult>`	The function that is called via the `/api/payments/{provider_name}/initiate` endpoint to initiate a payment for an order. More
`confirmOrder`	`(args: ConfirmOrderArgs) => Promise<void>`	The function that is called via the `/api/payments/{provider_name}/confirm-order` endpoint to confirm an order after a payment has been made. More
`endpoints`	`Endpoint[]`	(Optional) An array of endpoints to be bootstrapped to Payload's API in order to support the payment method. All API paths are relative to `/api/payments/{provider_name}`
`group`	`GroupField`	A group field config to be used in transactions to track the necessary data for the payment processor, eg. PaymentIntentID for Stripe. See Payment Fields for more details.

The arguments can be extended but should always include the PaymentAdapterArgs type which has the following types:

Property	Type	Description
`label`	`string`	(Optional) Allow overriding the default UI label for this adaper.
`groupOverrides`	`FieldsOverride`	(Optional) Allow overriding the default fields of the payment group. See Payment Fields for more details.

initiatePayment

The initiatePayment function is called when a payment is initiated. At this step the transaction is created with a status "Processing", an abandoned purchaase will leave this transaction in this state. It receives an object with the following properties:

Property	Type	Description
`transactionsSlug`	`Transaction`	The transaction being processed.
`data`	`object`	The cart associated with the transaction.
`customersSlug`	`string`	The customer associated with the transaction.
`req`	`PayloadRequest`	The Payload request object.

The data object will contain the following properties:

Property	Type	Description
`billingAddress`	`Address`	The billing address associated with the transaction.
`shippingAddress`	`Address`	(Optional) The shipping address associated with the transaction. If this is missing then use the billing address.
`cart`	`Cart`	The cart collection item.
`customerEmail`	`string`	In the case that `req.user` is missing, `customerEmail` should be required in order to process guest checkouts.
`currency`	`string`	The currency for the cart associated with the transaction.

The return type then only needs to contain the following properties though the type supports any additional data returned as needed for the frontend:

Property	Type	Description
`message`	`string`	A success message to be returned to the client.

At any point in the function you can throw an error to return a 4xx or 5xx response to the client.

A heavily simplified example of implementing initiatePayment could look like:

1import {
PaymentAdapter,
PaymentAdapterArgs,
4} from '@payloadcms/plugin-ecommerce'
5import Stripe from 'stripe'
6
7export const initiatePayment: NonNullable<PaymentAdapter>['initiatePayment'] =
async ({ data, req, transactionsSlug }) => {
  const payload = req.payload
10
  // Check for any required data
  const currency = data.currency
  const cart = data.cart
14
  if (!currency) {
    throw new Error('Currency is required.')
  }
18
  const stripe = new Stripe(secretKey)
20
  try {
    let customer = (
      await stripe.customers.list({
        email: customerEmail,
      })
    ).data[0]
27
    // Ensure stripe has a customer for this email
    if (!customer?.id) {
      customer = await stripe.customers.create({
        email: customerEmail,
      })
    }
34
    const shippingAddressAsString = JSON.stringify(shippingAddressFromData)
36
    const paymentIntent = await stripe.paymentIntents.create()
38
    // Create a transaction for the payment intent in the database
    const transaction = await payload.create({
      collection: transactionsSlug,
      data: {},
    })
44
    // Return the client_secret so that the client can complete the payment
    const returnData: InitiatePaymentReturnType = {
      clientSecret: paymentIntent.client_secret || '',
      message: 'Payment initiated successfully',
      paymentIntentID: paymentIntent.id,
    }
51
    return returnData
  } catch (error) {
    payload.logger.error(error, 'Error initiating payment with Stripe')
55
    throw new Error(
      error instanceof Error
        ? error.message
        : 'Unknown error initiating payment',
    )
  }
}

confirmOrder

The confirmOrder function is called after a payment is completed on the frontend and at this step the order is created in Payload. It receives the following properties:

Property	Type	Description
`ordersSlug`	`string`	The orders collection slug.
`transactionsSlug`	`string`	The transactions collection slug.
`cartsSlug`	`string`	The carts collection slug.
`customersSlug`	`string`	The customers collection slug.
`data`	`object`	The cart associated with the transaction.
`req`	`PayloadRequest`	The Payload request object.

The data object will contain any data the frontend chooses to send through and at a minimum the following:

Property	Type	Description
`customerEmail`	`string`	In the case that `req.user` is missing, `customerEmail` should be required in order to process guest checkouts.

The return type can also contain any additional data with a minimum of the following:

Property	Type	Description
`message`	`string`	A success message to be returned to the client.
`orderID`	`string`	The ID of the created order.
`transactionID`	`string`	The ID of the associated transaction.

A heavily simplified example of implementing confirmOrder could look like:

1import {
PaymentAdapter,
PaymentAdapterArgs,
4} from '@payloadcms/plugin-ecommerce'
5import Stripe from 'stripe'
6
7export const confirmOrder: NonNullable<PaymentAdapter>['confirmOrder'] =
async ({
  data,
  ordersSlug = 'orders',
  req,
  transactionsSlug = 'transactions',
}) => {
  const payload = req.payload
15
  const customerEmail = data.customerEmail
  const paymentIntentID = data.paymentIntentID as string
18
  const stripe = new Stripe(secretKey)
20
  try {
    // Find our existing transaction by the payment intent ID
    const transactionsResults = await payload.find({
      collection: transactionsSlug,
      where: {
        'stripe.paymentIntentID': {
          equals: paymentIntentID,
        },
      },
    })
31
    const transaction = transactionsResults.docs[0]
33
    // Verify the payment intent exists and retrieve it
    const paymentIntent =
      await stripe.paymentIntents.retrieve(paymentIntentID)
37
    // Create the order in the database
    const order = await payload.create({
      collection: ordersSlug,
      data: {},
    })
43
    const timestamp = new Date().toISOString()
45
    // Update the cart to mark it as purchased, this will prevent further updates to the cart
    await payload.update({
      id: cartID,
      collection: 'carts',
      data: {
        purchasedAt: timestamp,
      },
    })
54
    // Update the transaction with the order ID and mark as succeeded
    await payload.update({
      id: transaction.id,
      collection: transactionsSlug,
      data: {
        order: order.id,
        status: 'succeeded',
      },
    })
64
    return {
      message: 'Payment initiated successfully',
      orderID: order.id,
      transactionID: transaction.id,
    }
  } catch (error) {
    payload.logger.error(error, 'Error initiating payment with Stripe')
  }
}

Payment Fields

Payment fields are used primarily on the transactions collection to store information about the payment method used. Each payment adapter must provide a group field which will be used to store this information.

For example, the Stripe adapter provides the following group field:

1const groupField: GroupField = {
name: 'stripe',
type: 'group',
admin: {
  condition: (data) => {
    const path = 'paymentMethod'
7
    return data?.[path] === 'stripe'
  },
},
fields: [
  {
    name: 'customerID',
    type: 'text',
    label: 'Stripe Customer ID',
  },
  {
    name: 'paymentIntentID',
    type: 'text',
    label: 'Stripe PaymentIntent ID',
  },
],
23}

Client side Payment Adapter

The client side adapter should implement the PaymentAdapterClient interface:

Property	Type	Description
`name`	`string`	The name of the payment method. This will be used to identify the payment method in the API and on the frontend.
`label`	`string`	(Optional) A human-readable label for the payment method. This can be used as a human readable format.
`initiatePayment`	`boolean`	Flag to toggle on the EcommerceProvider's ability to call the `/api/payments/{provider_name}/initiate` endpoint. If your payment method does not require this step, set this to `false`.
`confirmOrder`	`boolean`	Flag to toggle on the EcommerceProvider's ability to call the `/api/payments/{provider_name}/confirm-order` endpoint. If your payment method does not require this step, set this to `false`.

And for the args use the PaymentAdapterClientArgs type:

Property	Type	Description
`label`	`string`	(Optional) Allow overriding the default UI label for this adaper.

Best Practices

Always handle sensitive operations like creating payment intents and confirming payments on the server side. Use webhooks to listen for events from Stripe and update your orders accordingly. Never expose your secret key on the frontend. By default Nextjs will only expose environment variables prefixed with NEXT_PUBLIC_ to the client.

While we validate the products and prices on the server side when creating a payment intent, you should override the validation function to add any additional checks you may need for your specific use case.

You are safe to pass the ID of a transaction to the frontend however you shouldn't pass any sensitive information or the transaction object itself.

When passing price information to your payment provider it should always come from the server and it should be verified against the products in your database. Never trust price information coming from the client.

When using webhooks, ensure that you verify the webhook signatures to confirm that the requests are genuinely from Stripe. This helps prevent unauthorized access and potential security vulnerabilities.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.