Movatterモバイル変換

[0]ホーム
URL:

API Reference

The Stripe API is organized aroundREST. Our API has predictable resource-oriented URLs, acceptsform-encoded request bodies, returnsJSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Stripe API in test mode, which doesn’t affect your live data or interact with the banking networks. The API key you use toauthenticate the request determines whether the request is live mode or test mode. Test mode supports somev2 APIs.

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

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

Just getting started?

Check out ourdevelopment quickstart guide.

Not a developer?

Use Stripe’sno-code options or apps fromour partners to get started with Stripe and to do more with your Stripe account—no code required.

Base URL
https://api.stripe.com
Client Libraries

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

Authentication

The Stripe API usesAPI keys to authenticate requests. You can view and manage your API keys inthe Stripe Dashboard.

Test mode secret keys have the prefixsk_test_ and live mode secret keys have the prefixsk_live_. Alternatively, you can userestricted API keys for granular permissions.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made overHTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticated Request
curl https://api.stripe.com/v1/charges \
  -usk_test_09l3shT...CzzZZsiLl2vAsk_test_09l3shTSTKHYCzzZZsiLl2vA:
# 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 orsign in.

Errors

Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the2xx range indicate success. Codes in the4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the5xx range indicate an error with Stripe’s servers (these are rare).

Some4xx errors that could be handled programmatically (e.g., a card isdeclined) include anerror code that briefly explains the error reported.

Attributes

  • codenullable string

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

  • decline_codenullable string

    For card errors resulting from a card issuer decline, a short string indicating thecard issuer’s 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

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

  • typeenum

    The type of error returned. One ofapi_error,card_error,idempotency_error, orinvalid_request_error

    Possible enum values
    api_error
    card_error
    idempotency_error
    invalid_request_error

More

  • 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 doesn’t have permissions to perform the request.
404Not FoundThe requested resource doesn’t exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
424External Dependency FailedThe request couldn’t 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 Stripe’s end. (These are rare.)
Error Types
api_errorAPI errors cover any other type of problem (e.g., a temporary problem with Stripe’s 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 can’t be charged for some reason.
idempotency_errorIdempotency errors occur when anIdempotency-Key is re-used on a request that does not match the first request’s API endpoint and parameters.
invalid_request_errorInvalid request errors arise when your request has invalid parameters.

Handling errors

Our Client libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

# Select a client library to see examples of
# handling different kinds of errors.

Expanding Responses

Many objects allow you to request additional information as an expanded response by using theexpand request parameter. This parameter is available on all API requests, and applies to the response of that request only. You can expand responses in two ways.

In many cases, an object contains the ID of a related object in its response properties. For example, aCharge might have an associated Customer ID. You can expand these objects in line with the expand request parameter. Theexpandable label in this documentation indicates ID fields that you can expand into objects.

Some available fields aren’t included in the responses by default, such as thenumber andcvc fields for the Issuing Card object. You can request these fields as an expanded response by using theexpand request parameter.

You can expand recursively by specifying nested fields after a dot (.). For example, requestingpayment_intent.customer on a charge expands thepayment_intent property into a full PaymentIntent object, then expands thecustomer property on that payment intent into a full Customer object.

You can use theexpand parameter on any endpoint that returns expandable fields, including list, create, and update endpoints.

Expansions on list requests start with thedata property. For example, you can expanddata.customers on a request to list charges and associated customers. Performing deep expansions on numerous list requests might result in slower processing times.

Expansions have a maximum depth of four levels (for example, the deepest expansion allowed when listing charges isdata.payment_intent.customer.default_source).

You can expand multiple objects at the same time by identifying multiple items in theexpand array.

curl https://api.stripe.com/v1/charges/ch_3LmzzQ2eZvKYlo2C0XjzUzJV \
  -usk_test_09l3shT...CzzZZsiLl2vAsk_test_09l3shTSTKHYCzzZZsiLl2vA: \
  -d"expand[]"=customer \
  -d"expand[]"="payment_intent.customer" \
  -G
Response
{
"id":"ch_3LmzzQ2eZvKYlo2C0XjzUzJV",
"object":"charge",
"customer":{
"id":"cu_14HOpH2eZvKYlo2CxXIM7Pb2",
"object":"customer",
// ...
},
"payment_intent":{
"id":"pi_3MtwBwLkdIwHu7ix28a3tqPa",
"object":"payment_intent",
"customer":{
"id":"cus_NffrFeUfNV2Hib",
"object":"customer",
// ...
},
// ...
},
// ...
}
[8]ページ先頭
©2009-2026 Movatter.jp