Create a payments page

Learn how to create a page to accept payments for your users.

Web

iOS

Android

Complexity:

Customize logo, images, and colors.

Built-in support for Apple Pay, and Google Pay.

View the demo to see a hosted example.

Accept a payment

Note

Refer to your platform profile to determine if either direct charges or destination charges is right for your business.

Destination charges

In this example, the platform is a home-rental marketplace that needs to create payments for homeowners who rent their properties. You can use destination charges in other applications as well.

What you're building

This sample integration is running in test mode, which means that it won’t create a real charge. Use as your card number, any three-digit CVC code, and an expiration date in the future to simulate a successful payment.

Create a Checkout Session Client and Server

A Checkout Session controls what your customer sees in the Stripe-hosted payment page such as line items, the order amount and currency, and acceptable payment methods.

Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.

checkout.html

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

On your server, make the following call to Stripe’s API. After creating a Checkout Session, redirect your customer to the URL returned in the response.

Command Line

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[][price]"="{{PRICE_ID}}" \
  -d "line_items[][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  -d "payment_intent_data[transfer_data][destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -d "mode"="payment" \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel"

payment_intent_data[transfer_data][destination] - This argument indicates that this is a destination charge. A destination charge means the charge is processed on the platform and then the funds are immediately and automatically transferred to the connected account’s pending balance. For our home-rental example, we want to build an experience where the customer pays through the platform and the homeowner gets paid by the platform.
line_items - This argument represents the items the customer is purchasing. The items are displayed in the Stripe-hosted user interface.
success_url - This argument redirects a user after they complete a payment.
cancel_url - This argument redirects a user after they click cancel.
payment_intent_data[application_fee_amount] - This argument specifies the amount your platform plans to take from the transaction. The full charge amount is immediately transferred from the platform to the connected account that’s specified by transfer_data[destination] after the charge is captured. The application_fee_amount is then transferred back to the platform, and the Stripe fee is deducted from the platform’s amount.

When performing destination charges, Checkout uses the brand settings of your platform account. See the Customize branding section for more information.

Note

This Session creates a destination charge. If you need to control the timing of transfers or need to transfer funds from a single payment to multiple parties, use separate charges and transfers instead.

Fulfillment Server-side

After the payment is completed, you’ll need to handle any fulfillment necessary on your end. A home-rental company that requires payment upfront, for instance, would connect the homeowner with the renter after a successful payment.

Caution

Don’t rely on the redirect to the success_url parameter alone for fulfilling purchases as:

Malicious users could directly access the success_url without paying and gain access to your goods or services.
Customers may not always reach the success_url after a successful payment. It is possible they close their browser tab before the redirect occurs.

Configure a webhook endpoint (for events from your account) in your dashboard.

Then create an HTTP endpoint on your server to monitor for completed payments to enable your sellers or service providers to fulfill purchases. Make sure to replace the endpoint secret key (whsec_...) in the example with your key.

server.rb

# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

post '/webhook' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  event = nil

  # Verify webhook signature and extract the event.
  # See https://stripe.com/docs/webhooks/signatures for more information.
  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload.
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid Signature.
    status 400
    return
  end

  if event['type'] == 'checkout.session.completed'
    session = event['data']['object']
    handle_completed_checkout_session(session)
  end

  status 200
end

def handle_completed_checkout_session(session)
  # Fulfill the purchase.
  puts session.to_s
end

Learn more in our fulfillment guide for Checkout.

Testing webhooks locally

Testing webhooks locally is easy with the Stripe CLI.

First, install the Stripe CLI on your machine if you haven’t already.
Then, to log in run stripe login in the command line, and follow the instructions.
Finally, to allow your local host to receive a simulated event on your connected account run stripe listen --forward-to localhost:{PORT}/webhook in one terminal window, and run stripe trigger --stripe-account={{CONNECTED_STRIPE_ACCOUNT_ID}} checkout.session.completed (or trigger any other supported event) in another.

Disputes

As the settlement merchant on charges, your platform is responsible for disputes. Make sure you understand the best practices for responding to disputes.

Create a subscription

You can create a recurring payment on a connected account with subscriptions. Subscriptions are created with direct charges. Optionally, specify an application_fee_percent to direct a percentage of each invoice payment to your platform.

The Checkout page uses the brand settings of the connected account, including its business name, icon, logo, and color. See the Customize branding section for more information.

Note

You can include a combination of one-time line items and recurring plans in a Checkout Session. If specified, application_fee_percent will apply to both one-time and recurring items.

Create a Checkout Session Client and Server

A Checkout Session controls what your customer sees in the Stripe-hosted payment page such as line items, the order amount and currency, and acceptable payment methods.

Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.

checkout.html

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

On your server, make the following call to the Stripe API. After creating a Checkout Session, redirect your customer to the URL returned in the response.

Command Line

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[][price]"="{{PRICE_ID}}" \
  -d "line_items[][quantity]"=1 \
  -d "subscription_data[application_fee_percent]"=10 \
  -d "mode"="subscription" \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel" \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"

Customize branding

Your platform and Standard connected accounts can use the Branding settings in the Dashboard to customize branding on the payments page. When performing destination charges, Checkout uses the brand settings of the platform account. For direct charges, and destination charges with on_behalf_of, Checkout uses the brand settings of the connected account. Platforms can configure the brand settings of connected Express and Custom accounts using the Accounts API.

The account update API accepts the following parameters for branding:

icon - Displayed next to the business name in the header of the Checkout page.
logo- If specified, displayed instead of the icon and business name in the header of the Checkout page.
primary_color - Used as the background color on the Checkout page.
secondary_color - Used as the button color on the Checkout page.

Command Line

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "settings[branding][icon]"=file_123 \
  -d "settings[branding][logo]"=file_456 \
  --data-urlencode "settings[branding][primary_color]"="#663399" \
  --data-urlencode "settings[branding][secondary_color]"="#4BB543"

Enable payment methods

View your payment methods settings and enable the payment methods you want to support. Card payments, Google Pay, and Apple Pay are enabled by default but you can enable and disable payment methods as needed.

Before the payment form is displayed, Stripe evaluates the currency, payment method restrictions, and other parameters to determine the list of supported payment methods. Payment methods that increase conversion and that are most relevant to the currency and customer’s location are prioritized. Lower priority payment methods are hidden in an overflow menu.