1. Home
  2. Web services
  3. Direct access to payout panel

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:

1.
{
    "status": "SUCCESS",     
    "token": "eyJsbGciOiJIUsI1NiIsInR5cCI6IkpXSGJ9.ey deOYW1lIjoicHJhY29kYXdjYS14eXoiLCJEaXJlY3RBY2Nlc3NQYXNzd29yZCI6ImdWNXoydXVHNVVnVDV6MnVGYWR5Z1Y1ejJ2VUN1UiIsImlhdCI6MTQ3NjA5sjQ2MSwiZXhwIjoxNDc2MTgyODYxfQ.G4aG14pVdqDnVqrbQAdXvxBpH8O8JRU84lN2Bu-4bDc"
}
2.
{
    "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:

1.
    {
        "status": "SUCCESS",
        "payments": [
            {
                "username": "receiver001",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            },
            {
                "username": "receiver002",
                "phoneNumber": "",
                "amount": "100",
                "unifiedPaymentId": ""
            }
        ],
        "notificationStatus": "SUCCESS",
    }
2.
{
    "status": "ERROR",
    "err": "ERR_PAYMENT_DATA"
    "additionalInfo": {
       "sentDataErrors": [
          {
             "paymentNumber": 0,
             "username": "receiver001",
             "phoneNumber": "",
             "errors": [
                {
                   "column": "Amount",
                   "errorMessage": "WARNING_INVALID_AMOUNT"
                }
             ]
          }
       ],
       "wrongMultiplyUsers": [],
       "usersWithDifferentData": [],
       "usersWithLimitOfPaymentAmountExceeded": []
    }
}
3.
    {
        "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:

1.

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

2.

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

3.

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

1.

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

2.

    {
        "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
Was this article helpful to you? Yes No

How can we help?