Notification Service
If payment point is configured as Web Service, CashBill will communicate with shop using notification service.
URL for notification service must be configured in CashBill Control Panel.
Notification request consist no sensitive data and consists of:
- name of notification (
cmd) - attribute of notification (
args) - digital signature (
sign)
Each notification is sent as GET request with following variables:
| Variable | Description |
|---|---|
cmd | name of notification |
args | comma (“,”) separated attributes (for ex. orderId) |
sign | digital signature |
Digital Signature
sign = md5(cmd + args + secretKey)
MD5 is crypto hash function, with result presented as hexadecimal lowercase string.
Available Notification Requests
Name of request (cmd) | Example value (args) | Description |
|---|---|---|
transactionStatusChanged | aasd34sf | Status of transaction has changed. Attribute: ID of the transaction |
refundStatusChanged | aasd34sf,1,pending | Status of refund has changed. Attributes: transaction ID, refund number and refund status |
blikDeclinedEvent | aasd34sf,DECLINE_STATUS_CODE | Blik Level 0 decline code. Attributes: transaction ID and decline status code |
blikAliasEvent | asd34sf,{"aliasUid":"alias-uuid","type":"BLIK_ALIAS_STATUS"} | BLIK alias event. Attributes: transaction ID and alias event details in JSON format ( aliasUid, type) |
BLIK event codes are described in the BLIK section Alias Status Codes and Decline Status Codes.
Refund Status Notification
The refundStatusChanged notification is sent when the status of a refund has changed. It is delivered using the same mechanism as transaction notifications (same notification URL, same signature and the same response requirements).
| Attribute | Example value | Description |
|---|---|---|
trans_id | aasd34sf | transaction identifier |
refund_id | 1 | refund number |
refund_status | pending | status of refund |
Attributes are passed in args in the following order, separated by commas:
args = trans_id + "," + refund_id + "," + refund_status
Make sure your notification endpoint responds correctly to the refundStatusChanged notification (and to any unknown cmd) with OK. An invalid response causes the notification to be retried, which may generate additional load on your endpoint.
Response To Notification
The response body must contain exactly the uppercase characters OK without any additional content.
The following responses are treated as errors and cause the notification request to be repeated:
A notification is confirmed only when the HTTP status is 200 OK and the response body contains exactly two bytes: OK.
The body must be uppercase without spaces, line breaks, quotation marks, or any additional content.
| HTTP status | Response body | Accepted |
|---|---|---|
200 OK | OK | YES |
200 OK | Empty body | NO |
200 OK | ok, Ok, or oK | NO |
200 OK | OK (with spaces) | NO |
200 OK | OK followed by a line break | NO |
200 OK | "OK" (with quotation marks) | NO |
200 OK | {"status":"OK"} | NO |
200 OK | <html>OK</html> | NO |
Any status other than 200 | OK or any other body | NO |
Any response marked NO is treated as an error and the notification request will be repeated.
Returning another successful HTTP status, such as 201 Created, 202 Accepted, or 204 No Content, does not confirm receipt of the notification.
Notifications are retried at minute-based intervals, followed by hourly and daily intervals, for up to few days. An incorrect response may increase traffic to your notification endpoint due to repeated requests for each transaction.
Example Notification
Transaction status change:
https://shop_url.com/?cmd=transactionStatusChanged&args=asd34sf&sign=c8143d45bf2f76fd38a6a9d77feb1a79
Refund status change:
https://shop_url.com/?cmd=refundStatusChanged&args=asd34sf%2C1%2Cpending&sign=c8143d45bf2f76fd38a6a9d77feb1a79
Custom notification URL for each shop can be settled in CashBill Control Panel.