Integrating payments can feel daunting, whether you’re building a new app from scratch or using a no-code platform like Bubble. Getting the flow right is critical for user experience and your bottom line. That’s where Stripe, and specifically its modern stripe payment gateway api, comes in. The Stripe Payment Gateway API is a powerful set of tools that lets you build customized payment experiences, and its core today is the Payment Intents API.

This guide breaks down everything you need to know about the Payment Intents API, the engine behind modern Stripe integrations. We’ll walk through the key concepts in a human way, helping you understand how to build a secure and smooth checkout. At Bricks Tech, we implement these patterns daily to build fast-moving MVPs for founders, and this is the foundational knowledge we rely on.

What is the Payment Intent API?

The Payment Intent API is Stripe’s primary tool for processing payments. Think of a PaymentIntent object as a single transaction’s entire journey, from the moment a customer decides to pay until the money is successfully in your account or the payment fails.

Stripe introduced this API to handle complex new regulations like Europe’s Strong Customer Authentication (SCA) laws that appeared in 2019. It abstracts away the complexity of multi step authorizations, making life easier for developers. Using the stripe payment gateway api through Payment Intents gives you built in benefits like automatic 3D Secure handling, preventing accidental double charges, and better reliability.

Each PaymentIntent has a unique ID and tracks the amount, currency, and allowed payment methods, acting as the single source of truth for a payment’s status.

The Payment Intent Lifecycle: From Start to Finish

A PaymentIntent moves through several states during the payment process. Understanding this lifecycle is key to building a robust system that can handle any customer action.

The main states are requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, succeeded, and canceled.

• requires_payment_method: This is the starting point. The PaymentIntent is created, but no payment details (like a credit card) are attached yet. Stripe recommends creating the intent as soon as you know the amount, for example, when a user enters your checkout page.

• requires_confirmation: A payment method is attached, and it’s ready for you to confirm the charge. Many integrations skip this by attaching and confirming in one step.

• requires_action: This is a crucial state. It means the customer needs to do something extra to authorize the payment. For card payments, this usually means completing a 3D Secure challenge (like entering a code from their bank app).

• processing: The payment is underway. You’ll often see this for asynchronous methods like bank debits, which can take several days to clear, while card payments often skip this state entirely because they are so fast.

• requires_capture: The funds have been authorized by the customer’s bank but not yet “captured” or transferred. This only happens if you choose a manual capture flow. This is common in marketplaces where you may authorize at order time and capture on fulfillment. See our Taraki jobs marketplace case study.

• succeeded: Success! The payment is complete, and the funds are on their way to you. This is a final state, meaning you can now fulfill the customer’s order.

• canceled: The payment was canceled by you or it expired. This also releases any hold on the customer’s funds.

Once a PaymentIntent succeeded or is canceled, it cannot be changed or reused. If a payment fails, the intent often reverts to requires_payment_method, allowing the customer to try again with a different card.

Putting It Into Practice: The Payment Flow

Now let’s look at how you actually use these concepts to take a payment with the stripe payment gateway api.

Creating a Payment Intent

The first step is always to create a PaymentIntent on your server. At a minimum, you need to provide an amount (in the smallest currency unit, like cents) and a currency. You can also specify which payment methods you’ll accept.

A best practice is to create the PaymentIntent as soon as your customer lands on the checkout page. This lets you track the entire payment attempt, even if the first try fails.

Confirming a Payment Intent

Confirmation is the step where you tell Stripe, “Okay, go ahead and charge the customer now”. This can be done from your server or, more commonly, from the client side using Stripe.js.

When you confirm a PaymentIntent, Stripe attempts the charge. Most modern integrations use automatic confirmation. Your server creates the intent and passes a special key to the frontend. Your frontend code then uses a function like stripe.confirmCardPayment() to handle the rest, including showing a 3D Secure pop up if needed.

The Client Secret: Your Frontend’s Magic Key

Every PaymentIntent has a client_secret. This is a unique key that is safe to use in your frontend code (your website or mobile app). It allows your client side application to securely confirm the payment without needing your highly sensitive secret API keys.

Your server creates the PaymentIntent and passes only the client secret to the frontend. This design keeps your integration secure and PCI compliant, as the client can perform payment actions but cannot change sensitive details like the amount.

Handling the Details: Payment Methods Explained

A payment can’t happen without a payment method. The stripe payment gateway api has a flexible system for handling them.

The Payment Method Object

A PaymentMethod object is a standardized representation of a customer’s payment instrument, like a credit card, a bank account, or a digital wallet. The PaymentMethods API is the modern way to handle payment details, replacing older concepts like Tokens and Sources.

You can attach a PaymentMethod to a Stripe Customer object to save it for future use, which is perfect for subscriptions or one click checkouts. A PaymentMethod on its own doesn’t move money; it must be used with a PaymentIntent to create a charge.

Understanding Payment Method Types

Stripe supports a huge variety of payment method types, which it groups into families:

• Cards: Visa, Mastercard, Amex, and others.

• Bank Debits: Pulling money from a bank account, like ACH in the US or SEPA in Europe.

• Bank Redirects: The customer is sent to their bank’s website to approve the payment, like iDEAL in the Netherlands.

• Buy Now, Pay Later: Services like Klarna and Afterpay.

• Wallets: Apple Pay, Google Pay, and others.

• Vouchers: The customer gets a barcode to pay with cash at a store, like OXXO in Mexico.

Global Reach: Supported Payment Methods by Region

The right payment methods to offer depend heavily on your customer’s location.

• North America: Cards are king, along with ACH Direct Debit in the US. Apple Pay and Google Pay are also very popular.

• Europe: SEPA Direct Debit is common for recurring payments, while bank redirects like iDEAL (Netherlands), Bancontact (Belgium), and Giropay (Germany) are essential for ecommerce.

• Asia Pacific: Local methods are key. For instance, FPX is popular in Malaysia, and JCB is an important card network in Japan. Alipay and WeChat Pay are dominant for Chinese customers.

• Latin America: Cash based vouchers like OXXO in Mexico and Boleto in Brazil are incredibly common, accounting for a large portion of online sales.

Offering locally preferred payment methods is a proven way to increase conversion. Stripe’s documentation provides a full guide on which methods are popular in each country. If you’re building a regulated fintech product, our fintech app development services can help you navigate method availability, compliance, and KYC from day one.

Single Use vs. Reusable Payment Methods

Some payment methods are inherently single use. An OXXO voucher, for instance, is for one specific payment and cannot be used again. Many bank redirects also create a one time mandate.

Others, like credit cards and bank debits, are reusable. You can save them to a customer’s profile and charge them again for subscriptions or future purchases, which is something roughly 40% of users prefer for faster checkouts. To do this properly, you need the customer’s consent.

Saving for Later: The setup_future_usage Parameter

To turn a one time payment into a reusable one, you use the setup_future_usage parameter on a PaymentIntent. This tells Stripe you plan to save the payment details.

• on_session: Use this if the customer will be present to approve future payments.

• off_session: Use this if you plan to charge the customer automatically in the background, like for a subscription.

Setting this parameter correctly helps Stripe perform the right level of authentication upfront, making future charges more likely to succeed.

Building a Robust Integration

A successful payment integration goes beyond just creating and confirming an intent. It’s about building a reliable system.

Best Practices for the Stripe Payment Gateway API

• Create the PaymentIntent Early: As mentioned, create the intent as soon as the checkout begins to track all attempts.

• Reuse PaymentIntents: If a customer leaves and comes back, reuse the same PaymentIntent for their cart instead of creating a new one. This keeps all attempts for a single order in one place.

• Use Idempotency Keys: An idempotency key is a unique token you send with your API request. It prevents duplicate transactions if a network error causes you to retry the request.

• Listen with Webhooks: Don’t rely only on the immediate API response. Use webhooks to get definitive updates about payment status.

• Use Stripe’s Tools: Leverage Stripe.js and Stripe Elements on the frontend. This minimizes your PCI compliance burden and ensures you handle things like 3D Secure correctly.

At Bricks Tech, we see firsthand how following these practices, especially reusing intents and listening to webhooks, results in more dependable payment flows. Book a 30-min call.

The Importance of Webhooks and Events

A webhook is a notification that Stripe sends to your server when an event happens. For payments, the most important event is payment_intent.succeeded.

Your server should have a dedicated webhook endpoint to listen for these events. This is the most reliable way to know when to fulfill an order, especially for delayed payment methods where confirmation might take hours or days. Relying on webhooks for fulfillment ensures you never miss a successful payment, even if the user closes their browser right after paying. For a broader view of designing resilient third-party integrations, see our comprehensive guide to API integration.

An Event is the actual data object Stripe sends. It contains the event type (like payment_intent.succeeded) and the full PaymentIntent object as it appeared at the time of the event.

Keeping Track: Using Payment Intent Metadata

You can attach your own custom data to a PaymentIntent using the metadata field. This is a set of key value pairs, like order_id: "12345".

This information is for your use only and is not seen by the customer. It’s incredibly useful for reconciling Stripe transactions with your internal database, as the metadata appears right in the Stripe Dashboard. You can also use metadata in Stripe Radar to create custom fraud rules.

Preventing Errors with Idempotency Keys

As mentioned in the best practices, an idempotency key is a unique value you send in an API request header to prevent duplicate operations.

If you send a request to create a payment and a network error occurs, you might not know if it succeeded. If you simply retry, you could charge the customer twice. By sending the same idempotency key with the retry, Stripe recognizes it and simply returns the result of the original request, without running it again. A common strategy is to use your internal order ID as the idempotency key.

Smart Sessions: Reusing a Payment Intent

Yes, you can and should reuse a PaymentIntent if a customer abandons their checkout and returns later. You can’t reuse an intent that has already succeeded or been canceled, but any incomplete intent can be picked back up.

To do this, you would store the PaymentIntent ID associated with the customer’s cart or session. When they return, you retrieve that intent from Stripe and continue the confirmation process. This provides a better user experience and keeps your payment records clean by consolidating all attempts for a single order into one object.

The User Experience and Edge Cases

A great integration handles all the little details that make a checkout feel seamless and secure.

Customer Actions and 3D Secure

Sometimes, a customer needs to perform an extra step to authorize a payment. This is called a “customer action”. The most common one is 3D Secure (3DS), a security protocol that acts like two factor authentication for online card payments.

Regulations like SCA in Europe mandate 3DS for most online transactions. The PaymentIntent API was built to handle this seamlessly. When 3DS is required, the intent moves to the requires_action state. If you’re using Stripe.js, it will automatically detect this and show the customer the necessary verification pop up or redirect them to their bank.

Immediate vs. Delayed Payment Notifications

• Immediate Notifications: For methods like credit cards, you typically get a success or failure notification within seconds. The PaymentIntent moves to a final state almost instantly.

• Delayed Notifications: For methods like ACH bank debits, it can take several business days to get a final confirmation. The PaymentIntent will be in the processing state during this time.

Your user interface should reflect this. For delayed methods, you should tell the user that their payment is “processing” and that you’ll notify them upon completion, which is a perfect use case for a webhook triggered email.

Customizing the Look: Dynamic Statement Descriptors

A statement descriptor is the text that appears on a customer’s bank or card statement. A clear descriptor reduces confusion and prevents chargebacks. The stripe payment gateway api lets you set a dynamic descriptor for each charge.

For card payments, you set a statement_descriptor_suffix. This text gets appended to your account’s default prefix. For example, if your prefix is “BRICKS TECH”, a suffix of “ORDER 123” would result in “BRICKS TECH* ORDER 123” on the statement. The total length, including the asterisk and space, is limited to 22 characters.

The Big Picture: Stripe’s Architecture

To truly master the stripe payment gateway api, it helps to understand how the different objects fit together.

How the Charge Object Relates to Payment Intents

A Charge object represents the actual movement of money. Before PaymentIntents, the Charge was the primary object you worked with. Now, a successful PaymentIntent creates a Charge object automatically.

A single PaymentIntent can actually result in multiple Charge objects if the customer has multiple failed attempts before a successful one. However, only one Charge associated with a PaymentIntent can ever succeed, which prevents double billing. You typically don’t need to interact with Charges directly during the payment flow, but you will reference the Charge ID for things like refunds or dispute handling.

How Stripe.js Creates Payment Methods

Stripe.js is the frontend JavaScript library that securely collects payment information in the browser. When you use Stripe Elements (pre built UI components for card inputs), the sensitive data is sent directly from the user’s browser to Stripe, never touching your server.

A call to a function like stripe.createPaymentMethod() sends this data to Stripe and returns a PaymentMethod object with a unique ID (pm_...). This ID is what you then use to confirm the PaymentIntent. This process is fundamental to Stripe’s security model and drastically reduces your PCI compliance scope.

Stripe Elements vs. Checkout

Stripe offers two main ways to build your frontend:

• Stripe Elements: These are customizable, pre built UI components you can embed directly into your own checkout page. They give you full control over the look and feel of your checkout flow while Stripe handles the secure collection of payment details. This is the choice for a fully custom user experience.

• Stripe Checkout: This is a complete, pre built payment page hosted by Stripe. You redirect your customer to a Stripe URL, where they complete the payment. Checkout is incredibly easy to set up and automatically supports dozens of payment methods, address collection, and handles 3D Secure for you. It’s an excellent choice for launching an MVP quickly.

Many of the startups we work with at Bricks Tech start with Stripe Checkout to get to market faster and ensure a best in class payment experience from day one. Explore our 4-8 week MVP process.

Stripe’s Core Object Model

The main objects in the stripe payment gateway api work together in a logical hierarchy.

1. Customer: Represents your user. A Customer can have multiple saved PaymentMethods.

2. PaymentMethod: A saved payment instrument (card, bank account). It’s attached to a Customer for reuse.

3. PaymentIntent: The intention to collect a payment. It orchestrates the entire transaction, linking a Customer and a PaymentMethod for a specific charge.

4. Charge: The result of a successful PaymentIntent. This is the record of money being moved.

For subscriptions, this extends to Subscription and Invoice objects, which in turn create PaymentIntents each billing cycle to collect payment. Understanding this model helps you navigate the API and build more complex features.

Frequently Asked Questions

What is the main advantage of the Stripe Payment Intent API?

The main advantage is its ability to handle modern payment complexities automatically. It was designed to manage dynamic authentication requirements like 3D Secure, which are required by regulations like SCA in Europe. This makes your integration more robust and future proof.

How does the stripe payment gateway api handle security?

Stripe handles security through a combination of client side tokenization and a clear separation of roles. Sensitive payment data is sent directly from the user’s browser to Stripe’s servers via Stripe.js and Elements, bypassing your server entirely. Your backend then uses secure tokens (like PaymentMethod IDs) and scoped keys (the client secret) to manage the payment, drastically reducing your PCI compliance burden.

Can I use the stripe payment gateway api without writing code?

Yes, to an extent. Many no code platforms like Bubble have plugins that integrate with the stripe payment gateway api. This allows you to build sophisticated payment flows, including subscriptions and marketplaces, with minimal to no custom code. This is a core part of how we build powerful apps quickly for our clients at Bricks Tech.

What is the difference between a Payment Intent and a Charge?

A PaymentIntent represents the entire lifecycle of a payment attempt, from creation through any authentication steps to the final outcome. A Charge is a more fundamental object representing a single, specific attempt to move money. A successful PaymentIntent creates a successful Charge, but a single PaymentIntent might be associated with multiple failed Charges if the customer retries the payment.

How do I handle different currencies with the stripe payment gateway api?

When you create a PaymentIntent, you specify the amount and the currency (e.g., usd, eur, gbp). Stripe will process the charge in that currency. You should also ensure that the payment methods you offer are compatible with the chosen currency. For example, iDEAL only works with EUR.

What is the best way to test my Stripe integration?

Stripe provides a comprehensive test mode with a separate set of API keys. You can use provided test card numbers to simulate different payment scenarios, including successful payments, declines, and payments that require 3D Secure authentication. Always test your integration thoroughly in test mode before going live. For inspiration, browse projects we’ve shipped for founders.