Stripe PHP

https://github.com/stripe/stripe-php
Admin
The Stripe PHP library provides convenient access to the Stripe API from applications written in the...
Tokens:394,340
Snippets:2,491
Trust Score:9.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies with just or composer

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Installs project dependencies. The 'just install' command is equivalent to 'composer install'.

```bash
just install
# or: composer install
```

--------------------------------

### Install a public preview SDK with composer require

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Use this command to install a specific public preview SDK version. Replace the version placeholder with the desired version from the releases page. Pinning the version is recommended to avoid breaking changes between preview versions.

```bash
composer require stripe/stripe-php:v<replace-with-the-version-of-your-choice>
```

--------------------------------

### Install Stripe PHP with Composer

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Run this command in your terminal to install the Stripe PHP bindings via Composer. Requires PHP 7.4.0 or later.

```bash
composer require stripe/stripe-php
```

--------------------------------

### Run the test suite with just or phpunit

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Runs the full test suite. Requires dependencies installed (including PHPUnit).

```bash
just test
# or: ./vendor/bin/phpunit
```

--------------------------------

### Install and run stripe-mock

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Fetches and runs stripe-mock from a background terminal. Required for the test suite.

```bash
go install github.com/stripe/stripe-mock@latest
stripe-mock
```

--------------------------------

### Install Composer on Mac OS

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Installs Composer via Homebrew on Mac OS. Required before installing dependencies.

```bash
brew install composer
```

--------------------------------

### Include init.php for manual installation

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Use this snippet to manually include the Stripe PHP bindings without Composer. Replace '/path/to/stripe-php/init.php' with the actual path to the downloaded release.

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

--------------------------------

### Create a customer with StripeClient

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Simple usage example that instantiates StripeClient with a test secret key and creates a customer with description, email, and payment_method. The resulting customer object is echoed.

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

--------------------------------

### Replace allTransactions with allSourceTransactions on SourceService

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v9

The `allTransactions` method on `SourceService` is removed. Use `allSourceTransactions` instead. The example shows the old and new calls with the same source ID.

```php
// change
$stripe->sources->allTransactions("src_12345");
// to
$stripe->sources->allSourceTransactions("src_12345");
```

--------------------------------

### Replace sourceTransactions with allSourceTransactions on Source

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v9

The `sourceTransactions` method on `Source` is removed. Use `allSourceTransactions` instead. The example shows the old and new calls with the same source ID.

```php
// change
Source::sourceTransactions("src_12345");
// to
Source::allSourceTransactions("src_12345");
```

--------------------------------

### Send custom requests with rawRequest and deserialize

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Use rawRequest to call undocumented APIs or bypass method definitions. Available from version 16 of the SDK. For GET requests, the params argument must be null and the query string must be written explicitly. The response body is a string; use deserialize to get a StripeObject.

```php
$stripe = new \Stripe\StripeClient('sk_test_xyz');
$response = $stripe->rawRequest('post', '/v1/beta_endpoint', [
  "caveat": "emptor"
], [
  "stripe_version" => "2022-11_15",
]);
// $response->body is a string, you can call $stripe->deserialize to get a \Stripe\StripeObject.
$obj = $stripe->deserialize($response->body);

// For GET requests, the params argument must be null, and you should write the query string explicitly.
$get_response = $stripe->rawRequest('get', '/v1/beta_endpoint?caveat=emptor', null, [
  "stripe_version" => "2022-11_15",
]);
```

--------------------------------

### Replace usageRecordSummaries with allUsageRecordSummaries on SubscriptionItem

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v9

The `usageRecordSummaries` method on `SubscriptionItem` is removed. Use `allUsageRecordSummaries` instead. The example shows the old and new calls with the same subscription item ID.

```php
// change
SubscriptionItem::usageRecordSummaries("sub_12345");
// to
SubscriptionItem::allUsageRecordSummaries("sub_12345");
```

--------------------------------

### Request with per-request API version 2022-08-01

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v12

This example shows a request that uses API version 2022-08-01 in both previous versions and v12 by passing 'stripe_version' as a request option. It covers both StripeClient and the global client.

```php
// If using StripeClient
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xyz',
]);

$stripe->customers->create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
],
[
  'stripe_version' => '2022-08-01',
]);

// If using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');

\Stripe\Customer::create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
],
[
  'stripe_version' => '2022-08-01',
]);
```

--------------------------------

### Request using default API version (2023-08-16 in v12)

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v12

This example shows a request that uses the account's default API version in v10 but will use 2023-08-16 in v12 because no 'stripe_version' is specified. It covers both StripeClient and the global client.

```php
// If using StripeClient
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xyz',
]);

$stripe->customers->create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);

// If using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');

\Stripe\Customer::create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);
```

--------------------------------

### Util::objectsToIds() before v20

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

Before v20, Util::objectsToIds() accepted only one parameter. This example shows the old signature that is no longer valid.

```php
$result = \Stripe\Util\Util::objectsToIds($params);
```

--------------------------------

### Close Dispute without params

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v9

Example of calling the close method on a Dispute resource without any parameters. This usage requires no changes in v9.

```php
$dispute->close();
```

--------------------------------

### Replace persons with allPersons on Account

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v9

The `persons` method on `Account` is removed. Use `allPersons` instead. The example shows the old and new static calls with the same account ID.

```php
// change
Account::persons("acct_1234")
// to
Account::allPersons("acct_1234")
```

--------------------------------

### Request with explicit API version 2020-08-27

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v12

This example shows a request that uses API version 2020-08-27 in both previous versions and v12 by specifying 'stripe_version' in the StripeClient config or using the global client with setApiVersion.

```php
// If using StripeClient
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xyz',
  'stripe_version' => '2020-08-27',
]);

$stripe->customers->create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);

// If using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');

\Stripe\Customer::create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);
```

--------------------------------

### Access last API response data with getLastResponse

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Use getLastResponse() on any object to access headers from the last API response. The example retrieves the Request-Id header after creating a customer.

```php
$customer = $stripe->customers->create([
    'description' => 'example customer',
]);
echo $customer->getLastResponse()->headers['Request-Id'];
```

--------------------------------

### Webhook::constructEvent with V2 payload (before)

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

Before v20, passing a V2 event notification payload to Webhook::constructEvent would silently succeed and return a malformed object. This example shows the incorrect usage that now throws an UnexpectedValueException.

```php
// V2 payload accidentally passed to V1 method — returned garbage, no error
$event = \Stripe\Webhook::constructEvent($v2Payload, $sigHeader, $secret);
```

--------------------------------

### V2 null value dropped before v20

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

Before v20, null values in V2 request params were silently stripped, resulting in an empty request body. This example shows the incorrect behavior.

```php
$client->v2->core->accounts->update($accountId, [
    'contact_phone' => null,  // Sent: {}  -- WRONG
]);
```

--------------------------------

### V2 null value preserved after v20

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

After v20, null values in V2 request params are preserved and sent as JSON null, enabling clearing of metadata entries and emptyable fields. This example shows the correct behavior.

```php
$client->v2->core->accounts->update($accountId, [
    'contact_phone' => null,  // Sends: {"contact_phone": null}  -- CORRECT
]);
```

--------------------------------

### Legacy approach using static methods

Source: https://github.com/stripe/stripe-php/wiki/Migration-to-StripeClient-and-services-in-7.33.0

The legacy pattern relies on static methods on resource classes, requiring global configuration and often multiple steps to retrieve and then act on a resource.

```php
<?php
// Initialize the API key
\Stripe\Stripe::setApiKey('sk_test_xxx');

// Set a global API version
\Stripe\Stripe::setApiVersion('2022-08-01');

// Retrieve the customer and then delete it
$customer = \Stripe\Customer::retrieve('cus_xxx');
$customer->delete();

// Create a Coupon
$coupon = \Stripe\Coupon::create([
  'percent_off' => 25,
  'duration' => 'repeating',
  'duration_in_months' => 3,
]);

// Retrieve and confirm a PaymentIntent
$paymentIntent = \Stripe\PaymentIntent::retrieve('pi_123');
$paymentIntent->confirm([
  'payment_method' => 'pm_card_visa'
];

// Create a Checkout Session
$checkoutSession = \Stripe\Checkout\Session::create([
  'success_url' => 'https://www.example.com/success',
  'cancel_url' => 'https://www.example.com/failure',
  'payment_method_types' => ['card'],
  'line_items' => [
    [
      'price' => 'price_ABCDE',
      'quantity' => 2,
    ],
  ],
]);

// Retrieve a Checkout Session and expand line_items
// Note the first parameter is now an array with id as a key to pass the resource id which was hard to figure out
$checkoutSession = \Stripe\Checkout\Session::retrieve([
  'id' => 'cs_test_123',
  'expand' => ['line_items'],
]);
```

--------------------------------

### Run an individual test file

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Runs a specific test file, e.g., tests/Stripe/UtilTest.php.

```bash
just test tests/Stripe/UtilTest.php
# or: ./vendor/bin/phpunit tests/Stripe/UtilTest.php
```

--------------------------------

### Per-request API key and Stripe account configuration

Source: https://github.com/stripe/stripe-php/blob/master/README.md

For apps using multiple keys (e.g., Stripe Connect), pass an options array with 'api_key' and 'stripe_account' to each request. Shown for both all() and retrieve() methods.

```php
$customers = $stripe->customers->all([],[    'api_key' => 'sk_test_...',    'stripe_account' => 'acct_...']);

$stripe->customers->retrieve('cus_123456789', [], [    'api_key' => 'sk_test_...',    'stripe_account' => 'acct_...']);
```

--------------------------------

### New StripeClient and services approach

Source: https://github.com/stripe/stripe-php/wiki/Migration-to-StripeClient-and-services-in-7.33.0

The new pattern uses an instance of StripeClient to access services, allowing for cleaner API calls without relying on global state.

```php
<?php
// Initialize a client with just the API key
$stripe = new \Stripe\StripeClient('sk_test_xxxx');

// Alternatively initialize a client with the API key and API version
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xxxx',
  'stripe_version' => '2022-08-01',
]);

// Create a coupon
$coupon = $stripe->coupons->create([
  'percent_off' => 25,
  'duration' => 'repeating',
  'duration_in_months' => 3,
]);

// Confirm a PaymentIntent
$paymentIntent = $stripe->paymentIntents->confirm(
  'pi_1DeQ7b2eZvKYlo2C5FUypnEA',
  ['payment_method' => 'pm_card_visa']
);

// Create a Checkout Session
$checkoutSession = $stripe->checkout->sessions->create([
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'payment_method_types' => ['card'],
  'line_items' => [
    [
      'price' => 'price_ABCDE',
      'quantity' => 2,
    ],
  ],
]);

// Retrieve a Checkout Session and expand line_items
$checkoutSession = $stripe->checkout->sessions->retrieve(
  'cs_test_123',
  [
    'expand' => ['line_items'],
  ]
);
```

--------------------------------

### Close Dispute with opts parameter migration

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v9

Shows the required change when the opts parameter was used. The new signature requires passing null as the first argument (params) before opts.

```php
// If "params" parameter is not used, change
$dispute->close([/* opts */]);
// to
$dispute->close(null, [/* opts */]);
```

--------------------------------

### Identify plugin with Stripe::setAppInfo

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Call this method once before any API request to identify your plugin. The second and third parameters are optional.

```php
\Stripe\Stripe::setAppInfo("MyAwesomePlugin", "1.2.34", "https://myawesomeplugin.info");
```

--------------------------------

### Set a beta version for preview features with Stripe::addBetaVersion

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Some preview features require a name and version in the Stripe-Version header, like feature_beta=v3. This function is only available in the public preview SDKs.

```php
Stripe::addBetaVersion("feature_beta", "v3");
```

--------------------------------

### Autoload Stripe PHP with Composer

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Include this line in your PHP script to load the Stripe PHP library using Composer's autoloader.

```php
require_once 'vendor/autoload.php';
```

--------------------------------

### Deprecation of resource.save - update with metadata

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v10

Shows the deprecated `save` method compared to the recommended static `update` method for updating a resource's metadata. The `update` method does not require retrieving the resource first.

```PHP
// before
$resource = $stripe->prices->retrieve('price_123');
$resource->metadata['key'] = 'value';
$resource->save();

// after
$resource = $stripe->prices->update('price_123', [
    'metadata' => ['key' => 'value'],
]);
```

--------------------------------

### Deprecation of resource.save - unset parameter with empty string

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v10

Shows the deprecated `save` method for unsetting a parameter by assigning `NULL`, and the recommended `update` method using an empty string `''` to preserve the previous behavior.

```PHP
// before
$resource = $stripe->prices->retrieve('price_123');
$resource->description = NULL;
$resource->save();

// after
$resource = $stripe->prices->update('price_123', [
    'description' => '',
]);
```

--------------------------------

### Configure custom CA bundle path

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Override the default internal CA certificate bundle by setting a custom path with Stripe::setCABundlePath().

```php
\Stripe\Stripe::setCABundlePath("path/to/ca/bundle");
```

--------------------------------

### Configure a PSR-3 logger with Stripe::setLogger

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Set a PSR-3 compatible logger to receive log messages instead of error_log. The library does minimal logging by default.

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

--------------------------------

### Format code with PHP CS Fixer

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Formats code using PHP CS Fixer. Required before submitting PRs; otherwise CI will fail.

```bash
just format
# or: ./vendor/bin/php-cs-fixer fix -v .
```

--------------------------------

### Set custom cURL options (e.g., proxy) with CurlClient

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Pass a CURLOPT_* array to the CurlClient constructor to set default cURL options for each request. Common options like timeouts may be overridden by the client. Use \Stripe\ApiRequestor::setHttpClient() to apply the custom client.

```php
// set up your tweaked Curl client
$curl = new \Stripe\HttpClient\CurlClient([CURLOPT_PROXY => 'proxy.local:80']);
// tell Stripe to use the tweaked client
\Stripe\ApiRequestor::setHttpClient($curl);
```

--------------------------------

### Correct webhook parsing methods for V1 and V2 events

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

Use Webhook::constructEvent for V1 events (object: "event") and StripeClient::parseEventNotification for V2 event notifications (object: "v2.core.event"). This is the recommended fix after the v20 change.

```php
// V1 events (object: "event")
$event = \Stripe\Webhook::constructEvent($payload, $sigHeader, $secret);

// V2 event notifications (object: "v2.core.event")
$event = $client->parseEventNotification($payload, $sigHeader, $secret);
```

--------------------------------

### Set CURLOPT_SSLVERSION for TLS compatibility

Source: https://github.com/stripe/stripe-php/blob/master/README.md

For systems that default to TLS 1.0/1.1, set CURLOPT_SSLVERSION to CURL_SSLVERSION_TLSv1 or CURL_SSLVERSION_TLSv1_2 to resolve TLS 1.2 requirement errors. Recommended to upgrade cURL and OpenSSL packages instead.

```php
$curl = new \Stripe\HttpClient\CurlClient([CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1]);
\Stripe\ApiRequestor::setHttpClient($curl);
```

--------------------------------

### Explicitly set API version when initializing stripe-php

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v12

Shows how to set an older API version (2020-08-27) when initializing stripe-php to avoid upgrading. For StripeClient, pass 'stripe_version' in the config array; for the global client, use \Stripe\Stripe::setApiVersion().

```diff
  // if using StripeClient
- $stripe = new \Stripe\StripeClient('sk_test_xyz');
+ $stripe = new \Stripe\StripeClient([
+   'api_key' => 'sk_test_xyz',
+   'stripe_version' => '2020-08-27',
+ ]);

  // if using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');
+ \Stripe\Stripe::setApiVersion('2020-08-27');
```

--------------------------------

### Webhook::constructEvent with V2 payload (after)

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

After v20, passing a V2 payload to Webhook::constructEvent throws an UnexpectedValueException with a message directing to use StripeClient::parseEventNotification instead.

```php
// Now throws UnexpectedValueException:
// "You passed an event notification to Webhook::constructEvent, which expects
//  a webhook payload. Use StripeClient::parseEventNotification instead."
```

--------------------------------

### Configure automatic network retries

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Set the maximum number of automatic retries for requests that fail due to intermittent network problems. Idempotency keys are added to guarantee retries are safe.

```php
\Stripe\Stripe::setMaxNetworkRetries(2);
```

--------------------------------

### Update bundled CA certificates

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Updates bundled CA certificates from the Mozilla cURL release.

```bash
./update_certs.php
```

--------------------------------

### Util::objectsToIds() after v20 with $serializeNull parameter

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

After v20, Util::objectsToIds() requires a second parameter $serializeNull. Pass false to strip nulls (V1 behavior) or true to preserve nulls for V2 JSON encoding.

```php
// Preserve existing behavior (strip nulls, as V1 always did):
$result = \Stripe\Util\Util::objectsToIds($params, false);

// Or preserve nulls for V2 JSON encoding:
$result = \Stripe\Util\Util::objectsToIds($params, true);
```

--------------------------------

### Set custom request timeouts with CurlClient

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Configure a custom CurlClient to modify connect and total timeouts in seconds. The default timeouts are defined by \Stripe\HttpClient\CurlClient::DEFAULT_TIMEOUT and DEFAULT_CONNECT_TIMEOUT. After setting the timeouts, the client is assigned to \Stripe\ApiRequestor::setHttpClient(). Note that decreasing timeouts for non-read-only calls is not recommended without using idempotency tokens.

```php
// set up your tweaked Curl client
$curl = new \Stripe\HttpClient\CurlClient();
$curl->setTimeout(10); // default is \Stripe\HttpClient\CurlClient::DEFAULT_TIMEOUT
$curl->setConnectTimeout(5); // default is \Stripe\HttpClient\CurlClient::DEFAULT_CONNECT_TIMEOUT

echo $curl->getTimeout(); // 10
echo $curl->getConnectTimeout(); // 5

// tell Stripe to use the tweaked client
\Stripe\ApiRequestor::setHttpClient($curl);

// use the Stripe API client as you normally would
```

--------------------------------

### StripeClient::parseEventNotification with V1 payload

Source: https://github.com/stripe/stripe-php/wiki/Migration-guide-for-v20

After v20, passing a V1 webhook payload to StripeClient::parseEventNotification throws an UnexpectedValueException directing to use Webhook::constructEvent instead.

```php
// V1 payload to V2 method now throws:
// "You passed a webhook payload to StripeClient::parseEventNotification, which
//  expects an event notification. Use Webhook::constructEvent instead."
```

--------------------------------

### Disable telemetry

Source: https://github.com/stripe/stripe-php/blob/master/README.md

Disable sending telemetry to Stripe about request latency and feature usage by setting enable telemetry to false.

```php
\Stripe\Stripe::setEnableTelemetry(false);
```
Tokens:
Raw