Payments

Blanq uses Stripe for payments. The setup is quite simple and only requires a few steps. The first thing you need to do is to create a Stripe account and get your API keys. Make sure that you have updated your environment variables with your Stripe keys.

Defining products

Products are defined in the app.config.ts under the products key with the signature:

type Product = {
  type: 'subscription' | 'payment',
  priceId: undefined | string,
  title: string,
  price: number,
  description: string,
  features: string[],
  action: string,
}

Explanation of the product fields

  • type: This is either subscription or payment. This is used to determine the type of product. A subscription is a recurring payment and a payment is once-off.
  • priceId: This is the Stripe price ID. This can be undefined if you want to have a 'free' product.
  • title: The title of the product.
  • price: The price of the product.
  • description: A description of the product. Currently all is denoted in USD, you'll have to update the code if you want to use a different currency.
  • features: An array of strings that describe the features of the product.
  • action: The text on the button that the user clicks to purchase the product.

It's important that you sync this config with actual products in your stripe account. The checkout session will use the priceId to let users purchase. If priceId is undefined, the button won't do anything.

Checkout and Portal

Checkout

The checkout endpoint creates the Stripe Checkout, on success - the user is redirected to an internal API endpoint where a subsequent 'subscriptions' or 'payments' entry is made in the database. Users can have multiple subscriptions and payments. Once the subscription is verified and created, the user is redirected back to the billing page and will see that the plan they subscribed to is highlighted.

Portal

The Portal is used so that users can manage their subscriptions and payments. Here they can cancel subscriptions and view their payment history and change their payment details. You need to ensure that Portal is configured correctly in your Stripe account.

Webhooks

Other than the redirect after payment, Blanq also listens to Stripe webhooks. The webhooks are used to update the database when a subscription is updated or canceled. The webhooks are verified with the Stripe secret key.

Webhook events

Blanq listens to the following events:

  • invoice.paid: To update the subscription status to active when a normal payment is made.
  • customer.subscription.updated: To update the subscription status when a subscription is updated (cancelled or renewed).
  • customer.subscription.deleted: To update the subscription status when a subscription to inactive when it is deleted.

Testing

You can use the Stripe CLI to test webhooks locally. You can use the following command to listen to events:

stripe login


stripe listen --forward-to localhost:3000/api/billing/webhook

Be sure to copy the webhook secret from the terminal into your .env file.