Stripe
If you would like to use Stripe as a payment gateway and send Orb invoices, follow the instructions here instead
The following instructions are only if you would like to use Stripe Invoicing to send and manage invoices.
Prerequisites:
- Stripe account with Invoicing enabled
Connecting Stripe with Orb
if you’re already using Stripe as a payment gateway, you can skip this step, since the connection already exists.
- In the Orb dashboard, click the dropdown menu on the bottom left and navigate to Organization settings, navigate to the “Integrations” tab of the modal, and select Connect to Stripe
- Follow the instructions to connect Stripe
Mapping items
Mapping items to products in Stripe is required for the integration to succeed. If you do not map items, invoices will fail to issue.
In Stripe, items are called Products, and can be found by searching for the product catalog. Create a product in Stripe for every item that you are selling in Orb. If you’d like Orb to also pull back any tax information from Stripe, select a tax treatment for the items.
Then, navigate to the Items tab in Orb under Settings, and select a Stripe item for each Orb item.
Configuring customers
When creating or updating customers in the Orb UI, select Stripe as the Payment Provider in order to view a list of previously created customers in your Stripe account.
Customer mappings can also be configured in the API, by passing in the customer’s Stripe ID under payment_provider_id
, and setting payment_provider
to stripe_invoice
. Note that the payment provider here is stripe_invoice
. If you instead pass stripe_charge
, we will use Stripe as a payment gateway, and not as an invoicing provider.
The customer’s Stripe ID can be found on the customer page, and starts with the prefix cus_
.
Once mappings are configured, invoices for customers with a Stripe payment provider ID will be synced to Stripe Invoicing. For synced invoices, payment methods and invoice display are controlled with Stripe’s platform settings.
Invoice Collection Behavior
When syncing invoices from Orb to Stripe, Orb’s auto-collection setting does not control how Stripe collects payment. Stripe provides two mechanisms for auto-collection:
charge_automatically
: Stripe will attempt to automatically charge the customer’s default payment method upon invoice finalization.send_invoice
: Stripe will send the invoice to the customer without immediately charging a card.
When syncing an Orb invoice to Stripe, Orb will determine which option to use depending on the due_date
of the invoice.
- For invoices with net terms set to zero,
collection_behavior
is set tocharge_automatically
- For invoices with non-zero net terms,
collection_behavior
is set tosend_invoice
Stripe’s auto_advance
field determines whether the invoice should be automatically finalized after it’s created. Orb sets this true
by default at the end of the invoice sync process. This setting does not control payment collection; it only controls whether the invoice moves out of draft state automatically.