Getting Started with Sources Preview

Step 2: Have the customer take any action that might be required

Some payment methods require your customer to complete a certain action before the source can be used in a charge request. For instance, customers using iDEAL must be redirected to their online banking service to authorize the payment.

The source’s flow parameter denotes what action, if any, your customer needs to take. There are four possible values you can expect:

Step 3: Confirm that the source is ready to use

When a source is created, its status is initially set to either pending or chargeable, depending on whether the payment method used requires any further customer action. A pending source must transition to chargeable before it can be used in a charge request. This occurs once the required customer action has been taken (e.g., authorizing the payment with their banking service).

If the payment method requires no customer action, then the source is created with its status immediately set to chargeable. It can then be immediately used in the creation of a charge request.

The status of a source can be one of five possible values:

Source webhooks

To be notified about changes to the source’s Status, you need to make use of webhooks and receive the following events:

For payment methods where the source is not immediately chargeable, your integration can either wait until it receives the source.chargeable webhook event, make use of client-side polling, or periodically retrieve the source and verify its status.

Step 4: Make a charge request using the source

When the source is chargeable, you can make a charge request, using the source ID as the value for the source parameter, to complete the payment.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=1099 \
   -d currency=eur \
   -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',
  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',
  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",
  "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("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",
  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",
}
chargeParams.SetSource("src_18eYalAHEMiOZZp1l9ZTjSU0")
ch, err := charge.New(chargeParams)

Step 5: Confirm that the charge has succeeded and the payment is complete

Depending on the payment method, the funds from the charge request might be available immediately (e.g., card payments) or might take a few days (e.g., ACH debits). The charge’s status parameter indicates whether or not the charge has been successful and funds are available. The status can be one of three values:

Some payment methods, such as credit and debit cards, receive immediate (synchronous) confirmation about whether the charge was successful, so you can instantly determine if the payment is complete.

For methods that are not immediate (asynchronous), the status of a charge can remain in a pending state for several days after its creation before it is updated to either succeeded or failed. For these types of payment methods, you should only fulfill your customer’s order once the charge has been successful. This confirms that the payment is complete and the funds are guaranteed as available. If a charge fails, the order has not been paid for.

Charge webhooks

To be notified about changes to the charge’s status, you should make use of webhooks and receive the following events:

• charge.succeeded: the charge has succeeded
• charge.failed: the charge has failed

You can make use of the charge.succeeded webhook to confirm when the charge’s status has transitioned to succeeded so you can fulfill your customer’s order.

Best practices for integrating payment methods

By taking into consideration the flexibility of Sources when designing your checkout flow, you can minimize any changes required to support additional payment methods. In a typical checkout flow for card payments (excluding 3D Secure), your integration collects the card information and creates a source, then immediately uses it to make a charge request. As there is no additional action for the customer to take, and card payments provide synchronous confirmation, we can immediately confirm if the payment is successful and that the funds are guaranteed—the use of webhooks isn’t necessary.

Other payment methods may require your customer to take additional action before a source is chargeable (e.g., iDEAL), or it can take a few days for the funds to be received (e.g., ACH). When making use of these types of payment methods, the use of webhooks is often necessary to determine the status of the Source and Charge objects relating to a payment, even when using client-side polling.

To ensure that your checkout process is as flexible as possible to support different methods of payment, we recommend the following approach.

• Your integration is set up to receive webhooks from Stripe so it can determine the status of Source and Charge objects, should you make use of payment methods other than cards
• All necessary payment information is collected from your customer and used to create a source
• Consider storing any order information (e.g., order number) as metadata when creating a source. This is useful when handling payment methods that require a customer action. Your integration can make a charge request once the source.chargeable webhook has been received, retrieving any metadata from the event in the process.
• If required, have your customer take the appropriate action while informing them that the payment is being processed. Your integration can determine what action to take, if any, from the Source object’s flow parameter.
• Once the charge.succeeded webhook is received (either instantly or after a certain amount of time), the funds are confirmed and you can notify the customer that the payment has been completed

Considerations for Stripe Connect platforms

Stripe Connect platform owners can make use of additional payment methods supported with Sources. How you approach the use of additional payment methods is dependent on whether your platform uses standalone or managed accounts. To learn more about creating payments for connected users, and which approach is best for you, refer to our Connect payments and fees documentation.

Creating sources on connected accounts

Should you need to create sources directly on your platform’s connected accounts, you can do so by passing source.stripeAccount with a value of a connected account’s ID when using Stripe.js.

// Set the connected Stripe Account on which the source should be created
Stripe.source.stripeAccount = "acct_24BFMpJ1svR5A89k";

Stripe.source.create({
  type: 'ideal',
  amount: 1099,
  currency: 'eur',
  owner: {
    name: 'Jenny Rosen',
  },
  redirect: {
    return_url: 'https://shop.example.com/crtA6B28E1',
  },
}, stripeResponseHandler);

If you’re creating sources server-side, you can make use of authentication using the Stripe-Account header with any of our supported libraries.

Creating charges on standalone accounts

These are normal Stripe accounts controlled by the account holder, the platform’s user. As such, each account must independently meet the requirements of a payment method (e.g., country or currency restrictions). The account holder must also activate the payment methods they wish to use, accepting any service agreements that might be necessary.

Charge requests for payment methods supported by Sources for standalone accounts must be created directly on the connected account which has activated the necessary payment method. Payments created directly on a connected account are only be available on that account.

Creating charges on managed accounts

Unlike standalone accounts, managed accounts are fully controlled by the platform. It is only the platform that needs to meet the requirements of, and activate, a payment method.

Charge requests for payment methods supported by Sources for managed accounts must be created through the platform’s account, using the destination parameter. Customers are charged only by your platform, which then transfers the necessary amount to the destination account.

Next steps

• Payment methods
• Sources API documentation