Create your account
Owner: product management or finance
Before you start building your integration, you need to create a Stripe account:
- Complete the registration form.
- Fill out your account application.
- 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.
- Optionally set up CVC and AVS checks.
- Set your default Statement descriptor.
Data migration and storage
Owner: finance or product management
Stripe has a dedicated Migrations Team (email@example.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 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.
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.
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.
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.
Below is a recommended list of events you can build notifications off of. These aren’t required to integrate with Stripe, but they can help automate some manual tasks. Depending on your unique use case, some may not apply.
- charge.succeeded: you can use this event to send customized email receipts when charges succeed (you can also send them when charges are created).
- payout.created and payout.paid: these events can be used to trigger notifications for internal teams (e.g., finance) so they know when to expect funds in your company’s bank account.
- charge.dispute.created and charge.dispute.updated: with disputes, it’s important to submit evidence before the deadline. These events can be used to track the dispute process so you respond to disputes quickly.
Card decline and update notifications
When charges are declined, Stripe returns a reason as part of the response to your charge request. You can parse these responses for the decline code to generate notifications for your customers. For example, if a charge is declined because of insufficient funds, you can build functionality that emails the customer and asks them to use a different card, or that they reach out to their bank.
Managing refunds and disputes
You can manage refunds and disputes using the Stripe Dashboard or the API. If needed, you can build webhooks that listen to events like charge.refunded or charge.dispute.closed so you can pull refund and dispute information into your internal systems.
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.