Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseManaged Payments
Use Payment Links
Build a checkout page
Build an advanced integration
Build an in-app integration
    Overview
    Payment Sheet
    Embedded Payment Element
      Accept in-app payments
      Customize look and feel
      Add custom payment methods
      Filter card brands
    Link out for in-app purchases
    Collect addresses
    US and Canadian cards
Payment methods
Add payment methods
Manage payment methods
Faster checkout with Link
Payment interfaces
Payment Links
Checkout
Web Elements
In-app Elements
Payment scenarios
Custom payment flows
Flexible acquiring
Orchestration
In-person payments
Terminal
Other Stripe products
Financial Connections
Crypto
Climate
HomePaymentsBuild an in-app integrationEmbedded Payment Element

Add custom payment methodsPublic preview

Add custom payment methods to the Embedded Payment Element.

Copy page

The Mobile 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 of 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 Mobile 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 Mobile Payment Element. Setting up the Mobile Payment Element requires some additional configuration work because custom payment method transactions process and finalize 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.

Before you begin

  1. Create a Stripe account or sign in.
  2. Follow the guide to accept in-app payments to complete a payments integration.

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 color of the Payment Element on your page and make sure that it displays clearly.
  • If you provide a logo with a background fill, provide rounded corners in your file because we won’t provide them.
  • Choose a logo variant that can scale down to 16 pixels × 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 custom payment method types

When you create your EmbeddedPaymentElement.Configuration object and initialize the EmbeddedPaymentElement, specify the custom payment methods that you want to add to the Embedded Payment Element and a handler to complete the payment.

@_spi(EmbeddedPaymentElementPrivateBeta) @_spi(CustomPaymentMethodsBeta) import StripePaymentSheet class MyCheckoutVC: UIViewController { func createEmbeddedPaymentElement() async throws -> EmbeddedPaymentElement { // ... var configuration = EmbeddedPaymentElement.Configuration() let customPaymentMethod = EmbeddedPaymentElement.CustomPaymentMethodConfiguration.CustomPaymentMethod(id: "cpmt_...", subtitle: "Optional subtitle") configuration.customPaymentMethodConfiguration = .init(customPaymentMethods: [customPaymentMethod], customPaymentMethodConfirmHandler: handleCustomPaymentMethod(_:_:)) // ... } func handleCustomPaymentMethod( _ customPaymentMethodType: EmbeddedPaymentElement.CustomPaymentMethodConfiguration.CustomPaymentMethod, _ billingDetails: STPPaymentMethodBillingDetails ) async -> EmbeddedPaymentElementResult { // ...explained in the next step } }

Complete the payment

When you call confirm on your EmbeddedPaymentElement instance and the customer has selected a custom payment method, it calls the handler with the custom payment method, and uses any billing details that you collected in the sheet.

Your implementation completes the payment (for example, by using your custom payment method provider’s SDK) and returns from the function with the result of the payment: completed, canceled, or failure(error:).

@_spi(EmbeddedPaymentElementPrivateBeta) @_spi(CustomPaymentMethodsBeta) import StripePaymentSheet class MyCheckoutVC: UIViewController { func createEmbeddedPaymentElement() async throws -> EmbeddedPaymentElement { // ... var configuration = EmbeddedPaymentElement.Configuration() let customPaymentMethod = EmbeddedPaymentElement.CustomPaymentMethodConfiguration.CustomPaymentMethod(id: "cpmt_...", subtitle: "Optional subtitle") configuration.customPaymentMethodConfiguration = .init(customPaymentMethods: [customPaymentMethod], customPaymentMethodConfirmHandler: handleCustomPaymentMethod(_:_:)) // ... } func handleCustomPaymentMethod( _ customPaymentMethodType: EmbeddedPaymentElement.CustomPaymentMethodConfiguration.CustomPaymentMethod, _ billingDetails: STPPaymentMethodBillingDetails ) async -> EmbeddedPaymentElementResult { // Your implementation needs to complete the payment with the payment method provider // When the payment completes, cancels, or fails, return the result. // This example code just immediately fails: let exampleError = NSError(domain: "MyErrorDomain", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to complete payment!"]) return .failed(error: exampleError) } }

OptionalSpecify the order of custom payment methods

Collect billing details

You can collect billing details using billingDetailsCollectionConfiguration on the Embedded Payment Element configuration. However, custom payment methods don’t collect billing details by default. To enable billing detail collection, set disableBillingDetailCollection to false on your CustomPaymentMethod.

var customPaymentMethod = EmbeddedPaymentElement.CustomPaymentMethodConfiguration.CustomPaymentMethod(id: "cpmt_...", subtitle: "Optional subtitle") customPaymentMethod.disableBillingDetailCollection = false

Test your integration

  1. Go through your checkout flow and verify that the Mobile Payment Element displays your custom payment method. This example configures your custom payment method in the second position after cards.
  2. Choose your custom payment method.
  3. Click Pay now to test your custom payment method integration. Verify that your integration completes the transaction and that any post-payment actions (for example, displaying a confirmation page, success message, or failure message) still work with your custom payment method integration.
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc