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.


PaymentOption

Type:  
Abstract:  no
Status:  Active
Java Class:  PaymentOption
Payment option information associated with the merchant.
id
References: Payment Option.Id
XML Representation: attribute
Attributes:
Default Value
Identifier of the object used for references; auto-incremented integer value.

Note that payment option code can be supplied as identifier when using API. In this case, prefix * is required. For example, paymentOptionId="*card1" .
code
References: Payment Option.Reference Code
XML Representation: attribute
Attributes: CreateOnly
Default Value
Pattern: CODE
Secondary identifier that can be used to cross-reference records between UniPay and integrated systems.

See Reference Code definition for additional information.

Code of Account to which instance of this object is attributed to. Depending on the context, Merchant Account Code field may contain either Merchant Code or 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.
createDate
References: Payment Option.Create Date
XML Representation: attribute
Attributes:
Default Value
Date when the record was created.

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.
type
References: Payment Option.Payment Option CL
XML Representation: attribute
Attributes: CreateOnly
Default Value
Reference to the entity that represents possible types of payment options.
accountNumber
References: Payment Option.Number
XML Representation: attribute
Attributes: Required, CreateOnly
Default Value
Number of a payment card or bank account.
accountAccessory
References: Payment Option.Accessory
XML Representation: attribute
Attributes: Required
Default Value
Pattern: NUMERIC
Expiration date of the card or bank routing number.
tokenCode
References: Payment Option.Token Code
XML Representation: attribute
Attributes:
Default Value
Code of the token associated with the particular payment option.
isActive
References: Payment Option.Is Active
XML Representation: attribute
Attributes: Default: true
Default Value true
Indicates whether the record is active in the system.
holderName
References: Payment Option.Holder Name
XML Representation: attribute
Attributes: Required
Default Value
Pattern: NAME
Name of the bank account or credit card holder.

The value is a concatenation of the firstName and lastName field values separated by a space.
csc
References: Payment Option.CVV2
XML Representation: attribute
Attributes:
Default Value
Pattern: NUMERIC
CVV2 code associated with payment.

Card security code (CSC) of the customer's card.
street1
References: Payment Option.Street1
XML Representation: attribute
Attributes:
Default Value
Pattern: STREET
Street name of the user's mailing address.
street2
References: Payment Option.Street2
XML Representation: attribute
Attributes:
Default Value
Pattern: STREET
Additional street name field for entering user's mailing address.
city
References: Payment Option.City
XML Representation: attribute
Attributes:
Default Value
Pattern: ALPHANUMERIC_EXTENDED
City name of the user's mailing address.
countryCode
References: Payment Option.Country CL
XML Representation: attribute
Attributes:
Default Value
Pattern: ALPHA
Enumeration of possible country codes associated with a user's mailing address.

Country code of the customer's address.
state
References: Payment Option.State
XML Representation: attribute
Attributes:
Default Value
Code of the state associated with a user's mailing address.
zipCode
References: Payment Option.ZIP Code
XML Representation: attribute
Attributes:
Default Value
ZIP or postal code associated with a user's mailing address.
customerId
References: Payment Option.Customer Account FK
XML Representation: attribute
Attributes:
Default Value
Reference to the entity that represent code of the customer account to which instance of this object is attributed to.

Identifier of the customer within the gateway.
cardType
References: Payment Option.Card Type
XML Representation: attribute
Attributes: Calculated
Default Value
Type of the card associated with payment option. Used to define the card icon rendered on the user interface.
accountId
References: Payment Option.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.
address
References: Payment Option.Address
XML Representation: attribute
Attributes: Calculated
Default Value
Address associated with a payment card or bank account holder. The value is a concatenation of the street1, street2, city, state, zipCode, countryCode field values separated by commas (,).
token
References: Payment Option.Token
XML Representation: attribute
Attributes: CreateOnly
Default Value

XML Sample:

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

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

JSON Sample:

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

XURL Sample:

?id=&code=&createDate=&type=&accountNumber=&accountAccessory=&tokenCode=&isActive=&holderName=&csc=&street1=&street2=&city=&countryCode=&state=&zipCode=&customerId=&accountId=&address=&token=&
id=
code=
createDate=
type=
accountNumber=
accountAccessory=
tokenCode=
isActive=
holderName=
csc=
street1=
street2=
city=
countryCode=
state=
zipCode=
customerId=
accountId=
address=
token=