Invoice Payment Flow - update sequence diagram and design specifications

[shaun-forgie]

Background

The blog post found here https://blog.killbill.io/blog/introducing-the-hyperswitch-plugin-for-kill-bill/ outlines the onboarding and payment flow for a new Kill Bill customer creating a new subscription.

While this diagram attempts to provide some context around why the payment is being processed it is uneccessary to deal with anything apart from the interactions between the kill bill payment plugin and the hyperswitch system.

In Kill Bill payments are only triggered after an invoice has been created. In the case where account holders have elected to authorise payments manually a message [email/SMS/Whatsapp etc...] also needs to be be sent with a link to an invoice payment URL that allows the payor to review the invoice and select the payment method to be used. As such the design material and sequence diagram should focus in this more generic invoice payment sequence to get a clearer picture of what needs to occur.

This generalised invoice payment flow is triggered by many different scenarios in Kill Bill including the new customer / new subscription scenario. However the most common scenario is the account or subscription billing cycle process that results in one or more invoices being created.

The KB plugin components involved in this process include: invoice / notification / payment controller / payment plugins

Invoice Payment Scenarios

The typical scenarios we need to focus on when paying an invoice include:

• One off manual payment authorisations [using payment links or possibly a new variant called an invoice payment link]
• Automated recurring payments [using an existing mandate or consent]

Payment processing failures will also need to be dealth with as retries and errors will need to be passed back to Kill Bill to update the payment status.

Once this is done we can elaborate a number of other important scenarios including:

• Part Payment of Invoices
• Account Lump Sum Payments [ settlement of blocked / disabled accounts as part of debt collection]

System Setups / Configuration Prerequisites

In order for invoice payment flows to work across Kill Bill and Hyperswitch system boundaries a variety of settings need to be in place. The following need to specified more clearly:

• the environment and topology needs to be defined including the API keys and endpoint URLs that are being used by billing and settlement systems to communicate along with the clarifying the number of instances of billing [KB] and settlement [HS] systems that are running including one to one and many to one [hub / spoke] setups.
• the logical system entities that Kill Bill and Hyperswitch are using to process the invoice payment flow. This means defining how entities are mapped / synchronised between systems. For example what Hyperswitch entity [organisation/merchant account/profile] is a KB tenant lined to and how are these entities to be coordinated.

As both systems are multi tenanted it is important to outline what assumptions are being made about who is operating each Kill Bill / Hyperswitch instance and what levels of self service or administrative oversight are given to Billers in this context.

[srujanchikke]

Hi @shaun-forgie ,

The above blog will redirect user to Hyperswitch docs. you can find information regarding payment links triggered by emails here . Regarding multi-tenant mapping we will get back to you.