Collect payments with Stripe

You can integrate Stripe Invoicing with Konnect Metering & Billing to:

• Deliver invoices to customers via Stripe Invoicing
• Charge credit cards and automate revenue collection via Stripe Payments
• Enable automatic sales tax calculation via Stripe tax
• Support multiple payment methods and currencies including cryptocurrency

The following lists show which parts of the revenue lifecycle is managed by Konnect Metering & Billing, Stripe Invoicing, Stripe Tax, and Stripe Payments:

Managed by Metering & Billing:

• Usage metering
• Products and prices
• Subscription management
• Billing and subscriptions
• Rating and invoice generation

Managed by Stripe:

• Tax calculations with Stripe Tax (if enabled)
• Sending invoices to customers with Stripe Invoicing
• Storing credit card details with Stripe Payments
• Payment collection with Stripe Payments

Configuring Metering & Billing with Stripe involves the following steps:

1. Install the Stripe app in Metering & Billing.
   1. Configure how you want to collect invoices with a billing profile.
   2. (Optional) Configure tax collection.
2. Configure existing or new customers from Stripe in Metering & Billing.
3. (Optional) Create an additional billing profile so you can automatically and manually collect invoices.
4. (Optional) Create a customer portal session.

When you configure the Stripe app in Metering & Billing, Konnect uses Stripe Invoicing to synchronize and deliver invoices, automate tax calculations (if enabled), and reconcile transactions.

Metering & Billing supports two payment collection methods with Stripe:

• Charge Automatically (default): Metering & Billing will tell Stripe to collect charges with the default payment method for the customer. This method works well for self service use cases. To collect charges automatically, you need to have a default payment method set for customer.
• Send Invoice: Metering & Billing will tell Stripe to email the invoice to the customer with the payment instructions. This method works well for enterprise clients. To send an invoice, you need to have an email address set for the Stripe customer.

You can use one or both methods by setting up one or more billing profiles. This is useful if you have different payment collection methods for different customers. For example, you can have a billing profile for self-service customers with automatic payment collection and a billing profile for enterprise customers with email invoicing. You can set the self-service billing profile as the default and link enterprise customers to the enterprise billing profile. This way your self-service customers are charged automatically and your enterprise clients will receive an email invoice.

When the Stripe app is installed and set as a billing profile, Metering & Billing will automatically synchronize invoices to Stripe Invoicing. Metering & Billing will create a Stripe Invoice for each Metering & Billing invoice and mark invoices as finalized to kick of the payment collection in Stripe.

When a paid subscription is created, Metering & Billing will enforce that a customer linked with Stripe has either a default payment method or an email address depending on the collection method settings.

Stripe fees: Stripe will charge a fee for each invoice, tax calculations and payment according to your contract with them. See Stripe Fees for more information.

Invoice timing

The timing of an invoice sent to your end customer is determined by two things: Metering & Billing settings and your Stripe configuration. Together, they control when an invoice is finalized and delivered.

The Metering & Billing billing profile defines how long the system waits for usage data before generating an invoice:

• Wait for Late Usage Events: How long Metering & Billing should delay invoice generation to account for delayed or out-of-order usage. Set to P0D to include only events already received (immediate generation).

  Important: Ingest delays can cause incorrect invoice amounts.

• Wait Before Sending Invoices: Additional wait time after the invoice is generated. Set to P0D to send immediately after processing.

Stripe applies its own timing rules when finalizing and sending invoices. By default, Stripe waits one hour before finalizing an invoice.
You can adjust this grace period in the invoice settings in Stripe.

You can enable automatic tax calculation for your invoices using Stripe as a payment provider. Tax calculation is based on the customer’s situation, location, product type, and other factors, so always consult a tax professional. You can use Stripe Tax to handle complex tax rules and rates for any region. The integration ensures accurate, up-to-date tax calculations for each invoice, removing the guesswork and reducing compliance risks.

Stripe calculates tax based on:

• Vendor location
• Customer location

• Product tax code (global default or per rate card)

  Defining tax codes: To define tax codes for rate cards, you can set default tax codes in the billing settings in Konnect. You can also specify tax codes per rate card by editing the product catalog when creating a plan.

To enable automatic tax calculation in Stripe, make sure you:

• Configure tax on your Stripe account.
• Review the default tax settings in your Stripe account.
• Install the Stripe app in Metering & Billing
• Set the Stripe app as the default billing profile
• Collect tax information from your customers at onboarding (for example: address and VAT number)
• Optionally use the Stripe Checkout Session to collect tax information from your customers

For more information, see the Stripe Tax documentation.

Before you install the Stripe integration in Metering & Billing, copy and save your Stripe API key from your dashboard.

1. In the Konnect sidebar, click Metering & Billing.
2. In the Metering & Billing sidebar, click Settings.
3. Click Stripe.
4. Click Install.
5. In the Stripe API Key field, enter your Stripe API key (secret key). For example: sk_523d....
6. Click Install Stripe app.
7. Choose how you want to send invoices:
   • To send invoices and collect payment automatically with Stripe, click Auto Collection.
   • To send an invoice and allow the customer the pay it in their preferred way, click Send Invoice.

   If you want to do both, you can configure an additional billing profile after setting up Stripe.

8. If you want to configure Stripe to collect taxes, click Advanced Customize Billing Profile and configure tax settings in the Tax Collection section.
9. Click Create Billing Profile.
10. Do one of the following:
    • To set this as the default billing profile, click Start Billing.
    • To not set this as the default billing profile, disable Set this as the new default billing profile and click Keep Current Default Profile.

You can create customers in Metering & Billing from existing customers in Stripe or from customers that don’t exist in Stripe.

curl -X POST "https://us.api.konghq.com/v3/openmeter/customers/$CUSTOMER_ID/billing/stripe/checkout-sessions" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "stripe_options": {
         "success_url": "https://example.com/success",
         "cancel_url": "https://example.com/cancel"
       },
       "customer": {
         "name": "ACME, Inc.",
         "currency": "USD",
         "usageAttribution": {
           "subjectKeys": [
             "subject-123"
           ]
         }
       },
       "options": {
         "mode": "setup"
       }
     }'

You can create a Stripe Portal Session to allow customers to manage their payment methods and download their invoice history. The session will contain a URL to the Stripe Portal.

The Stripe Portal Session allows customers to:

• Manage their payment methods
• Change billing address
• Download their invoice history

To create a Stripe Portal Session for customers, send a POST request to the /openmeter/customers/{customerId}/billing/stripe/portal-sessions endpoint:

curl -X POST "https://us.api.konghq.com/v3/openmeter/customers/$CUSTOMER_ID/billing/stripe/portal-sessions" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "stripe_options": {
         "returnURL": "https://your-app.com/portal"
       }
     }'