API Reference

The Stripe API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

API libraries

Libraries for the Stripe API are available in several languages.

https://api.stripe.com

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

To use your API key, assign it to Stripe.api_key. The Ruby library will then automatically send this key in each request.

To use your API key, assign it to stripe.api_key. The Python library will then automatically send this key in each request.

To use your API key, you need only call \Stripe\Stripe::setApiKey() with your key. The PHP library will then automatically send this key in each request.

To use your API key, assign it to Stripe.apiKey. The Java library will then automatically send this key in each request.

To use your API key, pass it to the stripe module. The Node.js library then will automatically send this key in each request.

To use your API key, assign it to stripe.Key. The Go library will then automatically send this key in each request.

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

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cURL uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password). You can set the default API key, or you can always pass a key directly to an object's constructor. Authentication is transparently handled for you in subsequent method calls. You can set the default key by passing it to the Stripe module (a constructor). Authentication is transparently handled for you in subsequent method calls.

A sample test API key is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.

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 (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Stripe's servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a card is declined), we return a 402 error code.

Attributes
  • type

    The type of error returned. Can be: api_connection_error, api_error, authentication_error, card_error, invalid_request_error, or rate_limit_error.

  • message optional

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

  • code optional

    For card errors, a short string from amongst those listed on the right describing the kind of card error that occurred.

  • param optional

    The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

HTTP status code summary

200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 - Server Errors Something went wrong on Stripe's end. (These are rare.)

Errors

Types
api_connection_error Failure to connect to Stripe's API.
api_error API errors cover any other type of problem (e.g., a temporary problem with Stripe's servers) and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request.
card_error Card 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.
invalid_request_error Invalid request errors arise when your request has invalid parameters.
rate_limit_error Too many requests hit the API too quickly.
Codes
invalid_number The card number is not a valid credit card number.
invalid_expiry_month The card's expiration month is invalid.
invalid_expiry_year The card's expiration year is invalid.
invalid_cvc The card's security code is invalid.
incorrect_number The card number is incorrect.
expired_card The card has expired.
incorrect_cvc The card's security code is incorrect.
incorrect_zip The card's zip code failed validation.
card_declined The card was declined.
missing There is no card on a customer that is being charged.
processing_error An error occurred while processing the card.
CVC validation and zip validation can be enabled/disabled in your settings.

Handling errors

Our API 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.

Our API libraries can produce errors for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability.

begin
  # Use Stripe's library to make requests...
rescue Stripe::CardError => e
  # Since it's a decline, Stripe::CardError will be caught
  body = e.json_body
  err  = body[:error]

  puts "Status is: #{e.http_status}"
  puts "Type is: #{err[:type]}"
  puts "Code is: #{err[:code]}"
  # param is '' in this case
  puts "Param is: #{err[:param]}"
  puts "Message is: #{err[:message]}"
rescue Stripe::RateLimitError => e
  # Too many requests made to the API too quickly
rescue Stripe::InvalidRequestError => e
  # Invalid parameters were supplied to Stripe's API
rescue Stripe::AuthenticationError => e
  # Authentication with Stripe's API failed
  # (maybe you changed API keys recently)
rescue Stripe::APIConnectionError => e
  # Network communication with Stripe failed
rescue Stripe::StripeError => e
  # Display a very generic error to the user, and maybe send
  # yourself an email
rescue => e
  # Something else happened, completely unrelated to Stripe
end
try:
  # Use Stripe's library to make requests...
  pass
except stripe.error.CardError, e:
  # Since it's a decline, stripe.error.CardError will be caught
  body = e.json_body
  err  = body['error']

  print "Status is: %s" % e.http_status
  print "Type is: %s" % err['type']
  print "Code is: %s" % err['code']
  # param is '' in this case
  print "Param is: %s" % err['param']
  print "Message is: %s" % err['message']
except stripe.error.RateLimitError, e:
  # Too many requests made to the API too quickly
  pass
except stripe.error.InvalidRequestError, e:
  # Invalid parameters were supplied to Stripe's API
  pass
except stripe.error.AuthenticationError, e:
  # Authentication with Stripe's API failed
  # (maybe you changed API keys recently)
  pass
except stripe.error.APIConnectionError, e:
  # Network communication with Stripe failed
  pass
except stripe.error.StripeError, e:
  # Display a very generic error to the user, and maybe send
  # yourself an email
  pass
except Exception, e:
  # Something else happened, completely unrelated to Stripe
  pass
try {
  // Use Stripe's library to make requests...
} catch(\Stripe\Error\Card $e) {
  // Since it's a decline, \Stripe\Error\Card will be caught
  $body = $e->getJsonBody();
  $err  = $body['error'];

  print('Status is:' . $e->getHttpStatus() . "\n");
  print('Type is:' . $err['type'] . "\n");
  print('Code is:' . $err['code'] . "\n");
  // param is '' in this case
  print('Param is:' . $err['param'] . "\n");
  print('Message is:' . $err['message'] . "\n");
} catch (\Stripe\Error\RateLimit $e) {
  // Too many requests made to the API too quickly
} catch (\Stripe\Error\InvalidRequest $e) {
  // Invalid parameters were supplied to Stripe's API
} catch (\Stripe\Error\Authentication $e) {
  // Authentication with Stripe's API failed
  // (maybe you changed API keys recently)
} catch (\Stripe\Error\ApiConnection $e) {
  // Network communication with Stripe failed
} catch (\Stripe\Error\Base $e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception $e) {
  // Something else happened, completely unrelated to Stripe
}
try {
  // Use Stripe's library to make requests...
} catch (CardException e) {
  // Since it's a decline, CardException will be caught
  System.out.println("Status is: " + e.getCode());
  System.out.println("Message is: " + e.getMessage());
} catch (RateLimitException e) {
  // Too many requests made to the API too quickly
} catch (InvalidRequestException e) {
  // Invalid parameters were supplied to Stripe's API
} catch (AuthenticationException e) {
  // Authentication with Stripe's API failed
  // (maybe you changed API keys recently)
} catch (APIConnectionException e) {
  // Network communication with Stripe failed
} catch (StripeException e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception e) {
  // Something else happened, completely unrelated to Stripe
}
// Note: Node.js API does not throw exceptions, and instead prefers the
// asynchronous style of error handling described below.
//
// An error from the Stripe API or an otheriwse asynchronous error
// will be available as the first argument of any Stripe method's callback:
// E.g. stripe.customers.create({...}, function(err, result) {});
//
// Or in the form of a rejected promise.
// E.g. stripe.customers.create({...}).then(
//        function(result) {},
//        function(err) {}
//      );

switch (err.type) {
  case 'StripeCardError':
    // A declined card error
    err.message; // => e.g. "Your card's expiration year is invalid."
    break;
  case 'RateLimitError':
    // Too many requests made to the API too quickly
    break;
  case 'StripeInvalidRequestError':
    // Invalid parameters were supplied to Stripe's API
    break;
  case 'StripeAPIError':
    // An error occurred internally with Stripe's API
    break;
  case 'StripeConnectionError':
    // Some kind of error occurred during the HTTPS communication
    break;
  case 'StripeAuthenticationError':
    // You probably used an incorrect API key
    break;
  default:
    // Handle any other types of unexpected errors
    break;
}
_, err := // Go library call

if err != nil {
  stripeErr := err.(*stripe.Error)

  switch stripeErr.Code {
  case stripe.IncorrectNum:
  case stripe.InvalidNum:
  case stripe.InvalidExpM:
  case stripe.InvalidExpY:
  case stripe.InvalidCvc:
  case stripe.ExpiredCard:
  case stripe.IncorrectCvc:
  case stripe.IncorrectZip:
  case stripe.CardDeclined:
  case stripe.Missing:
  case stripe.ProcessingErr:
  }
}

Expanding Objects

Many objects contain the ID of a related object in their response properties. For example, a Charge may have an associated Customer ID. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all API requests, and applies to the response of that request only.

You can nest expand requests with the dot property. For example, requesting invoice.customer on a charge will expand the invoice property into a full Invoice object, and will then expand the customer property on that invoice into a full Customer object.

You can expand multiple objects at once by identifying multiple items in the expand array.

curl https://api.stripe.com/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d expand[]=customer
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve(:id => "ch_17eT142eZvKYlo2CnA1fjKo8", :expand => ['customer'])
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8", expand=['customer'])
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve(array("id" => "ch_17eT142eZvKYlo2CnA1fjKo8", "expand" => array("customer")));
The Stripe Java library does not support this feature.
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8", {
  expand: ["customer"]
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{}
params.Expand("customer")
charge.Get("ch_17eT142eZvKYlo2CnA1fjKo8", params)

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a charge fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single charge is created.

To perform an idempotent request, attach a unique key to any POST request made to the API via the Idempotency-Key: <key> header.

To perform an idempotent request, provide an additional idempotency_key element to the request parameters.

To perform an idempotent request, provide a key to setIdempotencyKey() on a request.

To perform an idempotent request, provide an additional IdempotencyKey element to the request parameters.

How you create unique keys is completely up to you. We suggest using random strings or UUIDs. We'll always send back the same response for requests made with the same key. However, you cannot use the same key with different request parameters. The keys expire after 24 hours.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Idempotency-Key: 4bTXqbG6zcap4hu5" \
   -d amount=400 \
   -d source=tok_17drHk2eZvKYlo2CEEHm8kkG \
   -d currency=usd
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create({
  :amount => 400,
  :currency => "usd",
  :source => "tok_17drHk2eZvKYlo2CEEHm8kkG", # obtained with Stripe.js
  :description => "Charge for test@example.com"
}, {
  :idempotency_key => "4bTXqbG6zcap4hu5"
})
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  source="tok_17drHk2eZvKYlo2CEEHm8kkG", # obtained with Stripe.js
  idempotency_key='4bTXqbG6zcap4hu5'
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_17drHk2eZvKYlo2CEEHm8kkG", // obtained with Stripe.js
  "description" => "Charge for test@example.com"
), array(
  "idempotency_key" => "4bTXqbG6zcap4hu5",
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("amount", 400);
chargeParams.put("currency", "usd");
chargeParams.put("source", "tok_17drHk2eZvKYlo2CEEHm8kkG"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");

RequestOptions options = RequestOptions
  .builder()
  .setIdempotencyKey("4bTXqbG6zcap4hu5")
  .build();

Charge.create(chargeParams, options);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.create({
  amount: 400,
  currency: "usd",
  source: "tok_17drHk2eZvKYlo2CEEHm8kkG", // obtained with Stripe.js
  description: "Charge for test@example.com"
}, {
  idempotency_key: "4bTXqbG6zcap4hu5"
}, function(err, charge) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

args := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
  Desc: "Charge for test@example.com",
}
args.SetSource("tok_17drHk2eZvKYlo2CEEHm8kkG") // obtained with Stripe.js
args.Params.IdempotencyKey = "4bTXqbG6zcap4hu5"
ch, err := charge.New(args)

Metadata

Updatable Stripe objects—including Account, Charge, Customer, Refund, Subscription, and Transfer—have a metadata parameter. You can use this parameter to attach key-value data to these Stripe objects.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Stripe Customer object. Metadata is not used by Stripe (e.g., to authorize or decline a charge), and won't be seen by your users unless you choose to show it to them.

Some of the objects listed above also support a description parameter. You can use the description parameter to annotate a charge, for example, with a human-readable description, such as "2 shirts for test@example.com". Unlike metadata, description is a single string, and your users may see it (e.g., in email receipts Stripe sends on your behalf).

Note: You can have up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Sample metadata use cases
  • Link IDs

    Attach your system's unique IDs to a Stripe object for easy lookups. Add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer, for example.

  • Refund papertrails

    Store information about why a refund was created, and by whom.

  • Customer details

    Annotate a customer by storing the customer's phone number for your later use.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d source=tok_17drHk2eZvKYlo2CEEHm8kkG \
   -d metadata[order_id]=6735
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_17drHk2eZvKYlo2CEEHm8kkG", # obtained with Stripe.js,
  :metadata => {'order_id' => '6735'}
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  source="tok_17drHk2eZvKYlo2CEEHm8kkG", # obtained with Stripe.js
  metadata={'order_id': '6735'}
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_17drHk2eZvKYlo2CEEHm8kkG", // obtained with Stripe.js,
  "metadata" => array("order_id" => "6735")
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("amount", 400);
chargeParams.put("currency", "usd");
chargeParams.put("source", "tok_17drHk2eZvKYlo2CEEHm8kkG"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");
Map<String, String> initialMetadata = new HashMap<String, String>();
initialMetadata.put("order_id", "6735");
chargeParams.put("metadata", initialMetadata);

Charge.create(chargeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.create({
  amount: 400,
  currency: "usd",
  source: "tok_17drHk2eZvKYlo2CEEHm8kkG", // obtained with Stripe.js
  metadata: {'order_id': '6735'}
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
}
params.SetSource("tok_17drHk2eZvKYlo2CEEHm8kkG") // obtained with Stripe.js
params.AddMeta("order_id", "6735")
charge.New(params)
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list charges, list customers, and list invoices. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Stripe utilizes cursor-based pagination via the starting_after and ending_before parameters. Both take an existing object ID value (see below). The ending_before parameter returns objects created before the named object, in descending chronological order. The starting_after parameter returns objects created after the named object, in ascending chronological order. If both parameters are provided, only ending_before is used.

Arguments
  • limit optional

    A limit on the number of objects to be returned, between 1 and 100.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List Response Format
  • object string, value is "list"

    A string describing the object type returned.

  • data array

    An array containing the actual response elements, paginated by any request parameters.

  • has_more boolean

    Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

  • url string

    The URL for accessing this list.

curl https://api.stripe.com/v1/customers?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("limit", 3);

Customer.all(customerParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.list(
  { limit: 3 },
  function(err, customers) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CustomerListParams{}
params.Filters.AddFilter("limit", "", "3")
i := customer.List(params)
for i.Next() {
  c := i.Customer()
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers",
  has_more: false,
  data: [
    <Customer customer id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
&stripe.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is 2016-02-03. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version.

To set the API version on a specific request, send a Stripe-Version header.

To override the API version, assign the version to the Stripe.api_version property.

To override the API version, assign the version to the stripe.api_version property.

To override the API version, assign the version to the Stripe.apiVersion property.

To override the API version, pass the version to the \Stripe\Stripe::setApiVersion() method.

To override the API version, pass the version to the stripe.setApiVersion() method.

Since Go is strongly typed, the version is fixed in the library. Revert to an older version of the library to change the API version used.

You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Stripe-Version: 2016-02-03"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
Stripe.api_version = "2016-02-03"
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
stripe.api_version = '2016-02-03'
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
\Stripe\Stripe::setApiVersion("2016-02-03");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
Stripe.apiVersion = "2016-02-03";
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
stripe.setApiVersion('2016-02-03');
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
// Since Go is strongly typed,
// the version is fixed in the library.

Balance

This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account.

You can also retrieve a list of the balance history, which contains a list of transactions that contributed to the balance (e.g., charges, transfers, and so forth).

The available and pending amounts for each currency are broken down further by payment source types.

The balance object

Attributes
  • object string , value is "balance"

  • available array

    Funds that are available to be paid out automatically by Stripe or explicitly via the transfers API. The available balance for each currency and payment type can be found in the source_types property.

  • livemode boolean

  • pending array

    Funds that are not available in the balance yet, due to the 7-day rolling pay cycle. The pending balance for each currency and payment type can be found in the source_types property

{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
#<Stripe::Balance 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
<Balance balance at 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
Stripe\Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
com.stripe.model.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
&stripe.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}

The balance_transaction object

Attributes
  • id string

  • object string , value is "balance_transaction"

  • amount integer

    Gross amount of the transaction, in cents.

  • available_on timestamp

    The date the transaction’s net funds will become available in the Stripe balance.

  • created timestamp

  • currency currency

  • description string

  • fee integer

    Fees (in cents) paid for this transaction

  • fee_details list

    Detailed breakdown of fees (in cents) paid for this transaction

    child attributes
    • amount integer

    • application string

    • currency currency

    • description string

    • type string

      Type of the fee, one of: application_fee, stripe_fee or tax.

  • net integer

    Net amount of the transaction, in cents.

  • source string

    The Stripe object this transaction is related to.

  • sourced_transfers list

    The transfers (if any) for which source is a source_transaction.

    child attributes
    • object string , value is "list"

    • data array, contains: transfer object

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • status string

    If the transaction’s net funds are available in the Stripe balance yet. Either available or pending.

  • type string

    Type of the transaction, one of: charge, refund, adjustment, application_fee, application_fee_refund, transfer, transfer_cancel, transfer_refund, or transfer_failure.

{
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
#<Stripe::BalanceTransaction id=txn_17bBxN2eZvKYlo2CpkezPWCQ 0x00000a> JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
<BalanceTransaction balance_transaction id=txn_17bBxN2eZvKYlo2CpkezPWCQ at 0x00000a> JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
Stripe\BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
com.stripe.model.BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
{
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
&stripe.BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}

Retrieve balance

Retrieves the current account balance, based on the authentication that was used to make the request.

Arguments
  • No arguments…

Returns

Returns a balance object for the account authenticated as.

curl https://api.stripe.com/v1/balance \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Balance.retrieve()
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Balance.retrieve()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Balance::retrieve();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Balance.retrieve();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.balance.retrieve(function(err, balance) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

b, err := balance.Get(nil)
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
#<Stripe::Balance 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
<Balance balance at 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
Stripe\Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
com.stripe.model.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
&stripe.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7973335158,
      "source_types": {
        "card": 7964935984,
        "bank_account": 7012784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 214822794,
      "source_types": {
        "card": 214822794,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}

Retrieve a balance transaction

Retrieves the balance transaction with the given ID.

Arguments
  • id required

    The ID of the desired balance transaction (as found on any API object that affects the balance, e.g. a charge or transfer).

Returns

Returns a balance transaction if a valid balance transaction ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

curl https://api.stripe.com/v1/balance/history/txn_17bBxN2eZvKYlo2CpkezPWCQ \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BalanceTransaction.retrieve("txn_17bBxN2eZvKYlo2CpkezPWCQ")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BalanceTransaction.retrieve("txn_17bBxN2eZvKYlo2CpkezPWCQ")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\BalanceTransaction::retrieve("txn_17bBxN2eZvKYlo2CpkezPWCQ");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

BalanceTransaction.retrieve("txn_17bBxN2eZvKYlo2CpkezPWCQ");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.balance.retrieveTransaction(
  "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  function(err, balanceTransaction) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tx, err := balance.GetTx("txn_17bBxN2eZvKYlo2CpkezPWCQ", nil)
{
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
#<Stripe::BalanceTransaction id=txn_17bBxN2eZvKYlo2CpkezPWCQ 0x00000a> JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
<BalanceTransaction balance_transaction id=txn_17bBxN2eZvKYlo2CpkezPWCQ at 0x00000a> JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
Stripe\BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
com.stripe.model.BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
{
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}
&stripe.BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}

List all balance history

Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges, transfers, and so forth). The transactions are returned in sorted order, with the most recent transactions appearing first.

Arguments
  • available_on optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object available_on field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the available_on field is after this timestamp.

    • gte optional

      Return values where the available_on field is after or equal to this timestamp.

    • lt optional

      Return values where the available_on field is before this timestamp.

    • lte optional

      Return values where the available_on field is before or equal to this timestamp.

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • currency optional

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • source optional

    Only returns transactions that are related to the specified Stripe object ID (e.g. filtering by a charge ID will return all related charge transactions).

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • transfer optional

    For automatic Stripe transfers only, only returns transactions that were transferred out on the specified transfer ID.

  • type optional

    Only returns transactions of the given type. One of: charge, adjustment, application_fee, application_fee_refund, transfer, or transfer_failure

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit transactions, starting after transaction starting_after. Each entry in the array is a separate transaction history object. If no more transactions are available, the resulting array will be empty.

You can optionally request that the response include the total count of all transactions that match your filters. To do so, specify include[]=total_count in your request.

GET https://api.stripe.com/v1/balance/history
Stripe::BalanceTransaction.all
stripe.BalanceTransaction.all()
\Stripe\BalanceTransaction::all();
BalanceTransaction.all();
stripe.balance.listTransactions();
balance.List()
curl https://api.stripe.com/v1/balance/history?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BalanceTransaction.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BalanceTransaction.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\BalanceTransaction::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> balanceTransactionParams = new HashMap<String, Object>();
balanceTransactionParams.put("limit", 3);

Balancetransaction.all(balanceTransactionParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.balance.listTransactions({ limit: 3 }, function(err, transactions) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.TxListParams{}
params.Filters.AddFilter("limit", "", "3")
i := balance.List(params)
for i.Next() {
  tx := i.Transaction()
}
{
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    {
      "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "object": "balance_transaction",
      "amount": 1299,
      "available_on": 1455235200,
      "created": 1454687833,
      "currency": "usd",
      "description": null,
      "fee": 68,
      "fee_details": [
        {
          "amount": 68,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 1231,
      "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
      },
      "status": "pending",
      "type": "charge"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    #<Stripe::BalanceTransaction id=txn_17bBxN2eZvKYlo2CpkezPWCQ 0x00000a> JSON: {
      "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "object": "balance_transaction",
      "amount": 1299,
      "available_on": 1455235200,
      "created": 1454687833,
      "currency": "usd",
      "description": null,
      "fee": 68,
      "fee_details": [
        {
          "amount": 68,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 1231,
      "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
      },
      "status": "pending",
      "type": "charge"
    },
    #<Stripe::BalanceTransaction[...] ...>,
    #<Stripe::BalanceTransaction[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/balance/history",
  has_more: false,
  data: [
    <BalanceTransaction balance_transaction id=txn_17bBxN2eZvKYlo2CpkezPWCQ at 0x00000a> JSON: {
      "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "object": "balance_transaction",
      "amount": 1299,
      "available_on": 1455235200,
      "created": 1454687833,
      "currency": "usd",
      "description": null,
      "fee": 68,
      "fee_details": [
        {
          "amount": 68,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 1231,
      "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
      },
      "status": "pending",
      "type": "charge"
    },
    <stripe.BalanceTransaction[...] ...>,
    <stripe.BalanceTransaction[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/balance/history",
  "has_more" => false,
  "data" => [
    [0] => Stripe\BalanceTransaction JSON: {
      "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "object": "balance_transaction",
      "amount": 1299,
      "available_on": 1455235200,
      "created": 1454687833,
      "currency": "usd",
      "description": null,
      "fee": 68,
      "fee_details": [
        {
          "amount": 68,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 1231,
      "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
      },
      "status": "pending",
      "type": "charge"
    }
    [1] => <Stripe\BalanceTransaction[...] ...>
    [2] => <Stripe\BalanceTransaction[...] ...>
  ]
}
#<com.stripe.model.BalanceTransactionCollection id=#> JSON: {
  "data": [
    com.stripe.model.BalanceTransaction JSON: {
      "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "object": "balance_transaction",
      "amount": 1299,
      "available_on": 1455235200,
      "created": 1454687833,
      "currency": "usd",
      "description": null,
      "fee": 68,
      "fee_details": [
        {
          "amount": 68,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 1231,
      "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
      },
      "status": "pending",
      "type": "charge"
    },
    #<com.stripe.model.BalanceTransaction[...] ...>,
    #<com.stripe.model.BalanceTransaction[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    {
      "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "object": "balance_transaction",
      "amount": 1299,
      "available_on": 1455235200,
      "created": 1454687833,
      "currency": "usd",
      "description": null,
      "fee": 68,
      "fee_details": [
        {
          "amount": 68,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 1231,
      "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
      },
      "status": "pending",
      "type": "charge"
    },
    {...},
    {...}
  ]
}
&stripe.BalanceTransaction JSON: {
  "id": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "object": "balance_transaction",
  "amount": 1299,
  "available_on": 1455235200,
  "created": 1454687833,
  "currency": "usd",
  "description": null,
  "fee": 68,
  "fee_details": [
    {
      "amount": 68,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 1231,
  "source": "ch_17bBxN2eZvKYlo2C9wKdzseW",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17bBxN2eZvKYlo2C9wKdzseW"
  },
  "status": "pending",
  "type": "charge"
}

Charges

To charge a credit or a debit card, you create a charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique random ID.

The charge object

Attributes
  • id string

  • object string , value is "charge"

  • amount positive integer or zero

    Amount charged in cents

  • amount_refunded positive integer or zero

    Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued).

  • application_fee string

    The application fee (if any) for the charge. See the Connect documentation for details.

  • balance_transaction string

    ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).

  • captured boolean

    If the charge was created without capturing, this boolean represents whether or not it is still uncaptured or has since been captured.

  • created timestamp

  • currency currency

    Three-letter ISO currency code representing the currency in which the charge was made.

  • customer string

    ID of the customer this charge is for if one exists.

  • description string

  • destination string

    The account (if any) the charge was made on behalf of. See the Connect documentation for details.

  • dispute hash, dispute object

    Details about the dispute if the charge has been disputed.

  • failure_code string

    Error code explaining reason for charge failure if available (see the errors section for a list of codes).

  • failure_message string

    Message to user further explaining reason for charge failure if available.

  • fraud_details hash

    Hash with information on fraud assessments for the charge. Assessments reported by you have the key user_report and, if set, possible values of safe and fraudulent. Assessments from Stripe have the key stripe_report and, if set, the value fraudulent.

  • invoice string

    ID of the invoice this charge is for if one exists.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a charge object. It can be useful for storing additional information about the charge in a structured format.

  • order string

    ID of the order this charge is for if one exists.

  • paid boolean

    true if the charge succeeded, or was successfully authorized for later capture.

  • receipt_email string

    This is the email address that the receipt for this charge was sent to.

  • receipt_number string

    This is the transaction number that appears on email receipts sent for this charge.

  • refunded boolean

    Whether or not the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.

  • refunds list

    A list of refunds that have been applied to the charge.

    child attributes
    • object string , value is "list"

    • data list

      child attributes
      • id string

      • object string , value is "list"

      • amount integer

        Amount, in cents.

      • balance_transaction string

        Balance transaction that describes the impact on your account balance.

      • charge string

        ID of the charge that was refunded.

      • created timestamp

      • currency currency

        Three-letter ISO code representing the currency.

      • description string

      • metadata #

        A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

      • reason string

        Reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer.

      • receipt_number string

        This is the transaction number that appears on email receipts sent for this refund.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • shipping hash

    Shipping information for the charge.

    child attributes
    • address hash

      Shipping address.

      child attributes
      • city string

        City/Suburb/Town/Village/Ward

      • country string

        2-letter country code

      • line1 string

        Address line 1 (Street address/PO Box/Company name)

      • line2 string

        Address line 2 (Apartment/Suite/Unit/Building)

      • postal_code string

        Zip/Postal Code

      • state string

        State/Province/County/Prefecture

    • carrier string

      The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.

    • name string

      Recipient name.

    • phone string

      Recipient phone (including extension).

    • tracking_number string

      The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

  • source hash

    For most Stripe users, the source of every charge is a credit or debit card. This hash is then the card object describing that card.

  • statement_descriptor string

    Extra information about a charge. This will appear on your customer’s credit card statement.

  • status string

    The status of the payment is either succeeded or failed.

  • transfer string

    ID of the transfer to the destination account (only applicable if the charge was created using the destination parameter).

{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Create a charge

To charge a credit card, you create a charge object. If your API key is in test mode, the supplied payment source (e.g., card or Bitcoin receiver) won't actually be charged, though everything else will occur as if in live mode. (Stripe assumes that the charge would have completed successfully).

Arguments
  • amount required

    A positive integer in the smallest currency unit (e.g 100 cents to charge $1.00, or 1 to charge ¥1, a 0-decimal currency) representing how much to charge the card. The minimum amount is $0.50 (or equivalent in charge currency).

  • currency required

    3-letter ISO code for currency.

  • application_fee connect only optional

    A fee in cents that will be applied to the charge and transferred to the application owner's Stripe account. To use an application fee, the request must be made on behalf of another account, using the Stripe-Account header, an OAuth key, or the destination parameter. For more information, see the application fees documentation.

  • capture optional, default is true

    Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. Uncaptured charges expire in 7 days. For more information, see authorizing charges and settling later.

  • description optional, default is nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing.

  • destination connect only optional

    An account to make the charge on behalf of. If specified, the charge will be attributed to the destination account for tax reporting, and the funds from the charge will be transferred to the destination account. The ID of the resulting transfer will be returned in the transfer field of the response. See the documentation for details.

  • metadata optional, default is { }

    A set of key/value pairs that you can attach to a charge object. It can be useful for storing additional information about the customer in a structured format. It's often a good idea to store an email address in metadata for tracking later.

  • receipt_email optional, default is nullnilNonenullnullnullnull

    The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. If this charge is for a customer, the email address specified here will override the customer's email address. Receipts will not be sent for test mode charges. If receipt_email is specified for a charge in live mode, a receipt will be sent regardless of your email settings.

  • shipping optional, default is { }

    Shipping information for the charge. Helps prevent fraud on charges for physical goods.

  • customer optional, either customer or source is required

    The ID of an existing customer that will be charged in this request.

  • source optional, either source or customer is required

    A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.

    child attributes
    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • objectobjectobjectobjectobjectobjectobject required

      The type of payment source. Should be "card".

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • namenamenamenamenamenamename optional

      Cardholder's full name.

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

  • statement_descriptor optional, default is nullnilNonenullnullnullnull

    An arbitrary string to be displayed on your customer's credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you're charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <>"' characters, and will appear on your customer's statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.

Returns

Returns a charge object if the charge succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error if something goes wrong. A common source of error is an invalid or expired card, or a valid card with insufficient available balance.

If the cvccvccvccvccvccvccvc parameter is provided, Stripe will attempt to check the CVC's correctness, and the check's result will be returned. Similarly, if address_line1address_line1address_line1address_line1address_line1address_line1address_line1 or address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip are provided, Stripe will try to check the validity of those parameters. Some banks do not support checking one or more of these parameters, in which case Stripe will return an 'unavailable' result. Also note that, depending on the bank, charges can succeed even when passed incorrect CVC and address information.

POST https://api.stripe.com/v1/charges
Stripe::Charge.create
stripe.Charge.create()
\Stripe\Charge::create();
Charge.create();
stripe.charges.create();
charge.New()
curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d source=tok_17drHk2eZvKYlo2CEEHm8kkG \
   -d description="Charge for test@example.com"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_17drHk2eZvKYlo2CEEHm8kkG", # obtained with Stripe.js
  :description => "Charge for test@example.com"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  source="tok_17drHk2eZvKYlo2CEEHm8kkG", # obtained with Stripe.js
  description="Charge for test@example.com"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_17drHk2eZvKYlo2CEEHm8kkG", // obtained with Stripe.js
  "description" => "Charge for test@example.com"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("amount", 400);
chargeParams.put("currency", "usd");
chargeParams.put("source", "tok_17drHk2eZvKYlo2CEEHm8kkG"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");

Charge.create(chargeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.create({
  amount: 400,
  currency: "usd",
  source: "tok_17drHk2eZvKYlo2CEEHm8kkG", // obtained with Stripe.js
  description: "Charge for test@example.com"
}, function(err, charge) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

chargeParams := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
  Desc: "Charge for test@example.com",
}
chargeParams.SetSource("tok_17drHk2eZvKYlo2CEEHm8kkG")
ch, err := charge.New(chargeParams)
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Verification responses

CVC source[cvc_check]
pass The CVC provided is correct.
fail The CVC provided is incorrect.
unavailable The customer's bank did not check the CVC provided.
unchecked The CVC was provided but has not yet been checked. Checks are performed once a card is attached to a Customer object, or when a Charge is created.
Address line source[address_line1_check]
pass The first address line provided is correct.
fail The first address line provided is incorrect.
unavailable The customer's bank did not check the first address line provided.
unchecked The first address line was provided but has not yet been checked. Checks are performed once a card is attached to a Customer object, or when a Charge is created.
Address ZIP source[address_zip_check]
pass The ZIP code provided is correct.
fail The ZIP code provided is incorrect.
unavailable The customer's bank did not check the ZIP code.
unchecked The ZIP code was provided but has not yet been checked. Checks are performed once a card is attached to a Customer object, or when a Charge is created.

Retrieve a charge

Retrieves the details of a charge that has previously been created. Supply the unique charge ID that was returned from your previous request, and Stripe will return the corresponding charge information. The same information is returned when creating or refunding the charge.

Arguments
  • charge required

    The identifier of the charge to be retrieved.

Returns

Returns a charge if a valid identifier was provided, and returnsraisesraisesthrowsthrowsthrowsreturns an error otherwise.

curl https://api.stripe.com/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve("ch_17eT142eZvKYlo2CnA1fjKo8");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieve(
  "ch_17eT142eZvKYlo2CnA1fjKo8",
  function(err, charge) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := charge.Get("ch_17eT142eZvKYlo2CnA1fjKo8", nil)
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Update a charge

Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts only the description, metadata, receipt_email, fraud_details, and shipping as arguments.

Arguments
  • description optional, default is nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • fraud_details optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs you can attach to a charge giving information about its riskiness. If you believe a charge is fraudulent, include a user_report key with a value of fraudulent. If you believe a charge is safe, include a user_report key with a value of safe. Note that you must refund a charge before setting the user_report to fraudulent. Stripe will use the information you send to improve our fraud detection algorithms.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a charge object. It can be useful for storing additional information about the charge in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

  • receipt_email optional, default is nullnilNonenullnullnullnull

    This is the email address that the receipt for this charge will be sent to. If this field is updated, then a new email receipt will be sent to the updated address.

  • shipping optional, default is { }

    Shipping information for the charge. Helps prevent fraud on charges for physical goods.

Returns

Returns the charge object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an an error if update parameters are invalid.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}
ch = Stripe::Charge.retrieve({CHARGE_ID})
ch.description = {NEW_DESCRIPTION}
...
ch.save
ch = stripe.Charge.retrieve({CHARGE_ID})
ch.description = {NEW_DESCRIPTION}
...
ch.save()
$ch = \Stripe\Charge::retrieve({CHARGE_ID});
$ch->description = {NEW_DESCRIPTION};
...
$ch->save();
Charge ch = Charge.retrieve({CHARGE_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
ch.update(updateParams);
stripe.charges.update({CHARGE_ID}, {
  description: {NEW_DESCRIPTION}
});
charge.Update({CHARGE_ID}, &stripe.ChargeParams{Desc: {NEW_DESCRIPTION}})
curl https://api.stripe.com/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Charge for test@example.com"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8")
ch.description = "Charge for test@example.com"
ch.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8")
ch.description = "Charge for test@example.com"
ch.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_17eT142eZvKYlo2CnA1fjKo8");
$ch->description = "Charge for test@example.com";
$ch->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", "Charge for test@example.com");

ch.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.update(
  "ch_17eT142eZvKYlo2CnA1fjKo8",
  {
    description: "Charge for test@example.com"
  },
  function(err, charge) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Update(
  "ch_17eT142eZvKYlo2CnA1fjKo8",
  &stripe.ChargeParams{Desc: "Charge for test@example.com"},
)
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Capture a charge

Capture the payment of an existing, uncaptured, charge. This is the second half of the two-step payment flow, where first you created a charge with the capture option set to false.

Uncaptured payments expire exactly seven days after they are created. If they are not captured by that point in time, they will be marked as refunded and will no longer be capturable.

Arguments
  • charge required

  • amount optional

    The amount to capture, which must be less than or equal to the original amount. Any additional amount will be automatically refunded.

  • application_fee optional

    An application fee to add on to this charge. Can only be used with Stripe Connect.

  • receipt_email optional

    The email address to send this charge’s receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode.

  • statement_descriptor optional

    An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. Updating this value will overwrite the previous statement descriptor of this charge. While most banks display this information consistently, some may display it incorrectly or not at all.

Returns

Returns the charge object, with an updated captured property (set to true). Capturing a charge will always succeed, unless the charge is already refunded, expired, captured, or an invalid capture amount is specified, in which case this method will returnraiseraisethrowthrowthrowreturn an an error.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/capture
ch = Stripe::Charge.retrieve({CHARGE_ID})
ch.capture
ch = stripe.Charge.retrieve({CHARGE_ID})
ch.capture()
$ch = \Stripe\Charge::retrieve({CHARGE_ID});
$ch->capture();
ch = Charge.retrieve({CHARGE_ID});
ch.capture();
stripe.charges.capture({CHARGE_ID});
charge.Capture({CHARGE_ID})
curl https://api.stripe.com/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/capture \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8")
ch.capture
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8")
ch.capture()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_17eT142eZvKYlo2CnA1fjKo8");
$ch->capture();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ch = Charge.retrieve("ch_17eT142eZvKYlo2CnA1fjKo8");
ch.capture();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.capture("ch_17eT142eZvKYlo2CnA1fjKo8", function(err, charge) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Capture("ch_17eT142eZvKYlo2CnA1fjKo8", nil)
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": "True",
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": "true",
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": "true",
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": "true",
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

List all charges

Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most recent charges appearing first.

Arguments
  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • customer optional

    Only return charges for the customer specified by this customer ID.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • source optional dictionaryhashdictionaryassociative arrayMapobjectmap, default is { object: 'all' }

    A filter on the list based on the source of the charge. The value can be a dictionary with the following options:

    child arguments
    • object optional

      Return charges that match this source type string. Available options are all, alipay_account, bitcoin_receiver, or card.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit charges, starting after charge starting_after. Each entry in the array is a separate charge object. If no more charges are available, the resulting array will be empty. If you provide a non-existent customer ID, this call returnsraisesraisesthrowsthrowsthrowsreturns an error.

You can optionally request that the response include the total count of all charges that match your filters. To do so, specify include[]=total_count in your request.

GET https://api.stripe.com/v1/charges
Stripe::Charge.all
stripe.Charge.all()
\Stripe\Charge::all();
Charge.all(Map<String, Object> options);
stripe.charges.list();
charge.List()
curl https://api.stripe.com/v1/charges?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("limit", 3);

Charge.all(chargeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.list(
  { limit: 3 },
  function(err, charges) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeListParams{}
params.Filters.AddFilter("limit", "", "3")
i := charge.List(params)
for i.Next() {
  c := i.Charge()
}
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
      "object": "charge",
      "amount": 10000,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "captured": true,
      "created": 1455468394,
      "currency": "usd",
      "customer": null,
      "description": "Lots of nice things",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
      },
      "order": null,
      "paid": true,
      "receipt_email": "konrad@fortunenet.uk.com",
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17eT132eZvKYlo2C7iZgzraq",
        "object": "card",
        "address_city": "H",
        "address_country": "GB",
        "address_line1": "2",
        "address_line1_check": "pass",
        "address_line2": "I",
        "address_state": "",
        "address_zip": "S",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "K",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    #<Stripe::Charge id=ch_17eT142eZvKYlo2CnA1fjKo8 0x00000a> JSON: {
      "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
      "object": "charge",
      "amount": 10000,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "captured": true,
      "created": 1455468394,
      "currency": "usd",
      "customer": null,
      "description": "Lots of nice things",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
      },
      "order": null,
      "paid": true,
      "receipt_email": "konrad@fortunenet.uk.com",
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17eT132eZvKYlo2C7iZgzraq",
        "object": "card",
        "address_city": "H",
        "address_country": "GB",
        "address_line1": "2",
        "address_line1_check": "pass",
        "address_line2": "I",
        "address_state": "",
        "address_zip": "S",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "K",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    #<Stripe::Charge[...] ...>,
    #<Stripe::Charge[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/charges",
  has_more: false,
  data: [
    <Charge charge id=ch_17eT142eZvKYlo2CnA1fjKo8 at 0x00000a> JSON: {
      "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
      "object": "charge",
      "amount": 10000,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "captured": true,
      "created": 1455468394,
      "currency": "usd",
      "customer": null,
      "description": "Lots of nice things",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
      },
      "order": null,
      "paid": true,
      "receipt_email": "konrad@fortunenet.uk.com",
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17eT132eZvKYlo2C7iZgzraq",
        "object": "card",
        "address_city": "H",
        "address_country": "GB",
        "address_line1": "2",
        "address_line1_check": "pass",
        "address_line2": "I",
        "address_state": "",
        "address_zip": "S",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "K",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    <stripe.Charge[...] ...>,
    <stripe.Charge[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/charges",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Charge JSON: {
      "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
      "object": "charge",
      "amount": 10000,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "captured": true,
      "created": 1455468394,
      "currency": "usd",
      "customer": null,
      "description": "Lots of nice things",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
      },
      "order": null,
      "paid": true,
      "receipt_email": "konrad@fortunenet.uk.com",
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17eT132eZvKYlo2C7iZgzraq",
        "object": "card",
        "address_city": "H",
        "address_country": "GB",
        "address_line1": "2",
        "address_line1_check": "pass",
        "address_line2": "I",
        "address_state": "",
        "address_zip": "S",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "K",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
    [1] => <Stripe\Charge[...] ...>
    [2] => <Stripe\Charge[...] ...>
  ]
}
#<com.stripe.model.ChargeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Charge JSON: {
      "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
      "object": "charge",
      "amount": 10000,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "captured": true,
      "created": 1455468394,
      "currency": "usd",
      "customer": null,
      "description": "Lots of nice things",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
      },
      "order": null,
      "paid": true,
      "receipt_email": "konrad@fortunenet.uk.com",
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17eT132eZvKYlo2C7iZgzraq",
        "object": "card",
        "address_city": "H",
        "address_country": "GB",
        "address_line1": "2",
        "address_line1_check": "pass",
        "address_line2": "I",
        "address_state": "",
        "address_zip": "S",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "K",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    #<com.stripe.model.Charge[...] ...>,
    #<com.stripe.model.Charge[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
      "object": "charge",
      "amount": 10000,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
      "captured": true,
      "created": 1455468394,
      "currency": "usd",
      "customer": null,
      "description": "Lots of nice things",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
      },
      "order": null,
      "paid": true,
      "receipt_email": "konrad@fortunenet.uk.com",
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17eT132eZvKYlo2C7iZgzraq",
        "object": "card",
        "address_city": "H",
        "address_country": "GB",
        "address_line1": "2",
        "address_line1_check": "pass",
        "address_line2": "I",
        "address_state": "",
        "address_zip": "S",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "K",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    {...},
    {...}
  ]
}
&stripe.Charge JSON: {
  "id": "ch_17eT142eZvKYlo2CnA1fjKo8",
  "object": "charge",
  "amount": 10000,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "captured": true,
  "created": 1455468394,
  "currency": "usd",
  "customer": null,
  "description": "Lots of nice things",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
  },
  "order": null,
  "paid": true,
  "receipt_email": "konrad@fortunenet.uk.com",
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17eT142eZvKYlo2CnA1fjKo8/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17eT132eZvKYlo2C7iZgzraq",
    "object": "card",
    "address_city": "H",
    "address_country": "GB",
    "address_line1": "2",
    "address_line1_check": "pass",
    "address_line2": "I",
    "address_state": "",
    "address_zip": "S",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2016,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": "K",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Customers

Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.

The customer object

Attributes
  • id string

  • object string , value is "customer"

  • account_balance integer

    Current balance, if any, being stored on the customer’s account. If negative, the customer has credit to apply to the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account for recurring charges.

  • created timestamp

  • currency string

    The currency the customer can be charged in for recurring billing purposes (subscriptions, invoices, invoice items).

  • default_source string

    ID of the default source attached to this customer.

  • delinquent boolean

    Whether or not the latest charge for the customer’s latest invoice has failed

  • description string

  • discount hash, discount object

    Describes the current discount active on the customer, if there is one.

  • email string

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format.

  • shipping hash

    Shipping information associated with the customer.

    child attributes
    • address hash

      Customer shipping address.

      child attributes
      • city string

        City/Suburb/Town/Village/Ward

      • country string

        2-letter country code

      • line1 string

        Address line 1 (Street address/PO Box/Company name)

      • line2 string

        Address line 2 (Apartment/Suite/Unit/Building)

      • postal_code string

        Zip/Postal Code

      • state string

        State/Province/County/Prefecture

    • name string

      Customer name.

    • phone string

      Customer phone (including extension).

  • sources list

    The customer’s payment sources, if any

    child attributes
    • object string , value is "list"

    • data array

      The list contains all payment sources that have been attached to the customer. These may be Cards or BitcoinReceivers.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • subscriptions list

    The customer’s current subscriptions, if any

    child attributes
    • object string , value is "list"

    • data array, contains: subscription object

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
#<Stripe::Customer id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
<Customer customer id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}

Create a customer

Creates a new customer object.

Arguments
  • account_balance optional

    An integer amount in cents that is the starting account balance for your customer. A negative amount represents a credit that will be used before attempting any charges to the customer’s card; a positive amount will be added to the next invoice.

  • coupon optional

    If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount.

  • description optional

    An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • email optional

    Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • metadata optional

    A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • plan optional

    The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a valid card as well.

  • quantity optional

    The quantity you’d like to apply to the subscription you’re creating (if you pass in a plan). For example, if your plan is 10 cents/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged 50 cents (5 x 10 cents) monthly. Defaults to 1 if not set. Only applies when the plan parameter is also provided.

  • shipping optional dictionaryhashdictionaryassociative arrayMapobjectmap

    child arguments
    • address required

      child arguments
      • line1 required

      • city optional

      • country optional

      • line2 optional

      • postal_code optional

      • state optional

    • name required

    • phone optional

  • source optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The source can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below).

    child arguments
    • object required

      The type of payment source. Should be "card".

    • exp_month required

      Two digit number representing the card's expiration month.

    • exp_year required

      Two or four digit number representing the card's expiration year.

    • number required

      The card number, as a string without any separators.

    • address_city optional

    • address_country optional

    • address_line1 optional

    • address_line2 optional

    • address_state optional

    • address_zip optional

    • currency managed accounts only

      Required when adding a card to an account (not applicable to a customers or recipients). The card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • default_for_currency managed accounts only

      Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added in this currency) this card will become the default external account for its currency.

    • metadata optional

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name optional

      Cardholder's full name.

  • tax_percent optional

    A positive decimal (with at most two decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice. Can only be used if a plan is provided.

  • trial_end optional

    Unix timestamp representing the end of the trial period the customer will get before being charged. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.

Returns

Returns a customer object if the call succeeded. The returned object will have information about subscriptions, discount, and payment sources, if that information has been provided. If an invoice payment is due and a source is not provided, the call will returnraiseraisethrowthrowthrowreturn an an error. If a non-existent plan or a non-existent or expired coupon is provided, the call will returnraiseraisethrowthrowthrowreturn an an error.

If a source has been attached to the customer, the returned customer object will have a default_source attribute, which is an ID that can be expanded into the full source details when retrieving the customer.

POST https://api.stripe.com/v1/customers
Stripe::Customer.create
stripe.Customer.create()
\Stripe\Customer::create();
Customer.create();
stripe.customers.create();
customer.New()
curl https://api.stripe.com/v1/customers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Customer for test@example.com" \
   -d source=tok_17drHk2eZvKYlo2CEEHm8kkG
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.create(
  :description => "Customer for test@example.com",
  :source => "tok_17drHk2eZvKYlo2CEEHm8kkG" # obtained with Stripe.js
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.create(
  description="Customer for test@example.com",
  source="tok_17drHk2eZvKYlo2CEEHm8kkG" # obtained with Stripe.js
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::create(array(
  "description" => "Customer for test@example.com",
  "source" => "tok_17drHk2eZvKYlo2CEEHm8kkG" // obtained with Stripe.js
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("description", "Customer for test@example.com");
customerParams.put("source", "tok_17drHk2eZvKYlo2CEEHm8kkG"); // obtained with Stripe.js

Customer.create(customerParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.create({
  description: 'Customer for test@example.com',
  source: "tok_17drHk2eZvKYlo2CEEHm8kkG" // obtained with Stripe.js
}, function(err, customer) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customerParams := &stripe.CustomerParams{
  Desc: "Customer for test@example.com",
}
customerParams.SetSource("tok_17drHk2eZvKYlo2CEEHm8kkG") // obtained with Stripe.js
c, err := customer.New(customerParams)
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
#<Stripe::Customer id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
<Customer customer id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}

Retrieve a customer

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

Arguments
  • customer required

    The identifier of the customer to be retrieved.

Returns

Returns a customer object if a valid identifier was provided. When requesting the ID of a customer that has been deleted, a subset of the customer’s information will be returned, including a deleted property, which will be true.

curl https://api.stripe.com/v1/customers/cus_7uHWPtibiepb6V \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cus_7uHWPtibiepb6V")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cus_7uHWPtibiepb6V")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cus_7uHWPtibiepb6V");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.retrieve("cus_7uHWPtibiepb6V");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieve(
  "cus_7uHWPtibiepb6V",
  function(err, customer) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Get("cus_7uHWPtibiepb6V", nil)
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
#<Stripe::Customer id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
<Customer customer id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}

Update a customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer's active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid source: for each of the customer's current subscriptions, if the subscription is in the past_due state, then the latest unpaid, unclosed invoice for the subscription will be retried (note that this retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice). (Note also that no invoices pertaining to subscriptions in the unpaid state, or invoices pertaining to canceled subscriptions, will be retried as a result of updating the customer's source.)

This request accepts mostly the same arguments as the customer creation call.

Arguments
  • account_balance optional

    An integer amount in cents that represents the account balance for your customer. Account balances only affect invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.

  • coupon optional

    If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount.

  • default_source optional

    ID of source to make the customer’s new default for invoice payments

  • description optional

    An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • email optional

    Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • metadata optional

    A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • shipping optional dictionaryhashdictionaryassociative arrayMapobjectmap

    child arguments
    • address required

      child arguments
      • line1 required

      • city optional

      • country optional

      • line2 optional

      • postal_code optional

      • state optional

    • name required

    • phone optional

  • source optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The source can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below). Passing source will create a new source object, make it the new customer default source, and delete the old customer default if one exists. If you want to add additional sources instead of replacing the existing default, use the card creation API. Whenever you attach a card to a customer, Stripe will automatically validate the card.

    child arguments
    • object required

      The type of payment source. Should be "card".

    • exp_month required

      Two digit number representing the card's expiration month.

    • exp_year required

      Two or four digit number representing the card's expiration year.

    • number required

      The card number, as a string without any separators.

    • address_city optional

    • address_country optional

    • address_line1 optional

    • address_line2 optional

    • address_state optional

    • address_zip optional

    • currency managed accounts only

      Required when adding a card to an account (not applicable to a customers or recipients). The card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • default_for_currency managed accounts only

      Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added in this currency) this card will become the default external account for its currency.

    • metadata optional

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name optional

      Cardholder's full name.

Returns

Returns the customer object if the update succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error if update parameters are invalid (e.g. specifying an invalid coupon or an invalid source).

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}
cu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.description = {NEW_DESCRIPTION}
...
cu.save
cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.description = {NEW_DESCRIPTION}
...
cu.save()
$cu = \Stripe\Customer::retrieve({CUSTOMER_ID});
$cu->description = {NEW_DESCRIPTION};
...
$cu->save();
Customer cu = Customer.retrieve({CUSTOMER_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
cu.update(updateParams);
stripe.customers.update({CUSTOMER_ID}, {
  description: {NEW_DESCRIPTION},
  ...
});
customer.Update(
  {CUSTOMER_ID},
  &stripe.CustomerParams{
    Desc: {NEW_DESCRIPTION},
    ...
  })
curl https://api.stripe.com/v1/customers/cus_7uHWPtibiepb6V \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Customer for test@example.com"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_7uHWPtibiepb6V")
cu.description = "Customer for test@example.com"
cu.source = "tok_17drHk2eZvKYlo2CEEHm8kkG" # obtained with Stripe.js
cu.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_7uHWPtibiepb6V")
cu.description = "Customer for test@example.com"
cu.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7uHWPtibiepb6V");
$cu->description = "Customer for test@example.com";
$cu->source = "tok_17drHk2eZvKYlo2CEEHm8kkG"; // obtained with Stripe.js
$cu->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7uHWPtibiepb6V");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", "Customer for test@example.com");

cu.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.update("cus_7uHWPtibiepb6V", {
  description: "Customer for test@example.com"
}, function(err, customer) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Update(
      "cus_7uHWPtibiepb6V",
      &stripe.CustomerParams{Desc: "Customer for test@example.com"},
    )
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
#<Stripe::Customer id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
<Customer customer id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
{
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}

Delete a customer

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

Arguments
  • customer required

    The identifier of the customer to be deleted

Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, this call returnsraisesraisesthrowsthrowsthrowsreturns an error.

Unlike other objects, deleted customers can still be retrieved through the API, in order to be able to track the history of customers while still removing their credit card details and preventing any further operations to be performed (such as adding a new subscription).

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}
cu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.delete
cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.delete()
$cu = \Stripe\Customer::retrieve({CUSTOMER_ID});
$cu->delete();
Customer cu = Customer.retrieve({CUSTOMER_ID});
cu.delete();
stripe.customers.del({CUSTOMER_ID});
customer.Del({CUSTOMER_ID})
curl https://api.stripe.com/v1/customers/cus_7uHWPtibiepb6V \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_7uHWPtibiepb6V")
cu.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_7uHWPtibiepb6V")
cu.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7uHWPtibiepb6V");
$cu->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7uHWPtibiepb6V");
cu.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.del(
  "cus_7uHWPtibiepb6V",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := customer.Del("cus_7uHWPtibiepb6V")
{
  "deleted": true,
  "id": "cus_7uHWPtibiepb6V"
}
#<Stripe::Object id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_7uHWPtibiepb6V"
}
<Object object id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_7uHWPtibiepb6V"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "cus_7uHWPtibiepb6V"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "cus_7uHWPtibiepb6V"
}
{
  "deleted": true,
  "id": "cus_7uHWPtibiepb6V"
}
nil

List all customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Arguments
  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit customers, starting after customer starting_after. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrowreturn an an error.

You can optionally request that the response include the total count of all customers that match your filters. To do so, specify include[]=total_count in your request.

GET https://api.stripe.com/v1/customers
Stripe::Customer.all
stripe.Customer.all()
\Stripe\Customer::all();
Customer.all(Map<String, Object> options);
stripe.customers.list();
customer.List()
curl https://api.stripe.com/v1/customers?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("limit", 3);

Customer.all(customerParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.list(
  { limit: 3 },
  function(err, customers) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CustomerListParams{}
params.Filters.AddFilter("limit", "", "3")
i := customer.List(params)
for i.Next() {
  c := i.Customer()
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_7uHWPtibiepb6V 0x00000a> JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers",
  has_more: false,
  data: [
    <Customer customer id=cus_7uHWPtibiepb6V at 0x00000a> JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7uHWPtibiepb6V",
      "object": "customer",
      "account_balance": 0,
      "created": 1455468196,
      "currency": "usd",
      "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": "someone@example.com",
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17eSxo2eZvKYlo2CutV5MSci",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7uHWPtibiepb6V",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2016,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": "someone@example.com",
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
&stripe.Customer JSON: {
  "id": "cus_7uHWPtibiepb6V",
  "object": "customer",
  "account_balance": 0,
  "created": 1455468196,
  "currency": "usd",
  "default_source": "card_17eSxo2eZvKYlo2CutV5MSci",
  "delinquent": false,
  "description": null,
  "discount": null,
  "email": "someone@example.com",
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17eSxo2eZvKYlo2CutV5MSci",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7uHWPtibiepb6V",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2016,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": "someone@example.com",
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7uHWPtibiepb6V/subscriptions"
  }
}

Disputes

A dispute occurs when a customer questions your charge with their bank or credit card company. When a customer disputes your charge, you're given the opportunity to respond to the dispute with evidence that shows the charge is legitimate. You can find more information about the dispute process in our disputes FAQ.

The dispute object

Attributes
  • id string

  • object string , value is "dispute"

  • amount integer

    Disputed amount. Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).

  • balance_transactions array, contains: balance_transaction object

    List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.

  • charge string

    ID of the charge that was disputed

  • created timestamp

    Date dispute was opened

  • currency currency

    Three-letter ISO currency code representing the currency of the amount that was disputed.

  • evidence hash, dispute_evidence object

    Evidence provided to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review.

  • evidence_details hash

    Information about the evidence submission.

    child attributes
    • due_by timestamp

      Date by which evidence must be submitted in order to successfully challenge dispute. Will be null if the customer’s bank or credit card company doesn’t allow a response for this particular dispute.

    • has_evidence boolean

      Whether or not evidence has been saved for this dispute.

    • past_due boolean

      Whether or not the last evidence submission was submitted past the due date. Defaults to false if no evidence submissions have occurred. If true, then delivery of the latest evidence is not guaranteed.

    • submission_count integer

      The number of times the evidence has been submitted. You may submit evidence a maximum of 5 times.

  • is_charge_refundable boolean

    If true, it is still possible to refund the disputed payment. Once the payment has been fully refunded, no further funds will be withdrawn from your Stripe account as a result of this dispute.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a dispute object. It can be useful for storing additional information about the dispute in a structured format.

  • reason string

    Reason given by cardholder for dispute. Possible values are duplicate, fraudulent, subscription_canceled, product_unacceptable, product_not_received, unrecognized, credit_not_processed, incorrect_account_details, insufficient_funds, bank_cannot_process, debit_not_authorized, general. Read more about dispute reasons.

  • status string

    Current status of dispute. Possible values are warning_needs_response, warning_under_review, warning_closed, needs_response, response_disabled, under_review, charge_refunded, won, lost.

{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

The dispute_evidence object

Attributes
  • access_activity_log string

    Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity.

  • billing_address string

    The billing addess provided by the customer.

  • cancellation_policy string

    (ID of a file upload) Your subscription cancellation policy, as shown to the customer.

  • cancellation_policy_disclosure string

    An explanation of how and when the customer was shown your refund policy prior to purchase.

  • cancellation_rebuttal string

    A justification for why the customer’s subscription was not canceled.

  • customer_communication string

    (ID of a file upload) Any communication with the customer that you feel is relevant to your case (for example emails proving that they received the product or service, or demonstrating their use of or satisfaction with the product or service).

  • customer_email_address string

    The email address of the customer.

  • customer_name string

    The name of the customer.

  • customer_purchase_ip string

    The IP address that the customer used when making the purchase.

  • customer_signature string

    (ID of a file upload) A relevant document or contract showing the customer’s signature.

  • duplicate_charge_documentation string

    (ID of a file upload) Documentation for the prior charge that can uniquely identify the charge, such as a receipt, shipping label, work order, etc. This document should be paired with a similar document from the disputed payment that proves the two payments are separate.

  • duplicate_charge_explanation string

    An explanation of the difference between the disputed charge and the prior charge that appears to be a duplicate.

  • duplicate_charge_id string

    The Stripe ID for the prior charge which appears to be a duplicate of the disputed charge.

  • product_description string

    A description of the product or service which was sold.

  • receipt string

    (ID of a file upload) Any receipt or message sent to the customer notifying them of the charge.

  • refund_policy string

    (ID of a file upload) Your refund policy, as shown to the customer.

  • refund_policy_disclosure string

    Documentation demonstrating that the customer was shown your refund policy prior to purchase.

  • refund_refusal_explanation string

    A justification for why the customer is not entitled to a refund.

  • service_date string

    The date on which the customer received or began receiving the purchased service, in a clear human-readable format.

  • service_documentation string

    (ID of a file upload) Documentation showing proof that a service was provided to the customer. This could include a copy of a signed contract, work order, or other form of written agreement.

  • shipping_address string

    The address to which a physical product was shipped. You should try to include as much complete address information as possible.

  • shipping_carrier string

    The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas.

  • shipping_date string

    The date on which a physical product began its route to the shipping address, in a clear human-readable format.

  • shipping_documentation string

    (ID of a file upload) Documentation showing proof that a product was shipped to the customer at the same address the customer provided to you. This could include a copy of the shipment receipt, shipping label, etc, and should show the full shipping address of the customer, if possible.

  • shipping_tracking_number string

    The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

  • uncategorized_file string

    (ID of a file upload) Any additional evidence or statements.

  • uncategorized_text string

    Any additional evidence or statements.

{
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
#<Stripe::Object 0x00000a> JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
<Object object at 0x00000a> JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
Stripe\Object JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
com.stripe.model.Object JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
{
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
&stripe.Object JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}

Retrieve a dispute

Retrieves the dispute with the given ID.

Arguments
  • dispute required

    ID of dispute to retrieve.

Returns

Returns a dispute if a valid dispute ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

curl https://api.stripe.com/v1/disputes/dp_17Vv962eZvKYlo2CU7XhGGzB \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Dispute::retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.retrieve(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  function(err, dispute) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Get("dp_17Vv962eZvKYlo2CU7XhGGzB", nil)
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

Update a dispute

When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence in order to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.

Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. You may want to consult our guide to dispute types to help you figure out which evidence fields to provide.

Arguments
  • dispute required

    ID of the dispute to update.

  • evidence optional

    Evidence to upload to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review.

  • metadata optional

    A set of key/value pairs that you can attach to a dispute object. It can be useful for storing additional information about the dispute in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

Returns

Returns the dispute object.

POST https://api.stripe.com/v1/disputes/{DISPUTE_ID}
dispute = Stripe::Dispute.retrieve({DISPUTE_ID})
dispute.evidence => {NEW_EVIDENCE}
dispute.save
dispute = stripe.Dispute.retrieve({DISPUTE_ID})
dispute.evidence = {NEW_EVIDENCE}
dispute.save()
$dispute = \Stripe\Dispute::retrieve({DISPUTE_ID});
$dispute->evidence = {NEW_EVIDENCE};
$dispute->save();
Dispute dp = Dispute.retrieve({DISPUTE_ID});
Map<String, Object> disputeParams = new HashMap<String, Object>();
disputeParams.put("evidence", {NEW_EVIDENCE});
dp.update(disputeParams);
stripe.disputes.update({DISPUTE_ID}, {
  evidence: {NEW_EVIDENCE}
});
dispute.Update({DISPUTE_ID}, &stripe.DisputeParams{Evidence: {NEW_EVIDENCE}})
curl https://api.stripe.com/v1/disputes/dp_17Vv962eZvKYlo2CU7XhGGzB \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d evidence[customer_name]="Jane Austen" \
   -d evidence[product_description]="Lorem ipsum dolor sit amet." \
   -d evidence[shipping_documentation]=fil_15BZxW2eZvKYlo2CvQbrn9dc
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = Stripe::Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.evidence = {
    :customer_name => "Jane Austen",
    :product_description => "Lorem ipsum dolor sit amet.",
    :shipping_documentation => "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  }
dispute.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = stripe.Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.evidence = {
    "customer_name": 'Jane Austen',
    "product_description": 'Lorem ipsum dolor sit amet.',
    "shipping_documentation": 'fil_15BZxW2eZvKYlo2CvQbrn9dc'
  }
dispute.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$dp = \Stripe\Dispute::retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
$dp->evidence = array(
    "customer_name" => "Jane Austen",
    "product_description" => "Lorem ipsum dolor sit amet.",
    "shipping_documentation" => "fil_15BZxW2eZvKYlo2CvQbrn9dc"
  );
$dp->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute dp = Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
Map<String, Object> params = new HashMap<String, Object>();
Map<String, Object> evidence = new HashMap<String, Object>();
evidence.put("customer_name", "Jane Austen")
evidence.put("product_description", "Lorem ipsum dolor sit amet.")
evidence.put("shipping_documentation", "fil_15BZxW2eZvKYlo2CvQbrn9dc")
params.put("evidence", evidence)
dp.update(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.update(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  {
    evidence: {
      customer_name: 'Jane Austen',
      product_description: 'Lorem ipsum dolor sit amet.',
      shipping_documentation: 'fil_15BZxW2eZvKYlo2CvQbrn9dc'
    }
  },
  function(err, dispute) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Update(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  &stripe.DisputeParams{
    Evidence: &stripe.DisputeEvidenceParams{
      CustomerName: "Jane Austen",
      ProductDesc: "Lorem ipsum dolor sit amet.",
      ShippingDoc: "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    },
  },
)
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

Close a dispute

Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially ‘dismissing’ the dispute, acknowledging it as lost

The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.

Arguments
  • dispute required

    ID of dispute to close.

Returns

Returns the dispute object.

POST https://api.stripe.com/v1/disputes/{DISPUTE_ID}/close
dispute = Stripe::Dispute.retrieve({DISPUTE_ID})
dispute.close
dispute = stripe.Dispute.retrieve({DISPUTE_ID})
dispute.close()
$dispute = \Stripe\Dispute::retrieve({DISPUTE_ID});
$dispute.close();
Dispute dp = Dispute.retrieve({DISPUTE_ID});
dp.close();
stripe.disputes.close({DISPUTE_ID});
dispute.Close({DISPUTE_ID})
curl https://api.stripe.com/v1/disputes/dp_17Vv962eZvKYlo2CU7XhGGzB/close \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = Stripe::Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.close
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = stripe.Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.close()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$dp = \Stripe\Dispute::retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
$dp->close();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute dp = Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
dp.close()
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.close(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  function(err, dispute) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Close("dp_17Vv962eZvKYlo2CU7XhGGzB")
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}

List all disputes

Returns a list of your disputes.

Arguments
  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit disputes, starting after dispute starting_after. Each entry in the array is a separate dispute object. If no more disputes are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrowreturn an an error.

You can optionally request that the response include the total count of all disputes. To do so, specify include[]=total_count in your request.

GET https://api.stripe.com/v1/disputes
Stripe::Dispute.all
stripe.Dispute.all()
\Stripe\Dispute::all();
Dispute.all(Map<String, Object> options);
stripe.disputes.list();
dispute.List()
curl https://api.stripe.com/v1/disputes?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Dispute.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Dispute.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Dispute::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> disputeParams = new HashMap<String, Object>();
disputeParams.put("limit", 3);

Dispute.all(disputeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.list(
  { limit: 3 },
  function(err, disputes) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.DisputeListParams{}
params.Filters.AddFilter("limit", "", "3")
i := dispute.List(params)
for i.Next() {
  d := i.Dispute()
}
{
  "object": "list",
  "url": "/v1/disputes",
  "has_more": false,
  "data": [
    {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "available",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/disputes",
  "has_more": false,
  "data": [
    #<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "available",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    #<Stripe::Dispute[...] ...>,
    #<Stripe::Dispute[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/disputes",
  has_more: false,
  data: [
    <Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "available",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    <stripe.Dispute[...] ...>,
    <stripe.Dispute[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/disputes",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Dispute JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "available",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    }
    [1] => <Stripe\Dispute[...] ...>
    [2] => <Stripe\Dispute[...] ...>
  ]
}
#<com.stripe.model.DisputeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Dispute JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "available",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    #<com.stripe.model.Dispute[...] ...>,
    #<com.stripe.model.Dispute[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/disputes",
  "has_more": false,
  "data": [
    {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "available",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    {...},
    {...}
  ]
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "available",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

Events

Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when a charge succeeds, we create a charge.succeeded event; When an invoice payment attempt fails, we create an invoice.payment_failed event. Note that many API requests may cause multiple events to be created. For example, if you create a new subscription for a customer, you will receive both a customer.subscription.created event and a charge.succeeded event.

Like our other API resources, you can retrieve an individual event or a list of events from the API. We also have a system for sending the events directly to your server, called webhooks. Webhooks are managed in your account settings, and our webhook guide will help you get set up.

When using Connect, you can also receive notifications of events that occur in connected accounts. For these events, there will be an additional user_id attribute in the received Event object.

NOTE: Right now, we only guarantee access to events through the Retrieve Event API for 30 days.

The event object

Attributes
  • id string

  • object string , value is "event"

  • api_version string

    The Stripe API version used to render data. Note: this property is populated for events on or after October 31, 2014.

  • created timestamp

  • data hash

    Hash containing data associated with the event.

    child attributes
    • object hash

      describes the object the event is about. For example, an invoice.created event will have a full invoice object as the value of the object key.

    • previous_attributes hash

      Hash containing the names of the attributes that have changed and their previous values (only sent along with *.updated events)

  • livemode boolean

  • pending_webhooks positive integer or zero

    Number of webhooks yet to be delivered successfully (return a 20x response) to the URLs you’ve specified.

  • request string

    ID of the API request that caused the event. If null, the event was automatic (e.g. Stripe’s automatic subscription handling). Request logs are available in the dashboard but currently not in the API. Note: this property is populated for events on or after April 23, 2013.

  • type string

    Description of the event: e.g. invoice.created, charge.refunded, etc.

{
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
#<Stripe::Event id=evt_17eT292eZvKYlo2C2iRwF7Wr 0x00000a> JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
<Event event id=evt_17eT292eZvKYlo2C2iRwF7Wr at 0x00000a> JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
Stripe\Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
com.stripe.model.Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
{
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
&stripe.Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}

Retrieve an event

Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.

Arguments
  • id required

    The identifier of the event to be retrieved.

Returns

Returns an event object if a valid identifier was provided. All events share a common structure, detailed to the right. The only property that will differ is the data property.

In each case, the data dictionaryhashdictionaryassociative arrayMapobjectmap will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, a customer.created event will have the same information as retrieving the relevant customer would.

In cases where the attributes of an object have changed, data will also contain a dictionaryhashdictionaryassociative arrayMapobjectmap containing the changes.

curl https://api.stripe.com/v1/events/evt_17eT292eZvKYlo2C2iRwF7Wr \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Event.retrieve("evt_17eT292eZvKYlo2C2iRwF7Wr")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Event.retrieve("evt_17eT292eZvKYlo2C2iRwF7Wr")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Event::retrieve("evt_17eT292eZvKYlo2C2iRwF7Wr");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Event.retrieve("evt_17eT292eZvKYlo2C2iRwF7Wr");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.events.retrieve(
  "evt_17eT292eZvKYlo2C2iRwF7Wr",
  function(err, event) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

e, err := event.Get("evt_17eT292eZvKYlo2C2iRwF7Wr")
{
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
#<Stripe::Event id=evt_17eT292eZvKYlo2C2iRwF7Wr 0x00000a> JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
<Event event id=evt_17eT292eZvKYlo2C2iRwF7Wr at 0x00000a> JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
Stripe\Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
com.stripe.model.Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
{
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}
&stripe.Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}

List all events

List events, going back up to 30 days.

Arguments
  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • type optional

    A string containing a specific event name, or group of events using * as a wildcard. The list will be filtered to include only events with a matching event property

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit events, starting after event starting_after. Each entry in the array is a separate event object. If no more events are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrowreturn an an error.

You can optionally request that the response include the total count of all events that match your filters. To do so, specify include[]=total_count in your request.

GET https://api.stripe.com/v1/events
Stripe::Event.all
stripe.Event.all()
\Stripe\Event::all();
Event.all(Map<String, Object> options);
stripe.events.list();
event.List()
curl https://api.stripe.com/v1/events?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Event.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Event.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Event::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> eventParams = new HashMap<String, Object>();
eventParams.put("limit", 3);

Event.all(eventParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.events.list(
  { limit: 3 },
  function(err, events) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.EventListParams{}
params.Filters.AddFilter("limit", "", "3")
i := event.List(params)
for i.Next() {
  e := i.Event()
}
{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
      "object": "event",
      "api_version": "2016-02-03",
      "created": 1455468461,
      "data": {
        "object": {
          "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
          "object": "invoice",
          "amount_due": 0,
          "application_fee": null,
          "attempt_count": 0,
          "attempted": true,
          "charge": null,
          "closed": true,
          "currency": "usd",
          "customer": "cus_4OzVDNEzwljzDO",
          "date": 1455464556,
          "description": null,
          "discount": null,
          "ending_balance": 0,
          "forgiven": false,
          "lines": {
            "object": "list",
            "data": [
              {
                "id": "sub_4OzVHUhVi2G9ZN",
                "object": "line_item",
                "amount": 0,
                "currency": "usd",
                "description": null,
                "discountable": true,
                "livemode": false,
                "metadata": {
                },
                "period": {
                  "start": 1455464290,
                  "end": 1457969890
                },
                "plan": {
                  "id": "hjhlew",
                  "object": "plan",
                  "amount": 0,
                  "created": 1405352288,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {
                  },
                  "name": "Starter",
                  "statement_descriptor": null,
                  "trial_period_days": null
                },
                "proration": false,
                "quantity": 1,
                "subscription": null,
                "type": "subscription"
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
          },
          "livemode": false,
          "metadata": {
          },
          "next_payment_attempt": null,
          "paid": true,
          "period_end": 1455464290,
          "period_start": 1452785890,
          "receipt_number": null,
          "starting_balance": 0,
          "statement_descriptor": null,
          "subscription": "sub_4OzVHUhVi2G9ZN",
          "subtotal": 0,
          "tax": null,
          "tax_percent": null,
          "total": 0,
          "webhooks_delivered_at": 1455464569
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": null,
      "type": "invoice.payment_succeeded"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    #<Stripe::Event id=evt_17eT292eZvKYlo2C2iRwF7Wr 0x00000a> JSON: {
      "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
      "object": "event",
      "api_version": "2016-02-03",
      "created": 1455468461,
      "data": {
        "object": {
          "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
          "object": "invoice",
          "amount_due": 0,
          "application_fee": null,
          "attempt_count": 0,
          "attempted": true,
          "charge": null,
          "closed": true,
          "currency": "usd",
          "customer": "cus_4OzVDNEzwljzDO",
          "date": 1455464556,
          "description": null,
          "discount": null,
          "ending_balance": 0,
          "forgiven": false,
          "lines": {
            "object": "list",
            "data": [
              {
                "id": "sub_4OzVHUhVi2G9ZN",
                "object": "line_item",
                "amount": 0,
                "currency": "usd",
                "description": null,
                "discountable": true,
                "livemode": false,
                "metadata": {
                },
                "period": {
                  "start": 1455464290,
                  "end": 1457969890
                },
                "plan": {
                  "id": "hjhlew",
                  "object": "plan",
                  "amount": 0,
                  "created": 1405352288,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {
                  },
                  "name": "Starter",
                  "statement_descriptor": null,
                  "trial_period_days": null
                },
                "proration": false,
                "quantity": 1,
                "subscription": null,
                "type": "subscription"
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
          },
          "livemode": false,
          "metadata": {
          },
          "next_payment_attempt": null,
          "paid": true,
          "period_end": 1455464290,
          "period_start": 1452785890,
          "receipt_number": null,
          "starting_balance": 0,
          "statement_descriptor": null,
          "subscription": "sub_4OzVHUhVi2G9ZN",
          "subtotal": 0,
          "tax": null,
          "tax_percent": null,
          "total": 0,
          "webhooks_delivered_at": 1455464569
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": null,
      "type": "invoice.payment_succeeded"
    },
    #<Stripe::Event[...] ...>,
    #<Stripe::Event[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/events",
  has_more: false,
  data: [
    <Event event id=evt_17eT292eZvKYlo2C2iRwF7Wr at 0x00000a> JSON: {
      "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
      "object": "event",
      "api_version": "2016-02-03",
      "created": 1455468461,
      "data": {
        "object": {
          "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
          "object": "invoice",
          "amount_due": 0,
          "application_fee": null,
          "attempt_count": 0,
          "attempted": true,
          "charge": null,
          "closed": true,
          "currency": "usd",
          "customer": "cus_4OzVDNEzwljzDO",
          "date": 1455464556,
          "description": null,
          "discount": null,
          "ending_balance": 0,
          "forgiven": false,
          "lines": {
            "object": "list",
            "data": [
              {
                "id": "sub_4OzVHUhVi2G9ZN",
                "object": "line_item",
                "amount": 0,
                "currency": "usd",
                "description": null,
                "discountable": true,
                "livemode": false,
                "metadata": {
                },
                "period": {
                  "start": 1455464290,
                  "end": 1457969890
                },
                "plan": {
                  "id": "hjhlew",
                  "object": "plan",
                  "amount": 0,
                  "created": 1405352288,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {
                  },
                  "name": "Starter",
                  "statement_descriptor": null,
                  "trial_period_days": null
                },
                "proration": false,
                "quantity": 1,
                "subscription": null,
                "type": "subscription"
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
          },
          "livemode": false,
          "metadata": {
          },
          "next_payment_attempt": null,
          "paid": true,
          "period_end": 1455464290,
          "period_start": 1452785890,
          "receipt_number": null,
          "starting_balance": 0,
          "statement_descriptor": null,
          "subscription": "sub_4OzVHUhVi2G9ZN",
          "subtotal": 0,
          "tax": null,
          "tax_percent": null,
          "total": 0,
          "webhooks_delivered_at": 1455464569
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": null,
      "type": "invoice.payment_succeeded"
    },
    <stripe.Event[...] ...>,
    <stripe.Event[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/events",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Event JSON: {
      "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
      "object": "event",
      "api_version": "2016-02-03",
      "created": 1455468461,
      "data": {
        "object": {
          "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
          "object": "invoice",
          "amount_due": 0,
          "application_fee": null,
          "attempt_count": 0,
          "attempted": true,
          "charge": null,
          "closed": true,
          "currency": "usd",
          "customer": "cus_4OzVDNEzwljzDO",
          "date": 1455464556,
          "description": null,
          "discount": null,
          "ending_balance": 0,
          "forgiven": false,
          "lines": {
            "object": "list",
            "data": [
              {
                "id": "sub_4OzVHUhVi2G9ZN",
                "object": "line_item",
                "amount": 0,
                "currency": "usd",
                "description": null,
                "discountable": true,
                "livemode": false,
                "metadata": {
                },
                "period": {
                  "start": 1455464290,
                  "end": 1457969890
                },
                "plan": {
                  "id": "hjhlew",
                  "object": "plan",
                  "amount": 0,
                  "created": 1405352288,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {
                  },
                  "name": "Starter",
                  "statement_descriptor": null,
                  "trial_period_days": null
                },
                "proration": false,
                "quantity": 1,
                "subscription": null,
                "type": "subscription"
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
          },
          "livemode": false,
          "metadata": {
          },
          "next_payment_attempt": null,
          "paid": true,
          "period_end": 1455464290,
          "period_start": 1452785890,
          "receipt_number": null,
          "starting_balance": 0,
          "statement_descriptor": null,
          "subscription": "sub_4OzVHUhVi2G9ZN",
          "subtotal": 0,
          "tax": null,
          "tax_percent": null,
          "total": 0,
          "webhooks_delivered_at": 1455464569
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": null,
      "type": "invoice.payment_succeeded"
    }
    [1] => <Stripe\Event[...] ...>
    [2] => <Stripe\Event[...] ...>
  ]
}
#<com.stripe.model.EventCollection id=#> JSON: {
  "data": [
    com.stripe.model.Event JSON: {
      "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
      "object": "event",
      "api_version": "2016-02-03",
      "created": 1455468461,
      "data": {
        "object": {
          "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
          "object": "invoice",
          "amount_due": 0,
          "application_fee": null,
          "attempt_count": 0,
          "attempted": true,
          "charge": null,
          "closed": true,
          "currency": "usd",
          "customer": "cus_4OzVDNEzwljzDO",
          "date": 1455464556,
          "description": null,
          "discount": null,
          "ending_balance": 0,
          "forgiven": false,
          "lines": {
            "object": "list",
            "data": [
              {
                "id": "sub_4OzVHUhVi2G9ZN",
                "object": "line_item",
                "amount": 0,
                "currency": "usd",
                "description": null,
                "discountable": true,
                "livemode": false,
                "metadata": {
                },
                "period": {
                  "start": 1455464290,
                  "end": 1457969890
                },
                "plan": {
                  "id": "hjhlew",
                  "object": "plan",
                  "amount": 0,
                  "created": 1405352288,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {
                  },
                  "name": "Starter",
                  "statement_descriptor": null,
                  "trial_period_days": null
                },
                "proration": false,
                "quantity": 1,
                "subscription": null,
                "type": "subscription"
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
          },
          "livemode": false,
          "metadata": {
          },
          "next_payment_attempt": null,
          "paid": true,
          "period_end": 1455464290,
          "period_start": 1452785890,
          "receipt_number": null,
          "starting_balance": 0,
          "statement_descriptor": null,
          "subscription": "sub_4OzVHUhVi2G9ZN",
          "subtotal": 0,
          "tax": null,
          "tax_percent": null,
          "total": 0,
          "webhooks_delivered_at": 1455464569
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": null,
      "type": "invoice.payment_succeeded"
    },
    #<com.stripe.model.Event[...] ...>,
    #<com.stripe.model.Event[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
      "object": "event",
      "api_version": "2016-02-03",
      "created": 1455468461,
      "data": {
        "object": {
          "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
          "object": "invoice",
          "amount_due": 0,
          "application_fee": null,
          "attempt_count": 0,
          "attempted": true,
          "charge": null,
          "closed": true,
          "currency": "usd",
          "customer": "cus_4OzVDNEzwljzDO",
          "date": 1455464556,
          "description": null,
          "discount": null,
          "ending_balance": 0,
          "forgiven": false,
          "lines": {
            "object": "list",
            "data": [
              {
                "id": "sub_4OzVHUhVi2G9ZN",
                "object": "line_item",
                "amount": 0,
                "currency": "usd",
                "description": null,
                "discountable": true,
                "livemode": false,
                "metadata": {
                },
                "period": {
                  "start": 1455464290,
                  "end": 1457969890
                },
                "plan": {
                  "id": "hjhlew",
                  "object": "plan",
                  "amount": 0,
                  "created": 1405352288,
                  "currency": "usd",
                  "interval": "month",
                  "interval_count": 1,
                  "livemode": false,
                  "metadata": {
                  },
                  "name": "Starter",
                  "statement_descriptor": null,
                  "trial_period_days": null
                },
                "proration": false,
                "quantity": 1,
                "subscription": null,
                "type": "subscription"
              }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
          },
          "livemode": false,
          "metadata": {
          },
          "next_payment_attempt": null,
          "paid": true,
          "period_end": 1455464290,
          "period_start": 1452785890,
          "receipt_number": null,
          "starting_balance": 0,
          "statement_descriptor": null,
          "subscription": "sub_4OzVHUhVi2G9ZN",
          "subtotal": 0,
          "tax": null,
          "tax_percent": null,
          "total": 0,
          "webhooks_delivered_at": 1455464569
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": null,
      "type": "invoice.payment_succeeded"
    },
    {...},
    {...}
  ]
}
&stripe.Event JSON: {
  "id": "evt_17eT292eZvKYlo2C2iRwF7Wr",
  "object": "event",
  "api_version": "2016-02-03",
  "created": 1455468461,
  "data": {
    "object": {
      "id": "in_17eS1A2eZvKYlo2C7DEJr6Q2",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": true,
      "charge": null,
      "closed": true,
      "currency": "usd",
      "customer": "cus_4OzVDNEzwljzDO",
      "date": 1455464556,
      "description": null,
      "discount": null,
      "ending_balance": 0,
      "forgiven": false,
      "lines": {
        "object": "list",
        "data": [
          {
            "id": "sub_4OzVHUhVi2G9ZN",
            "object": "line_item",
            "amount": 0,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": false,
            "metadata": {
            },
            "period": {
              "start": 1455464290,
              "end": 1457969890
            },
            "plan": {
              "id": "hjhlew",
              "object": "plan",
              "amount": 0,
              "created": 1405352288,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Starter",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/invoices/in_17eS1A2eZvKYlo2C7DEJr6Q2/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": null,
      "paid": true,
      "period_end": 1455464290,
      "period_start": 1452785890,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_4OzVHUhVi2G9ZN",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1455464569
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": null,
  "type": "invoice.payment_succeeded"
}

Types of events

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn't rely on only these types existing in your code.

You'll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against. NOTE: Events that occur on "sub" resources like customer.subscription do not trigger the parent's update event.

Event
  • account.updated describes an account

    Occurs whenever an account status or property has changed.

  • account.application.deauthorized describes an application

    Occurs whenever a user deauthorizes an application. Sent to the related application only.

    child parameters
    • id string

    • object string, value is "application"

    • name string

      The name of the Connect application.

  • account.external_account.created describes an external account (e.g., card or bank account)

    Occurs whenever an external account is created.

  • account.external_account.deleted describes an external account (e.g., card or bank account)

    Occurs whenever an external account is deleted.

  • account.external_account.updated describes an external account (e.g., card or bank account)

    Occurs whenever an external account is updated.

  • application_fee.created describes an application fee

    Occurs whenever an application fee is created on a charge.

  • application_fee.refunded describes an application fee

    Occurs whenever an application fee is refunded, whether from refunding a charge or from refunding the application fee directly, including partial refunds.

  • application_fee.refund.updated describes a fee refund

    Occurs whenever an application fee refund is updated.

  • balance.available describes a balance

    Occurs whenever your Stripe balance has been updated (e.g. when a charge collected is available to be paid out). By default, Stripe will automatically transfer any funds in your balance to your bank account on a daily basis.

  • bitcoin.receiver.created describes a bitcoin receiver

    Occurs whenever a receiver has been created.

  • bitcoin.receiver.filled describes a bitcoin receiver

    Occurs whenever a receiver is filled (that is, when it has received enough bitcoin to process a payment of the same amount).

  • bitcoin.receiver.updated describes a bitcoin receiver

    Occurs whenever a receiver is updated.

  • bitcoin.receiver.transaction.created describes a bitcoin receiver

    Occurs whenever bitcoin is pushed to a receiver.

  • charge.captured describes a charge

    Occurs whenever a previously uncaptured charge is captured.

  • charge.failed describes a charge

    Occurs whenever a failed charge attempt occurs.

  • charge.refunded describes a charge

    Occurs whenever a charge is refunded, including partial refunds.

  • charge.succeeded describes a charge

    Occurs whenever a new charge is created and is successful.

  • charge.updated describes a charge

    Occurs whenever a charge description or metadata is updated.

  • charge.dispute.closed describes a dispute

    Occurs when the dispute is closed and the dispute status changes to charge_refunded, lost, warning_closed, or won.

  • charge.dispute.created describes a dispute

    Occurs whenever a customer disputes a charge with their bank (chargeback).

  • charge.dispute.funds_reinstated describes a dispute

    Occurs when funds are reinstated to your account after a dispute is won.

  • charge.dispute.funds_withdrawn describes a dispute

    Occurs when funds are removed from your account due to a dispute.

  • charge.dispute.updated describes a dispute

    Occurs when the dispute is updated (usually with evidence).

  • coupon.created describes a coupon

    Occurs whenever a coupon is created.

  • coupon.deleted describes a coupon

    Occurs whenever a coupon is deleted.

  • coupon.updated describes a coupon

    Occurs whenever a coupon is updated.

  • customer.created describes a customer

    Occurs whenever a new customer is created.

  • customer.deleted describes a customer

    Occurs whenever a customer is deleted.

  • customer.updated describes a customer

    Occurs whenever any property of a customer changes.

  • customer.discount.created describes a discount

    Occurs whenever a coupon is attached to a customer.

  • customer.discount.deleted describes a discount

    Occurs whenever a customer's discount is removed.

  • customer.discount.updated describes a discount

    Occurs whenever a customer is switched from one coupon to another.

  • customer.source.created describes a source (e.g., card or Bitcoin receiver)

    Occurs whenever a new source is created for the customer.

  • customer.source.deleted describes a source (e.g., card or Bitcoin receiver)

    Occurs whenever a source is removed from a customer.

  • customer.source.updated describes a source (e.g., card or Bitcoin receiver)

    Occurs whenever a source's details are changed.

  • customer.subscription.created describes a subscription

    Occurs whenever a customer with no subscription is signed up for a plan.

  • customer.subscription.deleted describes a subscription

    Occurs whenever a customer ends their subscription.

  • customer.subscription.trial_will_end describes a subscription

    Occurs three days before the trial period of a subscription is scheduled to end.

  • customer.subscription.updated describes a subscription

    Occurs whenever a subscription changes. Examples would include switching from one plan to another, or switching status from trial to active.

  • invoice.created describes an invoice

    Occurs whenever a new invoice is created. If you are using webhooks, Stripe will wait one hour after they have all succeeded to attempt to pay the invoice; the only exception here is on the first invoice, which gets created and paid immediately when you subscribe a customer to a plan. If your webhooks do not all respond successfully, Stripe will continue retrying the webhooks every hour and will not attempt to pay the invoice. After 3 days, Stripe will attempt to pay the invoice regardless of whether or not your webhooks have succeeded. See how to respond to a webhook.

  • invoice.payment_failed describes an invoice

    Occurs whenever an invoice attempts to be paid, and the payment fails. This can occur either due to a declined payment, or because the customer has no active card. A particular case of note is that if a customer with no active card reaches the end of its free trial, an invoice.payment_failed notification will occur.

  • invoice.payment_succeeded describes an invoice

    Occurs whenever an invoice attempts to be paid, and the payment succeeds.

  • invoice.updated describes an invoice

    Occurs whenever an invoice changes (for example, the amount could change).

  • invoiceitem.created describes an invoiceitem

    Occurs whenever an invoice item is created.

  • invoiceitem.deleted describes an invoiceitem

    Occurs whenever an invoice item is deleted.

  • invoiceitem.updated describes an invoiceitem

    Occurs whenever an invoice item is updated.

  • order.created describes an order

    Occurs whenever an order is created.

  • order.payment_failed describes an order

    Occurs whenever payment is attempted on an order, and the payment fails.

  • order.payment_succeeded describes an order

    Occurs whenever payment is attempted on an order, and the payment succeeds.

  • order.updated describes an order

    Occurs whenever an order is updated.

  • plan.created describes a plan

    Occurs whenever a plan is created.

  • plan.deleted describes a plan

    Occurs whenever a plan is deleted.

  • plan.updated describes a plan

    Occurs whenever a plan is updated.

  • product.created describes a product

    Occurs whenever a product is created.

  • product.deleted describes a product

    Occurs whenever a product is deleted.

  • product.updated describes a product

    Occurs whenever a product is updated.

  • recipient.created describes a recipient

    Occurs whenever a recipient is created.

  • recipient.deleted describes a recipient

    Occurs whenever a recipient is deleted.

  • recipient.updated describes a recipient

    Occurs whenever a recipient is updated.

  • sku.created describes a sku

    Occurs whenever a SKU is created.

  • sku.deleted describes a sku

    Occurs whenever a SKU is deleted.

  • sku.updated describes a sku

    Occurs whenever a SKU is updated.

  • transfer.created describes a transfer

    Occurs whenever a new transfer is created.

  • transfer.failed describes a transfer

    Occurs whenever Stripe attempts to send a transfer and that transfer fails.

  • transfer.paid describes a transfer

    Occurs whenever a sent transfer is expected to be available in the destination bank account. If the transfer failed, a transfer.failed webhook will additionally be sent at a later time. Note to Connect users: this event is only created for transfers from your connected Stripe accounts to their bank accounts, not for transfers to the connected accounts themselves.

  • transfer.reversed describes a transfer

    Occurs whenever a transfer is reversed, including partial reversals.

  • transfer.updated describes a transfer

    Occurs whenever the description or metadata of a transfer is updated.

  • ping has no description

    May be sent by Stripe at any time to see if a provided webhook URL is working.

File Uploads

There are various times when you'll want to upload files to Stripe (for example, when uploading dispute evidence). This can be done by creating a file upload object. When you upload a file, the API responds with a file token and other information about the file. The token can then be used to retrieve a file object.

Note that to upload documents, the uploads API endpoint must be used: https://uploads.stripe.com.

For further documentation and examples, see the File Upload Guide.

The file_upload object

Attributes
  • id string

  • object string , value is "file_upload"

  • created timestamp

  • purpose string

    The purpose of the uploaded file. Possible values are business_logo, dispute_evidence, identity_document, incorporation_article.

  • size integer

    The size in bytes of the file upload object.

  • type string

    The type of the file returned. Returns one of the following: pdf, jpg, png.

  • url string

    A read-only URL where the uploaded file can be accessed. Will be nil unless the uploaded file has one of the following purposes: business_logo, dispute_evidence. Also nil if retrieved with the publishable API key.

{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
#<Stripe::FileUpload id=fil_15BZxW2eZvKYlo2CvQbrn9dc 0x00000a> JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
<FileUpload file_upload id=fil_15BZxW2eZvKYlo2CvQbrn9dc at 0x00000a> JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
Stripe\FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
com.stripe.model.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
&stripe.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}

Create a file upload

To upload a file to Stripe, you’ll need to send a request of type multipart/form-data. The request should contain the file you would like to upload, as well as the parameters for creating a file.

All of Stripe’s officially supported API libraries should have support for sending multipart/form-data.

Arguments
  • file required

    A file to upload. The file should follow the specifications of RFC 2388 (which defines file transfers for the multipart/form-data protocol).

  • purpose required

    The purpose of the uploaded file. Possible values are business_logo, dispute_evidence, identity_document, incorporation_article.

Returns

Returns the file object.

POST https://uploads.stripe.com/v1/files
Stripe::FileUpload.create
stripe.FileUpload.create()
\Stripe\FileUpload::create();
FileUpload.create();
stripe.fileUploads.create();
fileupload.New()
curl https://uploads.stripe.com/v1/files \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -F purpose=dispute_evidence \
   -F file="@/path/to/a/file.jpg"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::FileUpload.create(
  :purpose => 'dispute_evidence',
  :file => File.new('/path/to/a/file.jpg')
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fp = open('/path/to/a/file.jpg', 'r')
stripe.FileUpload.create(
  purpose='dispute_evidence',
  file=fp
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$fp = fopen('/path/to/a/file.jpg', 'r');
\Stripe\FileUpload::create(array(
  'purpose' => 'dispute_evidence',
  'file' => $fp
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> fileUploadParams = new HashMap<String, Object>();
fileUploadParams.put("purpose", dispute_evidence);
fileUploadParams.put("file", new File('/path/to/a/file.jpg'));

Fileupload.create(fileUploadParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

var fp = fs.readFileSync('/path/to/a/file.jpg');
stripe.fileUploads.create({
  purpose: 'dispute_evidence',
  file: {
    data: fp,
    name: 'file_name.jpg',
    type: 'application/octet-stream'
  }
}, function(err, fileUpload) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fp, _ := os.Open("/path/to/a/file.jpg")
ch, err := fileupload.New(&FileUploadParams{
  Purpose: "dispute_evidence",
  File: fp,
})
{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
#<Stripe::FileUpload id=fil_15BZxW2eZvKYlo2CvQbrn9dc 0x00000a> JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
<FileUpload file_upload id=fil_15BZxW2eZvKYlo2CvQbrn9dc at 0x00000a> JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
Stripe\FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
com.stripe.model.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
&stripe.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}

Retrieve a file upload

Retrieves the details of an existing file object. Supply the unique file upload ID from a file creation request, and Stripe will return the corresponding transfer information.

Arguments
  • id required

    The identifier of the file upload to be retrieved.

Returns

Returns a file upload object if a valid identifier was provided, and returnsraisesraisesthrowsthrowsthrowsreturns an error otherwise.

curl https://uploads.stripe.com/v1/files/fil_15BZxW2eZvKYlo2CvQbrn9dc \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::FileUpload.retrieve("fil_15BZxW2eZvKYlo2CvQbrn9dc")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.FileUpload.retrieve("fil_15BZxW2eZvKYlo2CvQbrn9dc")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\FileUpload::retrieve("fil_15BZxW2eZvKYlo2CvQbrn9dc");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

FileUpload.retrieve("fil_15BZxW2eZvKYlo2CvQbrn9dc");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.fileUploads.retrieve(
  "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  function(err, fileUpload) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

f, err := fileupload.Get("fil_15BZxW2eZvKYlo2CvQbrn9dc", nil)
{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
#<Stripe::FileUpload id=fil_15BZxW2eZvKYlo2CvQbrn9dc 0x00000a> JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
<FileUpload file_upload id=fil_15BZxW2eZvKYlo2CvQbrn9dc at 0x00000a> JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
Stripe\FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
com.stripe.model.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
{
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}
&stripe.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}

List all file uploads

Returns a list of the files that you have uploaded to Stripe. The file uploads are returned sorted by creation date, with the most recently created file uploads appearing first.

Arguments
  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments
    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • purpose optional

    The file purpose to filter queries by. If none is provided, files will not be filtered by purpose.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit file uploads, starting after file upload starting_after. Each entry in the array is a separate file upload object. If no more file uploads are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrowreturn an an error.

You can optionally request that the response include the total count of all file uploads that match your filters. To do so, specify include[]=total_count in your request.

GET https://uploads.stripe.com/v1/files
Stripe::FileUpload.all
stripe.FileUpload.all()
\Stripe\FileUpload::all();
FileUpload.all(Map<String, Object> options);
stripe.fileUploads.list();
fileupload.List()
curl https://uploads.stripe.com/v1/files?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::FileUpload.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.FileUpload.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\FileUpload::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> fileUploadParams = new HashMap<String, Object>();
fileUploadParams.put("limit", 3);

Fileupload.all(fileUploadParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.fileUploads.list(
  { limit: 3 },
  function(err, fileUploads) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.FileuploadListParams{}
params.Filters.AddFilter("limit", "", "3")
i := fileupload.List(params)
for i.Next() {
  f := i.Fileupload()
}
{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
      "object": "file_upload",
      "created": 1419030898,
      "purpose": "dispute_evidence",
      "size": 739,
      "type": "pdf"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    #<Stripe::FileUpload id=fil_15BZxW2eZvKYlo2CvQbrn9dc 0x00000a> JSON: {
      "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
      "object": "file_upload",
      "created": 1419030898,
      "purpose": "dispute_evidence",
      "size": 739,
      "type": "pdf"
    },
    #<Stripe::FileUpload[...] ...>,
    #<Stripe::FileUpload[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/files",
  has_more: false,
  data: [
    <FileUpload file_upload id=fil_15BZxW2eZvKYlo2CvQbrn9dc at 0x00000a> JSON: {
      "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
      "object": "file_upload",
      "created": 1419030898,
      "purpose": "dispute_evidence",
      "size": 739,
      "type": "pdf"
    },
    <stripe.FileUpload[...] ...>,
    <stripe.FileUpload[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/files",
  "has_more" => false,
  "data" => [
    [0] => Stripe\FileUpload JSON: {
      "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
      "object": "file_upload",
      "created": 1419030898,
      "purpose": "dispute_evidence",
      "size": 739,
      "type": "pdf"
    }
    [1] => <Stripe\FileUpload[...] ...>
    [2] => <Stripe\FileUpload[...] ...>
  ]
}
#<com.stripe.model.FileUploadCollection id=#> JSON: {
  "data": [
    com.stripe.model.FileUpload JSON: {
      "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
      "object": "file_upload",
      "created": 1419030898,
      "purpose": "dispute_evidence",
      "size": 739,
      "type": "pdf"
    },
    #<com.stripe.model.FileUpload[...] ...>,
    #<com.stripe.model.FileUpload[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
      "object": "file_upload",
      "created": 1419030898,
      "purpose": "dispute_evidence",
      "size": 739,
      "type": "pdf"
    },
    {...},
    {...}
  ]
}
&stripe.FileUpload JSON: {
  "id": "fil_15BZxW2eZvKYlo2CvQbrn9dc",
  "object": "file_upload",
  "created": 1419030898,
  "purpose": "dispute_evidence",
  "size": 739,
  "type": "pdf"
}

Refunds

Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.

The refund object

Attributes
  • id string

  • object string , value is "refund"

  • amount integer

    Amount, in cents.

  • balance_transaction string

    Balance transaction that describes the impact on your account balance.

  • charge string

    ID of the charge that was refunded.

  • created timestamp

  • currency currency

    Three-letter ISO code representing the currency.

  • description string

  • metadata #

    A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

  • reason string

    Reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer.

  • receipt_number string

    This is the transaction number that appears on email receipts sent for this refund.

{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17eKtc2eZvKYlo2COcwbIlZB 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17eKtc2eZvKYlo2COcwbIlZB at 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Create a refund

When you create a new refund, you must specify a charge to create it on.

Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.

You can optionally refund only part of a charge. You can do so as many times as you wish until the entire charge has been refunded.

Once entirely refunded, a charge can't be refunded again. This method will returnraiseraisethrowthrowthrowreturn an an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.

Arguments
  • charge required

    The identifier of the charge to refund.

  • amount optional, default is entire charge

    A positive integer in cents representing how much of this charge to refund. Can only refund up to the unrefunded amount remaining of the charge.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

  • reason optional, default is null

    String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. Specifying fraudulent as the reason when you believe the charge to be fraudulent will help us improve our fraud detection algorithms.

  • refund_application_fee connect only optional, default is false

    Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Else, the application fee will be refunded with an amount proportional to the amount of the charge refunded.

    An application fee can only be refunded by the application that created the charge.

  • reverse_transfer connect only optional, default is false

    Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed for the same amount being refunded (either the entire or partial amount).

    A transfer can only be reversed by the application that created the charge.

Returns

Returns the refund object if the refund succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error if the charge has already been refunded or an invalid charge identifier was provided.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/refunds
Stripe::Refund.create
stripe.Refund.create()
\Stripe\Charge::create();
Map params = new HashMap();
Refund.create(params);
stripe.refunds.create(
  {},
  function(err, refund) {
  }
);
refund.New(&stripe.RefundParams{Charge: {CHARGE_ID}})
curl https://api.stripe.com/v1/refunds \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d charge=ch_17eT142eZvKYlo2CnA1fjKo8
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = Stripe::Refund.create(
  charge: "ch_17eT142eZvKYlo2CnA1fjKo8"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = stripe.Refund.create(
  charge="ch_17eT142eZvKYlo2CnA1fjKo8"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$re = \Stripe\Refund::create(array(
  "charge" => "ch_17eT142eZvKYlo2CnA1fjKo8"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("charge", "ch_17eT142eZvKYlo2CnA1fjKo8");

Refund.create(refundParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refunds.create({
  charge: "ch_17eT142eZvKYlo2CnA1fjKo8"
}, function(err, refund) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.New(&stripe.RefundParams{Charge: "ch_17eT142eZvKYlo2CnA1fjKo8"})
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17eKtc2eZvKYlo2COcwbIlZB 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17eKtc2eZvKYlo2COcwbIlZB at 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Retrieve a refund

Retrieves the details of an existing refund.

Arguments
  • refund required

    ID of refund to retrieve.

Returns

Returns a refund if a valid ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

curl https://api.stripe.com/v1/refunds/re_17eKtc2eZvKYlo2COcwbIlZB \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Refund.retrieve("re_17eKtc2eZvKYlo2COcwbIlZB")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Refund.retrieve("re_17eKtc2eZvKYlo2COcwbIlZB")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Refund::retrieve("re_17eKtc2eZvKYlo2COcwbIlZB");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Refund.retrieve("re_17eKtc2eZvKYlo2COcwbIlZB");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refunds.retrieve(
  "re_17eKtc2eZvKYlo2COcwbIlZB",
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.Get("re_17eKtc2eZvKYlo2COcwbIlZB", nil)
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17eKtc2eZvKYlo2COcwbIlZB 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17eKtc2eZvKYlo2COcwbIlZB at 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Update a refund

Updates the specified refund by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request only accepts metadata as an argument.

Arguments
  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

Returns the refund object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an an error if update parameters are invalid.

POST https://api.stripe.com/v1/refunds/{REFUND_ID}
refund = Stripe::Refund.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save
refund = stripe.Refund.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save()
$refund = \Stripe\Refund::retrieve({REFUND_ID});
$refund->metadata[{KEY}] = {VALUE};
$refund->save();
Refund refund = Refund.retrieve({REFUND_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);
stripe.refunds.update({REFUND_ID}, {
  metadata: {{KEY}: {VALUE}}
})
refund.Update({REFUND_ID}, &stripe.RefundParams{
  Meta: map[string]string{{KEY}: {VALUE}}
})
curl https://api.stripe.com/v1/refunds/re_17eKtc2eZvKYlo2COcwbIlZB \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = Stripe::Refund.retrieve("re_17eKtc2eZvKYlo2COcwbIlZB")
re.metadata["key"] = "value"
re.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = stripe.Refund.retrieve("re_17eKtc2eZvKYlo2COcwbIlZB")
re.metadata["key"] = "value"
re.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$re = \Stripe\Refund::retrieve("re_17eKtc2eZvKYlo2COcwbIlZB");
$re->metadata["key"] = "value";
$re->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Refund re = Refund.retrieve("re_17eKtc2eZvKYlo2COcwbIlZB");
Map<String, String> metadata = new HashMap<String, String>();
metadata.put("key", "value");
Map<String, Object> params = new HashMap<String, Object>();
params.put("metadata", metadata);
re.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refund.update(
  "re_17eKtc2eZvKYlo2COcwbIlZB",
  { metadata: { key: "value"} },
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ref, err := refund.Update(
  "re_17eKtc2eZvKYlo2COcwbIlZB",
  &stripe.RefundParams{
    Meta: map[string]string{ "key": "value" },
  })
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17eKtc2eZvKYlo2COcwbIlZB 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17eKtc2eZvKYlo2COcwbIlZB at 0x00000a> JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}

List all refunds

Returns a list of all refunds you’ve previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. For convenience, the 10 most recent refunds are always available by default on the charge object.

Arguments
  • charge optional

    Only return refunds for the charge specified by this charge ID.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit refunds, starting after refund starting_after. Each entry in the array is a separate refund object. If no more refunds are available, the resulting array will be empty. If you provide a non-existent charge ID, this call returnsraisesraisesthrowsthrowsthrowsreturns an error.

You can optionally request that the response includes the total count of all refunds that match your filters by specifying include[]=total_count in your request.

GET https://api.stripe.com/v1/refunds
Stripe::Refund.all
stripe.Refund.all()
\Stripe\Refund::all();
Refund.all(Map<String, Object> options);
stripe.refunds.list();
refund.List()
curl https://api.stripe.com/v1/refunds?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Refund.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Refund.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Refund::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("limit", 3);

Refund.all(refundParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refunds.list(
  { limit: 3 },
  function(err, refunds) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.RefundListParams{}
params.Filters.AddFilter("limit", "", "3")
i := refund.List(params)
for i.Next() {
  r := i.Refund()
}
{
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
      "object": "refund",
      "amount": 65000,
      "balance_transaction": null,
      "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
      "created": 1455437180,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    #<Stripe::Refund id=re_17eKtc2eZvKYlo2COcwbIlZB 0x00000a> JSON: {
      "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
      "object": "refund",
      "amount": 65000,
      "balance_transaction": null,
      "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
      "created": 1455437180,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    #<Stripe::Refund[...] ...>,
    #<Stripe::Refund[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/refunds",
  has_more: false,
  data: [
    <Refund refund id=re_17eKtc2eZvKYlo2COcwbIlZB at 0x00000a> JSON: {
      "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
      "object": "refund",
      "amount": 65000,
      "balance_transaction": null,
      "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
      "created": 1455437180,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    <stripe.Refund[...] ...>,
    <stripe.Refund[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/refunds",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Refund JSON: {
      "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
      "object": "refund",
      "amount": 65000,
      "balance_transaction": null,
      "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
      "created": 1455437180,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    }
    [1] => <Stripe\Refund[...] ...>
    [2] => <Stripe\Refund[...] ...>
  ]
}
#<com.stripe.model.RefundCollection id=#> JSON: {
  "data": [
    com.stripe.model.Refund JSON: {
      "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
      "object": "refund",
      "amount": 65000,
      "balance_transaction": null,
      "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
      "created": 1455437180,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    #<com.stripe.model.Refund[...] ...>,
    #<com.stripe.model.Refund[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
      "object": "refund",
      "amount": 65000,
      "balance_transaction": null,
      "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
      "created": 1455437180,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    {...},
    {...}
  ]
}
&stripe.Refund JSON: {
  "id": "re_17eKtc2eZvKYlo2COcwbIlZB",
  "object": "refund",
  "amount": 65000,
  "balance_transaction": null,
  "charge": "ch_17bnYj2eZvKYlo2C7p5wpMlz",
  "created": 1455437180,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Tokens

Often you want to be able to charge credit cards or send payments to bank accounts without having to hold sensitive card information on your own servers. Stripe.js makes this easy in the browser, but you can use the same technique in other environments with our token API.

Tokens can be created with your publishable API key, which can safely be embedded in downloadable applications like iPhone and Android apps. You can then use a token anywhere in our API that a card or bank account is accepted. Note that tokens are not meant to be stored or used more than once—to store these details for use later, you should create Customer or Recipient objects.

The token object

Attributes
  • id string

  • object string , value is "token"

  • bank_account hash

    Hash describing the bank account

    child attributes
    • id string

    • object string , value is "bank_account"

    • account_holder_type string

      The type of entity that holds the account. This can be either individual or company.

    • bank_name string

      Name of the bank associated with the routing number, e.g. WELLS FARGO.

    • country string

      Two-letter ISO code representing the country the bank account is located in.

    • currency currency

      Three-letter ISO currency code representing the currency paid out to the bank account.

    • fingerprint string

      Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.

    • last4 string

    • name string

      The name of the person or business that owns the bank account.

    • routing_number string

      The routing transit number for the bank account.

    • status string

      Possible values are new, validated, verified, verification_failed, or errored. A bank account that hasn’t had any activity or validation performed is new. If Stripe can determine that the bank account exists, its status will be validated. Note that there often isn’t enough information to know (e.g. for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be verified. If the verification failed for any reason, such as microdeposit failure, the status will be verification_failed. If a transfer sent to this bank account fails, we’ll set the status to errored and will not continue to send transfers until the bank details are updated.

  • card hash

    Hash describing the card used to make the charge

    child attributes
    • id string

      ID of card (used in conjunction with a customer or recipient ID)

    • object string , value is "card"

    • address_city string

    • address_country string

      Billing address country, if provided when creating card

    • address_line1 string

    • address_line1_check string

      If address_line1 was provided, results of the check: pass, fail, unavailable, or unchecked.

    • address_line2 string

    • address_state string

    • address_zip string

    • address_zip_check string

      If address_zip was provided, results of the check: pass, fail, unavailable, or unchecked.

    • brand string

      Card brand. Can be Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown.

    • country string

      Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you’ve collected.

    • currency currency

    • cvc_check string

      If a CVC was provided, results of the check: pass, fail, unavailable, or unchecked

    • dynamic_last4 string

      (For tokenized numbers only.) The last four digits of the device account number.

    • exp_month integer

    • exp_year integer

    • fingerprint string

      Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example.

    • funding string

      Card funding type. Can be credit, debit, prepaid, or unknown

    • last4 string

    • metadata #

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name string

      Cardholder name

    • tokenization_method string

      If the card number is tokenized, this is the method that was used. Can be apple_pay or android_pay.

  • client_ip string

    IP address of the client that generated the token

  • created timestamp

  • livemode boolean

  • type string

    Type of the token: card or bank_account

  • used boolean

    Whether or not this token has already been used (tokens can be used only once)

{
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
#<Stripe::Token id=tok_17drHk2eZvKYlo2CEEHm8kkG 0x00000a> JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
<Token token id=tok_17drHk2eZvKYlo2CEEHm8kkG at 0x00000a> JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
Stripe\Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
{
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
&stripe.Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}

Create a card token

Creates a single use token that wraps the details of a credit card. This token can be used in place of a credit card dictionaryhashdictionaryassociative arrayMapobjectmap with any API method. These tokens can only be used once: by creating a new charge object, or attaching them to a customer.

Arguments
  • card optional

    The card this token will represent. If you also pass in a customer, the card must be the ID of a card belonging to the customer. Otherwise, if you do not pass a customer, a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details, with the options described below.

    child parameters
    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • currencycurrencycurrencycurrencycurrencycurrencycurrency managed accounts only

      Required to be able to add the card to an account (in all other cases, this parameter is not used). When added to an account, the card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • namenamenamenamenamenamename optional

      Cardholder's full name.

  • customer optional

    For use with Stripe Connect only; this can only be used with an OAuth access token or Stripe-Account header.. For more details, see the shared customers documentation. A customer (owned by the application's account) to create a token for.

Returns

The created card token object is returned if successful. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error.

POST https://api.stripe.com/v1/tokens
Stripe::Token.create()
stripe.Token.create()
\Stripe\Token::create();
Token.create();
stripe.tokens.create();
token.New()
curl https://api.stripe.com/v1/tokens \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d card[number]=4242424242424242 \
   -d card[exp_month]=12 \
   -d card[exp_year]=2017 \
   -d card[cvc]=123
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Token.create(
  :card => {
    :number => "4242424242424242",
    :exp_month => 2,
    :exp_year => 2017,
    :cvc => "314"
  },
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Token.create(
  card={
    "number": '4242424242424242',
    "exp_month": 12,
    "exp_year": 2017,
    "cvc": '123'
  },
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Token::create(array(
  "card" => array(
    "number" => "4242424242424242",
    "exp_month" => 2,
    "exp_year" => 2017,
    "cvc" => "314"
  )
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> tokenParams = new HashMap<String, Object>();
Map<String, Object> cardParams = new HashMap<String, Object>();
cardParams.put("number", "4242424242424242");
cardParams.put("exp_month", 2);
cardParams.put("exp_year", 2017);
cardParams.put("cvc", "314");
tokenParams.put("card", cardParams);

Token.create(tokenParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.tokens.create({
  card: {
    "number": '4242424242424242',
    "exp_month": 12,
    "exp_year": 2017,
    "cvc": '123'
  }
}, function(err, token) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := token.New(&stripe.TokenParams{
  Card: &stripe.CardParams{
        Number: "4242424242424242",
        Month:  "12",
        Year:   "2017",
        CVC:    "123",
    },
})
{
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
#<Stripe::Token id=tok_17drHk2eZvKYlo2CEEHm8kkG 0x00000a> JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
<Token token id=tok_17drHk2eZvKYlo2CEEHm8kkG at 0x00000a> JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
Stripe\Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
{
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
&stripe.Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}

Create a bank account token

Creates a single use token that wraps the details of a bank account. This token can be used in place of a bank account dictionaryhashdictionaryassociative arrayMapobjectmap with any API method. These tokens can only be used once: by attaching them to a recipient or managed account.

Arguments

  • bank_account optional, default is nullnilNonenullnullnullnull

    The bank account this token will represent.

    child arguments
    • account_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_number required

      The account number for the bank account in string form. Must be a checking account.

    • countrycountrycountrycountrycountrycountrycountry required

      The country the bank account is in.

    • currencycurrencycurrencycurrencycurrencycurrencycurrency required

      The currency the bank account is in. This must be a country/currency pairing that Stripe supports.

    • routing_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_number optional

      The routing number, sort code, or other country-appropriate institution number for the bank account. For US bank accounts, this is required and should be the ACH routing number, not the wire routing number. If you are providing an IBAN for account_number, this field is not required.

    • namenamenamenamenamenamename optional

      The name of the person or business that owns the bank account. This field is required when attaching the bank account to a customer object.

    • account_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_type optional

      The type of entity that holds the account. This can be either "individual" or "company". This field is required when attaching the bank account to a customer object.

Returns

The created bank account token object is returned if successful. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error.

POST https://api.stripe.com/v1/tokens
Stripe::Token.create()
stripe.Token.create()
\Stripe\Token::create();
Token.create();
stripe.tokens.create();
token.New()
curl https://api.stripe.com/v1/tokens \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d bank_account[country]=US \
   -d bank_account[currency]=usd \
   -d bank_account[name]="Jane Austen" \
   -d bank_account[account_holder_type]=individual \
   -d bank_account[routing_number]=110000000 \
   -d bank_account[account_number]=000123456789
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Token.create(
    :bank_account => {
    :country => "US",
    :currency => "usd",
    :name => "Jane Austen",
    :account_holder_type => "individual",
    :routing_number => "1100000000",
    :account_number => "000123456789",
  },
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Token.create(
  bank_account={
    "country": 'US',
    "currency": 'usd',
    "name": 'Jane Austen',
    "account_holder_type": 'individual',
    "routing_number": '110000000',
    "account_number": '000123456789'
  },
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Token::create(array(
    "bank_account" => array(
    "country" => "US",
    "currency" => "usd",
    "name" => "Jane Austen",
    "account_holder_type" => "individual",
    "routing_number" => "110000000",
    "account_number" => "000123456789"
  )
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> tokenParams = new HashMap<String, Object>();
Map<String, Object> bank_accountParams = new HashMap<String, Object>();
bank_accountParams.put("country", "US");
bank_accountParams.put("currency", "usd");
bank_accountParams.put("name", "Jane Austen");
bank_accountParams.put("account_holder_type", "individual");
bank_accountParams.put("routing_number", "110000000");
bank_accountParams.put("account_number", "000123456789");
tokenParams.put("bank_account", bank_accountParams);

Token.create(tokenParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.tokens.create({
  bank_account: {
    country: 'US',
    currency: 'usd',
    name: 'Jane Austen',
    account_holder_type: 'individual',
    routing_number: '110000000',
    account_number: '000123456789'
  }
}, function(err, token) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := token.New(&stripe.TokenParams{
  Bank: &stripe.BankAccountParams{
      Country: "US",
      Currency: "usd",
      Name: "Jane Austen",
      AccountHolderType: "individual",
      Routing: "110000000",
      Account: "000123456789",
    },
})
{
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
#<Stripe::Token id=btok_7uHgmjWUBfUaQi 0x00000a> JSON: {
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
<Token token id=btok_7uHgmjWUBfUaQi at 0x00000a> JSON: {
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
Stripe\Token JSON: {
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
{
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
&stripe.Token JSON: {
  "id": "btok_7uHgmjWUBfUaQi",
  "object": "token",
  "bank_account": {
    "id": "ba_17eT7P2eZvKYlo2CUDMJtjiJ",
    "object": "bank_account",
    "account_holder_name": "Jane Austen",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1455468787,
  "livemode": false,
  "type": "bank_account",
  "used": false
}

Retrieve a token

Retrieves the token with the given ID.

Arguments
  • token required

    The ID of the desired token.

Returns

Returns a token if a valid ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

GET https://api.stripe.com/v1/tokens/{TOKEN_ID}
Stripe::Token.retrieve({TOKEN_ID})
stripe.Token.retrieve({TOKEN_ID})
\Stripe\Token::retrieve({TOKEN_ID});
Token.retrieve({TOKEN_ID});
stripe.tokens.retrieve({TOKEN_ID}, function(err, obj) {...});
token.Get({TOKEN_ID})
curl https://api.stripe.com/v1/tokens/tok_17drHk2eZvKYlo2CEEHm8kkG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Token.retrieve("tok_17drHk2eZvKYlo2CEEHm8kkG")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Token.retrieve("tok_17drHk2eZvKYlo2CEEHm8kkG")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Token::retrieve("tok_17drHk2eZvKYlo2CEEHm8kkG");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Token.retrieve("tok_17drHk2eZvKYlo2CEEHm8kkG");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.tokens.retrieve(
  "tok_17drHk2eZvKYlo2CEEHm8kkG",
  function(err, token) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := token.Get("tok_17drHk2eZvKYlo2CEEHm8kkG", nil)
{
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
#<Stripe::Token id=tok_17drHk2eZvKYlo2CEEHm8kkG 0x00000a> JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
<Token token id=tok_17drHk2eZvKYlo2CEEHm8kkG at 0x00000a> JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
Stripe\Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
{
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}
&stripe.Token JSON: {
  "id": "tok_17drHk2eZvKYlo2CEEHm8kkG",
  "object": "token",
  "card": {
    "id": "card_17drHk2eZvKYlo2C4kOaoYMC",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1455323356,
  "livemode": false,
  "type": "card",
  "used": false
}

Transfers

When Stripe sends you money or you initiate a transfer to a bank account, debit card, or connected Stripe account, a transfer object will be created. You can retrieve individual transfers as well as list all transfers.

View the documentation on creating transfers via the API.

The transfer object

Attributes
  • id string

  • object string , value is "transfer"

  • amount integer

    Amount (in cents) to be transferred to your bank account

  • amount_reversed integer

    Amount in cents reversed (can be less than the amount attribute on the transfer if a partial reversal was issued).

  • application_fee string

  • balance_transaction string

    Balance transaction that describes the impact of this transfer on your account balance.

  • created timestamp

    Time that this record of the transfer was first created.

  • currency currency

  • date timestamp

    Date the transfer is scheduled to arrive in the bank. This doesn’t factor in delays like weekends or bank holidays.

  • description string

    Internal-only description of the transfer

  • destination string

    ID of the bank account, card, or Stripe account the transfer was sent to.

  • destination_payment string

    If the destination is a Stripe account, this will be the ID of the payment that the destination account received for the transfer.

  • failure_code string

    Error code explaining reason for transfer failure if available. See Types of transfer failures for a list of failure codes.

  • failure_message string

    Message to user further explaining reason for transfer failure if available.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a transfer object. It can be useful for storing additional information about the transfer in a structured format.

  • reversals list

    A list of reversals that have been applied to the transfer.

    child attributes
    • object string , value is "list"

    • data list

      child attributes
      • id string

      • object string , value is "list"

      • amount integer

        Amount, in cents.

      • balance_transaction string

        Balance transaction that describes the impact on your account balance.

      • created timestamp

      • currency currency

        Three-letter ISO code representing the currency.

      • metadata #

        A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

      • transfer string

        ID of the transfer that was reversed.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • reversed boolean

    Whether or not the transfer has been fully reversed. If the transfer is only partially reversed, this attribute will still be false.

  • source_transaction string

    ID of the charge (or other transaction) that was used to fund the transfer. If null, the transfer was funded from the available balance.

  • source_type string

    The source balance this transfer came from. One of card, bank_account, bitcoin_receiver, or alipay_account

  • statement_descriptor string

    Extra information about a transfer to be displayed on the user’s bank statement.

  • status string

    Current status of the transfer (paid, pending, in_transit, canceled or failed). A transfer will be pending until it is submitted to the bank, at which point it becomes in_transit. It will then change to paid if the transaction goes through. If it does not go through successfully, its status will change to failed or canceled.

  • type string

    Can be card, bank_account, or stripe_account.

{
  "id": "tr_17e8fh2eZvKYlo2CxHKKMGs3",
  "object": "transfer",
  "amount": 1,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "bank_account": {
    "id": "ba_17e8fc2eZvKYlo2Cb664nFUx",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": null,
    "routing_number": "110000000",
    "status": "new"
  },
  "created": 1455390189,
  "currency": "usd",
  "date": 1455390189,
  "description": null,
  "destination": "ba_17e8fc2eZvKYlo2Cb664nFUx",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
    "foo": "bar"
  },
  "recipient": "rp_17e8fg2eZvKYlo2CqzZVk9eD",
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17e8fh2eZvKYlo2CxHKKMGs3/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "bank_account"
}
#<Stripe::Transfer id=tr_17e8fh2eZvKYlo2CxHKKMGs3 0x00000a> JSON: {
  "id": "tr_17e8fh2eZvKYlo2CxHKKMGs3",
  "object": "transfer",
  "amount": 1,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17bBxN2eZvKYlo2CpkezPWCQ",
  "bank_account": {
    "id": "ba_17e8fc2eZvKYlo2Cb664nFUx",
    "object": "bank_account",
    "account_holder_