Allowing customers to manually pay invoices with Stripe
August 18th, 2012
Stripe doesn’t offer a lot of flexibility with payment options. You can easily process one-time payments or setup recurring, automatic payments on a monthly/annual billing cycle. But if you’re looking to do something more complicated, things can get a little tricky.
For business-to-business startups, such as Scholastica, your customers often (and unfortunately) will not agree to any automated billing solution. Instead, because of annoying bureaucratic constraints, they need to review an invoice prior to making any sort of payment.
Unfortunately, Stripe does not support this type of manually billing workflow. And so the question: How can you use Stripe to create invoices but allow customers to manually pay them after the invoice is created?
An ideal solution would leverage Stripe’s built-in invoicing system rather than reimplementing some sort of internal invoice object, line items, etc. Stripe has a perfectly good invoicing process; if possible, we don’t want to recreate all that work, manage two separate payment processes, duplicate logic, etc. In short, a manually paid invoice should as much as possible resemble an automatically paid invoice with one exception: the customer should be allowed to review the invoice before approving any charges to their card.
Allow your customer to add their card in the usual fashion (i.e. they fill in whatever card information you’re collecting, click save, and you send a post to Stripe creating a new customer object). You’ll also want to add an optional checkbox which says something like “Don’t bill this card automatically”. By ticking this checkbox, customers can opt out of automatic billing.
As far as Stripe knows, a manually billed customer is no different from an automatically billed customer. Their card is stored normally and they can be subscribed to whatever plan makes sense for your app.
Now, here’s where things get interesting. When it’s time for your customer to pay their invoice, Stipe will issue a webhook one hour before charging their card. From the Stripe documentation:
Once an invoice is created, payment is automatically attempted. Note that the payment, while automatic, does not happen exactly at the time of invoice creation. If you have configured webhooks, the invoice will wait until one hour after the last webhook is successfully sent (or the last webhook times out after failing).
In your code, listen for that invoice.created webhook and, when it’s received, immediately mark the invoice as “closed”. This will prevent Stripe from attempting to charge the customer’s card. Again quoting from the Stripe documentation:
[The closed boolean determines] whether or not the invoice is still trying to collect payment. An invoice is closed if it’s either paid or it has been marked closed. A closed invoice will no longer attempt to collect payment.
Perhaps more importantly, however, prematurely closing the invoice gives you a easy an easy way to determine which invoices require manual payment. For example, your method might look something like:
def needs_manual_payment? closed? && !paid? end
This is necessary for writing conditional logic (e.g. showing manually billed customers different views, etc).
Step one accomplished: Your customer will not be automatically billed. Next you’ll need to give them a way to manually pay the prematurely “closed” invoice. Exactly how this should work depends somewhat on the needs of your app. At a high level, however, you’ll want to create a “Pay Invoice” button, which when clicked:
- Charges a one-time payment to your customer’s card equal the total amount due for the unpaid invoice.
- Marks the invoice as “paid”.
- Emails the customer a receipt.
Finally, because at least some of your customers will not be automatically billed, you’ll want to create an admin page where you can view unpaid invoices. This will make it easier to monitor outstanding invoices.