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 APIs Code Samples

Add a New Customer with a fixed term Subscription for 12 payments, using a credit card

A customer is buying a 12-month gym membership for $49.99 collected monthly, $49.99 due at signing. The membership is paid via credit card.

Note: The subscription is based on the previously created pricing plan. Before testing this scenario make sure that you have created pricing Plans described in the [https://unipaygateway.info/billing-api/sample/8 first sample].


View Implementation:

1) Creating a new customer.
Method: PUT
Path: [version]/[customers]/~create
Value Name
accountId 2001
code customer1
isActive true
organizationName Organization LLC
firstName John
lastName Smith
email jsmith@mail.com
phone 2129856472
street1 12 Main St
street2 5th Ave
city New York
state NY
zipCode 31904
countryCode US 
{
"accountId":"2001",
"code":"customer1",
"isActive":"true",
"organizationName":"Organization LLC",
"firstName":"John",
"lastName":"Smith",
"email":"jsmith@mail.com",
"phone":"2129856472",
"street1":"12 Main St",
"street2":"5th Ave",
"city":"New York",
"state":"NY",
"zipCode":"31904",
"countryCode":"US"
}
2) Adding the customer's credit card.
Method: PUT
Path: [version]/customers/[customer-id]/[payment-options]/~create
Value Name
isActive true
holderName John Smith
code card1
type VC
accountNumber 4111111111111111
accountAccessory 0422
csc 111
street1 233 12th Street
street2 5th Ave
city New York
state NY
zipCode 11111
countryCode US 
{
"isActive":"true",
"holderName":"John Smith",
"code":"card1",
"type":"VC",
"accountNumber":"4111111111111111",
"accountAccessory":"0422",
"csc":"111",
"street1":"233 12th Street",
"street2":"5th Ave",
"city":"New York",
"state":"NY",
"zipCode":"11111",
"countryCode":"US"
}
3) Adding a fixed term subscription for 12 payments based on the previously created pricing plan (Advanced monthly plan for $49.99).

Note: the billing cycle starts by default on the next day after the subscription is created. If you want the billing cycle to start from a specific date in the future, it should be defined in the firstBillingDate parameter in the request.
Method: PUT
Path: [version]/customers/[customer-id]/[subscriptions]/~create
Value Name
code subscription1
paymentOptionId *card1
planId *advanced_monthly
type F
length 12
firstBillingDate 2024-06-01
amount 4999
note Subscription for 12 payments 
{
"code":"subscription1",
"paymentOptionId":"*card1",
"planId":"*advanced_monthly",
"type":"F",
"length":"12",
"firstBillingDate":"2024-06-01",
"amount":"4999",
"note":"Subscription for 12 payments"
}
4) Creating an invoice for downpayment.
Method: PUT
Path: [version]/customers/[customer-id]/[transactions]/~create
Value Name
code invoice1
type RI
amount 4999 
{
"code":"invoice1",
"type":"RI",
"amount":"4999"
}
5) Collecting downpayment.
Method: PUT
Path: [version]/customers/[customer-id]/[transactions]/~create
Value Name
code payment1
type AP
accountType K
amount 4999 
{
"code":"payment1",
"type":"AP",
"accountType":"K",
"amount":"4999"
}
1) Creating a new customer.
Method: PUT
Path: [version]/[customers]/~create
Value Name
accountId 2001
code customer1
isActive true
organizationName Organization LLC
firstName John
lastName Smith
email jsmith@mail.com
phone 2129856472
street1 12 Main St
street2 5th Ave
city New York
state NY
zipCode 31904
countryCode US 
<customer
    accountId = "2001" 
    code = "customer1" 
    isActive = "true" 
    organizationName = "Organization LLC" 
    firstName = "John" 
    lastName = "Smith" 
    email = "jsmith@mail.com" 
    phone = "2129856472" 
    street1 = "12 Main St" 
    street2 = "5th Ave" 
    city = "New York" 
    state = "NY" 
    zipCode = "31904" 
    countryCode = "US" 
/>
2) Adding the customer's credit card.
Method: PUT
Path: [version]/customers/[customer-id]/[payment-options]/~create
Value Name
isActive true
holderName John Smith
code card1
type VC
accountNumber 4111111111111111
accountAccessory 0422
csc 111
street1 233 12th Street
street2 5th Ave
city New York
state NY
zipCode 11111
countryCode US 
<payment-option
    isActive = "true" 
    holderName = "John Smith" 
    code = "card1" 
    type = "VC" 
    accountNumber = "4111111111111111" 
    accountAccessory = "0422" 
    csc = "111" 
    street1 = "233 12th Street" 
    street2 = "5th Ave" 
    city = "New York" 
    state = "NY" 
    zipCode = "11111" 
    countryCode = "US" 
/>
3) Adding a fixed term subscription for 12 payments based on the previously created pricing plan (Advanced monthly plan for $49.99).

Note: the billing cycle starts by default on the next day after the subscription is created. If you want the billing cycle to start from a specific date in the future, it should be defined in the firstBillingDate parameter in the request.
Method: PUT
Path: [version]/customers/[customer-id]/[subscriptions]/~create
Value Name
code subscription1
paymentOptionId *card1
planId *advanced_monthly
type F
length 12
firstBillingDate 2024-06-01
amount 4999
note Subscription for 12 payments 
<subscription
    code = "subscription1" 
    paymentOptionId = "*card1" 
    planId = "*advanced_monthly" 
    type = "F" 
    length = "12" 
    firstBillingDate = "2024-06-01" 
    amount = "4999" 
    note = "Subscription for 12 payments" 
/>
4) Creating an invoice for downpayment.
Method: PUT
Path: [version]/customers/[customer-id]/[transactions]/~create
Value Name
code invoice1
type RI
amount 4999 
<transaction
    code = "invoice1" 
    type = "RI" 
    amount = "4999" 
/>
5) Collecting downpayment.
Method: PUT
Path: [version]/customers/[customer-id]/[transactions]/~create
Value Name
code payment1
type AP
accountType K
amount 4999 
<transaction
    code = "payment1" 
    type = "AP" 
    accountType = "K" 
    amount = "4999" 
/>
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.