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.

Base Resource URL:

https://[server-name]/api/v01/customers/[customer-id]/payment-options

Description:

Provides access to payment options associated with the specified customer.

Supported sub-resources:

Resource URL Description
https://[server-name]/api/v01/customers/[customer-id]/payment-options/[payment-option-id] Provides access to configuration settings for the specified payment option.

Supported Actions:

~create (request)

Method:  PUT
Implicit:  Yes
Returns:  PaymentOption
Consumes:  json,xml
Produces:  json,xml

Manage payment methods for recurring billing subscriptions. - Each payment option is linked to a specific customer, but customers can have multiple methods. - Serves as a recurring funding source for subscriptions. - Contains sensitive cardholder data; follow PCI compliance requirements. - Use tokenization to securely handle payment methods and reduce PCI DSS compliance scope. - Tokenization allows recurring payments without storing sensitive details in your system.
Path Parameters:
# Name Type Pattern Format Mode Usage Description
1 customer-id Long O System-generated unique identifier for the customer.\n\r\n> **Note:** Automatically generated by the system. This field must not be provided in your request.
Body Parameters:
# Name Type Pattern Format Mode Usage Description
1 countryCode String(3) ALPHA O The customer's country code.\n\r\n> **Note:** Use 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) used during transaction processing. This field is required even when using a token.\n\r\n> **Note:** For payment cards, format as MMYY (e.g., '1225' for December 2025). For bank accounts, provide the routing number. Maximum length is 10 characters.
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. This field is automatically populated based on customer information.
10 type Enum C O The type of payment option that will be created.
11 isActive Boolean O The status of the payment option.\n\r\n> **Note:** Possible values: true (active) or false (inactive). Default: `true`.
12 csc String NUMERIC O The card security code (three digits on the back of a payment card).\n\r\n> **Note:** Maximum length is 4 characters to accommodate American Express cards that have a 4-digit security code.
13 street1 String(128) STREET O The customer's street address (line 1).\n\r\n> **Note:** Maximum length is 128 characters.\n\r\n> **Tip:** Including accurate billing address information improves approval rates and may lower interchange costs.
14 street2 String(128) STREET O The customer's secondary street address (line 2).\n\r\n> **Note:** Additional street data such as apartment or suite number. 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:** State value format is subject to the associated country code. For US addresses, use the two-letter state code.
17 zipCode String(15) O The customer's ZIP or postal code.\n\r\n> **Note:** Format is subject to the associated country code. Maximum length is 15 characters.
19 code String(60) CODE C O The unique payment option ID supplied by the external/user's system.\n\r\n> **Note:** Optional secondary identifier. Typically a reference to an ID in your own system. If not provided, the system will use the object's id generated at creation time.
20 accountId Integer O The merchant account associated with the payment option.\n\r\n> **Note:** If your API user is associated with multiple merchant accounts, you can specify the merchant account ID to reduce the data set in API responses. Your credentials may be associated with more than one accountId.
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:** State value format is subject to the associated country code. For US addresses, use the two-letter state code.
24 zipCode String(15) ALPHANUMERIC_EXTENDED O The customer's ZIP or postal code.\n\r\n> **Note:** Format is subject to the associated country code. Maximum length is 15 characters.
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 used during transaction processing. This field is required if you are not using a token for the transaction.\n\r\n> **Note:** Maximum length is 20 characters with no spaces or special characters.\n\r\n> **Attention:** This field contains sensitive cardholder data that will be replaced with a secure token after processing.

~create (response)

Method:  PUT
Implicit:  Yes
Returns:  PaymentOption
Consumes:  json,xml
Produces:  json,xml

Manage payment methods for recurring billing subscriptions. - Each payment option is linked to a specific customer, but customers can have multiple methods. - Serves as a recurring funding source for subscriptions. - Contains sensitive cardholder data; follow PCI compliance requirements. - Use tokenization to securely handle payment methods and reduce PCI DSS compliance scope. - Tokenization allows recurring payments without storing sensitive details in your system.
Body Parameters:
# 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.

~find (request)

Method:  GET
Implicit:  Yes
Returns:  List<PaymentOption>
Consumes:  xurl
Produces:  json,xml

Returns a list of available payment options associated with the specified customer.
Path Parameters:
# Name Type Pattern Format Mode Usage Description
1 customer-id Long O System-generated unique identifier for the customer.\n\r\n> **Note:** Automatically generated by the system. This field must not be provided in your request.
Body Parameters:
# Name Type Pattern Format Mode Usage Description
1 offset Integer O Index of the first record returned from the search result.\n\r\n> **Note:** Default: `0`. Used with limit parameter for pagination.\n\r\n> **Tip:** Use this field for implementing paginated results.
2 limit Integer O Maximum number of records to load per search call.\n\r\n> **Note:** Default: `100`. Adjust based on performance requirements.\n\r\n> **Tip:** Use this field to balance response size and performance.

~find (response)

Method:  GET
Implicit:  Yes
Returns:  List<PaymentOption>
Consumes:  xurl
Produces:  json,xml

Returns a list of available payment options associated with the specified customer.
Body Parameters:
# 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.
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.