# Introduction to server-side SDKs

Learn how to install and use the Stripe server-side SDKs.

The Stripe server-side SDKs reduce the amount of work required to use our REST APIs. Stripe-maintained SDKs are available for Ruby, PHP, Java, Python, Node, .NET and Go. [Community libraries](https://docs.stripe.com/sdks/community.md) are also available for other server languages.

## Installation and setup

Select your language in the language selector below, then follow the instructions to install the SDK.

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

After completing the installation, you need to initialise Stripe:

#### Ruby

```ruby
require 'stripe'
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
```

## Send API requests

You can manipulate objects with the Stripe API in six primary ways: create, update, delete, retrieve, list, and search. The following examples show each of the six ways using the `Customer` object:

#### Create

Create a customer named John Doe.

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=John Doe"
```

#### Update

Retrieve a customer with a specific ID.

```curl
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jdoe@example.com"
```

#### Delete

Delete a customer with a specific ID.

```curl
curl -X DELETE https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### Retrieve

Retrieve a customer with a specific ID.

```curl
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### List

List the 5 most recently created customers.

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d limit=5
```

#### Search

Search for customers named Jane Doe.

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=name:'Jane Doe'"
```

API requests can contain different types of parameters. For example, here’s how to create a customer with a `name` (a string), `address` (an object), and `preferred_locales` (a list):

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=John Doe" \
  -d "address[country]=US" \
  -d "address[city]=San Fransisco" \
  -d "preferred_locales[]=EN" \
  -d "preferred_locales[]=FR"
```

When updating an object, you can clear some of its properties. For dynamically typed languages, send an empty string. For strongly typed languages, use specific constants. For example, here’s how to clear the `name` (a string) and `metadata` (a hash of key-value pairs) of a customer:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
customer = client.v1.customers.update('{{CUSTOMER_ID}}', {
  name: '',
  metadata: '',
})
```

This example clears all metadata, but you can also clear individual keys. Learn more about managing metadata in our [metadata guide](https://docs.stripe.com/metadata.md).

## Access the API response

Every time you make an API request, Stripe sends you back a response.

If you create, retrieve, or update an object, you get back the object itself:

```json
{
  "id": "pi_001",
  "object": "payment_intent",
  "amount": 1099,
  "currency": "usd",
  /* ... */
}
```

Use a variable to access the properties of that object:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
paymentIntent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}')
puts paymentIntent.amount
```

When listing or searching for objects, you get back a `List` object containing a `data` array with the objects requested:

```json
{
  "object": "list",
  "data": [
    {
      "id": "pi_003",
      "object": "payment_intent",
      "amount": 4200,
      "currency": "usd",
      /* ... */
    },
    {
      "id": "pi_002",
      "object": "payment_intent",
      "amount": 2100,
      "currency": "usd",
      "payment_method_types": [ "link" ],
      /* ... */
    }
  ],
  "has_more": true,
  "url": "/v1/payment_intents"
}
```

Use a loop on the `data` array to access the properties of each object:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
paymentIntentList = client.v1.payment_intents.list({ limit: 3 })
for pi in paymentIntentList.data do
  puts pi.amount
end
```

You could also use [auto-pagination](https://docs.stripe.com/pagination.md#auto-pagination) to iterate over all the results.

## Expanding responses

Some properties are expandable or includable, meaning you can return them by using the `expand` parameter. For example:

- Retrieve a PaymentIntent and expand its associated PaymentMethod.
  ```curl
  curl -G https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}} \
    -u "<<YOUR_SECRET_KEY>>:" \
    -d "expand[]=payment_method"
  ```
- Retrieve a Checkout Session and include the `line_items` property.
  ```curl
  curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \
    -u "<<YOUR_SECRET_KEY>>:" \
    -d "expand[]=line_items"
  ```

Learn more about [expanding responses](https://docs.stripe.com/expand.md).

## Retrieve the request ID

Each API request has a unique request ID (`req_xxx`) associated with it. You can use it to inspect the request in the Dashboard to see the parameters Stripe received, or to share it with Stripe support when you need to resolve an issue.

You can find the IDs in your [Dashboard logs](https://dashboard.stripe.com/test/workbench/logs), or directly with code like this:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
customer = client.v1.customers.create({ name: 'John Doe', })
puts customer.last_response.request_id
```

## Set additional request options

When sending API requests, you can set additional request options to:

- [Set a specific API version](https://docs.stripe.com/sdks/set-version.md).
- [Make requests on your connected accounts](https://docs.stripe.com/connect/authentication.md).
- [Provide idempotency keys](https://docs.stripe.com/api/idempotent_requests.md).

## Error handling

Each server SDK interprets error responses from the Stripe API as exception types, so you don’t need to parse the response status yourself. Use error handling conventions appropriate for each language to handle those errors.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
begin
  client.v1.payment_intents.create(params)
rescue Stripe::CardError => e
  puts "A payment error occurred: #{e.error.message}"
rescue Stripe::InvalidRequestError => e
  puts "An invalid request occurred."
rescue Stripe::StripeError => e
  puts "Another problem occurred, maybe unrelated to Stripe."
else
  puts "No error."
end
```

Learn more about [error handling](https://docs.stripe.com/error-handling.md).

## Undocumented params and fields

In some cases, you might encounter parameters on an API request or fields on an API response that aren’t available in the SDKs. This might happen when they’re undocumented or when they’re in preview and you aren’t using a preview SDK. Use the following guidance to send those parameters or access those fields.

### Send undocumented parameters

In the following example, you create a `Customer` with an undocumented boolean parameter. The code example uses `secret_feature_enabled`, which the SDKs don’t expose.

#### Java

```java

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
StripeClient stripeClient = new StripeClient("<<YOUR_SECRET_KEY>>");
CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("jenny.rosen@example.com")
    .putExtraParam("secret_feature_enabled", "true")
    .build();

stripeClient.v1().customers().create(params);
```

### Access undocumented fields

In the following example, you read an undocumented boolean field on the `Customer` object. The code sample uses `secret_feature_enabled`, which the SDKs don’t expose.

#### Java

```java

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
StripeClient stripeClient = new StripeClient("<<YOUR_SECRET_KEY>>");
final Customer customer = stripeClient.v1().customers().retrieve("cus_1234");
Boolean featureEnabled = customer.getRawJsonObject()
    .getAsJsonPrimitive("secret_feature_enabled")
    .getAsBoolean();
```

## Source code

The source code for each of our server SDKs is available on GitHub:

| Language   | Repository                                                 |
| ---------- | ---------------------------------------------------------- |
| **Ruby**   | [`stripe-ruby`](https://github.com/stripe/stripe-ruby)     |
| **PHP**    | [`stripe-php`](https://github.com/stripe/stripe-php)       |
| **Java**   | [`stripe-Java`](https://github.com/stripe/stripe-java)     |
| **Node**   | [`stripe-node`](https://github.com/stripe/stripe-node)     |
| **Python** | [`stripe-python`](https://github.com/stripe/stripe-python) |
| **.NET**   | [`stripe-dotnet`](https://github.com/stripe/stripe-dotnet) |
| **Go**     | [`stripe-go`](https://github.com/stripe/stripe-go)         |

## StripeClient

The `StripeClient` class acts as an entry point to help you discover resources and make requests to the Stripe API. The benefits of using this pattern over the older one that used global configuration are:

- You can simultaneously use multiple clients with different configuration options (such as API keys).
- It enables easier mocking during testing as `StripeClient` doesn’t use static methods.
- No extra API calls. In some languages, you had to call a retrieve before doing an update or delete. When using `StripeClient`, you can access all API endpoints with a single method call.

The Node.js SDK has always had the `Stripe` class which followed the same pattern. For rest of the languages, the new pattern was added in the following SDK versions. If you’re comparing code targeting older versions of these libraries with older patterns, the calls might look different.

| Migration guides                                                                                                                            | StripeClient release |
| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| [stripe-php migration guide](https://github.com/stripe/stripe-php/wiki/Migration-to-StripeClient-and-services-in-7.33.0)                    | 7.33.0               |
| [stripe-python migration guide](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v8-\(StripeClient\))                       | 8.0.0                |
| [stripe-java migration guide](https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23#stripeclient)                              | 23.0.0               |
| [stripe-ruby migration guide](https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v13)                                           | 13.0.0               |
| [stripe-dotnet migration guide](https://github.com/stripe/stripe-dotnet/blob/master/CHANGELOG.md#stripeclient)                              | 46.0.0               |
| [stripe-go migration guide](https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client#migrating-from-global-configuration) | 82.1.0               |

## Public and private preview versions

Stripe has features in the [public and private preview phases](https://docs.stripe.com/release-phases.md) that you can access through versions of the SDKs with the [`beta` or `b` suffix](https://docs.stripe.com/sdks/versioning.md#public-preview-release-channel) and the [`alpha` or `a` suffix](https://docs.stripe.com/sdks/versioning.md#private-preview-release-channel), respectively.