Integrate with the Invoicing API

Learn how to create and send an invoice with code.

The Dashboard is the most common way to create invoices. If you’d like to automate invoice creation, you can integrate with the API. Build a full, working Invoicing integration using our sample integration.

Note

You don’t need to integrate with the Payments API to integrate with the Invoicing API.

Set up Stripe

Use our official libraries for access to the Stripe API:

Create a product

To create a product, enter its name:

Create a price

Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the billing interval (when the price is for a subscription). Like products, if you only have a few prices, it’s preferable to manage them in the Dashboard. Use the unit amount to express prices in the lowest unit of the currency – in this case, cents (10 USD is 1,000 cents, so the unit amount is 1000).

Note

As an alternative, if you don’t need to create a price for your product, you can use the amount parameter during invoice item creation.

To create a price and assign it to the product, pass the product ID, unit amount, and currency. In the following example, the price for the “Gold Special” product is 10 USD:

Create a customer

The Customer object represents the customer purchasing your product. It’s required for creating an invoice. To create a customer with a name, email, and description, add the following code replacing the values with your own:

After you create the customer, store the customer id in your database so that you can use it later. The next step, for example, uses the customer ID to create an invoice.

Note

See Create a customer for additional parameters.

Create an invoice

Set the collection_method attribute to send_invoice. For Stripe to mark an invoice as overdue, you must add the days_until_due parameter. When you send an invoice, Stripe emails the invoice to the customer with payment instructions.

Then, create an invoice item by passing in the customer id, product price, and invoice ID invoice.

The maximum number of invoice items is 250.

If you set auto_advance to false, you can continue to modify the invoice until you finalise it. To finalise a draft invoice, use the Dashboard, send it to the customer, or pay it. You can also use the Finalise API:

Note

If you created the invoice in error, void it. You can also mark an invoice as uncollectible.

Accept invoice payment

When the invoice is finalised, a PaymentIntent is generated and associated with the invoice. Use Stripe Elements to collect payment details and confirm the invoice’s PaymentIntent.

Note

You can’t edit monetary values or the collection_method parameter after an invoice is finalised. This restriction also applies to the finalised invoice’s PaymentIntent. When you update the invoice’s PaymentIntent with an update call, you can only modify the setup_future_usage, metadata, payment_method, description, receipt_email, payment_method_data, payment_method_options, and shipping parameters.

The Payment Element securely collects all of the necessary payment details for a variety of payment methods. See Payment method and product support to determine if your configured payment methods are supported by both Invoicing and the Payment Element.

Pass the client secret to the front end

Stripe.js uses the PaymentIntent’s client_secret to securely complete the payment process. Get the invoice’s client secret by expanding its confirmation_secret attribute when finalizing the invoice or when making another API call, such as retrieve or update, on the invoice after you finalize it. Return the client_secret to the front end to complete payment.

After the invoice returns, access the client secret on the expanded confirmation_secret field.

Set up Stripe Elements

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.

pay-invoice.html
<head>
  <title>Pay Invoice</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

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

pay-invoice.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 page

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

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

When the form loads, create an instance of the Payment Element and mount it to the container DOM node. Pass the PaymentIntent’s client secret as an option when creating an instance of Elements.

pay-invoice.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in your checkout form, passing in the client secret.
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');

The Payment Element renders a dynamic form that allows your customer to pick a payment method. The form automatically collects all necessary payments details for the payment method selected by the customer.

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

Complete payment

Use stripe.confirmPayment to complete the payment using details from the Payment Element. This creates a payment method and confirms the invoice’s PaymentIntent, causing a charge to be made. If Strong Customer Authentication (SCA) is required for the payment, the Payment Element handles the authentication process before confirming the PaymentIntent.

Provide a return_url to the confirmPayment function to indicate where Stripe redirects the user after they complete the payment. Your user might first be redirected to an intermediate site, like a bank authorisation page, before being redirected to the return_url. Card payments immediately redirect to the return_url when a payment is successful.

pay-invoice.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

When your customer submits a payment, Stripe redirects them to the return_url and includes the following URL query parameters. The return page can use them to get the status of the PaymentIntent so it can display the payment status to the customer.

When you specify the return_url, you can also append your own query parameters for use on the return page.

Parameter	Description
`payment_intent`	The unique identifier for the `PaymentIntent`.
`payment_intent_client_secret`	The client secret of the `PaymentIntent` object. For subscription integrations, this client_secret is also exposed on the `Invoice` object through `confirmation_secret`

When the customer is redirected back to your site, you can use the payment_intent_client_secret to query for the PaymentIntent and display the transaction status to your customer.

Caution

If you have tooling that tracks the customer’s browser session, you might need to add the stripe.com domain to the referrer exclude list. Redirects cause some tools to create new sessions, which prevents you from tracking the complete session.

Use the payment_intent_client_secret query parameter to retrieve the PaymentIntent. Inspect the status of the PaymentIntent to decide what to show your customers. You can also append your own query parameters when providing the return_url, which persist through the redirect process.

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Handle post-payment events

Stripe sends an invoice.paid event when an invoice payment completes. Listen for this event to ensure reliable fulfilment. If your integration relies on only a client-side callback, the customer could lose connection before the callback executes, which would result in the customer being charged without your server being notified. Setting up your integration to listen for asynchronous events is also what enables you to accept different types of payment methods with a single integration.

Note

Successful invoice payments trigger both an invoice.paid and invoice.payment_succeeded event. Both event types contain the same invoice data, so it’s only necessary to listen to one of them to be notified of successful invoice payments. The difference is that invoice.payment_succeeded events are sent for successful invoice payments, but aren’t sent when you mark an invoice as paid_out_of_band. invoice.paid events, on the other hand, are triggered for both successful payments and out of band payments. Because invoice.paid covers both scenarios, we typically recommend listening to invoice.paid rather than invoice.payment_succeeded.

Use the Dashboard webhook tool or follow the webhook quickstart to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

In addition to handling the invoice.paid event, we recommend handling two other events when collecting payments with the Payment Element:

Event	Description	Action
payment_intent.processing	Sent when a customer successfully initiated a payment, but the payment has yet to complete. This event is most commonly sent when a bank debit is initiated. It’s followed by either a `invoice.paid` or `invoice.payment_failed` event in the future.	Send the customer an order confirmation that indicates their payment is pending. For digital goods, you might want to fulfill the order before waiting for payment to complete.
invoice.payment_failed	Sent when a customer attempted a payment on an invoice, but the payment failed.	If a payment transitioned from `processing` to `payment_failed`, offer the customer another attempt to pay.

Integrate with the Invoicing API

Learn how to create and send an invoice with code.

Note

Set up Stripe

Create a product

Create a price

Note

Create a customer

Note

Create an invoice

Note

Accept invoice payment

Note

Pass the client secret to the front end

Set up Stripe Elements

Add the Payment Element to your page

Complete payment

Caution

Handle post-payment events

Note

OptionalCustomize an invoice

See also