Integration

The integration phase is mostly completed by engineering and UX teams, though product management is still involved. Similar to the scoping phase, much of the work in the integration phase can be done in parallel. There's a checklist at the bottom of this page that you can use to help track your progress.

Create your platform account

Owner: product management or finance

Before you start building your integration, you need to create a Stripe account and add the Connect application. To create your account:

  1. Complete the registration form.
  2. Fill out your account application.

To add the Connect application to your account:

  1. Register your platform by clicking Connect in the left nav, and then the Settings icon.
  2. Click the Register your platform button and fill out the form.
  3. Click the + New user button on the team page to give your team access to the Dashboard. Engineering, finance, customer service, and product team members often need access. Make sure each user has the appropriate role and email notifications set.
  4. Optionally set up CVC and AVS checks.
  5. Set your default Statement descriptor. These can be set dynamically as well.
  6. Set your platform's payout schedule.

Data migration and storage

Owner: finance or product management

Stripe has a dedicated Migrations Team (support+migrations@stripe.com) that works with you to migrate your data. They need to know what data you intend to migrate, and how it maps to Stripe data. For example, you might want to migrate credit card numbers, and those credit card numbers need to be associated with a customer ID or a connected account ID. Your engineering team can use the Imports: Moving data to Stripe guide to work through the migration process.

If you have an MCC number, provide it to either the Migrations Team or your Sales representative so it can be used with your Stripe account. If you have an existing relationship with AMEX, we can port your SEID to Stripe.

Build seller experience

Owners: engineering, UX

Several teams might be involved in deciding what kind of seller experience to build, but your engineering and UX teams are responsible for building it.

Seller account creation

Every seller on your platform needs a Custom Stripe account. These are created through a seller onboarding form that you provide. Filling out this form also starts the identity verification process. Countries have their own laws when it comes to paying out funds to individuals and companies. These are typically known as “Know Your Customer” (KYC) regulations. To adhere to these regulations, you need to gather identity verification information on your customers and pass it to Stripe for verification. Some information you gather might be personally identifiable information (PII), such as social security numbers. Make sure to use account tokens to securely collect this information.

Collecting identity verification information

You can choose to gather all the required information upfront, or incrementally (tiered verification). The Required Verification Information page lists the minimum and maximum verification requirements by country. If you choose a tiered verification flow, you need to consider how additional information is gathered. There’s a technical recipe that uses webhooks to notify the seller. Some platforms prefer a frontend form that passes the information to Stripe within an API call.

Accepting terms of service

You need to ensure sellers accept the Stripe Connected Account Agreement. This has to be done before they can accept payments. It’s best to present these terms when they sign up. For added clarity, we recommend adding Stripe to your services agreement too.

Notifying sellers after submission

After sellers complete the onboarding form, it’s helpful to send them an email notification confirming you received their application, and whether their account is active. You can send additional notifications for verification status, when accounts receive their first payment, and expected payout dates too. The receiving and reacting to account activity section explains how to do this in more detail.

Collecting bank account information

If you’re collecting bank account information, make sure you know the formats for the countries you operate in. If needed, you can attach multiple bank accounts to a connected account using the external_account parameter.

Configuring a payout schedule

You need to configure payout schedules for your connected accounts. Payout schedules define when connected accounts are paid out, and are separate from your platform’s transfer schedule.

Create seller dashboard and reporting

Owner: engineering, UX

The Stripe Dashboard is available to you and your employees, but your connected accounts won’t have access to it. You can build seller dashboards so your connected accounts can track their payment history (charges, refunds, disputes, etc.) and status. You also have the option to generate reports to share with your connected accounts. You can also use Stripe Sigma to analyze your data.

Receiving and reacting to account activity

Webhooks allow you to monitor and react to changes to your connected accounts. For example, you may want to notify connected accounts if there are payout issues, or if you need more identity verification information. We recommend you implement a webhook endpoint that listens to these events:

account.updated triggers when account status or properties are changed. This event is useful for managing account verification. If additional verification information is needed, this event is triggered and you can check the fields_needed list to find what to collect from your connected account. You can then notify the connected account and even build a form using the update_account API so they can submit the information.

charge.dispute.created triggers when charges are disputed. You can notify your users when these occur and have them submit dispute evidence through your platform.

There are several payout events you might find useful. For example, you can use payout.created to notify connected accounts that a payout is on the way, and then use payout.paid to notify them when the transfer occurs. You could also use payout.failed to notify connected accounts when payouts fail.

Managing refunds and disputes

Platforms are responsible for managing refunds and disputes. For disputes, platform accounts are debited automatically, but you have the option to pull funds back from the seller. It’s recommended that you manage refunds and disputes using the API, but the Stripe Dashboard may be used for special cases. Refund and dispute flows can cause negative balances, which you can read more about in the Negative Balances guide.

Rejecting accounts

Similar to refunds and disputes, Connect Express and Custom integrations can reject accounts using the API. Rejecting accounts is commonly done when you suspect a connected account is fraudulent. Charges are disabled on rejected accounts, and funds can’t be transferred into or out of the account.

Build buyer experience

Owner: engineering, UX

Several teams might be involved in deciding what kind of buyer experience to build, but your engineering and UX teams are responsible for building it.

Collecting payment details

To accept payments, you need to collect payment details from buyers. Most integrations use Stripe Elements to build forms or payment request buttons that securely collect payment details. If you expect buyers to make future or recurring purchases, use the customer_object to save card details for later. This speeds up subsequent checkouts.

Creating charges

For Connect Express and Custom accounts, your platform needs to create charges with the destination or on_behalf_of parameter. This lets you create charges on behalf of connected accounts and take fees in the process.

If you need to accept currencies that are different from the currency deposited in your platform account, you need to change the currency parameter in the charge API call. You should also learn about currency conversions and how to work with multiple currencies using Connect.

Customizing charges

Collecting metadata lets you store additional information on charges, customers, accounts, and more. For example, you might want to assign order IDs or item descriptions to each charge. This information is useful for customer service and finance teams that use the Stripe Dashboard. Metadata is also used in reporting and you can query it in Stripe Sigma. Work with your customer service and finance teams to identify what metadata is useful to them.

Dynamic statement descriptors let you customize the statement description customers see on their credit card or bank statements. This information is useful to customers because it explains what a charge is for, which often reduces dispute risk.

Managing risk

While collecting payment details is enough to accept payments, there’s more you should do to manage risk and protect against fraud. When using Elements, you should collect the cardholder’s name and billing address when you create the token. It’s also common to save customer email addresses and shipping information.

If you’re using the Customer object to create charges, use the email address and shipping information attributes. If you’re using the Charge object, use the description for the email address, and the shipping attribute for the shipping address. Even if you don’t plan to use Stripe’s CVC check, you still need to pass CVCs. Financial institutions consider charges without CVCs as a higher risk, so it's best to pass them anyway.

You can use the fingerprint attribute to uniquely identify card numbers. This lets you check whether multiple customers are using the same card number, which sometimes indicates fraudulent activity that should be blocked.

You can also implement 3D Secure which adds a layer of security. This is recommended for high-risk payments that you or Stripe have identified (e.g., payments you suspect are fraudulent). 3D Secure requires your customers to complete additional steps during the payment process that could impact their checkout experience. For instance, if a customer does not know their 3D Secure information, they might not be able to complete the payment.

Notifications

There are a number of events you can listen to using webhooks. Listening to these events lets you set up notifications like sending emails to customers for successful charges, refunds, disputes, etc. You can also monitor API errors. For example, the card_error type lets you know when a charge fails. You can use this information to notify customers that they need to update payment details or other information. There are several third-party integrations that can help you with notifications as well.

Integration checklist

Use this checklist to help track your progress through the integration phase. Depending on your integration, some of the checklist items might not apply to you, or you might have other items to track that aren't listed. The state of each checkbox is stored in your browser's cache, so you can return to this page at any time to see what has completed.

Was this page helpful? Yes No

Send

Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.