Billing APIs

Introduction
Billing API is a RESTful API that allows setting up customers, collecting payments and maintaining balances for these customers, as well as creating recurring billing subscriptions.

Billing API documentation includes the following sections:

Objects - lists all recurring billing objects. The purpose of this section is to describe all object fields, their format and usage, provide the links to the corresponding database tables.

Type Enumerations – lists possible values that can be used in the respective fields within Billing API requests and responses. The purpose of this section is to provide an explanation of all enumerations used for API calls.

Actions - lists all actions that can be performed with key recurring billing objects. The purpose of this section is to describe the methods and format of API requests and the format of responses.

Integration Notes – lists integration notes associated with the Billing API objects and actions. The purpose of this section is to provide explicit information about the peculiarities of specific actions and object fields.

Code samples - provides examples of recurring billing use cases (creating billing plans, subscriptions, freeing or canceling subscriptions, reversing transactions, etc) and their implementation in JSON, XML, XURL formats. The purpose of this section is to provide examples that can be used for testing of the integration with the gateway.

To learn how to work with the Billing API, we recommend reviewing the integration notes first. Key recurring billing module terms are available here.
For more detailed information about the recurring billing configurations and management, check the Recurring Billing Guide.


Subscription

Type:  
Abstract:  no
Status:  Active
Java Class:  Subscription
Information about the subscription transaction.
id
References: Payment Plan.Id
XML Representation: attribute
Attributes:
Default Value
Identifier of the object used for references; auto-incremented integer value.
code
References: Payment Plan.Reference Code
XML Representation: attribute
Attributes:
Default Value
See Reference Code definition for additional information.
accountId
References: Payment Plan.Merchant Account Code
XML Representation: attribute
Attributes:
Default Value
Code of Merchant Account to which instance of this object is attributed to.
Depending on the context, Merchant Account Code field may contain either Merchant Code or Merchant Account Code.
The field is primarily used for data partitioning and data management, to make it easy to determine the ownership of a record within the database.
amount
References: Payment Plan.Amount
XML Representation: attribute
Attributes: CreateOnly
Default Value
The amount of money charged every time billing occurs for this payment plan (e.g. amount of the transaction). Value must be submitted in cents without a decimal point.
createDate
References: Payment Plan.Create Date
XML Representation: attribute
Attributes:
Default Value
Date when the record was created.

In API request, the date must be submitted in yyyy-MM-dd format.
In API response, the date is returned in yyyy-MM-dd HH:mm:ss format.
customerId
References: Payment Plan.Customer Account FK
XML Representation: attribute
Attributes:
Default Value
Reference to the entity that represents code of the customer account to which instance of this object is attributed to.
firstBillingDate
Type: Datetime
XML Representation: attribute
Attributes: Required
Default Value
lastBillingDate
References: Payment Plan.Last Invoicing Date
XML Representation: attribute
Attributes:
Default Value
Date when the last invoice was created.

In API request, the date must be submitted in yyyy-MM-dd format.
In API response, the date is returned in yyyy-MM-dd HH:mm:ss format.
lastUpdateDate
References: Payment Plan.Last Update Date
XML Representation: attribute
Attributes:
Default Value
Date when the payment plan was updated for the last time.

In API request, the date must be submitted in yyyy-MM-dd format.
In API response, the date is returned in yyyy-MM-dd HH:mm:ss format.
length
References: Payment Plan.Length
XML Representation: attribute
Attributes: CreateOnly
Default Value
Time period when the payment plan is active.

Length parameter is required for Fixed Subscriptions and cannot exceed 3 years.
For subscriptions longer than 3 years, use Perpetual Subscription type, which does not require length parameter.
Length maximum value correlated with the selected billingCycleType:
  • annually - 3,
  • semi-annually - 6,
  • quarterly - 12,
  • monthly - 36,
  • weekly - 153.
nextBillingDate
Type: Datetime
XML Representation: attribute
Attributes:
Default Value
The date must be submitted in yyyy-MM-dd format.
note
References: Payment Plan.Note
XML Representation: attribute
Attributes:
Default Value
Any additional notes related to the payment plan within the system.
paymentOptionId
Type: Long
XML Representation: attribute
Attributes:
Default Value
planId
Type: Long
XML Representation: attribute
Attributes:
Default Value
Identifier of the associated payment plan.
planName
Type: String
XML Representation: attribute
Attributes:
Default Value
Name of the associated payment plan.
status
References: Payment Plan.Status CL
XML Representation: attribute
Attributes:
Default Value
Represents current (or selected) status of the payment plan.

type
References: Payment Plan.Payment Plan CL
XML Representation: attribute
Attributes: CreateOnly
Default Value
Enumeration of possible types of payment plans.
billingCycleType
Type: String
XML Representation: attribute
Attributes:
Default Value
Type of the applied billing cycle.
pendingAdjustmentType
References: Payment Plan.Pending Adjustment Cl
XML Representation: attribute
Attributes:
Default Value
Type of the pending payment plan adjustment.
pendingAdjustmentEffectiveDate
Type: Datetime
XML Representation: attribute
Attributes:
Default Value
Effective date of the pending payment plan adjustment. The date must be submitted in yyyy-MM-dd format.
pendingAdjustmentNote
References: Payment Plan.Pending Adjustment Note
XML Representation: attribute
Attributes:
Default Value
Note associated with the pending payment plan adjustment.
pendingAdjustmentLength
References: Payment Plan.Pending Adjustment Length
XML Representation: attribute
Attributes:
Default Value
Length of the pending payment plan adjustment.

XML Sample:

<subscription
    id="" 
    code="" 
    accountId="" 
    amount="" 
    createDate="" 
    customerId="" 
    firstBillingDate="" 
    lastBillingDate="" 
    lastUpdateDate="" 
    length="" 
    nextBillingDate="" 
    note="" 
    paymentOptionId="" 
    planId="" 
    planName="" 
    status="" 
    type="" 
    billingCycleType="" 
    pendingAdjustmentType="" 
    pendingAdjustmentEffectiveDate="" 
    pendingAdjustmentNote="" 
    pendingAdjustmentLength="" />

"<subscription id=\"\" code=\"\" accountId=\"\" amount=\"\" createDate=\"\" customerId=\"\" firstBillingDate=\"\" lastBillingDate=\"\" lastUpdateDate=\"\" length=\"\" nextBillingDate=\"\" note=\"\" paymentOptionId=\"\" planId=\"\" planName=\"\" status=\"\" type=\"\" billingCycleType=\"\" pendingAdjustmentType=\"\" pendingAdjustmentEffectiveDate=\"\" pendingAdjustmentNote=\"\" pendingAdjustmentLength=\"\" />"

JSON Sample:

{
  "id": "",
  "code": "",
  "accountId": "",
  "amount": "",
  "createDate": "",
  "customerId": "",
  "firstBillingDate": "",
  "lastBillingDate": "",
  "lastUpdateDate": "",
  "length": "",
  "nextBillingDate": "",
  "note": "",
  "paymentOptionId": "",
  "planId": "",
  "planName": "",
  "status": "",
  "type": "",
  "billingCycleType": "",
  "pendingAdjustmentType": "",
  "pendingAdjustmentEffectiveDate": "",
  "pendingAdjustmentNote": "",
  "pendingAdjustmentLength": ""
}

Query String Sample:

?id=&code=&accountId=&amount=&createDate=&customerId=&firstBillingDate=&lastBillingDate=&lastUpdateDate=&length=&nextBillingDate=&note=&paymentOptionId=&planId=&planName=&status=&type=&billingCycleType=&pendingAdjustmentType=&pendingAdjustmentEffectiveDate=&pendingAdjustmentNote=&pendingAdjustmentLength=&
id=
code=
accountId=
amount=
createDate=
customerId=
firstBillingDate=
lastBillingDate=
lastUpdateDate=
length=
nextBillingDate=
note=
paymentOptionId=
planId=
planName=
status=
type=
billingCycleType=
pendingAdjustmentType=
pendingAdjustmentEffectiveDate=
pendingAdjustmentNote=
pendingAdjustmentLength=