Collect payments with a custom invoicing integration

You can integrate any external invoicing or payment provider with Konnect Metering & Billing using the Custom Invoicing app to:

• Deliver invoices to customers via your existing invoicing provider
• Perform custom validation before invoices are issued or sent to customers
• Map invoice line items to your external system’s data model

 
flowchart TB
    IN["Invoice notifications"]
    CIA["Custom Invoicing app"]
    IC["Invoice changes"]
    IU["Invoice updates"]
    INT["Integration"]
    INV["3rd party invoicing solution"]
    PGW["3rd party payment gateway"]

    IN -->|Invoice changes| IC
    CIA -->|Invoice updates| IU
    IC --> INT
    IU --> INT
    INT <--> INV
    INT <--> PGW
  

The following lists show which parts of the revenue lifecycle are managed by Konnect Metering & Billing and which are delegated to your external provider:

Managed by Metering & Billing:

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

Managed by your external provider:

• Sending invoices to customers
• Storing payment details
• Payment collection

Configuring Metering & Billing with a custom invoicing provider involves the following steps:

1. Create a notification channel.
2. Install the Custom Invoicing app in Metering & Billing.
3. Configure a billing profile or customer overrides.
4. Implement the integration using notifications as a data source and the Custom Invoicing API to advance invoice state.

Create a notification channel

Before you install the Custom Invoicing app, create a notification channel so Metering & Billing can send invoice events to your integration.

For steps to create and manage notification channels, see the Notifications documentation.

The Custom Invoicing app pauses invoice processing at key states and waits for your integration to signal completion before the invoice progresses through its lifecycle.

The app provides two optional synchronization hooks:

Additionally, payment status synchronization is mandatory once an invoice enters the payment processing state, regardless of hook configurations.

For initial implementation and testing, start with both synchronization hooks disabled. Enable them later as your integration matures. See Draft Sync Hook and Issuing Sync Hook for details.

After enabling the app, create a billing profile that references it. Use customer overrides to limit the app’s effect to specific customers rather than making it the default billing profile.

Basic setup

When no sync hooks are enabled, the invoice flow works as follows:

1. Metering & Billing creates the invoice according to the invoice lifecycle rules.
2. The invoice reaches payment processing state. Your integration must:
   1. Send the invoice to the customer.
   2. Initiate and accept payment.
   3. Call the Custom Invoicing app’s Update Payment Status API to set the payment state once payment is complete.

Your integration is responsible for managing the mapping between Metering & Billing invoice IDs and the corresponding entities in your external provider.

Draft Sync Hook

When the Draft Sync Hook is enabled, invoice processing pauses at draft.sync. Your integration must call the Submit Draft Synchronization Results endpoint to validate the draft and allow the invoice to proceed.

During draft synchronization, your integration can:

• Update the invoice number to align with your external system’s numbering scheme
• Synchronize the external system’s invoice identifier back to Metering & Billing
• Associate external IDs with individual line items and discounts

This eliminates manual ID mapping between Metering & Billing and your external system. Your integration can also use this state to perform invoice validation and make adjustments through the Update Invoice endpoint before the invoice advances.

Issuing Sync Hook

When the Issuing Sync Hook is enabled, invoice processing pauses at issuing.sync. Your integration must call the Submit Issuing Sync Results endpoint to validate the final invoice details before issuance.

During issuing synchronization, your integration can:

• Set the external payment identifier to link the invoice with your payment system
• Perform final validation of the invoice details before sending to the customer
• Ensure all external system requirements are met

1. In the Konnect sidebar, click Metering & Billing.
2. In the Metering & Billing sidebar, click Settings.
3. Click Apps.
4. Find the Custom Invoicing app and click Install.
5. Click Select Custom Invoicing.
6. (Optional) Expand the Advanced Hooks & Metadata section and configure the synchronization hooks:
   • To pause processing at the draft state, enable Draft Sync Hook.
   • To pause processing before issuance, enable Issuing Sync Hook.
7. Click Install App.
8. Enable Setup Invoice Notifications.
9. From the Channels dropdown menu, select your notification channels.
10. Click Setup Notifications.
11. Select a billing profile preset:
    • Auto Collection to charge the customer automatically.
    • Send Invoice to send an invoice and allow the customer to choose their payment method.
12. (Optional) Expand Advanced Customize Billing Profile to modify the default billing profile parameters.
13. Click Create Billing Profile.
14. Do one of the following:
    • To set this as the default billing profile, click Set as Default Profile.
    • To limit the app to specific customers, disable Set this as the new default billing profile, click Keep Current Default Profile, and then configure customer overrides.