Create a payments page
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.
Create a Checkout Session Client and Server
A Checkout Session controls what your customer sees in the embeddable payment form 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.
<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.
curl https://api.stripe.com/v1/checkout/sessions \ -u "
:" \ -d "line_items[0][price]"=sk_test_4eC39HqLyjWDarjtT1zdp7dc\ -d "line_items[0][quantity]"=1 \ -d "payment_intent_data[application_fee_amount]"=123 \ -d "payment_intent_data[transfer_data][destination]"={{PRICE_ID}}\ -d mode=payment \ --data-urlencode success_url="https://example.com/success" \ --data-urlencode cancel_url="https://example.com/failure"{{CONNECTED_ACCOUNT_ID}}
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 bytransfer_data[destination]
after the charge is captured. Theapplication_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.
# 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 =
# 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#verify-events 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'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
Learn more in our fulfillment guide for Checkout.
Testing webhooks locally
Use the Stripe CLI to test webhooks locally.
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 runstripe 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.
<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.
curl https://api.stripe.com/v1/checkout/sessions \ -u
: \ -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}}"sk_test_4eC39HqLyjWDarjtT1zdp7dc
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.
curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \ -u "
:" \ -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"sk_test_4eC39HqLyjWDarjtT1zdp7dc
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.