Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Billing
    Overview
    About the Billing APIs
    Subscriptions
      Overview
      Quickstart
      Use cases
      Build your integration
      Subscription features
        Subscription invoices
        Subscription schedules
        Subscription pricing
        Recurring pricing models
        Embed a pricing table
        Start subscriptions
        Set quantities
        Set billing cycles
        Backdate subscriptions
        Subscribe to multiple items
        Set trial periods
        Apply coupons
        Migrate subscriptions to Stripe
        How credit prorations are calculated
        Subscription payments
        Subscription payment methods
        Integrate with third-party payment processing
          Out-of-band invoices
        Collection methods
        Share a link to update payment details
        Strong Customer Authentication (SCA)
        Manage subscriptions
        Modify subscriptions
        Manage pending updates
      Analytics
    Invoicing
    Usage-based billing
    Connect and Billing
    Tax and Billing
    Quotes
    Revenue recovery
    Automations
    Scripts
    Revenue recognition
    Customer management
    Entitlements
    Test your integration
Tax
Reporting
Data
Startup incorporation
HomeFinance automationBillingSubscriptionsSubscription featuresIntegrate with third-party payment processing

Out-of-band invoices

Learn how to mark invoices as paid off of Stripe.

Copy page

When you submit payments to a third-party processor based on Stripe invoices, your system records the invoices as paid_out_of_band. The rest of Billing’s subscription cycle continues normally. You’ll customize two key Stripe Billing workflows:

  • Collecting customers’ payment method details
  • Paying invoices

Request Flow

The following diagrams illustrate the high-level request flows of a multiprocessor integration.

Collecting and storing customers’ payment method details

Paying invoices

Configure Stripe

To set up a multiprocessor integration, you have to make some configuration changes to Stripe.

Disable invoice emails

To prevent customers from paying directly on Stripe, disable automatic emails for any customer who processes payments on a third-party provider. To disable automatic emails:

  • Disable Send finalized invoices and credit notes to customers in Stripe’s automatic billing settings. After you change this setting, changes to any subscription with collection_method set to send_invoice won’t trigger customer emails. Only use this if all of your emailed subscription invoices are paid with a third-party payment provider.

Configure the customer portal

If you use the customer portal, disable Allow customers to view and update payment methods in the customer portal settings. (You also need to disable the Customers can switch plans setting.) You need to build custom flows to allow users to self-serve updates to their payment method on a third-party processor.

Sign up new customers

Create a Stripe customer

First create a blank Customer record on Stripe.

Command Line
cURL
curl -X POST https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Create a subscription

Next, create a Subscription and set the collection_method to send_invoice. This setting doesn’t require a Stripe payment method and generates Invoices that must be paid directly instead. Set the days_until_due parameter to the number of days an unpaid invoice remains open before your configured failed payment logic activates. You’re responsible for retrying failed payments on the third-party provider, and you need to set this long enough so that any recovery workflows you implement have time to complete.

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d customer=
{{CUSTOMER_ID}}
\ -d collection_method=send_invoice \ -d days_until_due=30

Present the amount to the user for payment

Third-party payments don’t work with Stripe Checkout or Elements. You have to build a checkout flow that uses the third party to create a valid payment method but with Stripe as the source of truth for billable amounts. To determine the amount to charge in the checkout flow, retrieve the initial invoice generated by the subscription.

Collect payment method details Third party

Follow the instructions from the third-party payment provider to collect payment method details from customers. Make sure to set up payment methods for use in future or off-session transactions.

The output of this step varies by processor. Some third-party processors provide a payment method token that you use to generate payments on that processor.

Update the Customer object

Update the Customer record created in the first step of the subscription creation flow. For convenience, store non-sensitive third-party tokens as metadata on the Customer record.

Remember to turn off the Send finalized invoices and credit notes to customers option before setting the email property on the Customer.

Command Line
cURL
curl https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}}
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d description="Third-party payment customer" \ -d "metadata[third_party_customer_id]"={{THIRD_PARTY_CUSTOMER_ID}} \ -d "metadata[third_party_payment_method_id]"={{THIRD_PARTY_PAYMENT_METHOD_ID}}

Collect payment

Listen for invoice.created webhook events

All invoices (including the first invoice created from a subscription) start in a draft state and trigger invoice.created webhooks. Invoices created by a subscription are automatically finalized after 1 hour to give time for integrations to modify the draft invoice. Finalize the invoice manually to skip this delay.

Invoice finalization triggers an invoice.finalized event. Listen to this event to trigger payments on the third-party processor.

Process payments Third party

Follow the instructions from the third-party payment provider to collect payments for the amounts represented on each invoice using the tokens stored on the associated Customer record. This might include listening to webhooks from the third party for notifications of successful payments.

Mark the Stripe Invoice as paid out-of-band

When payment on the third party is successful, mark the corresponding invoice as paid_out_of_band.

Command Line
cURL
curl https://api.stripe.com/v1/invoices/
{{INVOICE_ID}}
/pay
\ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d paid_out_of_band=true

Mark the invoice as paid before the subscription’s payment due date to keep the subscription operating normally. The Subscription object’s days_until_due attribute defines the payment due date.

Handle state changes

Stripe Subscription cancellation

To cancel Subscriptions, remove third-party payment method details from Stripe’s Customer records and your database. Listen for the customer.subscription.deleted event and delete any tokens related to the canceled subscription.

Third-party payment cancellation Third party

Some third-party payment processors allow end customers to cancel billing agreements directly. If the processor allows this, listen for any associated events and then cancel the subscription on Stripe.

Refunds and disputes Third party

You’re responsible for processing refunds and disputes originating from the third-party processor. To maintain accurate accounting data, use Credit Notes to adjust the amounts on issued invoices to log refunds. Create a Credit Note, and set the out_of_band_amount to the refunded amount.

Other considerations

Switching between third-party payments and Stripe

To switch a customer from a third-party processor to Stripe:

  1. Collect a new payment method for the customer by setting up future payments or using the Customer Portal.
  2. Update the subscription collection_method from send_invoice to charge_automatically and set the new payment method as the default_payment_method.
  3. Delete any existing third-party payment method tokens.

Retries

You must handle any recovery of failed third-party payments yourself. Stripe doesn’t have any visibility into the state of third-party payments until you mark an invoice as paid.

Taxes

Stripe Tax automatically adds the correct tax amounts to invoices as long as you set a billing postal code or IP address when updating the Customer record after checkout.

Partial Payments

We don’t support partial payments on out_of_band invoices. In the event of a partial payment, use a Credit Note to adjust the original invoice then manually generate a new invoice for any remaining balance.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc