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.

PaymentOption

Type:  
Abstract:  no
Status:  Active
Java Class:  PaymentOption
Payment option information associated with the merchant.

Available Fields:

# Name Type Pattern Format Mode Usage Description
1 countryCode String(3) ALPHA O The customer's country code.\n\r\n> **Note:** Uses standard two-letter country codes defined in ISO 3166-1 alpha-2 (e.g., 'US' for United States).
2 token String(50) C O The unique value generated by the system that securely represents sensitive payment data without exposing actual card or bank details.\n\r\n> **Attention:** This field contains sensitive information and should be handled securely.
3 accountAccessory String(80) NUMERIC R The card expiration date (for credit cards) or routing number (for bank accounts).\n\r\n> **Note:** For payment cards, format is MMYY (e.g., '1225' for December 2025). For bank accounts, this contains the routing number.
4 holderName String(150) NAME R The calculated field that combines the 'firstName' and 'lastName' values from the request.\n\r\n> **Note:** Maximum length is 150 characters.
5 address String R O The customer's complete address.\n\r\n> **Note:** The value is a concatenation of the street1, street2, city, state, zipCode, and countryCode field values. Maximum length is 100 characters.
6 createDate Datetime R O The date when the record was created.\n\r\n> **Note:** In the response, the date is returned with hour, minute, and second values, formatted as yyyy-MM-dd HH:mm:ss.
7 id Long R O The identifier of the object used for references; auto-incremented integer value.\n\r\n> **Note:** This is the primary system-generated identifier for the payment option.
8 tokenCode String(512) R O The code of the token associated with the payment option.\n\r\n> **Note:** This value can be used for future transactions with this payment method.
9 createDate Datetime R O The date when the record was created.\n\r\n> **Note:** In the response, the date is returned with hour, minute, and second values, formatted as yyyy-MM-dd HH:mm:ss.
10 type Enum C O The type of the payment method.
11 isActive Boolean O The status indicator that shows whether a record is active within the system.\n\r\n> **Note:** Possible values: true (1) or false (0). Default: `true` (1).
12 csc String NUMERIC O The card security code (three digits on the back of a payment card).\n\r\n> **Note:** This field is typically not returned in the response for security reasons.\n\r\n> **Attention:** This field contains sensitive security information.
13 street1 String(128) STREET O The customer's street address (line 1).\n\r\n> **Note:** Maximum length is 128 characters.
14 street2 String(128) STREET O The customer's street address (line 2).\n\r\n> **Note:** Maximum length is 128 characters.
15 city String(50) ALPHANUMERIC_EXTENDED O The customer's city.\n\r\n> **Note:** Maximum length is 50 characters.
16 state String(3) O The customer's state.\n\r\n> **Note:** For US addresses, this is the two-letter state code. Format depends on the associated country code.
17 zipCode String(15) O The customer's ZIP or postal code.\n\r\n> **Note:** Format depends on the associated country code. Maximum length is 15 characters.
18 customerId Long R O The ID of the customer in the system.\n\r\n> **Note:** This field establishes the relationship between the payment option and customer records.
19 code String(60) CODE C O The optional secondary identifier supplied by the external/user's system.\n\r\n> **Note:** Typically a reference to an ID in your own system. By default, this value is set to the same as the object's id returned in the response.
20 accountId Integer O The merchant account associated with this payment option.\n\r\n> **Note:** Your API credentials may be associated with more than one accountId.
21 address String R O The customer's complete address.\n\r\n> **Note:** The value is a concatenation of the street1, street2, city, state, zipCode, and countryCode field values. Maximum length is 100 characters.
22 token String C O The unique value generated by the system that securely represents sensitive payment data without exposing actual card or bank details.\n\r\n> **Attention:** This field contains sensitive information and should be handled securely.
23 state String(3) ALPHA O The customer's state.\n\r\n> **Note:** For US addresses, this is the two-letter state code. Format depends on the associated country code.
24 zipCode String(15) ALPHANUMERIC_EXTENDED O The customer's ZIP or postal code.\n\r\n> **Note:** Format depends on the associated country code. Maximum length is 15 characters.
25 tokenCode String(512) ALPHANUMERIC_EXTENDED R O The code of the token associated with the payment option.\n\r\n> **Note:** This value can be used for future transactions with this payment method.
26 token String TOKEN C O The unique value generated by the system that securely represents sensitive payment data without exposing actual card or bank details.\n\r\n> **Attention:** This field contains sensitive information and should be handled securely.
27 accountNumber String(80) C R The credit card or bank account number.\n\r\n> **Note:** This field is typically masked in the response for security reasons, showing only the last 4 digits of the actual number.\n\r\n> **Attention:** This field contains sensitive payment information and should be handled securely.

XML Sample:

<payment-option
    countryCode="" 
    token="" 
    accountAccessory="" 
    holderName="" 
    address="" 
    createDate="" 
    id="" 
    tokenCode="" 
    createDate="" 
    type="" 
    isActive="" 
    csc="" 
    street1="" 
    street2="" 
    city="" 
    state="" 
    zipCode="" 
    customerId="" 
    code="" 
    accountId="" 
    address="" 
    token="" 
    state="" 
    zipCode="" 
    tokenCode="" 
    token="" 
    accountNumber="" />

JSON Sample:

{
  "countryCode": "",
  "token": "",
  "accountAccessory": "",
  "holderName": "",
  "address": "",
  "createDate": "",
  "id": "",
  "tokenCode": "",
  "type": "",
  "isActive": "",
  "csc": "",
  "street1": "",
  "street2": "",
  "city": "",
  "state": "",
  "zipCode": "",
  "customerId": "",
  "code": "",
  "accountId": "",
  "accountNumber": ""
}

XURL Sample:

?countryCode=&token=&accountAccessory=&holderName=&address=&createDate=&id=&tokenCode=&createDate=&type=&isActive=&csc=&street1=&street2=&city=&state=&zipCode=&customerId=&code=&accountId=&address=&token=&state=&zipCode=&tokenCode=&token=&accountNumber=&
countryCode=
token=
accountAccessory=
holderName=
address=
createDate=
id=
tokenCode=
createDate=
type=
isActive=
csc=
street1=
street2=
city=
state=
zipCode=
customerId=
code=
accountId=
address=
token=
state=
zipCode=
tokenCode=
token=
accountNumber=
Copyright © United Thinkers. (UniPay - Payment Gateway Software)
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.