Create direct charges

Create charges directly on the connected account and collect fees.

Create direct charges when customers transact directly with a connected account, often unaware of your platform’s existence. With direct charges:

The payment appears as a charge on the connected account, not your platform’s account.
The connected account’s balance increases with every charge.
Your account balance increases with application fees from every charge.

This charge type is best suited for platforms providing software as a service. For example, Shopify provides tools for building online storefronts, and Thinkific enables educators to sell online courses.

Note

We recommend using direct charges for connected accounts that have access to the full Stripe Dashboard.

Web

iOS

Android

React Native

Build a custom payments integration by embedding UI components on your site, using Stripe Elements. The client-side and server-side code builds a checkout form that accepts various payment methods. See how this integration compares to Stripe’s other integration types.

To see how Link works for a returning user, enter the email demo@stripe.com. To see how Link works during a new signup, enter any other email and complete the rest of the form. This demo only displays Google Pay or Apple Pay if you have an active card with either wallet.

Integration effort

Some code

Integration type

Combine UI components into a custom payment flow

UI customization

CSS-level customization with the Appearance API

First, register for a Stripe account.

Use our official libraries to access the Stripe API from your application:

Create a PaymentIntent
Server-side

Stripe uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process.

The payment methods shown to customers during the checkout process are also included on the PaymentIntent. You can let Stripe automatically pull payment methods from your Dashboard settings or you can list them manually.

Unless your integration requires a code-based option for offering payment methods, don’t list payment methods manually. Stripe evaluates the currency, payment method restrictions, and other parameters to determine the list of supported payment methods. Stripe prioritizes payment methods that help increase conversion and are most relevant to the currency and the customer’s location. Stripe hides lower priority payment methods in an overflow menu.

Create a PaymentIntent on your server with an amount and currency. In the latest version of the API, specifying the automatic_payment_methods parameter is optional because Stripe enables its functionality by default. You can manage payment methods from the Dashboard. Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow.

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern frontend framework like React. Create the server endpoint that serves the client secret:

And then fetch the client secret with JavaScript on the client side:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Collect payment details
Client-side

Collect payment details on the client with the Payment Element. The Payment Element is a prebuilt UI component that simplifies collecting payment details for a variety of payment methods.

The Payment Element contains an iframe that securely sends payment information to Stripe over an HTTPS connection. Avoid placing the Payment Element within another iframe because some payment methods require redirecting to another page for payment confirmation. If you do choose to use an iframe and want to accept Apple Pay or Google Pay, the iframe must have the allow attribute set to equal "payment *".

The checkout page address must start with https:// rather than http:// for your integration to work. You can test your integration without using HTTPS, but remember to enable it when you’re ready to accept live payments.

Set up Stripe.js

The Payment Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Create an instance of Stripe with the following JavaScript on your checkout page:

checkout.js
// Initialize Stripe.js with the same connected account ID used when creating
// the PaymentIntent.
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  stripeAccount: '{{CONNECTED_ACCOUNT_ID}}'

});

Add Stripe Elements and the Payment Element to your payment page

The Payment Element needs a place to live on your payment page. Create an empty DOM node (container) with a unique ID in your payment form.

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Pay</button>
</form>

When the form has loaded, create an instance of the Payment Element and mount it to the container DOM node along with the client secret from the previous step. Pass this value as an option when creating the Elements instance.

The client secret must be handled carefully because it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with the Appearance API
  appearance: {/*...*/},
};
// Set up Stripe.js and Elements to use in checkout form using the client secret
const elements = stripe.elements(options);
// Create and mount the Payment Element
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");

The Payment Element renders a dynamic form that allows your customer to pick a payment method. The form automatically collects all necessary payments details for the payment method selected by the customer. You can customize the appearance of the Payment Element to match the design of your site when you set up the Elements object.

Submit the payment to Stripe
Client-side

Use stripe.confirmPayment to complete the payment using details from the Payment Element. Provide a return_url to this function to indicate where Stripe should redirect the user after they complete the payment. Your user may be first redirected to an intermediate site, like a bank authorization page, before being redirected to the return_url. Card payments immediately redirect to the return_url when a payment is successful.

If you don’t want to redirect for card payments after payment completion, you can set redirect to if_required. This only redirects customers that check out with redirect-based payment methods.

checkout.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Make sure the return_url corresponds to a page on your website that provides the status of the payment. When Stripe redirects the customer to the return_url, we provide the following URL query parameters:

Parameter	Description
`payment_intent`	The unique identifier for the `PaymentIntent`.
`payment_intent_client_secret`	The client secret of the `PaymentIntent` object.

Caution

If you have tooling that tracks the customer’s browser session, you might need to add the stripe.com domain to the referrer exclude list. Redirects cause some tools to create new sessions, which prevents you from tracking the complete session.

Use one of the query parameters to retrieve the PaymentIntent. Inspect the status of the PaymentIntent to decide what to show your customers. You can also append your own query parameters when providing the return_url, which persist through the redirect process.

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Handle post-payment events
Server-side

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard webhook tool or follow the webhook guide to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events is what enables you to accept different types of payment methods with a single integration.

In addition to handling the payment_intent.succeeded event, we recommend handling these other events when collecting payments with the Payment Element:

Event	Description	Action
payment_intent.succeeded	Sent when a customer successfully completes a payment.	Send the customer an order confirmation and fulfill their order.
payment_intent.processing	Sent when a customer successfully initiates a payment, but the payment has yet to complete. This event is most commonly sent when the customer initiates a bank debit. It’s followed by either a `payment_intent.succeeded` or `payment_intent.payment_failed` event in the future.	Send the customer an order confirmation that indicates their payment is pending. For digital goods, you might want to fulfill the order before waiting for payment to complete.
payment_intent.payment_failed	Sent when a customer attempts a payment, but the payment fails.	If a payment transitions from `processing` to `payment_failed`, offer the customer another attempt to pay.

Test the integration

Card number	Scenario	How to test
	The card payment succeeds and doesn’t require authentication.	Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
	The card payment requires authentication.	Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
	The card is declined with a decline code like `insufficient_funds`.	Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
	The UnionPay card has a variable length of 13-19 digits.	Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.

See Testing for additional information to test your integration.

OptionalEnable additional payment methods

Navigate to Manage payment methods for your connected accounts in the Dashboard to configure which payment methods your connected accounts accept. Changes to default settings apply to all new and existing connected accounts.

Consult the following resources for payment method information:

A guide to payment methods to help you choose the correct payment methods for your platform.
Account capabilities to make sure your chosen payment methods work for your connected accounts.
Payment method and product support tables to make sure your chosen payment methods work for your Stripe products and payments flows.

For each payment method, you can select one of the following dropdown options:

On by default	Your connected accounts accept this payment method during checkout. Some payment methods can only be off or blocked. This is because your connected accounts with access to the Stripe Dashboard must activate them in their settings page.
Off by default	Your connected accounts don’t accept this payment method during checkout. If you allow your connected accounts with access to the Stripe Dashboard to manage their own payment methods, they have the ability to turn it on.
Blocked	Your connected accounts don’t accept this payment method during checkout. If you allow your connected accounts with access to the Stripe Dashboard to manage their own payment methods, they don’t have the option to turn it on.

Dropdown options for payment methods, each showing an available option (blocked, on by default, off by default)

Payment method options

If you make a change to a payment method, you must click Review changes in the bottom bar of your screen and Save and apply to update your connected accounts.

Dialog that shows after clicking Save button with a list of what the user changed

Save dialog

Allow connected accounts to manage payment methods

Stripe recommends allowing your connected accounts to customize their own payment methods. This option allows each connected account with access to the Stripe Dashboard to view and update their Payment methods page. Only owners of the connected accounts can customize their payment methods. The Stripe Dashboard displays the set of payment method defaults you applied to all new and existing connected accounts. Your connected accounts can override these defaults, excluding payment methods you have blocked.

Check the Account customization checkbox to enable this option. You must click Review changes in the bottom bar of your screen and then select Save and apply to update this setting.

Screenshot of the checkbox to select when allowing connected owners to customize payment methods

Account customization checkbox

Payment method capabilities

To allow your connected accounts to accept additional payment methods, you must make sure their connected accounts have active capabilities for each payment method. Most payment methods have the same verification requirements as the card_payments capability, with some restrictions and exceptions. The payment method capabilities table lists the payment methods that require additional verification over cards.

Navigate to the Connected account payment settings in the Dashboard to request capabilities on your new and existing connected accounts for each payment method and country combination.

Collect fees

When a payment is processed, your platform can take a portion of the transaction in the form of application fees. You can set application fee pricing in two ways:

Use the Platform Pricing Tool to set and test pricing rules. This no-code feature in the Stripe Dashboard is currently only available for platforms responsible for paying Stripe fees.
Set your pricing rules in-house, specifying application fees directly in a PaymentIntent. Fees set with this method override the pricing logic specified in the Platform Pricing Tool.

Your platform can take an application fee with the following limitations:

The value of application_fee_amount must be positive and less than the amount of the charge. The application fee collected is capped at the captured amount of the charge.
There are no additional Stripe fees on the application fee itself.
In line with Brazilian regulatory and compliance requirements, platforms based outside of Brazil, with Brazilian connected accounts can’t collect application fees through Stripe.
The currency of application_fee_amount depends upon a few multiple currency factors.

The resulting charge’s balance transaction includes a detailed fee breakdown of both the Stripe and application fees. To provide a better reporting experience, an Application Fee is created after the fee is collected. Use the amount property on the application fee object for reporting. You can then access these objects with the Application Fees endpoint.

Earned application fees are added to your available account balance on the same schedule as funds from regular Stripe charges. Application fees are viewable in the Collected fees section of the Dashboard.

Caution

Application fees for direct charges are created asynchronously by default. If you expand the application_fee object in a charge creation request, the application fee is created synchronously as part of that request. Only expand the application_fee object if you must, because it increases the latency of the request.

To access the application fee objects for application fees that are created asynchronously, listen for the application_fee.created webhook event.

Flow of funds with fees

When you specify an application fee on a charge, the fee amount is transferred to your platform’s Stripe account. When processing a charge directly on the connected account, the charge amount—less the Stripe fees and application fee—is deposited into the connected account.

For example, if you make a charge of 10 USD with a 1.23 USD application fee (like in the previous example), 1.23 USD is transferred to your platform account. 8.18 USD (10 USD - 0.59 USD - 1.23 USD) is netted in the connected account (assuming standard US Stripe fees).

Flow of funds for a charge with an application fee

If you process payments in multiple currencies, read how currencies are handled in Connect.

Issue refunds

Just as platforms can create charges on connected accounts, they can also create refunds of charges on connected accounts. Create a refund using your platform’s secret key while authenticated as the connected account.

Application fees are not automatically refunded when issuing a refund. Your platform must explicitly refund the application fee or the connected account—the account on which the charge was created—loses that amount. You can refund an application fee by passing a refund_application_fee value of true in the refund request:

By default, the entire charge is refunded, but you can create a partial refund by setting an amount value as a positive integer. If the refund results in the entire charge being refunded, the entire application fee is refunded. Otherwise, a proportional amount of the application fee is refunded. Alternatively, you can provide a refund_application_fee value of false and refund the application fee separately.

Connect embedded components

Connect embedded components support direct charges. By using the payments embedded component, you can let your connected accounts view payment information, capture charges, and manage disputes from within your site.

The following components display information for direct charges:

Payments component: Displays all of an account’s payments and disputes.
Payments details: Displays information for a specific payment.
Disputes list component: Displays all of an account’s disputes.
Disputes for a payment component: Displays the disputes for a single specified payment. You can use it to include dispute management functionality on a page with your payments UI.

Create direct charges

Create charges directly on the connected account and collect fees.

Note

Integration effort

Integration type

UI customization

Create a PaymentIntentServer-side

Retrieve the client secret

Collect payment detailsClient-side

Set up Stripe.js

Add Stripe Elements and the Payment Element to your payment page

Submit the payment to StripeClient-side

Caution

Handle post-payment eventsServer-side

Test the integration

OptionalEnable additional payment methods

Allow connected accounts to manage payment methods

Payment method capabilities

Collect fees

Caution

Flow of funds with fees

Issue refunds

Connect embedded components

See also

Create a PaymentIntent
Server-side

Collect payment details
Client-side

Submit the payment to Stripe
Client-side

Handle post-payment events
Server-side