[ Web Proxy ]
URL:
Viewing: https://stripe.com/de-lu/docs/api [Back]  [Original]
Stripe API Reference
Find anything
/
Ask AI
Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

API Reference

The Stripe API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Stripe API in sandboxes without affecting your live data or interacting with banking networks. The API key that you use to authenticate the request determines whether the request runs in live mode or in a sandbox. Sandboxes support all v2 APIs. Test mode sandboxes support some v2 APIs.

The Stripe API doesnt support bulk updates. You can work on only one object per request.

The Stripe API differs for every account as we release new versions and tailor functionality. Log in to see docs with your test key and data.

Was this section helpful?YesNo

Just getting started?

Check out our development quickstart guide.

Not a developer?

Use Stripes no-code options or apps from our partners to get started with Stripe and to do more with your Stripe accountno code required.

Base URL
https://api.stripe.com
Client Libraries
Ruby
Python
PHP
Java
Node.js
Go
.NET

By default, the Stripe API Docs demonstrate using curl to interact with the API over HTTP. Select one of our official client libraries to see examples in code.

Authentication

The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard.

Test mode secret keys start with sk_test_ and have unrestricted access to their sandboxes. In live mode, you configure a restricted API key (starts with rk_live_) with specific API permissions. Using a restricted API key with only a subset of API permissions limits the damage a bad actor could cause if they obtained the key. In both test mode and live mode, you can create as many restricted API keys as you need for different use cases or components of your application. We also create a live mode secret key (starts with sk_live_) that grants access to all Stripe API resources. To protect your business, use restricted API keys instead.

Your API keys carry many privileges. Follow best practices to keep your keys safe. Dont embed secret or restricted API keys in source code or client-side applications. Instead, use your server platforms secrets vault to provide keys to your server-side applications. If your platform doesnt offer a secrets vault, set your keys in environment variables.

Make all API requests over HTTPS. Calls made over plain HTTP fail. API requests without authentication also fail.

Was this section helpful?YesNo
Authenticated Request
curl https://api.stripe.com/v1/charges \
  -u sk_test_wU7nrJCZspk1NPDxiQgAF05qsk_test_wU7nrJCZspk1NPDxiQgAF05q:
# The colon prevents curl from asking for a password.
Your API Key

A sample test API key is included in all the examples here, so you can test any example right away. Do not submit any personally identifiable information in requests made with this key.

To test requests using your account, replace the sample API key with your actual API key or sign in.

Errors

Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the information provided. For example, an omitted required parameter, a failed charge, or a declined card.
  • Codes in the 5xx range indicate an error with the Stripe servers (these are rare).
Was this section helpful?YesNo

Attributes

  • codenullable string

    For some errors that could be handled programmatically, a short string indicating the error code reported.

  • decline_codenullable string

    For card errors resulting from a card issuer decline, a short string indicating the card issuers reason for the decline if they provide one.

  • messagenullable string

    A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.

  • paramnullable string

    If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.

  • payment_intentnullable object

    The PaymentIntent object for errors returned on a request involving a PaymentIntent.

  • typeenum

    The type of error returned. One of api_error, card_error, idempotency_error, or invalid_request_error

    Possible enum values
    api_error
    card_error
    idempotency_error
    invalid_request_error

More
Expand all

  • advice_codenullable string

  • chargenullable string

  • doc_urlnullable string

  • network_advice_codenullable string

  • network_decline_codenullable string

  • payment_methodnullable object

  • payment_method_typenullable string

  • request_log_urlnullable string

  • setup_intentnullable object

  • sourcenullable object

HTTP Status Code Summary
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, often due to missing a required parameter.
401UnauthorizedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesnt have permissions to perform the request.
404Not FoundThe requested resource doesnt exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
424External Dependency FailedThe request couldnt be completed due to a failure in a dependency external to Stripe.
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething went wrong on Stripes end. (These are rare.)
Error Types
api_errorAPI errors cover any other type of problem (e.g., a temporary problem with Stripes servers), and are extremely uncommon.
card_errorCard errors are the most common type of error you should expect to handle. They result when the user enters a card that cant be charged for some reason.
idempotency_errorIdempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first requests API endpoint and parameters.
invalid_request_errorInvalid request errors arise when your request has invalid parameters.
Web Proxy Viewer  |  New URL  |  Original Page