What we do
Tools
Industries
Department
How we workLet's talk →
Home/Stripe/Stripe API
Stripe API

The Stripe API: Your Keys, a First Payment, and the Bugs Test Mode Hides

The Stripe API is a REST API your server calls with a secret or restricted key. Stripe.js and Elements are the browser side, which collect card details so they never touch your server. Below: where the keys are, the order to build a first payment in, the problems that only show up with real traffic, and where the numbers you'll need later actually live.

If you came for one thing

Your keys: on the API keys page in the Dashboard (dashboard.stripe.com/apikeys). Sandbox keys start pk_test_ and sk_test_, live keys pk_live_ and sk_live_. Only the publishable key is safe in browser code.

Which server key: Stripe now recommends a restricted key (rk_) with only the permissions your code needs, rather than the all-powerful secret key.

The docs: docs.stripe.com, with the full API reference and a guide per use case. Official SDKs cover Node, Python, Ruby, PHP, Java, Go and .NET.

Server or browser? Your server creates and reads objects through the API. Stripe.js runs in the browser, and Elements is its set of ready-made payment form components.

Your first Stripe payment, in the order that works

This is the custom-form path with the Payment Element. If Stripe's hosted Checkout page is enough for you, see our Stripe Checkout page instead, because it skips most of this.

  1. 1

    Work in a sandbox

    Use a sandbox and its test keys while you build. Nothing you create there can mix with live data, and card networks never see the payments.

  2. 2

    Create a PaymentIntent on your server

    Send the amount in the smallest currency unit (so $25.00 is 2500) and the currency. Return the PaymentIntent's client_secret to the page, never the key.

  3. 3

    Mount the Payment Element and confirm

    Load Stripe.js with your publishable key, mount the Payment Element with the client secret, and call stripe.confirmPayment when the customer submits. Stripe handles 3D Secure prompts inside that call.

  4. 4

    Fulfill from the webhook, not the redirect

    Listen for payment_intent.succeeded and ship, grant access or mark the invoice paid from there. A customer who closes the tab never reaches your success page, but the event still arrives. Our Stripe webhook setup guide covers the endpoint itself.

    Watch for: testing webhooks on your laptop. stripe listen --forward-to localhost:4242/webhook in the Stripe CLI forwards events to your local server, and stripe trigger payment_intent.succeeded fires one on demand.

  5. 5

    Run the failure cases, then switch keys

    Card 4242 4242 4242 4242 succeeds. Stripe's testing page lists cards that decline, ask for 3D Secure or open a dispute. Run refunds too. Then swap in live keys and the live webhook signing secret, which is a different value from the sandbox one.

Stripe API bugs that only appear with real traffic

Most of these come from retries, concurrency or volume, which a developer clicking through checkout alone never produces.

A retry charges the customer twice

How you'll know: A request timed out, your code tried again, and now there are two payments for one order.

Fix: Send an Idempotency-Key header on every POST, generated once per order or action (a UUID works). Stripe returns the first result for a repeat. Keys can be up to 255 characters, are kept for at least 24 hours, and Stripe rejects a reuse with different parameters.

Signature checks fail only in production

How you'll know: The webhook endpoint returns 400 for every event, though the same code passed against the CLI.

Fix: Your framework parsed the JSON before Stripe's library saw it. Verification needs the raw request body. Also check you're using the signing secret for this endpoint in live mode; sandbox and live have different ones.

Events arrive out of order, or twice

How you'll know: An invoice.paid lands before the invoice.created it depends on, or an order gets fulfilled twice.

Fix: Stripe doesn't promise order and can deliver an event more than once. Store each event ID you've processed and skip repeats. If you need the related object, fetch it from the API rather than waiting for its event. In live mode Stripe keeps retrying a failed delivery for up to three days.

Webhook payloads don't match your SDK

How you'll know: Fields your code expects are missing or renamed in events, though API responses look fine.

Fix: Each webhook endpoint has its own API version. It defaults to your account's version unless you set one when you create the endpoint, and the version your code sends per request doesn't change it. Typed SDKs such as .NET, Java and Go need the endpoint's version to match the SDK's, so set it explicitly and change it on purpose.

429 errors in a sale or a backfill

How you'll know: Requests fail with 429 Too Many Requests, and the Stripe-Rate-Limited-Reason header says which limit you hit.

Fix: The global limit is 100 requests a second in live mode and 25 in a sandbox, with most single endpoints capped at 25. Back off with jitter and queue bulk jobs. Don't load-test in a sandbox: its lower limits fail tests production would pass.

Polling instead of listening

How you'll know: A job checks every open PaymentIntent every few minutes to see if it's paid.

Fix: Stripe expects read requests to average no more than 500 per transaction over 30 days (with at least 10,000 a month allowed). Webhooks tell you when something changes, so you only read what moved.

Finding the number you need inside Stripe’s objects

Taking the payment is one object. The questions finance and ops ask afterwards live in others, and this is where most integrations stop short.

You need Where it is in the API The catch
Stripe's fee on one payment The balance transaction behind the charge: expand latest_charge.balance_transaction on the PaymentIntent It's in the smallest unit of your settlement currency, which may not be the currency the customer paid in.
Which payments a payout covered List balance transactions with payout=po_... This works for automatic payouts. Each line is a charge, refund, fee or adjustment, not an order, so you still have to map them back.
Your own order number on a payment metadata on the PaymentIntent, set when you create it Up to 50 keys, 500 characters a value. With Checkout, metadata on the Session stays on the Session unless you pass it through payment_intent_data.metadata.
Refunds and disputes against an order Refund and Dispute objects, and the charge.refunded and charge.dispute.created events A charge can have several partial refunds. Disputes come with a deadline; our Stripe disputes page covers the evidence side.
A month of everything, for the books Stripe's reports, Sigma or Data Pipeline, rather than paging through list endpoints Stripe's own docs point data-heavy jobs there. Paging through every charge costs read requests and time.

Questions people ask

Where do I find my Stripe API keys?

On the API keys page of your Stripe Dashboard, at dashboard.stripe.com/apikeys. Switch between sandbox and live mode to see each set. A live secret or restricted key you create yourself is shown only once, so store it in a secrets vault or environment variable straight away.

What's the difference between Stripe.js and the Stripe API?

The Stripe API is what your server calls, with a secret or restricted key, to create and read payments, customers and everything else. Stripe.js is a JavaScript library that runs in the customer's browser with your publishable key and collects payment details directly, so card numbers never pass through your server.

What's a Stripe API version, and do I need to worry about it?

Stripe versions its API by release date, and your account has a default version that requests and events use. You can override it per request in your code. Webhook events follow the version of the endpoint they're sent to, which is the account version unless you chose another when creating the endpoint. If you use a typed SDK (.NET, Java, Go), that endpoint version has to match the SDK. You don't need to chase every release, but upgrade deliberately and test.

Where is Stripe's official API documentation?

At docs.stripe.com. It holds the API reference, guides for each product, and the testing page with test card numbers. The older stripe.com/docs links send you there.

Do I need Stripe Elements if I'm already using Stripe.js?

Elements is part of Stripe.js, not a separate product. It gives you ready-made, styleable form components, such as the Payment Element, so you don't build card fields and validation yourself. Most custom payment forms use it.

Is there a fee to use the Stripe API?

No separate one. You pay Stripe's normal fees on the payments you process, whether they come through the API, Checkout or a Payment Link. Some products, such as Billing or Tax, are priced on top.

Should I use the Charges API or PaymentIntents?

PaymentIntents. Stripe treats the Charges API as legacy. PaymentIntents handle 3D Secure and other extra steps, and a Charge object is still created underneath, which is where you find the fee and the payout link.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.