The KillBill Plugin for Hyperswitch

[srujanchikke]

The Kill plugin for Hyperswitch is still in the development phase and it will be out very soon. I'm creating this thread to discuss suggestions and feedback about the killbill <> hyperswitch plugin.

[shaun-forgie]

Initial Thoughts

I have begun reviewing the initial design document around how kill bill and hyperswitch will work together. It can be found as an attachement to this comment.

Kill Bill with Hyperswitch.pdf

With respect to the user initiated payment/user flow-1 the suggested sequence needs further discussion from step 5 onwards. Kill Bill initiates payment only AFTER the invoice has been calculated and generated.

Many subscriptions can appear on the one invoice or be spread across many invoices if invoice groups are being used. Subscriptions can also be configured with their own invoicing cycle and generate invoices separately from the account billing cycle. It is important to realise that kill bill has support for a variety of different subscription types [standalone/base/add-ons] which allows for various flavours and flows.

Billing catalogs are versioned artefacts and a billing tenant can have past/current/future catalogs loaded. Subscriptions based on plans in the catalog can utilise pricing phases which allow for price changes to be defined for each phase. Alignment rules influence when a subscription starts. Subscriptions may be included into the account billing cycle for the customer, which happens on a day of the month, or they may have their own separate billing cycle if they have daily, weekly, fortnightly or another billing cycle frequency defined.

Many many scenarios exist. These scenarios will effect when the invoice gets generated and total amounts to be included on the invoice, which in turn impacts how much needs to be paid. The following is a non exhaustive list of things that can impact the amount that needs to be paid:

• is this first subscription created for the account
• does the subscription have a monthly billing cycle that aligns with the account billing cycle
• are price overrides in effect for the plan
• what dates are being used back dating / forward dating
• is this a parent / child account relationship
• does the base plan have child plans and do these have the same billing cycle

[srujanchikke]

Hi @shaun-forgie ,

I am reviewing the points you mentioned above with the current implementation of the Hyperswitch plugin. Any points that cannot be covered with the current implementation will be addressed in the next version of the plugin.

[shaun-forgie]

The design as it stands will not work for Kill Bill account holders. The central focus with payment scenarios is based around the invoice not the subscription. An invoicing payment portal should manage the redirection flow to the Hyperswitch unified checkout page.

Remember that many subscriptions will have a trial / free period. So when a user subscribes they will initially get an zero dollar invoice created.

[srujanchikke]

Yes, Killbill will charge the user when invoice is created. Merchant have to update the payment method manually for Killbill account holders. Current implementation of plugin only supports merchant initiated transactions. Customer initiated transaction will be processed via merchant portal and there he invokes to hyperswitch sdk to make zero dollar multi use mandate payment specifying amount .
We have released our first version of killbill-hyperswitch plugin. Please take a look at it.

[shaun-forgie]

Concepts / Semantics

I still need to clarify the responsibilities allocated to KB and HS and how this will actually be operated in a given region.

Background
Kill Bill is multi tenanted. This means many Billing Tenants can be using the same Kill Bill instance. KB <-> HS tenancies will need to be carefully synchronised.
The KB instance will be operated by a platform operator. The platform operator will be responsible for defining what payment gateways are enabled in a given region. Once regional settlement networks have been defined they can then be selected for use by the actual billing / settlement tenants. So regional platform configurations need to occur first.

Billing Tenants will need to select the settlement networks that are available in a region. They will need to register their merchant account API keys with HS. For example billing tenants may select 4 networks from the 10 available networks that have been enabled in that region.

Account Holders will have a default network / payment method / mandate setup against their account. However more than one payment network / payment method can be enabled for the account holder. Subscriptions can select from these predefined account based payment methods with a subscription chosing to use a payment method that is different to the account default.

Design Decisions

1. Regions - How will we restrict the number of payment networks that can be shown to Billing Tenants to a list of preapproved regional options.
2. Billing Tenants - How should we ensure tenancies are syncrhonised between HS / KB.
3. Account Holders - How should restrict which tenant configured payment networks can be used by an account holder.
4. Subscriptions - How should we specify a payment network / method for a given subscritpion.
5. Payment Network / Payment Method cross references. KB will need to keep references to both tenant and account holder specific payment networks and payment methods.

First thoughts. More to come.

[srujanchikke]

Please have a look at out business profile doc here

1. Regions - How will we restrict the number of payment networks that can be shown to Billing Tenants to a list of preapproved regional options.

• Billing Tenants can have different configuration for payment networks by mapping them to business profiles. To understand more about business profiles please look at this doc
  

2. Billing Tenants - How should we ensure tenancies are syncrhonised between HS / KB.

• Again KB tenants can be mapped to profiles in HS. We also have user level access for different merchant accounts same as killbill users.

3. Account Holders - How should restrict which tenant configured payment networks can be used by an account holder.

• Sending profile id in payment request should solve this problem. Tenant should be configured with profile id along with api keys.

4. Subscriptions - How should we specify a payment network / method for a given subscritpion.

• While creating payment method itself we can specify the profile in HS, Same will be used for merchant initiated transactions.

5. Payment Network / Payment Method cross references. KB will need to keep references to both tenant and account holder specific payment networks and payment methods.

• Business profiles should solve this problem.

[shaun-forgie]

So if KB sends the account holder [invoice payer] to the check out page it can be configured to only show the payment networks enabled for a certain profile?

[srujanchikke]

Yes, business profile id should be passed while creating payment intent to invoke HS SDK.

[shaun-forgie]

Support for Invoice Payment Links

I have been reading about payment link functionality here https://docs.hyperswitch.io/features/payment-flows-and-management/payment-links

How can we extend this to support Invoice Payment Links for invoices generated out of KB?

We are currently thinking about generating a tiny URL based string that can be used to redirect the user to a payment page.

[srujanchikke]

Yes, you can use payment link functionality for invoice payment links. But this can't be done using Hyperswitch plugin. You might want to create payment link via email notification plugin, and then update the invoice as per payment status. Merchant can customize the payment page and expiry as well.

[shaun-forgie]

The bill payers really needs to see the invoice in full detail and possibly have access to previous invoices as well if they want to pay more than one outstanding invoice. So the payment page is not really appropriate. Can we talk about how a more specialised bill payments page could be developed?

[shaun-forgie]

System Topology / Environments

We will be running regional production environments in which we have a many to one hub and spoke structure between Kill Bill instances and Hyperswitch.

How will we handle a hub and spoke based topology? Can tenants in HS [Orgs/Merchant/Profile] have a callback URL registered for updating the status of invoice payments to a specific instance of kill bill?

[shaun-forgie]

What is the maximum number of organisations that can run a hyperswitch instance?

[srujanchikke]

Hi @shaun-forgie ,

An organisation(super admin) can have multiple tenants at killbill; these tenants will be mapped to business profiles at Hyperswitch, and configurations can be done at all levels. Let's say you configured the return URL at the merchant level; this can be overridden by profile-level configuration. If I understand the last question correctly, a Hyperswitch instance can have as many organisations as it wants, It depends on how you scale the application and db instances.

What do you mean by this "Hyperswitch organisations are probably the closest thing to a kill bill tenancy." ? Does this means organisations should be mapped to tenants ?

[shaun-forgie]

@srujanchikke we would like a company [Biller] to be able to login to both their Bill Rush biller portal and the Hyperswitch organisational dashboard. So ideally we would like an kill bill tenant = hyperswtich organisation.

[srujanchikke]

Is BillRush biller portal Killbill Admin user Interface?

[shaun-forgie]

@srujanchikke

[shaun-forgie]

I have attached a UML class diagram that outlines the kill bill core payments model and classes.

[shaun-forgie]

This shows the three payment scenarios in orange on the left and the payment, payment transaction and payment attempt classes. Note the Invoice Payment and Invoice Payment Transaction sub-classes which relate to the Invoice Payment Scenario.

The question is: What payment status / information should be available in kill bill?

[srujanchikke]

PaymentTransactionStatus should be available in killbill to retireve the payment status. By default killbill plugin calls the connector everytime you call the retrievePayment() method.

[srujanchikke]

PaymentTransactionStatus is mapped to payment_intent status in hyperswitch.

[shaun-forgie]

We should probably list the Hyperswitch payment_intent status values and try and map those values to Kill Bill PaymentTransactionStatus values.

[srujanchikke]

Yes we have this mapping in plugin for PaymentPluginStatus,

private PaymentPluginStatus convertPaymentStatus(IntentStatus paymentStatus) {
        switch (paymentStatus) {
            case REQUIRES_CAPTURE:
            case SUCCEEDED:
            case PARTIALLY_CAPTURED:
            case PARTIALLY_CAPTURED_AND_CAPTURABLE:
                return PaymentPluginStatus.PROCESSED;
            case PROCESSING:
                return PaymentPluginStatus.PENDING;
            case CANCELLED:
                return PaymentPluginStatus.CANCELED;
            case FAILED:
                return PaymentPluginStatus.ERROR;
            default:
                return PaymentPluginStatus.UNDEFINED;
        }
    }

[shaun-forgie]

Merchant Initiated Transactions - AAV Refresh Cycles

The recent HS blog post here https://hyperswitch.io/blog/3ri-explained-understanding-merchant-initiated-authentication-clu83otw0002bkudkjlm9yk66 puts the spot light on the need for AAV - The Accountholder Authentication Value refreshes every 90 days.

Any ideas on how the Kill Bill \ HS integration will handle this and which system will manage this information and the refresh cycle?