Direct access to payout panel

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

Was this article helpful to you? Yes No 1

How can we help?