stripe-php: Official PHP Library for the Stripe API

A PHP Wrapper for the Stripe API That Stays Compatible Across API Versions

Stripe's API exposes dozens of resources: customers, payment methods, charges, invoices, subscriptions, and more. Building and maintaining raw HTTP calls to each endpoint requires parsing responses, handling errors, managing authentication headers, and staying current as Stripe's API evolves.

stripe-php removes that work. It provides a pre-defined set of PHP classes for API resources that initialize themselves dynamically from API responses. The README notes that this design makes the library compatible with a wide range of versions of the Stripe API, meaning a response that includes a new field Stripe adds does not break existing code that is unaware of that field.

The library requires the curl, json, and mbstring PHP extensions. Composer handles these dependencies automatically. The MIT license allows use in both open-source and proprietary PHP applications without additional obligations. Containerized environments that strip optional extensions should verify all three are present before deploying.

Installing stripe-php via Composer or Manual Download

Install using Composer:

composer require stripe/stripe-php

Then load the autoloader in your PHP script:

require_once 'vendor/autoload.php';

For projects that do not use Composer, the README describes a manual installation path: download the latest release from the GitHub releases page and include the init.php file directly:

require_once '/path/to/stripe-php/init.php';

The manual path requires you to ensure that the curl, json, and mbstring PHP extensions are loaded. With Composer, those dependencies are verified during installation. Both installation paths give you access to the same library classes and API methods.

Making Your First Stripe API Call with StripeClient

The current pattern uses a StripeClient instance initialized with your API key:

$stripe = new \Stripe\StripeClient('sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$customer = $stripe->customers->create([
    'description' => 'example customer',
    'email' => '[email protected]',
    'payment_method' => 'pm_card_visa',
]);
echo $customer;

The StripeClient object exposes service properties for each API resource (customers, paymentIntents, invoices, and others). Each service provides methods that map to the corresponding Stripe API operations: create, retrieve, update, list, and delete where applicable.

The README notes that a legacy integration pattern existed before version 7.33.0, which used the static Stripe::setApiKey() call instead of a StripeClient instance. Both patterns work, and a migration guide covers the differences. New code should use the StripeClient pattern.

Accessing Response Data and Configuring a PSR-3 Logger

Every API call response is accessible on the returned object through the getLastResponse() method. This gives you the HTTP status code, response headers, and the raw body from the most recent API call made by that object. This is useful for logging the full API response or for extracting headers like the request ID that Stripe uses for support inquiries.

The library supports PSR-3 compatible loggers. To route library log messages to your application's logger rather than the default error_log destination:

\Stripe\Stripe::setLogger($logger);

The library logs minimally by default. The PSR-3 integration means any logger that implements the Psr\Log\LoggerInterface, including Monolog, can be dropped in without additional adapter code.

The README also mentions that the SDK may print notices from Stripe that arrive in the Stripe-Notice response header. These notices are always printed when running in an agent environment. To suppress them when running outside an agent environment, set the STRIPE_SUPPRESS_NOTICES environment variable to true before running your integration.

Custom Timeouts and Proxy Configuration via CurlClient

To change request timeouts, replace the default HTTP client with a configured CurlClient:

$curl = new \Stripe\HttpClient\CurlClient();
$curl->setTimeout(10);
$curl->setConnectTimeout(5);

\Stripe\ApiRequestor::setHttpClient($curl);

The README includes a specific caution about reducing timeouts on write operations such as charge creation: if you locally timeout, the request on Stripe's side may still complete. To avoid charging a customer twice from a timeout retry, use Stripe's idempotency keys when making calls that could be retried.

For proxies, pass a cURL options array to the CurlClient constructor:

$curl = new \Stripe\HttpClient\CurlClient([CURLOPT_PROXY => 'proxy.local:80']);
\Stripe\ApiRequestor::setHttpClient($curl);

This sets the default cURL options for every request made by the SDK from that point forward.

Release Status: Alpha v21 and PHP Version Deprecations

The current release is v21.4.0-alpha.5, published 2026-09-23. The three most recent releases are all alpha tags (alpha.3, alpha.4, alpha.5) released within two weeks of each other in September 2026. The library has an OPENAPI_VERSION file and a CODEGEN_VERSION file in the repository, indicating that the library is generated from Stripe's OpenAPI specification rather than maintained entirely by hand. For production deployments, the safe approach is to pin a specific version in composer.json and review the CHANGELOG before each upgrade rather than accepting the latest alpha tag automatically.

PHP version support is shrinking. The README states that support for PHP 7.2 and 7.3 will be removed soon, and the versioning policy page at docs.stripe.com documents the schedule. PHP 5.4 and 5.5 were end-of-life years before September 2015 and July 2016 respectively, and the library ended support for them at earlier major versions. PHP 5.3 support ended at v5.9.2.

If your project runs on PHP 7.2 or 7.3, upgrading your runtime before it becomes unsupported in stripe-php avoids a forced rush migration later. Applications running PHP 5.x cannot use the current library and should not be connecting to Stripe through an unsupported runtime in any case.

stripe-php vs Building Raw cURL Calls: What the Library Saves

A common alternative to stripe-php for developers who want to minimize dependencies is to write direct cURL calls to Stripe's REST API. This gives full control over the HTTP layer but requires implementing several things the library handles automatically.

First, webhook signature verification. Stripe signs webhook payloads with a shared secret; verifying the signature prevents replay attacks and forged events. stripe-php includes a Webhook class that handles this. Implementing it correctly by hand requires careful handling of the raw request body and the timing window.

Second, idempotency key management. Stripe uses idempotency keys to prevent duplicate charges from retried requests. The library provides the header injection; a raw cURL implementation must add it manually on every request that needs it.

Third, response compatibility across API versions. The library's dynamic initialization handles fields that Stripe adds to API responses in new versions. A hand-rolled parser must be updated when the API response shape changes.

For a project where Stripe is the only external service and dependencies are strictly controlled, the raw cURL path is achievable. For any project that uses Composer already, stripe-php adds a single well-tested dependency that covers these cases.

Editorial conclusion

stripe-php is the practical default for PHP developers integrating Stripe: it avoids building and maintaining HTTP client code, webhook signature verification, and response parsing by hand. It is a poor fit for PHP 5.x projects: the library ended PHP 5.3 support at v5.9.2 and PHP 5.4 and 5.5 support at v6.43.1. The current v21 line is in alpha, so production deployments should pin a specific version and verify the CHANGELOG before upgrading. The three PHP extension requirements (curl, json, and mbstring) should be confirmed before deploying in containerized environments that strip optional extensions.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stripe/stripe-php on GitHub