1.13.8 Web API

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:

For payments with credit card the following fields are required:

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

 Example

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.

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

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

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

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).

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.

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

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

getCreditCardProviders

Returns information about available credit card type providers.

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

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

getSystemProviders

Returns information about available system providers.

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

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

getAmounts

Returns information about available amounts.

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

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

isEmailAvailable

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

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

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

isMobilePhoneAvailable

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

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

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

isLoginAvailable

Checks if the login is not used.

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

{
    "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

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

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

canStoreCreditCard

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

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

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

getStoredCreditCard

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

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

{
    "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

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

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

CheckAndFinalize

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

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

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

Finalize

 Changes transaction status according to the passed parameter.

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

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

GetSubscriptionInfo

 Returns information according to the passed transactionId.

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

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

<!-- List of semicolon separated IPs. Subnet mask is allowed. -->

    <add key="CreditCardApiAllowedIPs" value=""/>

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.

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

{
    "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.

{
    "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
    }
}

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

DeleteCard

Deleted credit card data

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

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

ChargeSavedCard

Makes recharge using stored credit card data

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

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

ChargeCard

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

{
    "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",
 
    }
}

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

Ping

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

{
    "operation": 6
}

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