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 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.
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 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.
Integration Notes
The connection URL for the sandbox server is: https://[server-name]/api/v01/.
Authorization is done via service users. To access the API, a service user is required to be granted with a Management API privilege. A user can submit API requests using either associated credentials or a temporary password generated via the authentication operation. See Security Management guide for more information.
Request method can be either GET or POST depending on the action you are submitting. The content-type must be set to application/x-www-form-urlencoded. Request fields are passed within the HTTPS request body and are required to be URL-encoded.
Response fields are passed within the HTTPS response body.
Both request and response field values are passed using name1=key1&name2=key2 format.
When submitting an API request, you can use either gateway server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).
In Billing module, the following API requests can be submitted only to the sanitizing data filter server URL:
Request method can be either GET or POST depending on the action you are submitting. The content-type must be set to application/x-www-form-urlencoded. Request fields are passed within the HTTPS request body and are required to be URL-encoded.
Response fields are passed within the HTTPS response body.
Both request and response field values are passed using name1=key1&name2=key2 format.
When submitting an API request, you can use either gateway server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).
In Billing module, the following API requests can be submitted only to the sanitizing data filter server URL:
- [version]/customers/[customer-id]/transactions/~process
- [version]/customers/[id]/payment-options/[payment-option-id]/~process
- [version]/customers/[customer-id]/payment-options/~create
{UniBill} is one of the {UniPay} modules providing the opportunity to set up recurring billing to withdraw payments from customers on a regular basis and keep track of their pricing plans, subscriptions and associated payments. Both user interface and RESTful API is used to communicate with the application within this module.
Before you start work with the API make sure that you familiarize yourself with the basic concepts of recurring billing.
There are goods and services that customers purchase on a regular basis. For example, gym membership, subscriptions to magazines or mobile apps, etc. Customers can pay for these types of goods/services via recurring billing. In the process of recurring billing, a merchant automatically charges a customer for the specific goods/services on a prearranged schedule, or a payment plan. To use a payment plan, the customer has to sign up to it by giving the consent to pay a certain amount on a regular basis. When the customer agrees to make payments with or without the underlying payment plan, a subscription is created. If there is a need for the customer to change the existing subscription (for example, cancel gym membership for a certain period time), the subscription adjustment is applied. To pay for the subscription, the customer can use any payment option (cash, card, check, etc).
In order to fully utilize the billing API functionality, you have to create a set of the objects for a merchant in the following sequence:
See integration notes for more information about the subscription object and about available subscription-related actions.
Subscription is associated with the following object:
See integration notes for more information.
Transaction is associated with the following objects:
The relationship between all of the billing API objects is shown in the diagram below.
Before you start work with the API make sure that you familiarize yourself with the basic concepts of recurring billing.
There are goods and services that customers purchase on a regular basis. For example, gym membership, subscriptions to magazines or mobile apps, etc. Customers can pay for these types of goods/services via recurring billing. In the process of recurring billing, a merchant automatically charges a customer for the specific goods/services on a prearranged schedule, or a payment plan. To use a payment plan, the customer has to sign up to it by giving the consent to pay a certain amount on a regular basis. When the customer agrees to make payments with or without the underlying payment plan, a subscription is created. If there is a need for the customer to change the existing subscription (for example, cancel gym membership for a certain period time), the subscription adjustment is applied. To pay for the subscription, the customer can use any payment option (cash, card, check, etc).
In order to fully utilize the billing API functionality, you have to create a set of the objects for a merchant in the following sequence:
- Customer - a merchant's customer who subscribes to the merchant’s goods/services and pays for them via the gateway, through an external system (for example, a terminal that is used separately from the gateway), or via cash/check.
- create - creates a customer.
- find - returns a list of available customers based on specified search criteria: first name, last name, organization name.
- load - returns configuration settings for the selected customer.
- modify - updates the selected customer with the specified values.
- Plan - pricing plan, which determines how often and how much a customer has to pay.
- create - creates a pricing plan.
- find - returns a list of available pricing plans based on specified search criteria: customer account number, create date, amount, billing cycle type.
- load - returns configuration settings for the selected pricing plan.
- modify - updates the selected pricing plan with the specified values.
- Subscription - customer’s subscription to a specific pricing plan.
- create - creates a subscription.
- find - returns a list of available subscriptions based on specified criteria: identifier of a plan associated with the subscription, create date, subscription status, next billing date.
- load - returns settings of the subscription specified in the request.
- modify - Updates the subscription with the specified values.
- cancel - cancels the subscription right away or on the specified date.
- freeze - freezes the subscription for the specified period.
- pause - pauses the subscription right away or on the specified date.
- uncancel - uncancels the specified subscription if it has not been canceled yet. Applicable only to pending cancellation subscriptions (the ones that have an effective date in future).
- unfreeze - unfreezes the specified subscription if it has been previously frozen.
- unpause - unpauses the specified subscription if it has been previously paused.
See integration notes for more information about the subscription object and about available subscription-related actions.
Subscription is associated with the following object:
- Subscription adjustment - adjustments made to a particular subscription (for example, subscription termination, cancellation, etc).
- find - returns a list of available adjustments associated with the specified subscription.
- Payment Option - customer’s payment card or bank account encrypted and stored within the system.
- create - creates a payment option.
- find - returns a list of available payment options associated with the specified customer.
- load - returns configuration settings for the specified payment option.
- modify - updates the selected payment option with the specified values.
- process - creates and processes a transaction based on the specified payment option.
- Transaction - customer’s transactions used to pay for a subscription.
- create - creates a transaction associated with the specified customer.
- find - returns a list of the transactions associated with the specified customer.
- process - creates and processes a transaction associated with the specified customer.
- load - returns data associated with the specified transaction.
- reverse - reverses/voids the specified transaction.
See integration notes for more information.
Transaction is associated with the following objects:
- ProcessingRequest - contains transaction request data to process a transaction via the gateway.
- ProcessingInfo - contains transaction response data, i.e. detailed information about the transaction processed by the gateway (for example, responseCode, responseMessage, etc). Included in the Transaction object.
The relationship between all of the billing API objects is shown in the diagram below.
When submitting a payment/refund transaction, the information can be passed via one of the following fields:
Any of these fields can be included in the request. If more than one field value is submitted within a transaction, the processing priority will be the following:
1) accountData (accountNumber and token are ignored);
2) accountNumber (token is ignored);
3) token.
- accountData - track/EMV data of a payment card. See integration notes for more information.
- accountNumber - number of a payment card or bank account.
- token - token associated with a payment card or bank account. It can be used instead of a payment card or bank account number in subsequent transaction processing. Note: This field can be submitted only if tokenization service is enabled.
Any of these fields can be included in the request. If more than one field value is submitted within a transaction, the processing priority will be the following:
1) accountData (accountNumber and token are ignored);
2) accountNumber (token is ignored);
3) token.
While working with the API, various entities within the system, such as merchants, resellers, etc, need to be referenced. API fields that correspond to the references for these entities are of the Reference type (for example, customerId, planId, etc). Each of these entities has two identifiers:
— Internal identifier - numeric value, provided by the gateway; unique within the system.
— External identifier - alphanumeric value up to 60 characters, provided by an integrated external system for cross-referencing; preferably unique within the scope that makes sense to an integrator.
When an API call with reference to an entity has to be submitted, this entity can be referenced by either an internal or external identifier. By default, the system expects an internal identifier to be submitted (e.g. customerId=1234). To let the system know that an external identifier is being submitted, its value must be preceded by an asterisk (e.g. customerId=*1234). This is applicable to all fields of Reference type.
For example, a customer has an internal ID, generated by the gateway (e.g.5678), and an external ID, provided by a submitter (e.g. cust_8765). If an internal ID should be used in the API calls, it is submitted via the customerId field as it is: customerId=5678. If an external ID should be used in the API calls, it is submitted with an asterisk as a prefix: customerId=*cust_8765.
The following entities can be submitted using either an internal or external identifier:
— External identifier - alphanumeric value up to 60 characters, provided by an integrated external system for cross-referencing; preferably unique within the scope that makes sense to an integrator.
When an API call with reference to an entity has to be submitted, this entity can be referenced by either an internal or external identifier. By default, the system expects an internal identifier to be submitted (e.g. customerId=1234). To let the system know that an external identifier is being submitted, its value must be preceded by an asterisk (e.g. customerId=*1234). This is applicable to all fields of Reference type.
For example, a customer has an internal ID, generated by the gateway (e.g.5678), and an external ID, provided by a submitter (e.g. cust_8765). If an internal ID should be used in the API calls, it is submitted via the customerId field as it is: customerId=5678. If an external ID should be used in the API calls, it is submitted with an asterisk as a prefix: customerId=*cust_8765.
The following entities can be submitted using either an internal or external identifier:
- customer;
- payment option;
- plan;
- subscription;
- transaction.
Pre-set prices for the services that a merchant provides to customers are represented in the API as the Plan object. To create a plan, use the create action.
To use a service, a customer can be subscribed to a previously created plan, though the payment plan is not required for the creation of the subscription.
To create a subscription, use the create action, indicating the ID of the selected plan in the request. Note that a customer can only be subscribed to one plan.
After a subscription is created, the customer can terminate or cancel the subscription.
For this purpose, you can use one of the following actions:
In cases when a customer wants to re-activate the subscription, you can reverse the actions described above. To reverse a previously applied action, the following actions are used:
After reversal, a state of a subscription depends on whether an effective date passed:
To view all actions that have been applied to a certain subscription, use the find action, indicating an ID for the subscription in the request.
To use a service, a customer can be subscribed to a previously created plan, though the payment plan is not required for the creation of the subscription.
To create a subscription, use the create action, indicating the ID of the selected plan in the request. Note that a customer can only be subscribed to one plan.
After a subscription is created, the customer can terminate or cancel the subscription.
For this purpose, you can use one of the following actions:
- pause - pauses a subscription in cases when a customer wants to suspend the subscription for an unspecified period of time. A subscription can be paused immediately or on the next billing date.
- freeze - freezes a subscription in cases when a customer wants to terminate the subscription for a specified period (from 1 to 6 periods). Can be applied only to the subscriptions with billingCycleType=weekly or monthly. The subscription can be frozen only on one of the next billing dates. After the predefined number of freeze charges has passed, the subscription is reactivated automatically.
- cancel - cancels a subscription in cases when a customer wants to refuse the services or change the plan they subscribed to. The subscription can be canceled immediately or on the next billing date.
In cases when a customer wants to re-activate the subscription, you can reverse the actions described above. To reverse a previously applied action, the following actions are used:
- unpause - reverses the pause action;
- unfreeze - reverses the freeze action. Note that there may be a situation when you set a freeze for a billing date in the future, and then you want to prolong the freeze. In this case, you have to unfreeze the subscription that is set for freeze in the future and re-set the freeze for a desirable number of months. On the other hand, if the subscription has already been frozen (i.e. billing date has already come), you have to set an additional freeze for a desirable number of months without unfreezing the previous one.
- uncancel - reverses the cancel action. Can be applied only if cancellation date is a date in future. If cancellation date is set as today or a previous date, a subscription cannot be uncancelled.
After reversal, a state of a subscription depends on whether an effective date passed:
- if the effective date of the pause/freeze/cancel has not come, a planned action is cancelled, and the state of the subscription stays the same, i.e. its status is indicated as Current both before and after the action is undone;
- if the effective date of the pause/freeze/cancel has already come, a current action is cancelled, and the subscription is reactivated, i.e. its status is indicated as
To view all actions that have been applied to a certain subscription, use the find action, indicating an ID for the subscription in the request.
The following subscription types can be created within the system:
When a subscription is created, it can obtain one of the following statuses:
- Fixed subscription – indicates that the subscription will continue for a set number of periods. For example, $10 per month for 12 months.
- Perpetual subscription – indicates that the subscription will continue with a recurring amount until the user explicitly cancels it. For example, $10 per month until cancelled.
When a subscription is created, it can obtain one of the following statuses:
- Unbilled - indicates that no billing has occurred since the subscription was created.
- Deferred - indicates that no invoice will be generated in the upcoming billing associated with the subscription, because the first billing date is set for the following month. For example, today is November 15, and we create a monthly subscription with the first billing date set as December 20. In this case, on November 20 the subscription will obtain a deferred status, because this date is expected by the system to be the first billing date.
- Current - indicates that the subscription is active.
- Paused - indicates that the subscription is set on hold by a customer. See integration notes for more information.
- Freeze - indicates that the subscription is terminated. See integration notes for more information.
- Cancelled - indicates that the subscription is canceled. See integration notes for more information..
- Expired - indicates that all payments associated with a subscription have been made. Note that only a fixed subscription can obtain this status.
Recurring billing is also used to keep track of the payments and outstanding charges of a customer according to their payment plan. The transaction types described below are available to align the customer’s balance.
Since all these transactions are initiated and controlled by a merchant, they belong to a group of merchant-initiated transactions. However, in the process of recurring billing you may also receive transactions from a processor. This type of transactions is considered as processor/bank initiated.
All transactions are divided into merchant-initiated (i.e. that are submitted by a merchant) and bank/processor-initiated (i.e. that are retrieved from a processor).
The following merchant-initiated transactions are available within the billing API:
To track the amounts that are expected to be withdrawn from a customer:
Invoice - represents an amount that a customer owes to a merchant.
Fee - represents the amount of a fee collected from a customer under certain conditions. The fee can be charged to a customer only if this condition is explicitly stated in the agreement between the customer and the merchant.
To record the funds withdrawn from a customer and deposited to the merchant’s account:
Payment - represents a real-time transaction used to cover a customer’s debt to a merchant. The amount of the debt equals the amount of a previously generated invoice.
Claim – represents a batch transaction used to cover a customer’s debt to a merchant. The amount of the debt equals the amount of a previously generated invoice.
To record funds withdrawn from the merchant’s bank account and transferred to the customer in case of an error, or when specific business scenario is applied:
Credit - represents an amount that a merchant owes to a customer. For example, a customer cancels their subscription. To cover an amount of a previously generated invoice, a credit transaction is used. After the credit is issued, the customer’s balance is set to zero.
Refund - represents amount that a merchant credits to a customer. Can only be performed after settlement.
Void - represents a transaction that has been reverted. Can only be performed before settlement. No further action can be taken for a voided transaction.
The following bank/processor-initiated transactions are available within the billing API:
Decline - represents a payment or refund that got declined.
Returns - represents a direct debit payment that has not been honored by a bank.
Chargeback - represents a reversal of a prior outbound transfer of funds from a customer's payment card to a merchant.
Chargeback Reversal - represents a reversal of a payment card chargeback, i.e. money is given back to the merchant or customer.
For merchant-initiated transactions you can apply the following actions. See integration notes for more information.
Since all these transactions are initiated and controlled by a merchant, they belong to a group of merchant-initiated transactions. However, in the process of recurring billing you may also receive transactions from a processor. This type of transactions is considered as processor/bank initiated.
All transactions are divided into merchant-initiated (i.e. that are submitted by a merchant) and bank/processor-initiated (i.e. that are retrieved from a processor).
The following merchant-initiated transactions are available within the billing API:
To track the amounts that are expected to be withdrawn from a customer:
Invoice - represents an amount that a customer owes to a merchant.
Fee - represents the amount of a fee collected from a customer under certain conditions. The fee can be charged to a customer only if this condition is explicitly stated in the agreement between the customer and the merchant.
To record the funds withdrawn from a customer and deposited to the merchant’s account:
Payment - represents a real-time transaction used to cover a customer’s debt to a merchant. The amount of the debt equals the amount of a previously generated invoice.
Claim – represents a batch transaction used to cover a customer’s debt to a merchant. The amount of the debt equals the amount of a previously generated invoice.
To record funds withdrawn from the merchant’s bank account and transferred to the customer in case of an error, or when specific business scenario is applied:
Credit - represents an amount that a merchant owes to a customer. For example, a customer cancels their subscription. To cover an amount of a previously generated invoice, a credit transaction is used. After the credit is issued, the customer’s balance is set to zero.
Refund - represents amount that a merchant credits to a customer. Can only be performed after settlement.
Void - represents a transaction that has been reverted. Can only be performed before settlement. No further action can be taken for a voided transaction.
The following bank/processor-initiated transactions are available within the billing API:
Decline - represents a payment or refund that got declined.
Returns - represents a direct debit payment that has not been honored by a bank.
Chargeback - represents a reversal of a prior outbound transfer of funds from a customer's payment card to a merchant.
Chargeback Reversal - represents a reversal of a payment card chargeback, i.e. money is given back to the merchant or customer.
For merchant-initiated transactions you can apply the following actions. See integration notes for more information.
| create | process | reverse | |
|---|---|---|---|
| Invoice | + | + | |
| Credit | + | + | |
| Fee | + | + | |
| Payment | + | + | + |
| Claim | + | ||
| Refund | + | + | + |
| Void |
There may be cases when some payments are processed outside of the gateway (i.e. paid via cash/check). However, the system needs to keep track of either transactions that were processed through the system (processed transactions) or those that were processed outside of the system (recorded transactions) to align the customer’s balance. For this reason, the recorded transactions need to be posted against customer’s account to keep balance of the customer. Thus, you can use the billing API for both processing of transactions and keeping record of them.
How to process a transaction
To submit a transaction for processing, the following actions are used:
In both cases, the transaction response returned by the system contain the following data:
How to create a transaction and store it within the gateway without processing
To add transaction record to the gateway without its processing, transactions~create create action is used. It creates a transaction using data submitted within the Transaction object and saves the record within the gateway.
This action can be used to create an invoice, credit, fee, payment, refund transactions. See integration notes for more information about transaction types.
How to cancel processed and stored transactions
In case you need to cancel a transaction that has been either created or processed, use the reverse action. After the action is applied, the indicate transaction is reversed. Note that the transaction cannot be returned to its initial state after reversal. A list of the transaction types that can be reversed, as well as their final states, are listed below.
How to process a transaction
To submit a transaction for processing, the following actions are used:
- transactions~process action- submits a transaction to the gateway using data within the ProcessingRequest object. See integration notes for more information about payment data processing priority.
- payment-options/[payment-option-id~process] - submits a transaction to the gateway using data within the ProcessingRequest object and a previously created payment option, which ID is indicated in the request. See integration notes for more information about payment data processing priority.
In both cases, the transaction response returned by the system contain the following data:
- Transaction object with the payment or refund type that contains transaction data;
- ProcessingInfo object that contains data associated with the processed transaction.
How to create a transaction and store it within the gateway without processing
To add transaction record to the gateway without its processing, transactions~create create action is used. It creates a transaction using data submitted within the Transaction object and saves the record within the gateway.
This action can be used to create an invoice, credit, fee, payment, refund transactions. See integration notes for more information about transaction types.
How to cancel processed and stored transactions
In case you need to cancel a transaction that has been either created or processed, use the reverse action. After the action is applied, the indicate transaction is reversed. Note that the transaction cannot be returned to its initial state after reversal. A list of the transaction types that can be reversed, as well as their final states, are listed below.
| Transaction Type | Reversal Result |
|---|---|
| Invoice | Invoice Reversal |
| Credit | Credit Reversal |
| Customer Fee | Fee Reversal |
| Payment | Void or Refund |
| Claim | Refund |
| Refund | Refund Reversal |
API response consists of the header (HTTP status code) and the body.
500 Internal Server Error is returned in the response header if the server encountered an unexpected issue that prevented it from processing and fulfilling the request that you have submitted. In this case, the response is not generated and, thus, the response body is empty.
If the request has been fulfilled on the server, 200 OK is returned in the header, and the API response is generated and returned in the body. The response body may contain an API object - if the request has been processed successfully or a Unipay Exception (response code and error message) - if an application error occurred while processing your request. For example, when processing a sale transaction, 200 OK status code is returned in the header both in the case of approval and decline.
500 Internal Server Error is returned in the response header if the server encountered an unexpected issue that prevented it from processing and fulfilling the request that you have submitted. In this case, the response is not generated and, thus, the response body is empty.
If the request has been fulfilled on the server, 200 OK is returned in the header, and the API response is generated and returned in the body. The response body may contain an API object - if the request has been processed successfully or a Unipay Exception (response code and error message) - if an application error occurred while processing your request. For example, when processing a sale transaction, 200 OK status code is returned in the header both in the case of approval and decline.