Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseManaged Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

Accept a payment with Billie

Learn how to set up your integration with Billie.

Unified line items

To maximize approval rates when you integrate with Billie, include line_items data to represent what’s in a shopper’s cart. For early access, see Payments line items.

Use the Payment Element to embed a custom Stripe payment form in your website or application and offer payment methods to customers. For advanced configurations and customizations, refer to the Accept a Payment integration guide.

Set up Stripe
Server-side

To get started, create a Stripe account.

Use our official libraries for access to the Stripe API from your application:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Collect payment details
Client-side

You’re ready to collect payment details on the client with the Payment Element. The Payment Element is a prebuilt UI component that simplifies collecting payment details for a variety of payment methods.

The Payment Element contains an iframe that securely sends payment information to Stripe over an HTTPS connection. Avoid placing the Payment Element within another iframe because some payment methods require redirecting to another page for payment confirmation.

The checkout page address must start with https:// rather than http:// for your integration to work. You can test your integration without using HTTPS, but remember to enable it when you’re ready to accept live payments.

Set up Stripe.js

The Payment Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Create an instance of Stripe with the following JavaScript on your checkout page:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Add the Payment Element to your checkout page

The Payment Element needs a place on your checkout page. Create an empty DOM node (container) with a unique ID in your payment form:

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

After the form above loads, create an Elements instance with a mode, amount, and currency. These values determine which payment methods your customer sees. To provide a new payment method in your form, make sure you enable it in the Dashboard.

checkout.js
const options = {
  mode: 'payment',
  amount: 1000,
  currency: 'eur',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

You can customize the Payment Element to match the design of your site by passing the appearance object into options when creating the Elements provider.

Collect addresses

By default, the Payment Element only collects the necessary billing address details. To collect a customer’s full billing address (to calculate the tax for digital goods and services, for example) or shipping address, use the Address Element.

Create a PaymentIntent
Server-side

Run custom business logic immediately before payment confirmation

Navigate to step 5 in the finalize payments guide to run your custom business logic immediately before payment confirmation. Otherwise, follow the steps below for a simpler integration, which uses stripe.confirmPayment on the client to both confirm the payment and handle any next actions.

When the customer submits your payment form, use a PaymentIntent to facilitate the confirmation and payment process. Create a PaymentIntent on your server with an amount and currency. To prevent malicious customers from choosing their own prices, always decide how much to charge on the server-side (a trusted environment) and not the client.

Included on a PaymentIntent is a client secret. Return this value to your client for Stripe.js to use to securely complete the payment process.

main.rb
Ruby
Python
PHP
Node.js
Java
Go
.NET
No results
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


post '/create-intent' do
  intent = Stripe::PaymentIntent.create({
    # To allow saving and retrieving payment methods, provide the Customer ID.
    customer: customer.id,
    amount:  1000,
    currency: 'eur',
  })
  {client_secret: intent.client_secret}.to_json
end

Submit the payment to Stripe
Client-side

Use stripe.confirmPayment to complete the payment using details from the Payment Element.

Provide a return_url to this function to indicate where Stripe redirects the user after they complete the payment. Your user might be initially redirected to an intermediate site, such as a bank authorization page, before being redirected to the return_url. Card payments immediately redirect to the return_url when a payment is successful.

If you don’t want to redirect for card payments after payment completion, you can set redirect to if_required. This only redirects customers that check out with redirect-based payment methods.

checkout.js
const form = document.getElementById('payment-form');
const submitBtn = document.getElementById('submit');

const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
  submitBtn.disabled = false;
}

form.addEventListener('submit', async (event) => {
  // We don't want to let default form submission happen here,
  // which would refresh the page.
  event.preventDefault();

  // Prevent multiple form submissions
  if (submitBtn.disabled) {
    return;
  }

  // Disable form submission while loading
  submitBtn.disabled = true;

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the PaymentIntent and obtain clientSecret
  const res = await fetch("/create-intent", {
    method: "POST",
  });

  const {client_secret: clientSecret} = await res.json();

  // Confirm the PaymentIntent using the details collected by the Payment Element
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
  } else {
    // Your customer is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

OptionalHandle post-payment events

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.

  • Handle events manually in the Dashboard

    Use the Dashboard to View your test payments in the Dashboard, send email receipts, handle payouts, or retry failed payments.

  • Build a custom webhook

    Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

  • Integrate a prebuilt app

    Handle common business events, such as automation or marketing and sales, by integrating a partner application.

OptionalSeparate authorization and capture

You can separate authorization and capture to create a charge now, but capture funds later. Stripe cancels the PaymentIntent and sends a payment_intent.canceled event if the payment isn’t captured during the 7-day window.

If you’re certain you can’t capture the payment, we recommend canceling the PaymentIntent instead of waiting for the 7-day window to elapse.

1. Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set capture_method to manual when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s Billie account.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d confirm=true \
  -d currency=eur \
  -d "payment_method_types[]"=billie \
  -d "payment_method_data[type]"=payment_method \
  -d capture_method=manual \
  --data-urlencode return_url="https://www.example.com/checkout/done"

2. Capture the funds

After the authorization succeeds, the PaymentIntent status transitions to requires_capture. To capture the authorized funds, make a PaymentIntent capture request.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/payment_intents/{PAYMENT_INTENT_ID}/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Stripe captures the total authorized amount by default. You can also specify amount_to_capture to be less than or equal to the total.

Optional Cancel the authorization

If you need to cancel an authorization, you can cancel the PaymentIntent.

OptionalAdd line items to the PaymentIntent

Unified line items

To maximize approval rates when you integrate with Billie, include line_items data to represent what’s in a shopper’s cart. For early access, see Payments line items.

Test your integration

To test your integration, choose the payment method and tap Pay. In a sandbox, this redirects you to a test payment page where you can approve or decline the payment.

In live mode, tapping Pay redirects you to the Billie website—you don’t have the option to approve or decline the payment with Billie.

Error codes

The following table details common error codes and recommended actions:

Error codeRecommended action
payment_intent_invalid_currencyEnter a supported currency.
missing_required_parameterCheck the error message for more information about the required parameter.
payment_intent_payment_attempt_failedThis code can appear in the last_payment_error.code field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling.
payment_intent_authentication_failureThis code can appear in the last_payment_error.code field of a PaymentIntent. Check the error message for a detailed failure reason and suggestion on error handling. This error occurs when you manually trigger a failure when testing your integration.
payment_intent_redirect_confirmation_without_return_urlProvide a return_url when confirming a PaymentIntent.
Was this page helpful?
YesNo