Payout panel is a system to manage the list of payouts. Contact with us if you are interested in it. Direct access is used to add lists outside panel.

Definitions

Backend address – URL of the API, it is delivered along with other general information.

Authentication password – password that is generated at activation of API integration, it is required to authenticate.

API Key – string that contains security credentials that allow to access API functions, it expires in 24 hours from creation.

API Usage

Communication with API takes place through REST requests sent to backend address. Before using other functions, API key must be obtained by authenticate function descripted in API specification. This key must me given in another request’s x-access-token header.

API integration activation

To start using Panel’s API, authorized admin user needs to go to General Settings and activate “API integration” switch, then copy “Authentication password”, it will be necessary to get access to API.

Errors

In case of error while performing request, API returns response containing information about error that occurred. It has following parameters:

Parameter	Data type	Example value	Description
error	object	n/a	Object containing information about error
error.message	string	One of required fields is empty!	Verbal description of error that occurred
error.type	string	INVALID_PARAMS	Type of error, possible values are listed in table below
errors	array	[]	It is not used in API integration

Possible types of error:

Type	Description
INVALID_PARAMS	One of required parameters is empty or given value is invalid
INSUFFICIENT_FUNDS	Panels account does not have enough funds to realize payout

Example response:

{
   "error": {
      "message":"One of required fields is empty!",
      "type": "INVALID_PARAMS"
   }, "errors": []
}

Dates and time zones

Dates should be passed in ISO or RFC2822 compatible format.

API specification

Authenticate

In order to use other API functions temporary API key must be obtained through this method. It is valid for 24 hours.

Method: POST

Address: /api/authenticate

Parameters:

Parameter	Data Type	Required	Example value	Description
apiKey	string	Yes	abc0123456789	Authentication password that can be found in general panel settings

Example request:

curl -X POST “http://paydev2.billon.tv:5006/api/authenticate” -H “accept: application/json” -H “Content-Type: application/json” -d “{ \”apiKey\”: \”1234567890\”}”

Response parameters:

Parameter	Data type	Example value	Description
token	string	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0	API Key required in another requests.

Example response:

{
   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0"
}

Possible types of error: INVALID_PARAMS

Create payout

This method allows to add new payout to panel. Request contains recipient data as well, if it does not exist it will be created based on this data. If project with this name does not exist it will be created.

Method: POST

Address: /api/payment/create

Headers:

x-access-token – API key obtained throught authenticate

Parameters:

Parameter	Data Type	Required	Example value	Description
amount	number	Yes	1	Amount to pay out
currency	string	Yes	GBP	Currency of payout
startDate	string	Yes	2018-01-01 12:00:00	Date from which payout is valid
endDate	string	Yes	2018-01-02 00:00:00	Date to which payout is valid
name	string	Yes	Project name	Name of project to which payout will be added
description	string	Yes	Payment description	Payout description
userName	string	One of userName, phoneNumber or referenceId	tester	Recipients username
phoneNumber	string		123456789	Recipients phone number
referenceId	string		1	Recipients reference number
firstName	string	No	test	Recipients first name
lastName	string	No	tester	Recipients last name
email	string	No	test@test.test	Recipients email address
notification	boolean	Yes	true	Whether recipient should receive notification about this payout

Example request:

curl -X POST “http://paydev2.billon.tv:5006/api/payment/create” -H “accept: application/json” -H “x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0” -H “Content-Type: application/json” -d “{ \”amount\”: 1, \”currency\”: \”GBP\”, \”startDate\”: \”2018-01-01 12:00:00\”, \”endDate\”: \”2018-01-02 00:00:00\”, \”name\”: \”Project name\”, \”description\”: \”Payment description\”, \”userName\”: \”tester\”, \”phoneNumber\”: “123456789”, \”referenceId\”: 1, \”firstName\”: “test”, \”lastName\”: “tester”, \”email\”: “test@test.test”, \”notification\”: true}”

Response parameters:

Parameter	Data type	Example value	Description
payments	array	nd.	Single element array containing created payout
payments[0].amount	number	1	Amount to pay out
payments[0].id	number	1	Payout id number
payments[0].currency	string	GBP	Currency of payout
payments[0].startDate	date	2018-01-01T12:00:00.000Z	Date from which payout is valid
payments[0].endDate	date	2018-01-02T00:00:00.000Z	Date to which payout is valid
payments[0].description	string	Payment description	Payout description
payments[0].notification	boolean	true	Whether recipient should receive notification about this payout
payments[0].status	string	READY	Status with which payout was created. Posible values: READY – Ready to be received UNAUTHORIZED – Awaits authorization
payments[0].recipientId	number	1	Recipient id number
payments[0].projectId	number	1	Project id number
payments[0].updatedAt	date	2018-01-01T00:00:00.000Z	Payouts last update date
payments[0].createdAt	date	2018-01-01T00:00:00.000Z	Payouts creation date

Example response:

{
   "payments": [
      {
         "amount": 1,
         "id": 1,
         "currency": "PLN",
         "startDate": "2018-01-01T12:00:00.000Z",
         "endDate": "2018-01-02T00:00:00.000Z",
         "description": "Payment description",
         "notification": true,
         "status": "READY",
         "recipientId": 1,
         "projectId": 1,
         "updatedAt": "2018-01-01T00:00:00.000Z",
         "createdAt": "2018-01-01T00:00:00.000Z"
      }
   ]
}

Possible types of error: INVALID_PARAMS, INSUFFICIENT_FUNDS

Cancel payout

This method allows to cancel existing payout. Cancelled payout cannot be received or be activated again. Cancelling of payout also releases funds blocked by it. This method returns number of payouts that were properly cancelled.

Method: POST

Address: /api/payment/cancel

Headers:

x-access-token – API key obtained throught authenticate

Parameters:

Parameter	Data Type	Required	Example value	Description
ids	array	Yes	[1,2,3]	Array containing id numbers of payments to cancel

Example request:

curl -X POST “http://paydev2.billon.tv:5006/api/payment/cancel” -H “accept: application/json” -H “x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiSldUIn0.1CWW9yelrYaVHB3CXYHJE0CkbMWlPUnSRCxOgjC_LT0” -H “Content-Type: application/json” -d “{ \”ids\”: [1,2,3]}”

Response parameters:

Parameter	Data type	Example value	Description
success	number	3	Number of payouts that were properly canceled

Example response:

{"success": 3}

Possible types of error: INVALID_PARAMS