The onlineshop provides web services which allow for integration with 3^rd party software. For example if you want to connect existing website or self-care portal and allow clients to utilize the same payment related features as those available in our family of products (VUP and softphones). The web services are divided into three subsystems:

Payments API – methods related to recharging client accounts through predefined payment providers
Credit card API – managing the credit card details
Common API – methods handling balance transfer, IMTU and other functionalities

Payment API

The payment API provides an URL for making online payments. By default it is located at https://domain/OnlineShop/Pay.aspx

The HTTP Secure protocol should be used to protect the sensitive client data.

The request’s parameters have to be sent using POST method. Below are the mandatory, general parameters:

Parameter	Description	Example
x_payment	payment provider name	PayPalStandardProvider
x_type	client type	32
x_amount	transaction amount	5.50
x_login	user name	johndoe

For payments with credit card the following fields are required:

Parameter	Description	Example
x_cvd	credit card secure code	111
x_creditcardnr	credit card number	1111111111111111
x_expiremonth	credit card expiry month	01
x_expireyear	credit card expiry year	2020

For every provider there is a list of specific mandatory and optional fields as below:

Provider	Parameters
CrediMaxProvider	Amount FirstName LastName Country State Zip City Address Email
MoneyBookersProvider	Amount FirstName LastName Country State Zip City Address Email
CashUProvider	Amount FirstName LastName Country State Zip City Address Email
BarclayProvider	Amount FirstName LastName Country State Zip City Address Email
PayPalStandardProvider	Amount Email
GoogleCheckoutProvider	Amount Email
IPay88Provider	Amount PaymentMethod FirstName LastName Country Phone MobilePhone State Zip City Address Email

Example

<form method="POST" action="https://domain/OnlineShop/Pay.aspx">

<input type="hidden" name="x_payment" value="PayPalStandardProvider" />

<input type="hidden" name="x_type" value="32" />

<input type="hidden" name="x_amount" value="12.20" />

<input type="hidden" name="x_login" value="johndoe" />

<input type="hidden" name="x_email" value="john@doe.com" />

<input type="submit" />

</form>

Common API

This API provides a set of auxiliary methods related to online payments.

The API uses the JSON RPC 2.0 specification. In short the JSON RPC relies on sending HTTP POST requests to the same URL and specifying the requested functionality in the enclosed JSON data. Also the responses contain data in JSON format.

Request

{
	"jsonrpc" : "2.0"
	"id" : 1,
	"method" : "methodName"
	"params" : {},
}

Success Response

{
	"jsonrpc" : "2.0",
	"id" : 1,
	"result" {}
}

Failed Response

{
	"jsonrpc" : "2.0",
	"id" : 1,
	"error" :
	{
		"code" : -1,
		"message" : "",
		"data" :
		{
			"errorNumber" : ""
		}
	}
}

Name	Type	Description
jsonrpc	String	Indicates version of JSON RPC. Should be always "2.0".
id	Integer	Identifies request and can be used to recognize response if methods are called asynchronously. May be any valid integer value.
method	String	Method name.
params	Object	Object containing plain parameters or more complex objects.
result	Object	Contains result of the method execution and is present only for successful requests. If this parameter is present and is not null then request was successful.
error	Object	Contains error description. If this parameter is present and is not null it means that the request failed.
code	Integer	Contains error code that uniquely identifies error reason. It is always below 0.
message	String	Description of the error reason.
data	Object	Contains additional error informations.
errorNumber	String	Unique error number (requests that failed with the same error code will generate different error numbers). This number should be presented when contacting with support.

Sending requests

The default URL for sending requests is https://domain/OnlineShop/common.api

Every request must be authenticated with basic authentication procedure in which the username (client login) and password are sent in the request header.

The id parameter doesn't have to be unique. If you are not using id in response you may always pass 0 or 1.

After receiving a response check first if successful before deserializing the result. The successful responses always contain result parameter.

The code parameter can be used to define or retrieve the error description to be shown to the user. The message parameter is intended for developers only.

Data types

Following table describes simple data types (more complex objects are desribed in 'Methods Reference' section).

Type name	Example	Notes
Integer	23454
String	"Desription"
Boolean	true	true or false First letter must be lowercase.
DateTime	2012-01-23T12:45:23+01:00	Date and/or time value as desribed in ISO 8601 standard. For a quick reference full allowed format is YYYY-MM-DDThh:mm:ss±hh:mm.
Object	{"login" : "testClient"}	A complete object containing simple data types or another objects.
Array	["one", "two"]	Array of simple data types, objects or arrays.
Decimal	23.45	Decimal part is separated with dot '.'.

Paged request and response

Some of the methods return paged data. In that case the request parameters include paging object and a filter object. Respones include the totalCount integer indicating the total number of records counted without paging and the records which is an array of objects. Response will not contain information about the current page or page size. This information should be stored on the client side if needed. Exceeding pages range does not produce error. Instead, the records object will be empty.

Methods

Below is the list of the available methods:

getOnlineProviders
getCreditCardProviders
getSystemProviders
getAmounts
isEmailAvailable
isMobilePhoneAvailable
isLoginAvailable
isCreditCardStored
canStoreCreditCard
getStoredCreditCard
balanceTransfer
CheckAndFinalize
Finalize
GetSubscriptionInfo
system.listMethods
system.version
system.about

getOnlineProviders

Returns information about available (enabled) payment providers.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "getOnlineProviders",
    "params" : null
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" :
    [
        {
            "name" : "",
            "shortName" : "",
            "caption" : "",
            "description" : "",
            "imageUrl" : "",
        }
    ]
}

getCreditCardProviders

Returns information about available credit card type providers.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "getCreditCardProviders",
    "params" : null
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : 
    [
        {
            "name" : "",
            "shortName" : "",
            "caption" : "",
            "description" : "",
            "imageUrl" : "",
        }
    ]
}

getSystemProviders

Returns information about available system providers.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "getSystemProviders",
    "params" : null
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : 
    [
        {
            "name" : "",
            "shortName" : "",
            "caption" : "",
            "description" : ""
        }
    ]
}

getAmounts

Returns information about available amounts.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "getAmounts",
    "params" :
    {
        "create" : false,
        "clientType" : 32
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : 
    [
    ]
}

isEmailAvailable

Checks if the email address is not used (by another user)

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "isEmailAvilable",
    "params" :
    {
        "email" : "",
        "clientType" : 32
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : true
}

isMobilePhoneAvailable

Checks if the mobile phone number is not used already (by another user).

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "isMobilePhoneAvailable",
    "params" :
    {
        "mobilePhone" : "",
        "clientType" : 32
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : true
}

isLoginAvailable

Checks if the login is not used.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "isLoginAvailable",
    "params" :
    {
        "login" : ""
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : true
}

isCreditCardStored

Checks if the credit card details are stored and can be used to recharge. NOTE: Authorization: Basic login:password

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "isCreditCardStored",
    "params" : null
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : true
}

canStoreCreditCard

Checks if the credit card can be stored for further usage. NOTE: Authorization: Basic login:password

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "canStoreCreditCard",
    "params" : null
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : true
}

getStoredCreditCard

Returns stored credit card data. Card number and CVV is encrypted. NOTE: Authorization: Basic login:password

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "getStoredCreditCard",
    "params" : null
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" :
    {
        "code" : "",
        "month" : "",
        "year" : "",
        "number" : "",
        "city" : "",
        "country" : "",
        "firstName" : "",
        "lastName" : "",
        "state" : "",
        "street" : "",
        "zip" : "",
    }
}

balanceTransfer

Makes balance transfer between users. NOTE: Authorization: Basic login:password

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "balanceTransfer",
    "params" :
    {
        "fromLogin": "",
        "fromPassword": "",
        "toLogin": "",
        "amount": 0
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : 0
}

CheckAndFinalize

Checks the transaction result with the provider and finalizes transaction depending on the result.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "CheckAndFinalize",
    "params" :
    {
        "transactionId": 0,
        "userId": 0,
        "module": "",
        "signature": ""
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : 0
}

Finalize

Changes transaction status according to the passed parameter.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "Finalize",
    "params" :
    {
        "transactionId": 0,
        "status": "",
        "userId": 0,
        "module": "",
        "signature": ""
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : 0
}

GetSubscriptionInfo

Returns information according to the passed transactionId.

Request

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "GetSubscriptionInfo",
    "params" :
    {
        "transactionId": 0
    }
}

Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" :
    {
        "IsActive": true,
        "DateTimeFormat": "yyyy-MM-dd HH:mm:ss",
        "StartTimeFormatted": "2015-01-01 00:00:00",
        "EndTimeFormatted": "2020-12-31 23:59:59",
    }
 }

Response statuses

0 - OK
1 - Wrong operation type
2 - Stored credit card not found
3 - Unspecified error (check log)
4 - Invalid JSON request format (probably missing something, e.g. a name)
5 - Credit card provider is not available or misconfigured.
6 - Failed to save credit card information on provider side.
7 - Provider does not allow storing credit card information.
8 - Unable to delete credit card data on provider server.
9 - Provider does not allow saving credit card information.
10 - Your transaction failed. The card could not be charged by the provider
11 - Your transaction failed. X is the exact error code returned by a given provider
12 - Wrong username or password

Credit card API

This API provides methods for credit cards related operations. They can be utilized by external systems integrating with voipswitch platform. . The API is also used internally within the platform by the Event manager’s autorecharge function.

The API can be accessed only from the IP addresses defined in the AppSettings.config file in the following section:

The web service is built using the HTTP REST architecture.

The URL for sending request is https://domain/OnlineShop/cc.ashx

Methods

The methods available in the API cc.ashx:

GetCard = 1
SaveCard = 2
DeleteCard = 3
ChargeSavedCard = 4
ChargeCard = 5
Ping = 6

GetCard

Returns credit card data, only the last few digits are shown, the other digits are masked with '*', security code and expiry date of the card are not returned for security reasons.

Request

{
    "operation" : 1,
    "isReseller" : false
}

Response

{
    "status" : 0,
    "message" : "",
    "data" :
    {
        "CardNumber" : "37**********0012",
        "FirstName" : "First Name",
        "LastName" : "Last Name",
        "Street" : "Street",
        "City" : "City",
        "Country" : "Country",
        "State" : "State",
        "Zip" : "Zip",
        "Zip" : "Zip",
        "Amount" : 10.5,
        "LowAmount" : 5.5,
        "UseAutoRecharge" : true,
        "UseRecurringPayments" : true
    }
}

SaveCard

Saves credit card data.

Request

{
    "operation" : 2,
    "isReseller" : false,
    "data" :
    {
        "CardNumber" : "3700000000000012",
        "CardCode" : "123",
        "ExpiryMonth" : "01",
        "ExpiryYear" : "12",
        "FirstName" : "First Name",
        "LastName" : "Last Name",
        "Street" : "Street",
        "City" : "City",
        "Country" : "Country",
        "State" : "State",
        "Zip" : "Zip",
        "Amount" : 10.5,
        "LowAmount" : 5.5,
        "UseAutoRecharge" : true,
        "UseRecurringPayments" : true
    }
}

Response

{
    "status" : 0
    "message" : ""
}

DeleteCard

Deleted credit card data

Request

{
    "operation" : 3,
    "isReseller" : false
}

Response

{
    "status" : 0
    "message" : ""
}

ChargeSavedCard

Makes recharge using stored credit card data

Request

{
    "operation" : 4,
    "isReseller" : false,
    "amount" : 10.5
}

Response

{
    "status" : 0
    "message" : ""
}

ChargeCard

Makes recharge using provided credit card data but does NOT save that card in the database.

Request

{
    "operation": 5,
    "isReseller": false,
    "amount": 10.5,
    "data": {
        "CardNumber": "3700000000000012",
        "CardCode": "123",
        "ExpiryMonth": "01",
        "ExpiryYear": "12",
        "FirstName": "First Name",
        "LastName": "Last Name",
        "Street": "Street",
        "City": "City",
        "Country": "Country",
        "State": "State",
        "Zip": "Zip",
 
    }
}

Response

{
    "status" : 0
    "message" : ""
}

Ping

Returns if API is properly configured and ready to process requests.

Request

{
    "operation": 6
}

Response

{
    "status" : 0
    "message" : ""
}

Browser not supported