Card Payments with Sources Preview

    Use Sources to accept card payments from around the world. If you need help after reading this, search our documentation or check out answers to common questions. You can even chat live with other developers in #stripe on freenode.

    Stripe users can process card payments from customers around the world using Sources—a single integration path for creating payments using any supported method. During the payment process, your integration creates a source representing the card information. This source is then used in a charge request to debit the card and complete the payment.

    Within the scope of Sources, cards are are a pull-based, synchronous method of payment. This means that your integration takes action to debit the amount from the customer’s card and there is immediate confirmation about the success or failure of a payment.

    Handling card information

    Card information is sensitive by nature. While sources for other payment methods are created server-side, card sources must be created client-side using Stripe.js. This ensures that no sensitive card data passes through your server so your integration can operate in a PCI compliant way.

    When your customer submits their card information using your payment form, it is sent directly to Stripe, and a representative Source object is returned for you to use. The process is similar to the creation of tokens. If you’re already using Stripe.js to tokenize card information, switching to sources is only a small change.

    Prerequisite: Consider a flexible checkout flow if you want to accept additional payment methods

    Card payments with Sources has fewer steps and requirements than other payment methods. As it’s a synchronous method and there is no additional customer action to take, the use of webhooks isn’t necessary. If you only want to accept card payments, you can simply follow the steps within this documentation to begin accepting cards with Sources.

    However, should you wish to accept other methods of payment available through Sources (e.g., iDEAL, SEPA Direct Debit, etc.), additional steps are required, making the use of webhooks are necessary. You can refer to our best practices for developing a flexible checkout flow that supports different payment methods.

    Step 1: Create a Source object

    To create a source with Stripe.js, first include the library within your payment page and set your publishable API key. Once included, use the following source.create method (instead of card.createToken) to create a source when a customer submits their card information in your payment form:



    Stripe.source.create({
      type: 'card',
      card: {
        number: $('.card-number').val(),
        cvc: $('.card-cvc').val(),
        exp_month: $('.card-expiry-month').val(),
        exp_year: $('.card-expiry-year').val(),
      },
      owner: {
        address: {
          postal_code: $('.address_zip').val()
        }
      }
    }, stripeResponseHandler);
    

    When your script receives the response from Stripe’s servers, the following stripeResponseHandler function is called. Similar to using Stripe.js to create card tokens, this function does the following:

    • If the card information entered by the user returned an error, the error is displayed on the page
    • If no errors were returned then a source was created successfully. Add the returned source ID to the form and submit the form to your server.
    function stripeResponseHandler(status, response) {
    
      // Grab the form:
      var $form = $('#payment-form');
    
      if (response.error) { // Problem!
    
        // Show the errors on the form
        $form.find('.payment-errors').text(response.error.message);
        $form.find('button').prop('disabled', false); // Re-enable submission
    
      } else { // Source was created!
    
        // Get the source ID:
        var source = response.id;
    
        // Insert the source into the form so it gets submitted to the server:
        $form.append($('<input type="hidden" name="source" />').val(source));
    
        // Submit the form:
        $form.get(0).submit();
    
      }
    }
    

    Once the source has been created, its status is immediately set to chargeable. No additional customer action is needed so the source can be used straight away.

    As card payments are a pull-based payment method, there is no movement of funds during the creation of a source. Only when a successful charge request has been made is the customer’s card debited and you receive the funds.

    Source creation in mobile applications

    If you’re building an iOS or Android app, you can implement sources using our mobile SDKs. Refer to our sources documentation for iOS or Android to learn more.

    Step 2: Make a charge request or save the payment details for later

    After creating a chargeable source, you can either make a charge request to complete a payment or save the card details to use for future payments or subscriptions.

    Making a charge request

    Use the Source object’s ID as the value for the source parameter when performing a charge request:

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

    A card source must be used within a few minutes of its creation as CVC information is only available for a short amount of time. Card sources do not expire, but using them after a delay can result in a charge request that is performed without CVC information. The consequences of this can be higher decline rates and increased risk of fraud.

    Although the status of the source is chargeable, this does not mean that the payment is going to be successful. A charge request can still fail if the customer’s bank declines the payment.

    Saving the payment information for later

    Instead of using a source to create a charge request immediately, you can also save the card source to a Customer object for use in creating future payments (e.g., subscriptions).

    curl https://api.stripe.com/v1/customers \
       -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.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.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::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";
    
    Map<String, Object> customerParams = new HashMap<String, Object>();
    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({
      source: "src_18eYalAHEMiOZZp1l9ZTjSU0",
    }, function(err, customer) {
      // asynchronously called
    });
    

    Once saved, use the Customer object when making a charge request, and the customer’s card is automatically charged. When using a source to create a payment, the customer has to provide their card information each time they make a purchase.

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

    Card payments are a synchronous method so confirmation of the charge’s status happens in real-time. Your integration immediately receives the result of the charge request—either a Charge object upon success or an exception upon failure. Once the charge has been confirmed as successful, the payment has been successfully completed and you can notify your customer and fulfill the order.

    If you’re making use of webhooks, your integration also receives either of the following events:

    Event Description
    charge.succeeded The charge succeeded and the payment is complete.
    charge.failed The charge has failed and the payment could not be completed.

    Disputed payments

    Card networks provide a process for cardholders to dispute payments made with their card. A dispute can be filed by the cardholder any time after a payment has been successful. It is still possible for a successful payment to be reversed if the bank investigates a dispute and decides it should be refunded.

    Disputes can be made for a variety of reasons. As such, you should make the appropriate decisions regarding your business and how you manage disputes, if they occur, and how to avoid them completely.

    Next steps

    Congrats! You've learned about processing card payments using Sources. Some documentation you might want to read next: