Stripe

Octane uses Stripe Connect to integrate directly with Stripe services in a number of ways:

1. Customers: link Octane customers to existing Stripe customers, or automatically generate Stripe counterparts for customers created in Octane.
2. Invoicing: send out Stripe Invoices directly to your customers.
3. Payments: collect payments using any of Stripe's supported payment methods.

Stripe Setup Guide

Connecting your Stripe account with Octane takes a few short steps.

1. Set up your Octane account

If you haven't already, register with Octane and walk through the steps in the Portal Quickstart guide.

2. Link your Stripe account

Under Settings -> Invoicing & Payments, click Connect with Stripe to link your Stripe Account. We use Stripe Connect to facilitate invoicing and payments on your behalf.

🚧

Using a Stripe Test Account?

If you're using a Stripe test account for testing or development purposes, flip the "Use Stripe test account" toggle to set up a test account connection.

Enabling different Stripe integrations

There are a number of integrations with Stripe, all of which are controlled through your billing settings. Billing settings can be found on Settings -> Invoicing & Payments.

📘

Customer billing overrides

All billing settings can be overridden on a per-customer basis. Overrides can be useful if you have a few customers that you'd like to bill without Stripe, for example. Read more on setting per-customer overrides in our Invoice Settings guide.

Automate Stripe invoicing

To automatically send invoices to customers (with or without a Stripe integration), switch on Enable Invoice Delivery. By default, Octane will send out emails directly to your customers.

To send invoices using Stripe Invoicing instead, enable the Invoicing via Payment Provider option. To have Octane create the Stripe invoices in draft mode, you can enable Draft Mode. With this setting enabled, Stripe invoices will be created but will not be sent out to your customers without your explicit action.

Collect payments through Stripe

To automatically charge customers' payment methods through Stripe, enable Auto-Charge in addition to Enable Invoice Delivery. The customer's on-file payment method will be used to automatically charge the total amount due on their invoice.

Create and Link Stripe Customers

When creating customers in Octane via the API, you can set the autogenerate_payment_gateway_customer parameter to true to have Octane automatically create corresponding customers in Stripe. Additionally, existing customers can be linked to Stripe Customers using their existing Stripe Customer IDs through the API.

Stripe customers can also be created or linked via the Octane Portal. Under Integrations -> Payments on a customer's page, you can click Generate Stripe Customer to create a new counterpart. Alternatively, enter an existing Stripe Customer ID to link the Octane and Stripe customers.

Invoicing & Payments Flow

There are a number of steps between when an invoice is generated and when a customer's payment clears. Here is the lifecycle of that flow when a Stripe integration is enabled.

❗️

A note about reverse synchronization:

Octane is unaware of any invoices, payments, and customers created directly in Stripe. In general, all actions should be initiated from Octane. Contact us if you are taking any actions directly in Stripe and are unsure about how Octane will handle the change.

1. Once a customer's billing cycle ends, Octane waits for the configured invoice grace period.
2. After the invoice grace period, Octane generates an invoice in INVOICE_GENERATED state and waits for the configured payment grace period. The invoice is NOT issued or charged yet — it just remains available in Octane for you to examine until the grace period ends.
3. After the payment grace period, Octane attempts to issue and charge the invoice according to your billing settings. For example, if you are invoicing via Stripe with auto-charging enabled, Octane will create a Stripe invoice with collection method set to charge_automatically. Stripe will auto-advance this invoice after one hour, sending the invoice to the customer and charging their payment method.
   a. If the customer doesn't have an email set in Stripe, creating the Stripe invoice will fail.
   b. If the customer doesn't have a payment method in Stripe, the invoice will be created with collection method set to send_invoice. This means the invoice will be sent to the customer with options to pay it, but will not be automatically charged.
4. Octane listens to Stripe webhook events for any changes to the invoice, reflecting any status changes in Octane. For example, after the invoice is paid in Stripe, Octane will also mark that invoice as paid.

📘

Using Octane's Webhook API

Octane can notify you of any invoice changes through our Webhook API. See our Webhooks Quickstart guide to get started.

Other Settings & Customizations

There are a number of ways to fine-tune your billing and invoicing flow.

Invoice Memo

You can set a message to be displayed in the "memo" area of Stripe invoices by adding it to the "Memo" field under Settings -> Invoicing & Payments.

Memos can be customized for each invoice using variables surrounded by braces. For example, Invoice for {customer_display_name} would get turned into Invoice for John Steinbeck when generating an invoice for John Steinbeck.

Octane allows the following template variables to be used into the memo message:

• customer_display_name: The display name of the customer being invoiced.
• min_item_start_time: The beginning timestamp of the first line item on the invoice.
• max_item_end_time: The ending timestamp of the last item on the invoice.

Days Until Due

For invoices that aren't automatically charged, "Days Until Due" can be used to determine the due date on invoices. If you have a payment grace period set, you may want take that into account.

Line item descriptions

The description for line items generated from Metered Components defaults to the display name of the underlying Meter. You can override the description of these line items by setting the "Invoice Display Name" in the Metered Component.