Add custom payment methods

Use the Payment Element with Checkout Sessions API to enable merchant-instructed payments.

Stripe includes a pre-configured PayPal custom payment method that uses a Stripe adapter you can host in your environment and integrate natively with Checkout.

Complete the deployment steps to deploy the PayPal adapter and configure your integration before you proceed.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('sk_test_...', {
  apiVersion: '2025-03-31.basil; checkout_merchant_instructed_orchestration_preview=v1;',
});

Configure the Checkout Session

Pass custom_payment_method_types=['cpmt_…'] when you create the Checkout Session to display your PayPal payment method. You can view your custom payment methods and IDs in the Custom Payment Methods page of the Dashboard.

const stripe = require('stripe')('sk_test_...', {
  apiVersion: '2025-03-31.basil; checkout_merchant_instructed_orchestration_preview=v1;',
});

const session = await stripe.checkout.sessions.create({
  ui_mode: 'custom',
  // 'setup' mode isn't available for this private preview.
  mode: 'payment' | 'subscription',
  custom_payment_method_types: ['cpmt_1RyfcvBYVDeTVJWf0MxpDkkf'],

  // You can still pass payment_method_types to indicate
  // which Stripe-supported payment methods this Checkout Session accepts.
  payment_method_types: ['card', ...],

  // Or, if using dynamic payment methods, you can continue using
  // payment method configurations.
  payment_method_configuration: 'pmc_123',
  ...
});

Dynamic payment methods don’t display custom payment methods, but you can use both in your integration. The Payment Element adds specified custom payment methods after applying the logic to display Stripe-supported payment methods.

Stripe payment methods

Custom payment method

Client-side changes

Follow the Elements with Checkout Sessions guide for client-side changes when building a page with Stripe Elements using the Checkout Sessions API. To submit the payment, render a “Pay” button that calls confirm from useCheckoutElements.

Limitations for private preview

The PayPal adapter is in private preview and is subject to the following limitations.

API version requirement

You must use the 2025-03-31.basil API version or later. See the basil changelog for details.

PayPal feature support

• Currency conversion: PayPal can automatically convert incoming payments to your preferred currency. Stripe doesn’t support payments converted this way. If you use the adapter, configure PayPal to Accept all payments without converting the currency, either adding to an existing balance or creating a new holding currency where needed. In PayPal, go to Account settings > Payment preferences > Block payments > Update.

• Pending Payment Review: PayPal occasionally moves transactions into a pending_review state that the adapter doesn’t support. We recommend refunding such payments.

Billing considerations

• Customer portal: Customers can manage subscriptions using existing custom payment methods in the customer portal, but can’t update the subscription’s payment method to a custom payment method.

• Free trials: Customers that receive free trials as part of their initial subscription purchase can’t complete the transaction using a custom payment method.

• Revenue recovery: Stripe attempts to retry failed payments through the custom payment method adapter, but off-Stripe payments have limited support for revenue recovery. They support automations and scheduled retries on failed payments, and are included in revenue recovery analytics. They don’t support revenue recovery emails or Smart Retries.

  If your account has Smart Retries selected, CPM retries don’t use the ML model. Instead, they fall back to a schedule based on your Dashboard Max retries and Drop-dead days settings. In live mode, retries are predictable and evenly spaced. In a sandbox, retry timing might appear irregular.

For consistent CPM retry behavior, configure custom retries in your Dashboard retry settings. Because CPM retries are grouped with card payment retries, this setting also applies to card payments. You can then listen for webhook events and programmatically email your customers.

Connect considerations

• Direct charges only: The adapter supports only direct charges, where customers transact directly with the connected account.
• No application fees: You can’t collect application fees on adapter-processed PayPal payments during the private preview.
• The account processing charges hosts the adapter: The account that creates the transaction (for example, a connected account with direct charges) must deploy and host the adapter in their own environment. You can’t share the adapter across accounts.
• Broader Connect support: Additional charge types (destination charges, separate charges and transfers) and application fees aren’t supported during private preview. Contact your Stripe representative to learn more.

Off-Stripe payment support

• Disputes: Stripe doesn’t handle disputes for custom payment methods. You must respond to disputes from third-party processors. You can’t report disputes on payment records at this time.
• Fraud: Radar doesn’t support off-Stripe custom payment methods. Checkout doesn’t support a third-party fraud library integration during private preview.
• Payment records: Off-Stripe transactions generate a Payment Record object instead of a Payment Intent object. The payment record of a custom payment method shows success, failed, and canceled statuses.
• Unified payment and revenue reporting: Some Dashboard charts or Stripe resources (such as Balance Transactions) don’t include Payment Records activity. In some scenarios you might need to join Payment Records API data for a complete dataset.

Checkout considerations

• Redirect-based flows only: PayPal payments through the adapter currently require a full-page redirect to PayPal for customer authorization. This applies to Checkout full page, Checkout elements, and embedded form.

• Other flows in progress: Modal (pop-up) and Express Checkout Element PayPal flows aren’t supported during private preview.

• Payment method availability: When you add the PayPal custom payment method to a Checkout Session, the following payment methods aren’t available:

  • ACSS debit
  • BLIK
  • US bank account
    (only available with the Payment Element)

  With dynamic payment methods, these payment methods don’t appear in Checkout. If you include them in payment_method_types, Stripe returns an error.

Adaptive Pricing

Adaptive Pricing doesn’t work with custom payment methods. If enabled, Checkout presents customers with either localized currencies or with custom payment methods.

Stripe Managed Payments

Stripe Managed Payments makes Stripe the Merchant of Record. The PayPal adapter isn’t compatible with this because it requires a direct integration between you and PayPal, with you as the merchant of record.