inTandem platform uses apps to extend its capabilities and offer integration options with other systems. For a deeper overview on apps click here.

A billing app is a specialized application designed to seamlessly integrate inTandem platform with your billing system. This integration ensures a smooth financial transaction process, enhancing the overall user experience. Below, we outline the primary responsibilities of a billing app and provide a glossary of key terms to help you navigate this essential component of your product infrastructure.

Glossary

• Product - a software functionality scope for end users. For example - Core CRM Modules, QuickBooks app, 250 SMS monthly quota.
• Purchasable - a commercial agreement between inTandem and a partner to sell a product, a subset of a product or a bundle of products for a certain price.
  For example: Premium subscription, Quickbook app.
• Subscription - a record describing a product purchased by a specific user and its commercial: create date, product id, price, related purchasable, commercial terms (price, expiration date, auto renewal etc.).

Key functionalities

Presenting the Checkout Form

The billing app is responsible for presenting a checkout form to users. This form facilitates:

• Retrieving the Business's payment method details: ensures that payment information is collected and stored accurately when needed.
• Obtaining user confirmation: secures the user’s consent for the purchase, ensuring transparency and compliance.

Managing Subscription Actions

The app handles user actions related to subscriptions, including:

• Creating Subscriptions: Facilitates new subscription sign-ups.
• Cancelling Subscriptions: Manages subscription termination processes.
• Changing Plans: Allows users to upgrade, downgrade, or modify their subscription plans as needed.

Handling Billing System Events

The billing app manages various events originating from the billing system, such as:

• Dunning: Addresses payment failures and retries.
• Subscription updates: Automatically updates subscription details within the product based on billing system notifications.

Implementation

Customized billing app is dedicated to a specific partner and should be handled by that partner only.

App creation

To manage the partner's businesses billing, the partner needs to create the app first (more on how to create an app here).

An example of Create App API call:

curl --location 'https://api.vcita.biz/platform/v1/apps' \
--header 'Authorization: Bearer {directory token}' \
--header 'Content-Type: application/json' \
--data '{
    "app_code_name": "samplebillingapp",
    "name": "Sample billing app",
    "redirect_uri": "https://samplebillingapp.mydirectory.com/",
    "trusted": true,
    "openid": true,
    "app_type":"billing_app"
}'

📘

The app needs to be set as trusted so it will work seamlessly for the users.

📘

The app_type is billing_app to indicate this app uses the billing integration point.

Assign the app to all businesses

App assignment means allowing businesses to access the app. Using the directory token, partners can assign apps to their businesses.

The billing app should not appear in the app market, and businesses should not be able to uninstall it, which means the partner needs to assign it as internal on the directory level.

An example of App Assignment API call:

curl --location 'https://api.vcita.biz/platform/v1/apps/{app code name}/assign' \
--header 'Authorization: Bearer {Directory API token}' \
--header 'Content-Type: application/json' \
--data '{
    "directory_uid": "{Directory uid}",
    "internal": true
}'

1. implement an application with a trusted authentication >> refer to create an application - make a sample application.
2. set vcita to work with your billing app (internal) - not available yet
3. in the application handle:
   1. receive sku (plan, current_plan)
   2. get business_uid from token
   3. receive cancelURL(cu), success URL(su)
4. First Purchase - Handle purchase 2 flows:
   1. has credit card details
   2. first time purchase
5. Handle change plan, cancel subscription and dunning >> Refer to manage subscriptions for documentation + Refer to the correct API calls (Create, Update, Delete)
6. Update subscription - API
7. Return to the success URL when payment is made

Authentication

Billing flows are sensitive by nature. They impact the user's expenses, experience in the product, and involve sensitive user's data. The application should use OAuth authentication flow to authorize the user and get a business token for calling different APIs in the user's context. More about the authentication flow here.

Purchase flows

inTandem provides users with the ability to make in-product purchases seamlessly. This guide outlines the steps involved in the following purchase flows which the billing app handles.

1. Purchase new subscription
2. Cancel subscription
3. Change plans
4. Dunning