Add custom payment methods

Add custom payment methods to the Payment Element.

The Stripe Payment Element lets your users pay with many payment methods through a single integration. Use custom payment methods if you need to display additional payment methods that aren’t processed through Stripe. If you use custom payment methods, you can optionally record purchases processed outside Stripe to your Stripe account for reporting purposes.

To configure a custom payment method, create it in your Stripe Dashboard, and provide a display name and icon that the Payment Element also displays. The Stripe Dashboard also provides access to over 50 preset custom payment methods. After you create the payment method, follow the guide below to configure the Payment Element. Setting up the Payment Element requires some additional configuration work because custom payment method transactions process and finalise outside of Stripe.

Note

When integrating with a third party payment processor, you’re responsible for complying with applicable legal requirements, including your agreement with your PSP, applicable laws, and so on.

This guide adds a custom payment method using the HTML or JS example from the Collect payment details before creating an Intent guide.

Before you begin

Create a Stripe account or sign in.
Follow the Collect payment details before creating an Intent guide to complete a payments integration.
Then, for each custom payment method you want to provide, follow the steps below.

Create your custom payment method in the Dashboard
Dashboard

Go to Settings > Payments > Custom Payment Methods to get to the custom payment methods page. Create a new custom payment method and provide the display name and logo that the Payment Element displays.

Choose the right logo

If you provide a logo with a transparent background, consider the background colour of the Payment Element on your page and make sure that it stands out.
If you provide a logo with a background fill, we won’t provide rounded corners – include these in your file.
Choose a logo variant that can scale down to 16 pixels x 16 pixels. This is often the standalone logo mark for a brand.

After creating the custom payment method, the Dashboard displays the custom payment method ID (beginning with cpmt_) needed in step 2.

Add the custom payment method type to your Stripe elements config
Client-side

In your checkout.js file where you initialise Stripe Elements, specify the customPaymentMethods to add to the Payment Element. In addition to providing the ID from step 1 (it begins with cpmt_), provide the options.type and optional subtitle.

checkout.js
const elements = stripe.elements({
  // ...
  customPaymentMethods: [
    {
      id: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
,
      options: {
        type: 'static',
        subtitle: 'Optional subtitle',
      }
    }
  ]
});

When the Payment Element loads, it now shows your custom payment method.

Stripe Payment Element showing a custom payment method called PM Name.

OptionalDisplay embedded custom content
Preview
Client-side

Display your content within the context of the Payment Element by using the embedded customPaymentMethod type. You can use embedded content to integrate your custom payment form logic with the Payment Element UI.

Stripe Payment Element showing a custom payment method called PM Name, with custom content overlaid in the form container.

To use the embed functionality, add a custom payment method with type: 'embedded' and manage your custom content using these two callbacks:

handleRender: handleRender is called when a payment method is selected. It contains a reference to a container DOM node which you can render your content into.
(Optional) handleDestroy: the handleDestroy hook is called when a payment method is deselected and when Payment Element is unmounted. Use it to perform cleanup, such as removing event listeners or a custom SDK.

Security tip

You should only render trusted content within the container provided by handleEmbed. Rendering markup that you don’t control, especially from a user or an unsanitised source, can easily introduce a cross-site scripting vulnerability (XSS).

Tools such as React Portals allow you to integrate your rendering logic with your application code:

checkout.js
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

export default function App() {
  const [embedContainer, setEmbedContainer] = useState();

  const options = {
    customPaymentMethods: [
      {
        id: '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}',
        options: {
          type: 'embedded',
          subtitle: 'Embedded payment method',
          embedded: {
            handleRender: (container) => {
              setEmbedContainer(container);
            },
            handleDestroy: () => {
              setEmbedContainer(null);
            }
          }
        }
      }
    ]
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutFormWithPaymentElement />
      {embedContainer && createPortal(<EmbeddedCpmContent />, embedContainer)}
    </Elements>
  );
};

Handle payment method submission
Client-side

Update the handleSubmit function that’s called when users click the pay button on your website so that custom payment method transactions are processed outside Stripe.

The elements.submit() function retrieves the currently selected payment method type. If the selected payment method is your custom payment method, process the transaction accordingly. For example, you might show a modal and then process the payment on your own server, or redirect your customer to an external payment page.

checkout.js
async function handleSubmit(e) {
  const { submitError, selectedPaymentMethod } = await elements.submit();

  if (selectedPaymentMethod === '{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}'
) {
    // Process CPM payment on merchant server and handle redirect
    const res = await fetch("/process-cpm-payment", { method: 'post' });
    ...
  } else {
    // Process Stripe payment methods
    ...
  }
}

OptionalSpecify the order of custom payment methods
Client-side

By default, the Payment Element shows custom payment methods last. To manually specify the order of payment methods, set the paymentMethodOrder property on the options configuration when creating your Payment Element instance.

checkout.js
const paymentElement = elements.create('payment', {
  // an array of payment method types, including custom payment method types
  paymentMethodOrder: [...]
});

Add custom payment methods