Subscription Billing Overview

Purpose

This service is responsible for tracking merchant, customer, payment, plan and subscription information to initiate charges at regular intervals. This allows merchants to setup payment planes for purchased equipment, service plans for long term customers or just about any situation where customers are routinely charged the same amount over an extended period of time.

Common usage

Once a merchant has been boarded into the system they will be able to access RBS with their MerchantProfileId and ServiceKey.  See Managing Merchant Profiles for help boarding a merchant.  The merchant will be required to submit a Session Token and their MerchantProfileId for each call to RBS.

Normally this system will be used to charge a customer a fixed amount on a monthly basis. The reason behind the charge can vary wildly, as long as it's 'always' the same amount. The merchant can configure just about everything to do with processing the transaction when the subscription is created. Most of it can be adjusted at a later date if needed.

The system has the concept of "Addons" and "Discounts" as well. These are additional charges or credits applied to the subscription during billing. They can be configured to run for a certain amount of time or single use. They will be accounted for in the total amount charged to the customers account when billing occurs.

For the example below we'll use a Gym membership program to describe how the system should be setup and configured.

D's Gym offers two access plans, "Regular Joe" and "Busy Brian". The Regular Joe plan is $50/month and Busy Brian is $100/month. (Brian gets extended hours and the VIP equipment including the Thigh Master and Shake Weights) They also offer a discount on your plan if you refer a friend of $10/month for 3 months. You can also get the Hydration Highway which is $20/month but you get unlimited drinks from the cooler (normally $1.5 ea). The Busy Brian comes with Hydration Highway by default because aint nobody got time for buying drinks, the customer can opt out if they want.

This merchant would setup 1 Addon and 1 Discount as below.

Name Friendly Discount
Description $10 for Friend Referral
Amount 10
Number of Cycles 3
Modified By D
Identifier BDPlan

 

Name Hydration Highway
Description Unlimited Drinks
Amount 20
NeverExpires true
Modified By D
Identifier HHFreeDrinks

This merchant would setup 2 plans in the system as described blow.

Name Regular Joe
Description Basic membership
Day of month to bill 5
Price

50

Failure Option Retry
Modified By D
Never Expires true
Identifier RJPlan

 

Name Busy Brian
Description Vip membership
Day of month to bill 5
Price

100

Failure Option Retry
Modified By D
Addons HHFreeDrinks
Never Expires true
Identifier BBPlan

The merchant is now all set and ready to add their first subscription and customer!!

First you have to create the customer and the payment method. Both of these are very straight forward, look at the data objects below.

Now that you have a customer you can create the subscription. When creating a subscription you can either use all the default data from the plan, or override individual fields as you see fit. Below we'll use the minimum required.

Plan Identifier BBPlan
Payment Method Identifier FrysPayment
Identifier FrysSub

This will create a new subscription for Fry on the Busy Brian plan which includs the Hydration Highway addon. Normal billing will occur monthly on the 5th regardless of the day of week or holidays.

Important Things

Identifier

Most of the data objects will have an Identifier associated with them. This is a merchant assignable reference value. If the merchant does not assign an Identifier when creating an item that accepts an Identifier one will be assigned to it (a GUID). Identifiers can be modified by the Update interfaces for the associated object. These interfaces will accept 2 Identifiers, one in the update object being passed in and one as a parameter. The parameter is for the current Identifier and identifies which item in the DB is to be updated with the information in the passed object.

First Payment / StartDate / Trial Periods

When a new subscription is created many calculations take place to fill in all the data. If there is a trial period specified, it starts immediately, under no circumstances will a trial start on a future date. When there is a trial period the service start date will be the day after the trial period ends.

If there is no trial the service start date will be today, unless otherwise specified.

On the service start date the subscription will be billed for the partial amount covering from the start date to first regular billing period date.  If the start date is the first billing date, normal billing will occur.

If the service start date is today (ie we are making a new sub, and service is starting immediately) the subscription amount (possibly partial) will be charged immediately. If this immediate charge fails, the subscription will not be created.

Regardless of the service start date, regular billing will occur on the day of the month specified by BillingDayOfMonth.  


Failed Transactions

1st Decline

If the merchant has AutomaticRetries turned on, the sub will be set to be billed again in DaysTillRetry number of days.

If AutomaticRetries is turned off, go straight to failure option logic.

2nd Decline

Nothing special. Retry in DaysTillRetry days

+3rd Decline

Go to failure option logic

Failure Options:

  • Cancel: The subscription should be put into the canceled state, no further billing will take place.
  • Retry: The subscription will continue to be retried every 'DaysTillRetry' days, indefinitely, until end of contract. Additional cycles will be added to the billing amount as appropriate. 
  • PastDue: Leave the state as past due, retry only on normal billing dates. Additional cycles will be added to the billing amount as appropriate.

Note: While in the PastDue state the only change that a merchant can make to a subscription is to change the PaymentMethodId.


Manual Payment

If the merchant wants to kick a subscription out of PastDue without waiting for a billing to succeed they can use the ManualPayment method. This will bill the subscription immediately for a specified amount. If the transaction succeeds the subscription will be brought to the current state regardless of the amount specified. If the transaction fails, no action is taken. A charge of $0 approves immediately without processing any payment.

Integration

There are exposed data objects representing all of the data concepts required. The bulk of the interface for this projects consists of Create, Updated, and Get methods for these data objects. I will not cover these individually. They all pretty much operate the same way. All methods return a response object, the type of these response objects will be dependent on what your doing.

All response objects are descendants of the common "Response" objects, this object has 2 properties, ResultCode (enum) and ResultMessage. The various child objects will have additional fields populated according do what your doing (ie "GetCustomerResponse" will also have a Customer property). The result code should be validated as "OK" before checking the additional fields. I will not cover all the Response objects as they are pretty much self explanatory.

Note: When getting a list of objects, if no objects are found and there are no errors, "OK" with an empty list will be returned. If you getting a specific object and it's not found "Error" will be returned.


Data Objects

Most of the properties of these objects are self explanatory and therefore not listed here. Objects with an "ID" support Identifier referencing.

AchAccount: Contains data identifying an ACH account.

AddressInfo: Data pertaining to an Address, address are associated with a form of payment, not a customer. They can't be accessed directly, address information is returned in conjunction with payment account information.

Addon: ID - Describes an additional fee for a subscription.

BillingPlan: ID - Describes the default settings to use when a new subscription is created.

CreditCard: Contains data identifying a Credit Card account.

Customer: ID - Basic information about a customer.

Discount: ID - Describes a credit for a subscription.

Merchant: Internal use only, contains all the merchant data.

PaymentMethod: ID - Represents the association between a payment account (ie CreditCard) and a customer. A given customer can have multiple payments and multiple subscriptions.

Subscription: ID - All the data about a subscription.

BillingCycle: Contains all the billing details of a Subscription.

Transaction: Contains a lot of data from all the other objects, essentially a snapshot of the subscription before billing occurs along with the processing results. If there is a question about a transaction or there is an error associated with it we can see what led up to the issue.


Info Objects

Some objects have a corresponding "Info" version (ie SubscriptionInfo"), these are used during update and create commands. They assist in distinguishing between properties that you can and can't modify. For instance, Subscription has a Status that can't be directly manipulated, so SubscriptionInfo does not have this field. Another example is when dealing with customer account information: "AchAccount" only displays the token for the ach account while "AchAccountInfo" is used to create a new account in the system and accepts a full account number.

 

Updated: 11/30/16 ~DS

Comments