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 Adjustment Enum

Billing API Index (Actions)

Show

URL	Action	Method
[version]/customers view
[version]/customers	~create	PUT
[version]/customers	~find	GET
[version]/customers/[customer-id] view
[version]/customers/[customer-id]	~load	GET
[version]/customers/[customer-id]	~modify	POST
[version]/customers/[customer-id]/payment-options view
[version]/customers/[customer-id]/payment-options	~create	PUT
[version]/customers/[customer-id]/payment-options	~find	GET
[version]/customers/[customer-id]/payment-options/[payment-option-id] view
[version]/customers/[customer-id]/payment-options/[payment-option-id]	~load	GET
[version]/customers/[customer-id]/payment-options/[payment-option-id]	~modify	POST
[version]/customers/[customer-id]/payment-options/[payment-option-id]	~process	POST
[version]/customers/[customer-id]/subscriptions view
[version]/customers/[customer-id]/subscriptions	~create	PUT
[version]/customers/[customer-id]/subscriptions	~find	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id] view
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~cancel	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~freeze	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~load	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~modify	POST
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~pause	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~uncancel	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~unfreeze	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]	~unpause	GET
[version]/customers/[customer-id]/subscriptions/[subscription-id]/adjustments view
[version]/customers/[customer-id]/subscriptions/[subscription-id]/adjustments	~find	GET
[version]/customers/[customer-id]/transactions view
[version]/customers/[customer-id]/transactions	~create	PUT
[version]/customers/[customer-id]/transactions	~find	GET
[version]/customers/[customer-id]/transactions	~process	POST
[version]/customers/[customer-id]/transactions/[transaction-id] view
[version]/customers/[customer-id]/transactions/[transaction-id]	~load	GET
[version]/customers/[customer-id]/transactions/[transaction-id]	~reverse	GET
[version]/customers/[customer-id]/transactions/[transaction-id]/allocations view
[version]/customers/[customer-id]/transactions/[transaction-id]/allocations	~find	GET
[version]/plans view
[version]/plans	~create	PUT
[version]/plans	~find	GET
[version]/plans/[plan-id] view
[version]/plans/[plan-id]	~load	GET
[version]/plans/[plan-id]	~modify	POST

Reverse a previous sale

PaymentOption

Type:

Abstract: no

Status: Active

Java Class: PaymentOption

Payment option information associated with the merchant.

Available Fields:

accountAccessory
accountId
accountNumber
address
cardType
city
code

countryCode
createDate
csc
customerId
holderName
id
isActive

state
street1
street2
token
tokenCode
type
zipCode

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:

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:

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 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:

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 name of the user's mailing address.

street2

References: Payment Option.Street2

XML Representation: attribute

Attributes:

Default Value

Pattern:

Additional street name field for entering user's mailing address.

city

References: Payment Option.City

XML Representation: attribute

Attributes:

Default Value

Pattern:

City name of the user's mailing address.

countryCode

References: Payment Option.Country CL

XML Representation: attribute

Attributes:

Default Value

Pattern:

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=