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