Kaui Guide

Introduction

PDF Version of Kaui Guide

To download a PDF version of this guide, click here.

What Is Kaui?

"Kaui" (KAUI) stands for Kill (Bill) Admin User Interface. This self-contained web application interacts with Kill Bill over HTTPS.

Backoffice staff (for example, Support or Finance) will find Kaui useful to process refunds, credits, chargebacks, and so forth. Kaui also enables the Kill Bill administrator to perform more advanced tasks, such as managing tags, uploading a catalog, and configuring the tenant(s).

Other types of users who might find Kaui useful are developers (for testing), operations, and product managers.

Note: For Developers: Kaui functionality is provided via a series of Ruby on Rails mountable engines. You can extend its functionality (for example, to provide a custom UI for your plugins) by mounting your own engine(s).

How to Use This Guide

The first half of this guide explains the more basic components:

Getting Started
Basic search and Advanced search
Accounts
Payment methods
Subscriptions
Invoices
Payments
Timeline

Advanced and administrative features are covered in the second half of the guide:

Tenants
Users, roles, and permissions
Catalog
Overdue
Translation files
Tags
Custom fields

Note: The Plugin Manager and Analytics functionality is currently undocumented.

About Screenshots

The screenshots displayed in this guide may differ from what you see on your Kaui screen. That’s because your user permissions control what features you can access (i.e., what you see on the screen).

If you have any questions about why your Kaui screen doesn’t match what you see in this guide, ask your Kaui administrator.

Other Learning Resources

Videos

We regularly add new overviews and tutorials to our YouTube videos, so check in from time to time.

Glossary

The terms listed below are used frequently in this guide. We’ve provided an abbreviated description below. For a full description, see the Kill Bill Glossary.

Account (a.k.a. customer account): A record that contains details about the customer (name, address, etc.).
Child: An account that is associated with a parent account.
External Key: An alternative unique ID for an object.
Parent: An account that contains one or more child accounts.
Payment Method: A record of the details required for Kill Bill to trigger a payment.
Permissions: In Kill Bill, a defined action that can be performed in a system (for example, TAG_CAN_ADD OR ACCOUNT_CAN_CREATE). You can assign one or more permissions to a role, which can then be associated with a user. The user can only perform the permissions associated with that role.
Plan: Define how much a customer pays for a product and the frequency of the payment.
Plugin: Software that runs alongside Kill Bill in order to provide additional functionality.
Phase (a.k.a plan phase): Time periods within a subscription during which certain rules apply.
Subscription: A contract between you (the business) and a customer that associates an account with a plan and a specific start date.
Tag: A property that can be added to an object (for example, an account or a subscription) for information purposes or to affect the behavior of the system.
Tenant: The division or organization that is using Kill Bill as a group of users. Note that an organization can have more than one tenant, as Kill Bill supports multi-tenancy.
User: A person who logs on to use Kaui.
User Role: A group of permissions that specify which actions the user is allowed to perform in Kaui. A user can have multiple roles. A role can have multiple permissions.

Getting Started

First-Time Login

Note: Kill Bill handles authentication. The method your organization uses to manage users is highly configurable. For information on managing users and permissions, see the Users chapter.

To log in to Kaui:

Type in your username and password, then select the Sign In button.

Kaui displays the Add New Tenant screen:
Enter the tenant Name, API Key, and API Secret.

Note: The API key and API secret pair are used in all HTTP requests to ensure that the user issuing the request has the correct permissions to access the tenant.
Click the Save button.

Log In to Kaui

To log in to Kaui:

Type in your username and password, then select the Sign In button.
If your organization uses more than one Kill Bill tenant, select the tenant from the dropdown.
Click the Save button:

Log Out of Kaui

To log out of Kaui, select SIGN OUT in the upper right corner of the Kill Bill homepage:

Homepage Layout

The homepage is the screen that Kaui displays after you first log in.

Basic Search
Advanced Search
Plugin Manager and Analytics
Tags and Custom Fields
Users, Tenants, and Admin
Username / Tenant name and logout
Latest invoices, accounts, and payments (latest records created for this tenant)
This is Killian, the Kill Bill mascot!

Return to Homepage

From any screen in Kill Bill, you can return to the homepage by clicking the logo in the upper left corner:

Icons

Icon Description

Icon	Description
	Add—Indicates you can add an item, such as a payment method, credit, charge, etc.
	Dry-run invoice—Appears on the Account page. Clicking it manually triggers a committed or dry-run invoice.
	Expand—Expand a section or dropdown menu.
	Collapse—Collapse a section.
	Tags—_Admin-level feature:_ On the home page, click to access Tags, Tag Definitions, and Custom Fields. All users: In other locations in Kaui, click to select a tag to apply to the current object (for example, an account).
	Kaui Package Manager—Appears at the top of the screen and gives you access to plugin specific screens. (Also known as Kill Bill Plugin Manager.)
	Add-on—Appears on the Subscription screen and lets you add an add-on to the account’s subscription.
	Make a payment—Appears on the Invoice screen and lets you make a payment against the invoice.
	Users, Tenants, & Admin—_Admin level feature:_ Appears at the top of the screen and gives you access to Users, Tenants, and Admin.
	Appears in the Payment Methods section of the Account page, clicking the Refresh icon triggers a refresh for each payment plugin installed in Kill Bill, for that account. When you refresh a payment method, Kill Bill retrieves the latest payment information from where it’s stored (for example, from Stripe or another payment gateway). Note: This icon does not display if the only payment method listed is `EXTERNAL_PAYMENT`.

i PlusGreen

Add—Indicates you can add an item, such as a payment method, credit, charge, etc.

i InvoiceGen

Dry-run invoice—Appears on the Account page. Clicking it manually triggers a committed or dry-run invoice.

i DownArrow

Expand—Expand a section or dropdown menu.

i UpArrow

Collapse—Collapse a section.

i Tag

Tags—_Admin-level feature:_ On the home page, click to access Tags, Tag Definitions, and Custom Fields.

All users: In other locations in Kaui, click to select a tag to apply to the current object (for example, an account).

i Plug

Kaui Package Manager—Appears at the top of the screen and gives you access to plugin specific screens. (Also known as Kill Bill Plugin Manager.)

i Addon

Add-on—Appears on the Subscription screen and lets you add an add-on to the account’s subscription.

i CreditCard

Make a payment—Appears on the Invoice screen and lets you make a payment against the invoice.

i Gears

Users, Tenants, & Admin—_Admin level feature:_ Appears at the top of the screen and gives you access to Users, Tenants, and Admin.

i Refresh

Appears in the Payment Methods section of the Account page, clicking the Refresh icon triggers a refresh for each payment plugin installed in Kill Bill, for that account. When you refresh a payment method, Kill Bill retrieves the latest payment information from where it’s stored (for example, from Stripe or another payment gateway).

Note: This icon does not display if the only payment method listed is EXTERNAL_PAYMENT.

Grids/Tables

Grids (also referred to as tables) appear throughout Kaui to keep lists organized:

For very large grids, use the pagination controls to view different "pages:"

To sort columns on a grid, click the up/down arrow in that column’s header:

Kaui shows you which column is currently sorted by the purple arrow:

The direction of the arrow (up or down) indicates if the column is sorted in ascending or descending order.

If relevant, you can click a link in the grid to view that item’s detail. For example, on the Invoices grid, click the link to open that specific invoice:

Kaui allows you to edit the columns displayed in a table. To do this, click on the Edit Columns button:

This displays a new menu that lets you select the columns that you would like to view/hide:

You can click on the checkbox next to a column name to show/hide it from the view. For example, in the screenshot below only the Account Id, Name and External Key columns are displayed in the table:

You can also drag and drop a column name to change its position in the table. For example, to display the External Key field as the first column in the table, click the External Key field in the Edit Columns UI, drag it to the top of the list and drop it.

To download the data from a table, click on the Download CSV button:

This displays some additional download customizations:

If you are on the accounts page and would like to download data for all the accounts created in this week, you can select This Week and click the Download button:

On clicking the Download button, a CSV file is generated and downloaded.

By default, only the fields displayed on the screen are included in the CSV. if you would like all the fields to be included, you should click the "All fields" checkbox:

Basic Search

Tip: To view all accounts, place your cursor in the search field and press the Enter key.

To search for customer accounts, use the basic search. Basic search is available at the top of the screen no matter where you are in Kaui.

You can search for an account using the following criteria:

Account ID
External key
Name
Email address

Basic search is also available in the center of the homepage:

$ShowSearchHomepage$

Advanced Search

An advanced search can help you find account information as well as other types of objects in the system:

Bundle
Credit
Custom field
Invoice
Invoice payment
Payment
Subscription
Tag
Tag definition
Transaction

To perform an advanced search:

On the homepage, click Advanced search:

Kaui displays the Advanced Search pop-up:
In the Object type field, select the object type you want to search for:

Note: For information on which fields are searched for each object type, see the table in the next section.
In the Search for field, enter the identifier (ID) of the object you’re searching for. (Example: If you’re searching for a specific invoice, type in the invoice number.)
If you want Kaui to search and display the first record in the search results, click the Fast search checkbox.
Click the Search button. Kaui displays the search results.

Tip: At the bottom of the Advanced Search pop-up, Kaui displays the search syntax. You can copy and paste this advanced search syntax into a basic search field. This is helpful if you frequently perform the same kinds of advanced searches. For example:

Searchable Fields by Object Type

Object Type	Searchable Fields
Account	account ID, name, email, company name, external key
Bundle	account ID, bundle ID, external key
Credit	invoice item ID
Custom field	custom field ID, field name, field value, object type
Invoice	invoice number, invoice ID, account ID, currency
Invoice payment	payment ID
Payment	payment ID, external key
Payment method	payment method ID, external key
Subscription	subscription ID, external key
Tag	tag ID
Tag definition	tag definition ID
Transaction	transaction ID, external key

Object Type

Searchable Fields

Account

account ID, name, email, company name, external key

Bundle

account ID, bundle ID, external key

Credit

invoice item ID

Custom field

custom field ID, field name, field value, object type

Invoice

invoice number, invoice ID, account ID, currency

Invoice payment

payment ID

Payment

payment ID, external key

Payment method

payment method ID, external key

Subscription

subscription ID, external key

Tag

tag ID

Tag definition

tag definition ID

Transaction

transaction ID, external key

Checking Kaui Version

You can check the current Kaui version by typing http://<your Kaui URL>/health in the browser. This displays the following:

Accounts

This section helps you become familiar with customer accounts and the layout of the Account page.

The Account page provides information about a specific customer, such as email address, physical address, and so forth. It is also the central location for the customer’s billing information, subscriptions, invoices, and payment methods.

The next section explains how the Account page is laid out. To skip this and see the task-based steps, see Create an Account.

Account Page Layout

The Account page has the following sections:

Sub-menu
Account information
Billing info
Personal info
Payment methods

1. Account Sub-Menu

The Account sub-menu organizes and provides access to different areas of the customer’s account:

To see these areas, click the relevant item on the sub-menu. To return to the customer’s Account page, click Account on the sub-menu.

2. Account Information

This section of the screen displays a summary of the customer’s account information, such as their ID, currency, and time zone. To edit this information, click Edit next to Account Information.

Here you can perform the following tasks for the customer account:

Edit an account
Link to a parent account
Attach a tag to an account

3. Personal Information

This section of the screen displays the customer’s personal contact information (read only).

By default, Personal Information details are hidden for GDPR Compliance and customer privacy. To see the information, click Show/Hide Content.

To edit this information, see the Edit an Account section.

4. Billing Info

Here you can perform the following tasks for the customer:

Pay all unpaid invoices
Add a credit
Create a charge

You can also see a summary of billing information:

Field	Description
Account balance	Amount of money due on the account, including any account credits.
Account credit	Amount of any money owed to the customer.
Overdue status	The status of the customer’s account that indicates if they are overdue or up-to-date on their invoice payments. Note: The account can have a negative account balance, but not be overdue. That’s because overdue status depends on invoice due dates and how late payments are defined based on a company’s business policy. For example, an invoice may not be overdue if a company allows a 15-day grace period (a.k.a. NET terms) to make a payment.
Bill cycle day (BCD)	The day of the month on which the system generates an invoice for this account. This field applies to accounts that are subscribed to monthly subscriptions (or a multiple of monthly, such as quarterly, annually, etc.). For more information, see the Account Field Descriptions table.
Next invoice date	The date on which the system generates the customer’s next invoice.

Field

Description

Account balance

Amount of money due on the account, including any account credits.

Account credit

Amount of any money owed to the customer.

Overdue status

The status of the customer’s account that indicates if they are overdue or up-to-date on their invoice payments.

Note: The account can have a negative account balance, but not be overdue. That’s because overdue status depends on invoice due dates and how late payments are defined based on a company’s business policy. For example, an invoice may not be overdue if a company allows a 15-day grace period (a.k.a. NET terms) to make a payment.

Bill cycle day (BCD)

The day of the month on which the system generates an invoice for this account. This field applies to accounts that are subscribed to monthly subscriptions (or a multiple of monthly, such as quarterly, annually, etc.). For more information, see the Account Field Descriptions table.

Next invoice date

The date on which the system generates the customer’s next invoice.

The Trigger invoice generation feature lets you generate an invoice, either as a test or in a committed state.

5. Payment Methods

This section of the Account page lets you:

Add a payment method
Set a payment method as default
Delete a payment method
Apply a transaction to a payment method (authorize, charge, credit, etc.)

For more information on payment methods, see the Payment Methods chapter.

Create an Account

At the top right of the screen, click Create New Account:
Kaui opens the Add New Account screen:
Fill in the fields. For field descriptions, see Account Field Descriptions.
Click the Save button.

Account Field Descriptions

Field Description

Field	Description
Name	The customer’s first and last name.
First name length	This field sets the length of the customer’s first name. Kill Bill automatically calculates this number based on the location of the space between the first and last name. You can overwrite it with a different number, if necessary. Note: This field is used if your organization needs to extract customers' first or last names for communication (invoices, emails, etc.). The field lets an organization accommodate variations of names used across the globe.
External key	An optional alternate ID for the account. Once this is saved for the customer, you cannot change it. Tip: The external key feature is helpful if you integrate Kill Bill with another system, such as a CRM, and want to use that system’s ID in Kill Bill (for identification, searching, and so forth). Once this is set and saved for the customer, you cannot change it.
Email	The main email address to use for communicating with the customer.
Bill cycle day (BCD)	For monthly or quarterly subscriptions, what day of the month the invoice is created. Once this is saved for the customer, you cannot change it. Note: The system has three types of billing (date) alignment that affect the BCD: `ACCOUNT`, `SUBSCRIPTION`, and `BUNDLE`. For more information about the three billing alignment types, see Catalog Examples and "Billing Alignment Rules" in the Subscription Guide.
Currency	The currency that the customer uses to make purchases. Once this is saved for the customer, you cannot change it.
Timezone	The time zone in which the customer resides. Once this is saved for the customer, you cannot change it.
Locale	Indicates the language that Kaui uses to send communication to the customer (invoices, emails, etc.) If your organization communicates with customers in a language that’s different than the system’s default language, it’s important to select the appropriate locale for the customer. For more information, see the internationalization overview document.
Address line 1 and Address line 2	The street address where the customer resides.
Zip code	The zip code for the area in which the customer resides.
Company	If relevant, the company/organization the customer works for.
City	The city in which the customer resides.
State	The state in which the customer resides.
Country	The country in which the customer resides.
Phone	The customer’s phone number.
Notes	Additional information about the account. These notes are not viewable by the customer.
Migrated?	This field is for informational purposes only. You can check this box if you have migrated this customer account into Kill Bill.
Contact email addresses	Additional addresses to which account-related emails will be sent. The email addresses listed here will receive the same emails as the main Email address. For more information, see Add Additional Contact Emails.

Name

The customer’s first and last name.

First name length

This field sets the length of the customer’s first name. Kill Bill automatically calculates this number based on the location of the space between the first and last name. You can overwrite it with a different number, if necessary.

Note: This field is used if your organization needs to extract customers' first or last names for communication (invoices, emails, etc.). The field lets an organization accommodate variations of names used across the globe.

External key

An optional alternate ID for the account. Once this is saved for the customer, you cannot change it.

Tip: The external key feature is helpful if you integrate Kill Bill with another system, such as a CRM, and want to use that system’s ID in Kill Bill (for identification, searching, and so forth). Once this is set and saved for the customer, you cannot change it.

The main email address to use for communicating with the customer.

Bill cycle day (BCD)

For monthly or quarterly subscriptions, what day of the month the invoice is created. Once this is saved for the customer, you cannot change it.

Note: The system has three types of billing (date) alignment that affect the BCD: ACCOUNT, SUBSCRIPTION, and BUNDLE. For more information about the three billing alignment types, see Catalog Examples and "Billing Alignment Rules" in the Subscription Guide.

Currency

The currency that the customer uses to make purchases. Once this is saved for the customer, you cannot change it.

Timezone

The time zone in which the customer resides. Once this is saved for the customer, you cannot change it.

Locale

Indicates the language that Kaui uses to send communication to the customer (invoices, emails, etc.) If your organization communicates with customers in a language that’s different than the system’s default language, it’s important to select the appropriate locale for the customer. For more information, see the internationalization overview document.

Address line 1 and Address line 2

The street address where the customer resides.

Zip code

The zip code for the area in which the customer resides.

Company

If relevant, the company/organization the customer works for.

City

The city in which the customer resides.

State

The state in which the customer resides.

Country

The country in which the customer resides.

Phone

The customer’s phone number.

Notes

Additional information about the account. These notes are not viewable by the customer.

Migrated?

This field is for informational purposes only. You can check this box if you have migrated this customer account into Kill Bill.

Contact email addresses

Additional addresses to which account-related emails will be sent. The email addresses listed here will receive the same emails as the main Email address. For more information, see Add Additional Contact Emails.

Edit an Account

You can make changes to most of the account fields after it has been created.

Note: You cannot change the following fields: Bill Cycle Day, Currency, External Key, and Time Zone.

Open the account on the Account page.
Next to Account Information, click Edit.

Kaui opens the Update Account screen:
Make changes to the fields. For field descriptions, see Account Field Descriptions.
Click the Save button.

Export Account Data

You can export the data for an account. This creates a text file with the data from all the KB tables for the particular account. Such a text file can then be sent to the KB team for debugging purpose.

Open the account on the Account page.
Next to Account Information, click Export.:
Kaui creates a text file with the account data.

Add Additional Contact Emails

If a customer wants to receive email at more than one email address (which is the one defined in the Email field for the account), you can add more email addresses.

Open the account on the Account page.
In the Personal Information section, click the gray down arrow to expand the section.
Click the plus sign next to Contact emails.

Kaui opens the Add New Email screen:
Type in a single email address.
Select the Save button. Kaui returns to the Account page.
To see the email address you added, expand the Personal Information section:
To add another email address, repeat steps 2 - 5.

Delete Additional Contact Emails

Warning: Kaui does not ask you to confirm your deletion; use this feature with caution.

To remove additional contact emails:

Open the account on the Account page.
In the Personal Information section, click the gray down arrow to expand the section.
Next to the email you want to delete, click the red X. Kaui immediately deletes the email address.

Close an Account

Use the steps in this section to indicate you will no longer be doing business with a customer. If the customer has unpaid invoices, using the steps below, you can choose to either write off or item-adjust them.

Note: Closing an account does not delete it. It only indicates the account is no longer a customer of yours. Once you close the account, its data becomes read-only, and you cannot make changes to it.

Open the account on the Account page.
Next to Account Information, click Close.

Kaui displays the Close Account pop-up:
Check the Name and Account ID fields to ensure you are closing the correct account.
Toggle any of the following options:
- Cancel All Subscriptions—Stops any subscriptions that are current for this account.
- Write Off Unpaid Invoices—Brings the balance for all unpaid invoices to zero. When you choose to write off the invoice, it is removed from Account Receivables.
- Item Adjust Unpaid Invoices—Adds an invoice line item with a negative amount to bring each unpaid invoice’s balance to zero.
  
  Note: The last two options are mutually exclusive (i.e., you can only select one of them).
Click the Close button.

Kaui displays a message that lets you know the account was closed. In addition, the Account sub-menu displays "Closed:"

Link to Parent Account

When you link an account to a parent account, the account becomes a child account. Defining a parent-child association between accounts lets you define which entity is responsible for paying the invoice. For more information on this feature, see the Hierarchical Accounts Tutorial.

As a preparation step, open the parent account and copy the account ID in the Account Information section.
Open the account that will become the child account.
In the Account Information section of the child account, click the plus sign icon next to the Parent field:

Kaui opens a pop-up:
Click in the Parent account id field and paste in the account ID that you copied in step 1.
To set the parent as responsible for all payments associated with this account, check the Is payment delegated to a parent? box. If you do not check this box, the child account is responsible for its own payments.
Click the Save button. Kaui displays the parent account ID as a link in the Account Information section.

You can open the parent account by clicking the account ID link.

Add Credit to an Account

Issuing a credit in Kaui creates a credit memo. For accounting purposes, the memo is saved with the customer account’s invoices.

On the Account page, click Add Credit at the top of the Billing Info section.

Kaui opens the Add New Credit screen:
Fill in the fields:
- Amount—The amount of the credit.
- Currency—The currency defaults from the customer account and should not need to be changed.
- Reason—The reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.
- Comment—The text you enter here displays on the Timeline page after saving the credit. Adding comments is optional.
Click the Save button. To view the credit, select Invoices on the sub-menu.

On the Account page (in the Billing Info section), Kaui adjusts the account balance and account credit accordingly.

Create a Charge on an Account

Creating a charge in Kaui creates a new invoice. To create a charge:

On the Account page, click Create Charge at the top of the Billing Info section.

Kaui opens the Add New Charge screen:
To set the invoice as a draft instead of immediately committing it, uncheck the Auto-commit box.
Fill in the fields:
- Amount—The amount of the charge.
- Currency—The currency defaults from the customer account and should not need to be changed.
- Description and Comment—What you type here displays on the customer’s invoice. Both fields are optional.
Click Save and Kaui generates an invoice.
If you unchecked the Auto-commit box and have changed your mind, you can click the text Commit at the top of the page.

If you do not commit the invoice, it will stay in Draft mode. You can commit it by opening it from the Invoices page and clicking Commit.

On the Account page (in the Billing Info section), Kaui adjusts the account balance to reflect the amount of the charge.

Payment Methods

Overview

A customer account can have several payment methods to allow for making payments in different ways, such as credit cards, debit cards, PayPal, and so forth. The payment method includes the details needed for Kill Bill to process a payment against an invoice.

Saving this information in Kaui makes it easier to accept payments from the customer because the customer or service staff don’t need to repeatedly provide their payment method details.

In production systems, payment method information is typically added via gateway-specific data flows. However, developers can use the Payment Method section for testing purposes.

Note: Although you can’t edit a payment method, you can delete it.

Warning! For PCI compliance, do not enter any genuine payment information in these fields.

About Payment Plugin Names

Each payment method is associated with a payment plugin, a type of software that performs the backend processing for that specific payment method. The Plugin name field specifies the name of this payment plugin. (Example: killbill-stripe).

The plugin name is typically mentioned in the plugin’s readme file. For example, in the Stripe plugin readme file, the plugin name is specified in the command line.

View Payment Method Details

To view a payment method after it’s created:

Open the account on the Account page.
In the Payment Methods area, click the gray down arrow next to the payment method.

Kaui expands the details for the payment method:

Set a Payment Method as the Default

Kill Bill uses the default payment method to automatically pay invoices (whether that invoice is generated by the system or manually by a user).

To set a payment method as the default:

Open the account on the Account page. In the Payment Methods section, click the star icon next to the relevant payment method:

The filled star indicates it’s now the default payment method.

Add Payment Method

To add a payment method:

Open the account on the Account page.
Next to Payment Methods, click the plus sign:

Kaui displays the Add New Payment Method screen:
Fill in the fields. For field descriptions, see Payment Method Field Descriptions.
Click the Save button.

Payment Method Field Descriptions

Field Description

Field	Description
External key	An optional alternate ID for the payment method. Once this is saved for the customer, you cannot change it.
Plugin name	Type in the name of the plugin that is associated with this type of payment method. Each payment method is associated with a payment plugin that does the backend processing related to the payment method. The Plugin name field specifies the name of the payment plugin associated with the payment method (Example: `killbill-stripe`). The Plugin name is typically mentioned in the plugin’s `readme` file. For example, in the Stripe plugin `readme` file, the plugin name is specified in the command line.
Card type	The name of the credit or debit card.
Card holder name	The name that appears on the card.
Expiration month Expiration year	The month and year the card expires. Enter month as mm and year as yy. (Examples: `07` for the month of July and `23` for the year 2023.)
Credit card number	The credit card number, typed without dashes.
Address 1, Address 2, City, ZIP code, State, Country	The billing address associated with this card.
Add property (Name/Value)	Use the Name/Value fields to assign custom fields and values to the payment method. Note: Custom fields are an advanced feature. For more information, see Custom Fields.
Default payment method?	Check the box to set this payment method as the default. Kill Bill uses the default payment method to automatically pay invoices (whether the invoice is generated by the system or manually by a user). Note: If you forget to select this box, you can set the payment method as the default by clicking the star icon next to the payment method on the Account page:

External key

An optional alternate ID for the payment method. Once this is saved for the customer, you cannot change it.

Plugin name

Type in the name of the plugin that is associated with this type of payment method.

Each payment method is associated with a payment plugin that does the backend processing related to the payment method. The Plugin name field specifies the name of the payment plugin associated with the payment method (Example: killbill-stripe).

The Plugin name is typically mentioned in the plugin’s readme file. For example, in the Stripe plugin readme file, the plugin name is specified in the command line.

Card type

The name of the credit or debit card.

Card holder name

The name that appears on the card.

Expiration month Expiration year

The month and year the card expires. Enter month as mm and year as yy. (Examples: 07 for the month of July and 23 for the year 2023.)

Credit card number

The credit card number, typed without dashes.

Address 1, Address 2, City, ZIP code, State, Country

The billing address associated with this card.

Add property (Name/Value)

Use the Name/Value fields to assign custom fields and values to the payment method.

Note: Custom fields are an advanced feature. For more information, see Custom Fields.

Default payment method?

Check the box to set this payment method as the default. Kill Bill uses the default payment method to automatically pay invoices (whether the invoice is generated by the system or manually by a user).

Note: If you forget to select this box, you can set the payment method as the default by clicking the star icon next to the payment method on the Account page:

Apply a Transaction to a Payment Method

This section explains how to apply a transaction to a payment method. These transactions are directly applied on the payment instrument (as opposed to being applied to the unpaid invoice).

Use this functionality only for transactions unrelated to invoices and/or payments.

Example: After paying her final invoice, a customer cancels her subscription and demands a full refund because she is dissatisfied. In this case, you would process this transaction (the refund) against the payment method as explained in this section.

You can perform the following transactions from the Payment Methods section:

Authorize
Capture
Credit (see note)

Purchase (i.e., charge)
Refund
Void

Note: "Credit" here refers to depositing funds directly to the customer card and is unrelated to account credits.

Open the account on the Account page.
In the Payment Methods area, click the gray down arrow next to the payment method.
Select the type of transaction you want to perform:

Note: This area lists Authorize, Purchase, and Credit. For other transaction types, click any of these options. You will be able to change the transaction type on the next screen.

Kaui displays the Process Transaction screen:
Fill in the fields. For field descriptions, see Process Transaction Field Descriptions.
Click the Save button. Kaui saves the transaction and displays it on the Payments page.

Process Transaction Field Descriptions

Field Description

Field	Description
Transaction type	From the dropdown list, select the type of transaction you want to perform.
Amount	The amount of the transaction.
Currency	The currency to use for the transaction. This field defaults from the customer account.
Payment key	The unique payment key (ID) to which you want to apply the transaction. This field is required for transaction types that are applied to a specific payment (Capture, Chargeback, Refund, Void). Note: You can copy the payment key for a specific transaction from the External Key column of the Payments page. Or you can copy it from the URL displayed on your browser’s address line: Example: URL: `https://demo.killbill.io/accounts/cb736a4f-9b56-4074-ae07-1d37b37cb69f/payments/0d1e11e5-2df6-4b6b-992f-e9ff2de38cef` Payment key: `0d1e11e5-2df6-4b6b-992f-e9ff2de38cef`
Transaction key	Kill Bill automatically generates an external transaction key for Authorize, Purchase, and Credit transactions. To process a transaction that requires the transaction key, open the payment detail from the Payments screen and copy the key from the Transaction External Key column. image::../assets/img/kaui/TransactionKey-Labeled.png[width=350,align="center"]
Reason	The reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.
Comment	The text you enter here displays on the Timeline page after the transaction is complete. Adding comments is optional.
Add control plugin	For information on control plugins, see Plugin Manager.
Add property (Name/Value)	Use this area to assign custom fields and values to the transaction. For information on custom fields, see Custom Fields.

Transaction type

From the dropdown list, select the type of transaction you want to perform.

Amount

The amount of the transaction.

Currency

The currency to use for the transaction. This field defaults from the customer account.

Payment key

The unique payment key (ID) to which you want to apply the transaction. This field is required for transaction types that are applied to a specific payment (Capture, Chargeback, Refund, Void).

Note: You can copy the payment key for a specific transaction from the External Key column of the Payments page. Or you can copy it from the URL displayed on your browser’s address line:

Example:

URL: https://demo.killbill.io/accounts/cb736a4f-9b56-4074-ae07-1d37b37cb69f/payments/0d1e11e5-2df6-4b6b-992f-e9ff2de38cef

Payment key: 0d1e11e5-2df6-4b6b-992f-e9ff2de38cef

Transaction key

Kill Bill automatically generates an external transaction key for Authorize, Purchase, and Credit transactions. To process a transaction that requires the transaction key, open the payment detail from the Payments screen and copy the key from the Transaction External Key column.

image::../assets/img/kaui/TransactionKey-Labeled.png[width=350,align="center"]

Reason

The reason is automatically selected based on Kaui configuration settings. However, you can make a different selection.

Comment

The text you enter here displays on the Timeline page after the transaction is complete. Adding comments is optional.

Add control plugin

For information on control plugins, see Plugin Manager.

Add property (Name/Value)

Use this area to assign custom fields and values to the transaction. For information on custom fields, see Custom Fields.

Delete Payment Method

Warning: Kaui does not ask you to confirm your deletion; use this feature with caution.

To delete a payment method:

Open the account on the Account page.
In the Payment Methods area, click the red X next to the payment method. Kaui immediately removes the payment method.

Subscriptions

Overview

This section helps you get familiar with the Subscriptions area of Kill Bill.

For more information on subscriptions, see the Subscription Guide.

Open Subscriptions Page

To view the subscriptions for an account, open the account and click Subscriptions on the sub-menu. This area of Kaui lists the subscriptions associated with an account.

On the Subscriptions page, you can:

Add a subscription
Add an add-on product to a subscription
Pause and resume a subscription
Change a subscription’s plan and amount
Cancel a subscription
Update the billing cycle day (BCD) for the subscription

Add a Subscription

Note: To create a subscription, you must have at least one product and one plan defined in the catalog.

On the Subscriptions page, click the plus sign to the right of Subscription Bundles:

Kaui displays the Add New Subscription screen:
Fill in the fields. For field information, see Add Subscription Field Descriptions.
Click the Save button.

Add Subscription Field Descriptions

Field	Description
Bundle Key	If you leave this field blank, Kill Bill generates a unique bundle key. If necessary, you can enter a different bundle key.
Subscription Key	If you leave this field blank, Kill Bill generates a unique subscription key. If necessary, you can enter a different subscription key.
Plan	Select the plan from the dropdown list. These options come from the plans defined in the catalog.
Price Override	If you need to override the price for the plan you’ve selected, enter an amount in this field.
Immediate Creation	Select this option to start the subscription immediately.
Specify a date	To define a specific date on which the subscription begins, select this option, and choose a date from the Date field that appears.

Field

Description

Bundle Key

If you leave this field blank, Kill Bill generates a unique bundle key. If necessary, you can enter a different bundle key.

Subscription Key

If you leave this field blank, Kill Bill generates a unique subscription key. If necessary, you can enter a different subscription key.

Plan

Select the plan from the dropdown list. These options come from the plans defined in the catalog.

Price Override

If you need to override the price for the plan you’ve selected, enter an amount in this field.

Immediate Creation

Select this option to start the subscription immediately.

Specify a date

To define a specific date on which the subscription begins, select this option, and choose a date from the Date field that appears.

Add an Add-On Product to a Subscription

This section explains how to add an add-on product to a customer’s subscription.

Note: To add an add-on to a subscription, the add-on must exist in the catalog and be available in the base plan.

Open the account and click Subscriptions on the sub-menu.
Hover over the gift icon and click Add add-on:

Kaui opens the Add New Add-On screen:
Fill in the fields. For field information, see Add New Add-On Field Descriptions.

Add New Add-On Field Descriptions

Field	Description
Subscription Key	Note that this subscription key applies to the add-on, not the original subscription. If you leave this field blank, Kill Bill generates a unique subscription key. If necessary, you can enter a different subscription key.
Plan	Select the add-on to add to the subscription.
Price Override	If you need to override the price for the add-on you’ve selected, enter an amount in this field.
Immediate Creation	Select this option to start the subscription immediately.
Specify a date	To define a specific date on which the subscription begins, select this option, and choose a date from the Date field that appears.

Field

Description

Subscription Key

Note that this subscription key applies to the add-on, not the original subscription. If you leave this field blank, Kill Bill generates a unique subscription key. If necessary, you can enter a different subscription key.

Plan

Select the add-on to add to the subscription.

Price Override

If you need to override the price for the add-on you’ve selected, enter an amount in this field.

Immediate Creation

Select this option to start the subscription immediately.

Specify a date

To define a specific date on which the subscription begins, select this option, and choose a date from the Date field that appears.

Pause/Resume Subscriptions

Pausing and resuming happens at the subscription bundle level. In other words, pause/resume affects all subscriptions and add-ons in the customer’s account.

Note: While a customer’s subscription bundle is paused, you cannot add any new subscriptions or add-ons to the account.

You can use the pause/resume feature to:

Stop a subscription bundle indefinitely
Reactivate a paused subscription bundle
Set a specific time period during which the bundle is paused and then automatically resumed

To pause or resume a subscription bundle, perform the following steps:

Open the account and click Subscriptions on the sub-menu.
Hover over the gift icon and click Pause / Resume:

Kaui opens the Pause/Resume screen:
Fill in the following fields:
- Pause date—The calendar date on which to temporarily stop the subscription bundle. To resume a paused subscription, leave this field blank.
- Resume date—The calendar date on which to remove the pause from the subscription(s). To set a pause to continue indefinitely, leave this field blank.
- Comment—The text you enter here displays on the Timeline page after saving the pause/resume. Adding comments is optional.
Click the Pause / Resume button. Kaui displays a success message at the top of the screen.

Change a Subscription

In Kaui, you can change a customer’s subscription from one plan to another plan. You can also define a different price than what is set in the catalog and when the change takes effect.

To change an account’s subscription:

Open the account and click Subscriptions on the sub-menu.
In the Actions column (far right), click Change.

Kaui opens the Change Subscription screen:
In the New plan field, select a different plan.
If you need to override the price for the plan you’ve selected, enter the amount in the Price Override field.
To accept the system’s default policy for changing subscriptions (END_OF_TERM), leave Default policy selected and click Save.

OR

You can select one of two other options: Specify Policy or Specify a date. This will override the policy defined in the catalog for the plan. For information on this topic, see "Plan Change Timing" in the Subscription Guide.
- Specify Policy: You can select either IMMEDIATE or END_OF_TERM. For information on these two policies, see "Subscription Alignment Rules" in the Subscription Guide.
- Specify a date: Click on this and choose a date from the Change Date calendar that appears. Make sure to choose an effective date that is in the future.

Cancel a Subscription

To cancel an account’s subscription:

Open the account and click Subscriptions on the sub-menu.
In the Actions column (far right), click Cancel.

Kaui displays several options. The option you select defines how Kill Bill handles billing for the canceled subscription:

Cancellation Options

Option	Description
Cancel (default policy)	Uses the default policy specified for the plan in the catalog.
Cancel start of term (full credit)	Cancels the subscription immediately and refunds whatever amounts have been paid toward the subscription.
Cancel immediately (partial credit)	Cancels the subscription immediately and applies a partial credit to the account based on how much of the service has been consumed.
Cancel end of term (no credit)	Cancels the subscription at the end of the billing period with no refund to the customer. Note that after using this option to cancel, you can still reinstate the customer (i.e., reverse the cancellation).
Cancel a subscription given a date	If you select this option, Kaui displays a pop-up from which to choose a date: Use requested date for billing: To set the entitlement date and billing date the same as the date you just selected, check this box. Otherwise, if you leave the checkbox empty, the entitlement date is the same as you just selected BUT the billing date defaults to immediate.

Option

Description

Cancel (default policy)

Uses the default policy specified for the plan in the catalog.

Cancel start of term (full credit)

Cancels the subscription immediately and refunds whatever amounts have been paid toward the subscription.

Cancel immediately (partial credit)

Cancels the subscription immediately and applies a partial credit to the account based on how much of the service has been consumed.

Cancel end of term (no credit)

Cancels the subscription at the end of the billing period with no refund to the customer. Note that after using this option to cancel, you can still reinstate the customer (i.e., reverse the cancellation).

Cancel a subscription given a date

If you select this option, Kaui displays a pop-up from which to choose a date:

Use requested date for billing: To set the entitlement date and billing date the same as the date you just selected, check this box.

Otherwise, if you leave the checkbox empty, the entitlement date is the same as you just selected BUT the billing date defaults to immediate.

Update the Billing Cycle Day

Follow the steps below to update the billing cycle day (BCD) defined for a subscription. These steps assume the subscription is billed on a monthly basis.

If you update the BCD with these steps, the new BCD overrides what is specified in the billing alignment rules in the catalog.

Note: These steps do not change the account billing cycle day specified in the "Billing Info" section on the Account page.

Open the account and click Subscriptions on the sub-menu.
In the Actions column (far right), click Update BCD.

Kaui opens the Update Subscription BCD screen:
In the Billing Cycle Day field, Kaui displays the currently defined BCD. Enter the number for the day of the month on which to bill.
For this change to be effective immediately, leave the Effective Date field at its current setting. Otherwise, you can define a later date for this change to occur.

Note: If Effective Date is the same as today’s date, you will not see this change take place immediately.
Click the Save button. On the Account page, the Next Invoice Date is adjusted to reflect the new BCD.

Invoices

This section helps you become familiar with the Invoices and Invoice Details pages.

For more information on invoices, see the "Invoicing" section of the Subscription Guide.

Invoices Page

The Invoices page lists the invoices for the currently selected account. To open the Invoices page, open the account and select Invoices on the sub-menu.