Sources and Customers

Learn how to attach Sources to Customers and manage Customers' Sources.

A Source object can either be single-use or reusable as indicated by its usage parameter. While Sources can be charged directly, reusable Sources should always be attached to a Customer object for later reuse.

Attaching reusable Sources to Customers will also enable you to present your customers with a list of reusable payment methods (such as cards or bank debits) they previously used with your app or website.

Reusable Sources

Certain payment methods allow for the creation of sources that can be reused for additional payments without your customer needing to complete the payment process again. Sources that can be reused have their usage parameter set to reusable.

When using reusable Sources it is imperative that you attach them to a Customer before charging them as charging a Source directly will consume it (i.e. transition its status from chargeable to consumed), preventing any further charge creation.

Attaching a Source to a new Customer

It is possible to create a Customer and attach a Source you created to it in one API call. This is useful if this is the first time you’re seeing this customer and you haven’t yet created a Customer for them.

curl https://api.stripe.com/v1/customers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d email="paying.user@example.com" \
   -d source=src_18eYalAHEMiOZZp1l9ZTjSU0

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.create({
  email: 'paying.user@example.com',
  source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.create(
  email='paying.user@example.com',
  source='src_18eYalAHEMiOZZp1l9ZTjSU0',
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::create(array(
  "email" => "paying.user@example.com",
  "source" => "src_18eYalAHEMiOZZp1l9ZTjSU0",
));

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("email", "paying.user@example.com");
customerParams.put("source", "src_18eYalAHEMiOZZp1l9ZTjSU0");

Customer customer = Customer.create(customerParams);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.customers.create({
  email: "paying.user@example.com",
  source: "src_18eYalAHEMiOZZp1l9ZTjSU0",
}, function(err, customer) {
  // asynchronously called
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customerParams := &stripe.CustomerParams{
  Email: "paying.user@example.com",
}
customerParams.SetSource("src_18eYalAHEMiOZZp1l9ZTjSU0")
c, err := customer.New(customerParams)

In this case, the Source will become the Customer’s default source since it is the only one attached to the Customer object. The default source is automatically selected if you attempt to create a Charge by specifying the customer parameter without a source parameter.

Attaching a Source to an existing Customer

If you already created a Customer object to represent your customer it is also possible to attach a new Source to it:

curl https://api.stripe.com/v1/customers/cus_AFGbOSiITuJVDs/sources \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d source=src_18eYalAHEMiOZZp1l9ZTjSU0

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_AFGbOSiITuJVDs")
customer.sources.create({:source => "src_18eYalAHEMiOZZp1l9ZTjSU0")

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_AFGbOSiITuJVDs")
customer.sources.create(source="src_18eYalAHEMiOZZp1l9ZTjSU0")

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::retrieve("cus_AFGbOSiITuJVDs");
$customer->sources->create(array("source" => "src_18eYalAHEMiOZZp1l9ZTjSU0"));

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer customer = Customer.retrieve("cus_AFGbOSiITuJVDs");
Map<String, Object> params = new HashMap<String, Object>();
params.put("source", "src_18eYalAHEMiOZZp1l9ZTjSU0");
customer.getSources().create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.customers.createSource("cus_AFGbOSiITuJVDs", {
  source: "src_18eYalAHEMiOZZp1l9ZTjSU0"
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CustomerSourceParams{
  Customer: "cus_AFGbOSiITuJVDs",
  Source: &stripe.SourceParams{
    Token: "src_18eYalAHEMiOZZp1l9ZTjSU0",
  },
}
paymentsource.New(params)

Since a default source probably already existed on the Customer, the newly attached source won’t be the Customer’s default source. It is possible to update the Customer default source to the Source of your choice with an additional API call:

curl https://api.stripe.com/v1/customers/cus_AFGbOSiITuJVDs \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d default_source=src_18eYalAHEMiOZZp1l9ZTjSU0

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_AFGbOSiITuJVDs")
customer.default_source = "src_18eYalAHEMiOZZp1l9ZTjSU0"
customer.save

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_AFGbOSiITuJVDs")
customer.default_source = "src_18eYalAHEMiOZZp1l9ZTjSU0"
customer.save()

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::retrieve("cus_AFGbOSiITuJVDs");
$customer->default_source = "src_18eYalAHEMiOZZp1l9ZTjSU0";
$customer->save()

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer customer = Customer.retrieve("cus_AFGbOSiITuJVDs");
Map<String, Object> params = new HashMap<String, Object>();
params.put("default_source", "src_18eYalAHEMiOZZp1l9ZTjSU0");
customer.update(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.customers.update("cus_AFGbOSiITuJVDs", {
  default_source: "src_18eYalAHEMiOZZp1l9ZTjSU0"
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Upate(
  "cus_AFGbOSiITuJVDs",
  &stripe.CustomerParams{DefaultSource: "src_18eYalAHEMiOZZp1l9ZTjSU0"},
)

Charging a Source attached to a Customer

Finally, when charging a reusable Source you should specify the Customer and the Source as part of the charge request:

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=1099 \
   -d currency=eur \
   -d customer=cus_AFGbOSiITuJVDs \
   -d source=src_18eYalAHEMiOZZp1l9ZTjSU0

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = Stripe::Charge.create({
  amount: 1099,
  currency: 'eur',
  customer: 'cus_AFGbOSiITuJVDs',
  source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = stripe.Charge.create(
  amount=1099,
  currency='eur',
  customer='cus_AFGbOSiITuJVDs',
  source='src_18eYalAHEMiOZZp1l9ZTjSU0',
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$charge = \Stripe\Charge::create(array(
  "amount" => 1099,
  "currency" => "eur",
  "customer" => "cus_AFGbOSiITuJVDs",
  "source" => "src_18eYalAHEMiOZZp1l9ZTjSU0",
));

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("amount", 1099);
chargeParams.put("currency", "eur");
chargeParams.put("customer", "cus_AFGbOSiITuJVDs");
chargeParams.put("source", "src_18eYalAHEMiOZZp1l9ZTjSU0");

Charge charge = Charge.create(chargeParams);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.charges.create({
  amount: 1099,
  currency: "eur",
  customer: "cus_AFGbOSiITuJVDs",
  source: "src_18eYalAHEMiOZZp1l9ZTjSU0",
}, function(err, charge) {
  // asynchronously called
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

chargeParams := &stripe.ChargeParams{
  Amount: 1099,
  Currency: "eur",
  Customer: "cus_AFGbOSiITuJVDs",
}
chargeParams.SetSource("src_18eYalAHEMiOZZp1l9ZTjSU0")
ch, err := charge.New(chargeParams)

If you attempt to charge a Source attached to a Customer directly without specifying the Customer, you’ll receive an error asking for you to specify the Customer to which the Source is attached. Conversely if you attempt to charge a Customer without specifying a Source, the Customer’s default source will be used by default.

Single-use Sources

Single-use sources must be created each time a customer makes a payment and cannot be reused for later charge requests. For that reason, while technically possible, we do not recommend that you attach them to customers.

Attributing single-use Sources payments to Customers

While a single-use Source should not be directly attached to a Customer you may still want to attribute the Charge to the Customer. For that reason we support you passing a customer along with a source when making a charge request even if the Source provided is not attached to the Customer provided.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=1099 \
   -d currency=eur \
   -d customer=cus_AFGbOSiITuJVDs \
   -d source=src_18eYalAHEMiOZZp1l9ZTjSU0

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = Stripe::Charge.create({
  amount: 1099,
  currency: 'eur',
  customer: 'cus_AFGbOSiITuJVDs',
  source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = stripe.Charge.create(
  amount=1099,
  currency='eur',
  customer='cus_AFGbOSiITuJVDs',
  source='src_18eYalAHEMiOZZp1l9ZTjSU0',
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$charge = \Stripe\Charge::create(array(
  "amount" => 1099,
  "currency" => "eur",
  "customer" => "cus_AFGbOSiITuJVDs",
  "source" => "src_18eYalAHEMiOZZp1l9ZTjSU0",
));

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("amount", 1099);
chargeParams.put("currency", "eur");
chargeParams.put("customer", "cus_AFGbOSiITuJVDs");
chargeParams.put("source", "src_18eYalAHEMiOZZp1l9ZTjSU0");

Charge charge = Charge.create(chargeParams);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.charges.create({
  amount: 1099,
  currency: "eur",
  customer: "cus_AFGbOSiITuJVDs",
  source: "src_18eYalAHEMiOZZp1l9ZTjSU0",
}, function(err, charge) {
  // asynchronously called
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

chargeParams := &stripe.ChargeParams{
  Amount: 1099,
  Currency: "eur",
  Customer: "cus_AFGbOSiITuJVDs",
}
chargeParams.SetSource("src_18eYalAHEMiOZZp1l9ZTjSU0")
ch, err := charge.New(chargeParams)

In that instance, the created Charge object will have a reference to both the Customer and the Source passed even if they are not directly related with one another.