Payments

Orb integrates with payment gateways like Stripe for payment processing. Once a customer in Orb is mapped to the corresponding customer in the payment gateway, Orb can automatically pull in the relevant payment information.

​

Auto-collection

If auto-collection is enabled for a customer or subscription, Orb will attempt to charge the default payment method on the invoice due date. In Orb, the due date and the auto-collection behavior are decoupled, enabling the following possible behaviors:

• An invoice can be “due on issue” and have auto-collection enabled, allowing you to immediately collect payment at the end of the billing period.
• An invoice can be due with delayed net-terms (e.g. 30 days), allowing you to collect payment in the following month. In this case, the invoice will still be delivered to your customer when it’s issued, so payment may be received beforehand.
• An invoice or customer may have auto-collection disabled, in which case the customer will be liable for inputting payment on the invoice portal manually.

​

Configuring net terms and collection behavior

The due date of an invoice is determined by its “net terms”, which represents the days offset from the invoice date or issuance date, depending on the calculation method selected. This setting can be found and updated in the Invoices tab of your account settings. Choose “net terms” from the available templated date ranges in the dropdown, or provide a custom due date. This is configurable at the plan-level, but can be overridden per subscription or invoice. It’s common for enterprise customers to have extended terms (e.g. 30 or 60 days) and self-serve customers to have invoices that are due on issue (which reflects a net-terms value of 0). Unlike net-terms behavior, auto collection can be configured on a per-customer basis. If a customer is initialized with a linked payment provider customer, auto-collection is turned on by default, but can be manually disabled. Similarly, if a customer is later linked to a payment provider customer, auto-collection is automatically enabled. As with net-terms, auto-collection can be turned off for individual invoices.

​

Payment methods

Orb automatically syncs the default payment method from the payment gateway and displays it on the customer page. The payment method used for a given invoice is also shown on the invoice itself and locked once the invoice is paid to reflect the actual transaction. Orb supports all payment methods available through the connected payment gateway for one-time payments. However, when saving a payment method to use as the customer’s default, only a subset of those methods may be eligible—depending on the gateway. For example, with Stripe, one-time payments can be made using credit cards, ACH transfers, Stripe Link, digital wallets (Apple Pay, Google Pay), and crypto. Saved payment methods, however, are typically limited to credit cards, ACH, and Stripe Link. For automatic payments (e.g. autopay when an invoice is issued), Orb supports credit cards, ACH transfers, Stripe Link, Apple Pay, Google Pay, and Amazon Pay. If you would like to support any other payment methods for recurring payments, please contact the Orb team.

​

Payment method selection

When Orb attempts to charge a customer, it determines which payment method to use by checking the following fields in order of priority:

1. Stripe’s customer.invoice_settings.default_payment_method - The explicitly configured default payment method
2. Stripe’s legacy customer.default_source field - Used for backward compatibility with older Stripe integrations
3. Most recently created payment method - If neither of the above are set, Orb automatically uses whichever payment method was most recently attached to the customer in Stripe

​

What this means for your customers

• Customers without an explicit default: Even if a customer doesn’t have a default payment method explicitly configured in Stripe, Orb will still attempt to charge them using whichever payment method was added most recently
• Automatic fallback: This happens automatically without any configuration needed on your end
• No payment method scenario: The only scenario where a charge would fail due to missing payment information is if the customer has no payment methods attached at all in Stripe

​

Best practices

While the automatic fallback to the most recent payment method provides convenience, we recommend ensuring customers have an explicit default payment method set in Stripe (invoice_settings.default_payment_method) for clarity and predictability. Relying on explicit defaults gives you more control over which payment method gets charged and avoids potential confusion if customers have multiple payment methods on file.

​

Excluding payment methods

When using Orb Invoicing with Stripe as a payment gateway, you can exclude specific Stripe payment method types on a per-customer basis. This is useful for enterprise contracts or sales-led deals where credit card processing fees may be prohibitively expensive. Excluded payment methods will not be available for the customer to select during payment and will not be used for auto-collection. If a customer’s default payment method becomes excluded, Orb will attempt to use the next available compatible payment method for auto-collection. Excluded payment methods can be configured per-customer in the payment configuration section of the customer’s details page, or via the API using the payment_configuration field. For the full list of payment method types, see Stripe’s PaymentMethod documentation.

​

Dunning behavior

If auto collection is enabled and the invoice cannot be collected for the configured payment method, Orb will automatically retry the charge after 1, 4, and 9 days from the initial payment attempt. Orb also retries payments intelligently when they’re most likely to succeed. If the linked customer at the payment gateway does not have a payment method set, Orb will not attempt to create a dunning schedule. However, any time a payment method is initially set or changed from a previous method, Orb will create a new dunning schedule and immediately try to collect on the invoice even if the invoice has completed dunning or is not eligible for the next retry as per the dunning schedule. This ensures that payment recovery happens immediately.

​

Distinguishing invoice types in payment workflows

When handling payment webhooks or building payment recovery flows, use the invoice_source field to differentiate between invoice types:

• invoice_source=subscription: Recurring charges from the customer’s subscription
• invoice_source=one_off: One-time charges such as credit purchases or manual invoices

This distinction is useful for:

• Payment failure handling: Retry subscription invoices more aggressively than one-off credit purchases. Subscription failures may indicate a need to block product access, while credit purchase failures mean the credits aren’t granted.
• Customer communication: Send different messages for recurring billing failures versus failed credit purchases. A subscription payment failure might trigger account suspension warnings, while a credit purchase failure is less critical.
• Analytics and reporting: Separate subscription revenue from prepaid credit revenue to understand different revenue streams.

See the invoice schema for all available fields.

​

Payment receipts PDFs

Orb generates receipts when an invoice is successfully paid. Receipt generation happens at the moment the invoice transitions to the paid state, regardless of whether payment was collected via auto-collection, through the invoice/customer portal, or is marked as paid. How to access receipts:

• A receipt is included as an attachment in the payment success email that Orb sends to the customer when the invoice is paid via auto-collection.
• In the Orb dashboard, open any paid invoice to download the receipt and invoice PDFs.
• In the customer-facing invoice portal, the invoice reflects a Paid status and remains available for download.

​

Automatic balance carryover for small invoices

For customers using Stripe Payments, Orb can automatically handle invoices that fall below Stripe’s minimum charge threshold. This feature helps avoid payment failures and customer confusion for small invoice amounts.

​

How it works

When enabled, Orb will:

1. Detect small invoices: During invoice finalization, identify invoices below the minimum threshold
2. Apply balance automatically: Deduct the invoice amount from the customer’s account balance
3. Mark as paid: The invoice is marked as paid (no payment processing occurs)
4. Carry forward balance: The unpaid amount becomes a negative customer balance that carries forward to future invoices

​

Configuration

This feature can be configured in your Stripe Payments settings:

• Navigate to Settings > Payments > Stripe
• Toggle “Rollover small invoices”
• The feature is enabled by default when setting up Stripe
• Applies to all Orb-handled invoices (not externally synced invoices)

​

Minimum thresholds

The threshold varies by currency and matches Stripe’s minimum charge amounts. Orb uses these same minimums to determine when an invoice should be automatically rolled over.

​

Customer experience

From the customer’s perspective:

• Small invoices are automatically marked as paid without requiring action
• No “Payment Failed” emails are sent for amounts below the threshold
• The carried balance appears as a line item on the next invoice
• Once the accumulated balance exceeds the minimum threshold, normal payment processing resumes

​

Tax configuration

Refer to the tax automation integrations documentation to learn how to use an automated tax provider to enrich your invoices with tax information.