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. If you want to use it, you have to log into the panel and select the option “Direct Access“ in the settings (it can be turned on only by a super admin). After turning it on, the password, which will be needed to authorize in Direct Access, will be generated.

The communication in Direct Access takes place by REST via the POST method. The communication address is located in panel settings after logging to the super admin.

Available requests:

authenticate

The operation is used to verify the payer. In reply it generates the token to communicate further. The token is valid for 25 hours. The recommended replacement every 24 hours.

Required JSON:

{
    "wui": "<merchant_app_name>",
    "directAccessPassword": "<direct_access_password>"
}

Request parameters:

Name	Type	Description
wui	string	The name of seller’s application.	Required
directAccessPassword	string	The password to Direct Access.	Required

Examples of JSONs in response:

{
    "status": "SUCCESS",     
    "token": "eyJsbGciOiJIUsI1NiIsInR5cCI6IkpXSGJ9.ey deOYW1lIjoicHJhY29kYXdjYS14eXoiLCJEaXJlY3RBY2Nlc3NQYXNzd29yZCI6ImdWNXoydXVHNVVnVDV6MnVGYWR5Z1Y1ejJ2VUN1UiIsImlhdCI6MTQ3NjA5sjQ2MSwiZXhwIjoxNDc2MTgyODYxfQ.G4aG14pVdqDnVqrbQAdXvxBpH8O8JRU84lN2Bu-4bDc"
}

{
    "status": "ERROR",
    "err": "ERR_WRONG_PARAMETERS"
}

Response parameters:

Name	Type	Description
status	string	The request status. Possible replies: “SUCCESS” or “ERROR”.
token	string	Token used to verify in another requests. It is valid for one day.
err	string	Error type.

Possible errors:

Error	Description
ERR_WRONG_PARAMETERS	Wrong parameters.
ERR_DATABASE	Database-related problem.
ERR_WUI_NOT_VALID	The function of Direct Access is turned off, or the password/name of seller’s application is invalid.

addNewList

The operation is used to create a new active list and to add payouts in it.

Required JSON:

    {
        "token": "<received_token>",
        "listName": "<new_list_name>",
        "currency": "<currency_ISO>",
        "payments": [
            {
                "userName": "<recipient_name>",
                "phoneNumber": "<phone_number>",
                "firstName": "<recipient_first_name>",
                "lastName": "<recipient_last_name>",
                "email": "<email>",
                "amount": "<amount>",
                "startDate": "<start_date_YYYY-MM-DD hh:mm:ss>",
                "endDate": "<end_date_YYYY-MM-DD hh:mm:ss>",
                "referenceId": "<reference_Id>",
                "description": "<description>"
            },
            {
                "userName": "<recipient_name>",
                "phoneNumber": "<phone_number>",
                "firstName": "<recipient_first_name>",
                "lastName": "<recipient_last_name>",
                "email": "<email>",
                "amount": "<amount>",
                "startDate": "<start_date_YYYY-MM-DD hh:mm:ss>",
                "endDate": "<end_date_YYYY-MM-DD hh:mm:ss>",
                "referenceId": "<reference_Id>",
                "description": "<description>"
            }
        ],
       "sendNotification": "<boolean>"
    }

Request parameters:

Name	Type	Description
token	string	Verifying token.	Required
listName	string	New list name.	Required
currency	string	The currency in the ISO 4217 format.	Required
payments	array	The list of payouts to be added.	Required
sendNotification	boolean	Informs if the notification about payouts are about to be sent. It works only if the notification function is active. In default settings it is set as false.	Optional

Parameters of payments:

Name	Type	Description
userName	string	Recipient’s username.	Required if we identify the recipients by name
phoneNumber	string	Recipient’s phone number.	Required if we identify the recipients by phone number
firstName	string	Recipient’s first name.	Optional
lastName	string	Recipient’s last name.	Optional
email	string	Recipient’s email address.	Optional
amount	string	Amount to receive.	Required
startDate	string	Początek ważności odbioru wynagrodzenia.	Optional
endDate	string	Koniec ważności odbioru wynagrodzenia.	Optional
referenceId	string	Payout ID assigned by the employer	Optional
description	string	Description for the payout	Optional

Examples of JSONs in response:

    {
        "status": "SUCCESS",
        "payments": [
            {
                "username": "receiver001",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            },
            {
                "username": "receiver002",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            }
        ],
        "notificationStatus": "SUCCESS",
    }

{
    "status": "ERROR",
    "err": "ERR_PAYMENT_DATA"
    "additionalInfo": {
       "sentDataErrors": [
          {
             "paymentNumber": 0,
             "username": "receiver001",
             "phoneNumber": "",
             "errors": [
                {
                   "column": "Amount",
                   "errorMessage": "WARNING_INVALID_AMOUNT"
                }
             ]
          }
       ],
       "wrongMultiplyUsers": [],
       "usersWithDifferentData": [],
       "usersWithLimitOfPaymentAmountExceeded": []
    }
}

    {
        "status": "SUCCESS",
        "payments": [
            {
                "username": "receiver001",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            },
            {
                "username": "receiver002",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            }
        ],
        "notificationStatus": "WARNING",
        "err": "ERR_NOTIFICATION_SENDING",
        "additionalInfo": {
                  paymentsWithNotSentNotifications: [
              {
                  "userName": "receiver001",
                  "phoneNumber": "",
                  "amount": "100",
                  "referenceId": "",
                  "error": "sendByEmailFailed"
              }
           ],
           usersWithNotSentNotifications: [
              {
                  "userName": "receiver002",
                  "phoneNumber": "",
                  "error": "noEmail"
              }
           ],
        }
    }

Response parameters:

Name	Type	Description
status	string	Request status. Possible replies are: ‘SUCCESS’ i ‘ERROR’.
payments	array	List of added payments with the assigned ‘unifiedPaymentId’.
notificationStatus	string	Status of sending the notifications. Possible replies are: ‘SUCCESS’, ‘DISABLED’ i ‘WARNING’.
err	string	Error type.
additionalInfo	string	Additional information.

Possible errors:

Error	Description
ERR_WRONG_PARAMETERS	Wrong parameters.
ERR_DATABASE	Database-related problem.
ERR_TOKEN_IS_NOT_VALID	Invalid token.
ERR_PAYMENT_LIST_NAME_IS_TAKEN	The payment list name is taken.
ERR_PAYMENT_DATA_IS_EMPTY	‘payments’ array is empty.
ERR_PAYMENT_DATA	There are errors in ‘payments’ array.
ERR_NOTIFICATION_SENDING	There are problems with sending some of the notifications. Note: the list and payouts has been added successfully.

AdditionalInfo of the error ERR_PAYMENT_DATA:

{
   "sentDataErrors": [
      {
         "paymentNumber": 0,
         "username": "receiver001",
         "phoneNumber": "",
         "errors": [
            {
               "column": "Amount",
               "errorMessage": "WARNING_INVALID_AMOUNT"
            }
         ]
      }
   ],
   "wrongMultiplyUsers": [],
   "usersWithDifferentData": [],
   "usersWithLimitOfPaymentAmountExceeded": []
}

Parameters:

Name	Type	Description
sentDataErrors	array	Includes information which data in the payout is invalid.
wrongMultiplyUsers	array	The list of users who are added in the “payments“ array more than once, but their data is not compliant.
usersWithDifferentData	array	The list of users who have different data than those saved in the panel (the users were earlier added to the panel).
usersWithLimitOfPaymentAmountExceeded	array	The list of users who exceeded the limit of payout amount.

Parameters of sentDataErrors:

Name	Type	Description
paymentNumber	number	The number informing which payout includes errors.
username	string	User name.
phoneNumber	string	User phone number.
errors	array	The number of errors in the payout.

Parameters of errors:

Name	Type	Description
column	string	Informs which of the parameters in the payout is invalid.
errorMessage	string	Error message.

Possible errors in errors:

Error	column	Description
WARNING_FIELD_CANNOT_BE_EMPTY	UserName / PhoneNumber	A field cannot be empty.
WARNING_INCLUDES_FORBIDDEN_CHARS	UserName	A field includes forbidden symbols.
WARNING_SUPERADMIN_CANNOT_BE_RECIPIENT	UserName	Superadmin cannot be a recipient.
WARNING_WRONG_PHONE_NUMBER	PhoneNumber	Phone number is invalid.
WARNING_PHONE_NUMBER_IS_TAKEN	PhoneNumber	Phone number is taken by another user. (identification by the user name)
WARNING_USERNAME_IS_TAKEN	UserName	User name is taken by another user. (identification by the user phone number)
WARNING_FORBIDDEN_CHARS_OR_DIGITS_IN_FIRST_NAME	FirstName	User first name includes forbidden symbols.
WARNING_FORBIDDEN_CHARS_OR_DIGITS_IN_LAST_NAME	LastName	User last name includes forbidden symbols.
WARNING_INVALID_EMAIL_ADDRESS	Email	Invalid email address.
WARNING_INVALID_AMOUNT	Amount	Invalid amount.
WARNING_INVALID_DATE	StartDate / EndDate	Invalid date.
WARNING_INVALID_DATE_FORMAT	StartDate / EndDate	Invalid date format.
WARNING_END_DATE_CANNOT_BE_PAST	EndDate	The end date cannot be past.
WARNING_START_DATE_HAS_TO_BE_EALIER	StartDateAndEndDate	The start date has to be earlier than the end date.

AdditionalInfo of the error ERR_NOTIFICATION_SENDING:

{
   paymentsWithNotSentNotifications: [
      {
         "userName": "receiver001",
         "phoneNumber": "",
         "amount": "100",
         "referenceId": "",
         "error": "sendByEmailFailed"
      }
   ],
   usersWithNotSentNotifications: [
      {
         "userName": "receiver002",
         "phoneNumber": "",
         "error": "noEmail"
      }
   ],
}

Parameters:

Name	Type	Description
paymentsWithNotSentNotifications	array	The list of payouts with unsent notifications. (error related with text message/email)
usersWithNotSentNotifications	array	The list of users who were not sent the notifications due to the lack of data.

Parameters of paymentsWithNotSentNotifications:

Name	Type	Description
userName	string	User name.
phoneNumber	string	User phone number.
amount	string	The payout amount.
referenceId	string	Reference ID number.
error	string	Error.

Parameters of usersWithNotSentNotifications:

Name	Type	Description
userName	string	User name.
phoneNumber	string	User phone number.
error	string	Error.

Possible errors in paymentsWithNotSentNotifications:

Error	Description
sendBySmsFailed	Text message could not be sent.
sendByEmailFailed	Email could not be sent.

Possible errors in usersWithNotSentNotifications:

Error	Description
noPhoneNumber	Phone number missing.
noEmail	Email address missing.

addPaymentsToDefault

The operation is used toadd payouts to default list.

Required JSON:

    {
        "token": "<received_token>",
        "payments": [
            {
                "userName": "<recipient_name>",
                "phoneNumber": "<phone_number>",
                "firstName": "<recipient_first_name>",
                "lastName": "<recipient_last_name>",
                "email": "<email>",
                "amount": "<amount>",
                "startDate": "<start_date_YYYY-MM-DD hh:mm:ss>",
                "endDate": "<end_date_YYYY-MM-DD hh:mm:ss>",
                "referenceId": "<reference_Id>",
                "description": "<description>"
            },
            {
                "userName": "<recipient_name>",
                "phoneNumber": "<phone_number>",
                "firstName": "<recipient_first_name>",
                "lastName": "<recipient_last_name>",
                "email": "<email>",
                "amount": "<amount>",
                "startDate": "<start_date_YYYY-MM-DD hh:mm:ss>",
                "endDate": "<end_date_YYYY-MM-DD hh:mm:ss>",
                "referenceId": "<reference_Id>",
                "description": "<description>"
            }
        ],
       "sendNotification": "<boolean>"
    }

Request parameters:

Name	Type	Description
token	string	Verifying token.	Required
payments	array	The list of payouts to be added.	Required
sendNotification	boolean	Informs if the notification about payouts are about to be sent. It works only if the notification function is active. In default settings it is set as false.	Optional

Examples of JSONs in response:

    {
        "status": "SUCCESS",
        "payments": [
            {
                "username": "receiver001",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            },
            {
                "username": "receiver002",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            }
        ],
        "notificationStatus": "SUCCESS",
    }

    {
        "status": "ERROR",
        "err": "ERR_PAYMENT_DATA",
        "additionalInfo": {
           "sentDataErrors": [
              {
                 "paymentNumber": 0,
                 "username": "receiver001",
                 "phoneNumber": "",
                 "errors": [
                    {
                       "column": "Amount",
                       "errorMessage": "WARNING_INVALID_AMOUNT"
                    }
                 ]
              }
           ],
           "wrongMultiplyUsers": [],
           "usersWithDifferentData": [],
           "usersWithLimitOfPaymentAmountExceeded": []
        }
    }

    {
        "status": "SUCCESS",
        "payments": [
            {
                "username": "receiver001",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            },
            {
                "username": "receiver002",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            }
        ],
        "notificationStatus": "WARNING",
        "err": "ERR_NOTIFICATION_SENDING",
        "additionalInfo": {
                  paymentsWithNotSentNotifications: [
              {
                  "userName": "receiver001",
                  "phoneNumber": "",
                  "amount": "100",
                  "referenceId": "",
                  "error": "sendByEmailFailed"
              }
           ],
           usersWithNotSentNotifications: [
              {
                  "userName": "receiver002",
                  "phoneNumber": "",
                  "error": "noEmail"
              }
           ],
        }
    }

Response parameters:

Name	Type	Description
status	string	Request status. Possible replies are: ‘SUCCESS’ i ‘ERROR’.
payments	array	List of added payments with the assigned ‘unifiedPaymentId’.
notificationStatus	string	Status of sending the notifications. Possible replies are: ‘SUCCESS’, ‘DISABLED’ i ‘WARNING’.
err	string	Error type.
additionalInfo	string	Additional information.

Possible errors:

Error	Description
ERR_WRONG_PARAMETERS	Wrong parameters.
ERR_DATABASE	Database-related problem.
ERR_TOKEN_IS_NOT_VALID	Invalid token.
ERR_PAYMENT_LIST_NAME_IS_TAKEN	The payment list name is taken.
ERR_PAYMENT_DATA_IS_EMPTY	‘payments’ array is empty.
ERR_PAYMENT_DATA	There are errors in ‘payments’ array.
ERR_NOTIFICATION_SENDING	There are problems with sending some of the notifications. Note: the list and payouts has been added successfully.

revokePayment

The operation is used to cancel the payout.

    {
        "token": "<received_token>",
        "unifiedPaymentId": "<unified_payment_Id>",
        "reason": "<revoke_reason>"
    }

Request parameters:

Name	Type	Description
token	string	Verifying token.	Required
unifiedPaymentId	string	Payout identifier.	Required
reason	string	Reason for the cancellation of the payout.	Required

    {
        "status": "SUCCESS",
        "listStatus": "DEACTIVATED",
    }

    {
        "status": "ERROR",
        "err": "ERR_PAYMENT_DATA"
    }

Response parameters:

Name	Type	Description
status	string	Request status. Possible replies are: ‘SUCCESS’ i ‘ERROR’.
listStatus	array	List status after cancellation of the payout. Possible replies are: ‘ACTIVATED’, ‘DEACTIVATED’ i ‘REVOKED’.
err	string	Error type.

Possible errors:

Error	Description
ERR_WRONG_PARAMETERS	Wrong parameters.
ERR_DATABASE	Database-related problem.
ERR_TOKEN_IS_NOT_VALID	Invalid token.
ERR_UNIFIED_PAYMENT_ID_IS_NOT_VALID	‘unifiedPaymentId’ is invalid.
ERR_NO_REASON	No reason for the cancellation of the payout.
ERR_PAYMENT_IS_REVOKED	The payout has been already revoked.
ERR_PAYMENT_IS_FINISHED	The payout has been already finished.
ERR_PAYMENT_IS_TRANSFERRING	The payout is in the process of transfer.

getPaymentStatus

The operation is used to check the status of a payout.

Required JSON:

    {
        "token": "<received_token>",
        "unifiedPaymentId": "<unified_payment_Id>"
    }

Request parameters:

Name	Type	Description
token	string	Verifying token.	Required
unifiedPaymentId	string	Payout identifier.	Required

Enums of ‘paymentStatus’:

Enum	Description
READY	The payout is ready to receive.
ON_HOLD	The payout is on hold.
REVOKED	The payout is revoked.
TRANSFERRING	The payout is in the process of transfer.
TRANSFERRED	The payout has been transferred.

Possible errors:

Error	Description
ERR_WRONG_PARAMETERS	Wrong parameters.
ERR_DATABASE	Database-related problem.
ERR_TOKEN_IS_NOT_VALID	Invalid token.
ERR_UNIFIED_PAYMENT_ID_IS_NOT_VALID	‘unifiedPaymentId’ is invalid.

Popup of receipt by bank transfer

You need to add a scripts ‘billon.js’ oraz ‘billon-salary-iframe.js’, which we can provide, to a page to run a popup to collect the salary by bank transfer. You need to call a function ‘billon.salaryIframe(<an object with the parameters>)’ in page code when clicking on the chosen HTML element with the following parameters:

address: the address of a page with popup, for example „https://wyplaty.billongroup.com/production/popup”, which we can prepare specifically
data: {
unifiedPaymentId: payment identifier
}
onClosed (optional): function called after a user closes popup

Available requests:

Popup of receipt by bank transfer

How can we help?