From UniCharge Integration Library
Jump to: navigation, search

How does the library work?

The library is a group of classes that are structured around the interchange XML defined by the iBilling processing service. The library automatically handles marshalling (objects to xml) and unmarshalling (xml to objects) processes and provides logic to resolve all internal xml references (once XML is unmarshalled, all id references in XML are replaced with actual objects (or proxy objects) in the object tree). The library also has some additional logic for the handling of dates and charges within payment plans.

What is a proxy object?

A proxy object is an instance of a business entity (e.g. CustomerAccount, PaymentOption) that has only its ID. Usually, when find/query is performed on a specific object (PaymentOption for example), all object references from PaymentOption to object business entities (e.g. CustomerAccount) will return as proxies. Using proxies enables the system not to send unnecessary data back and forth (when a list of payment options is loaded, customer account info is not needed in many cases). Any proxy object may be converted into the actual business object using standard find/query procedures (via ID as the lookup field).

What is forecasting period?

The Forecasting Period is a value, in months, for which future billing forecasting is desired. All future payments are represented by Charges in iBilling. Since perpetual and complimentary plans are infinite, a length is needed to pre-create charge objects (which are normally used to forecast future billing amounts). The number of charges that need to be created for any given plan is derived from the forecasting period (in combination with the type of the billing cycle – monthly, weekly, etc). For example, if a forecasting period is 12, a monthly perpetual plan will always have 12 charges, a weekly one 52 and an annual plan only 1.

What is a merchant code?

A merchant code is a value uniquely identifying a merchant. A merchant is a company or gateway that integrates with the iBilling processing engine.

What is merchantAccountCode?

The Merchant account code is a value identifying a processing subset within a larger merchant. Small companies may only use one merchant account code. For a large company, merchant account may represent a facility/department or group of facilities within the company. For companies acting as gateways to process many small individual clients, the merchant account code may represent each small individual client (the gateway itself will have a merchant code).

What is ID and how is it different from code?

ID is a system generated value used internally to track references between objects. ID is read-only. Code is an assignable value that is used by the external client’s system to identify the given object. If code is not specified, its value is defaulted to ID. The code may only be specified at the moment of an object’s creation and cannot be changed. The code must be unique within the scope of a merchant.

Why does complimentary plan need an amount?

For accounting/tax purposes, complimentary plans must carry a value. Value is also created by knowing the amount "given away." Although zero amount is not advisable, 0 is a valid value. No payments are ever collected for complimentary plans or invoices. They are usually balanced out with Allowance transactions.

Why are all amounts specified in cents?

Some languages (such as Java) use a complex storage mechanism for floating point numbers which results in round-off issues in cases of basic mathematical operations. To avoid any of such issues, all values are specified in cents. A conversion can be done by dividing any value by 100.

What is a proper format for the billing cycle’s code?

When creating a billing cycle code in the portal, make sure that the first character of the code is the first letter of the billing cycle type (W-Weekly, B-Biweekly, etc) and the following two characters are the date when the cycle is to be processed (for weekly 1-Monday, 7-Sunday; for biweekly just like weekly, plus 8 – second Monday and 15 – second Sunday; for all other types use two symbol digit to specify day of the month).

Should I use constructors in classes directly?

Languages like PHP or Ruby that do not support package/namespace level visibility, some of the system reserved methods become accessible. This primarily applies to all constructor functions/method. Do not call constructors directly (e.g. $account = new CustomerAccount() or account = CustomerAccount.new), use createXXX functions/methods instead (e.g. $account = $session.createCustomerAccount())

What is a linked plan?

Each Charge (future payment) within a payment plan in iBilling always carries the same value (has the same amount). Thus, to represent a plan with 12 payments of $10 each, we could create a single plan with 12 charges. However, there are cases when we want to have a different amount on several of the payments. For example, we may want 6 payments of $10, followed by 6 payments of $15). In such cases, we would create 2 plans linked to each other: first - 6 x $10 and second - 6 x $15. The second plan would be the linked plan and would become active only after the first is fully processed and cancelled. Any changes to the first plan (cancellations/freezes) will automatically be reflected in the second plan. iBilling allows an unlimited level of linking.

What are deferred value and deferred length?

There is a need to distinguish two plans that have the same length and the same amount, but begin on different days. Let’s assume we have 2, 12 x $10 plans ($120 value each). The first one begins on Jan 1st and the second one begins on Feb 1st, but both are already created. To distinguish between these plans iBilling uses a notion of deferred value. The second plan will have deferred length of 1 and deferred value of $10 ( 1 x $10 ), indicating that although the second plan will be processed on the next billing, the first invoice for this plan will only be issued after the deferred value is equal to 0. Each time billing is processed, the deferred length is reduced by 1 and the deferred value is reduced by the monthly amount of the plan.

In the case of a processing error, how do I get a message indicating the error’s cause?

In case of validation or processing error, a language standard Exception will be generated. The message of the exception will explain the cause of the error and will contain response code in the case of credit card declines. Use standard exception handling mechanism (e.g. try/catch or rescue) to catch the exception and extract the message from it.

Is the value of Amount an integer field?

Yes. The amount needs to be sent as integer in the integration with ibilling. i.e The amount is specified in cents. If a Payment Plan is setup for $10. The amount would be sent as 1000. This holds good for all amounts specified in payments, paymentplans and invoices.

What is Accessory field in PaymentOption and AssetTransaction?

The accessory field is used to store both credit card expiration date and bank account's routing number. When sending a payment/creating payment option using credit card, this field should be assigned the value of the card’s expiration date in MMYY format. When sending a payment/creating payment option using bank account information, this field should be assigned the value of account’s routing number for EFT up to 10 chars.

How can I change billing dates after payment plans has been created?

Assume we have two monthly cycles – M03 and M15

Assume we have a single fixed term payment plan for 2 months with next billing date on July 3rd.

Assume today is June 1st, thus our plan looks like this:

June 3rd July 3rd August 3rd Sept 3rd
deferred fixed (billing) fixed (billing)

If we want the plan to bill on june 3rd, instead of july, we need to cancel the 0th charge. Thus:

June 3rd July 3rd August 3rd Sept 3rd
fixed (billing) fixed (billing)

If we want the plan to bill on august 3rd, instead of july, we need to add a freeze in position 1. Thus:

June 3rd July 3rd August 3rd Sept 3rd
deferred freeze fixed (billing) fixed (billing)

If we want to move it to august 3rd, we would add 2 freezes, etc. If we want to change the date to 15th, we would need to change the billing cycle code in the plan. No other changes to dates are possible. The same concept is applicable to expiration date.

Personal tools

Integration Info
Library Documentation