Integrate with third-party payment processors
Learn how to use Stripe subscriptions and invoices with third party payment processors.
To process payments for your Billing subscriptions and invoices with a third-party processor, you have the following options:
When you submit payments for Stripe invoices to a third-party processor, your system records the invoices as paid_
. The remaining subscription cycle continues normally. To use out-of-band invoices, you need to 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 must 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 processor. To disable automatic emails:
- From the automatic billing settings in the Dashboard, disable Send finalized invoices and credit notes to customers. After you change this setting, changes to any subscription with collection_method set to
send_
won’t trigger customer emails. Only use this if all of your emailed subscription invoices are paid with a third-party processor.invoice
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 must also 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 object on Stripe.
Create a subscription
Next, create a Subscription and set the collection_
to send_
. This setting doesn’t require a Stripe payment method and generates Invoices that must be paid directly instead. Set the days_
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 processor, and you must set a long enough time for days_
so that any recovery workflows you implement have time to complete.
Present the amount to the user for payment
Third-party payments don’t work with Stripe Checkout or Elements. You must build a checkout flow that uses the third party to create a valid payment method, but uses Stripe to determine 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 processor 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 object created in the first step of the subscription creation flow. For convenience, store non-sensitive third-party tokens as metadata on the Customer object.
Remember to disable the Send finalized invoices and credit notes to customers option before setting the email
property on the Customer.
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 allow time for integrations to modify the draft invoice. You can finalize the invoice manually if you want to skip this delay.
Invoice finalization triggers an invoice.finalized event, which you should listen for to trigger payments on the third-party processor.
Process payments Third party
Follow the instructions from the third-party processor to collect payments for the amounts represented on each invoice using the tokens stored on the associated Customer object. 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 processor is successful, mark the corresponding invoice as paid_
.
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
Cancel subscriptions
To cancel a subscription, remove the third-party payment method details from the Stripe Customer object 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 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
Switch between third-party payments and Stripe
To switch a customer from a third-party processor to Stripe:
- Collect a new payment method for the customer by setting up future payments or using the customer portal.
- Update the subscription collection_method from
send_
toinvoice charge_
and set the new payment method as theautomatically default_
.payment_ method - 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 object after checkout.
Partial payments
We don’t support partial payments on out_
invoices. In the event of a partial payment, use a Credit Note to adjust the original invoice, and then manually generate a new invoice for any remaining balance.