CashBill Payments API
To use REST API payment point should be configured as “Web Service”.
REST service is available at:
https://pay.cashbill.pl/ws/rest/
Testing can be performed using:
https://pay.cashbill.pl/testws/rest/
On every successful request service returns application/json with HTTP 200. In case of error, reply consists of HTTP status code with details in response body.
Digital Signature (Authentication)
Digital signature can be generated by concatenation of request data with secret key, obtainable in CashBill Control Panel.
Used crypto hash function is SHA1, with result presented as hexadecimal lowercase string.
Error Response
Every error response returns application/json with http status of error. JSON response contains errorMessage key with more informations about error reason.
ex.
# HTTP 401 Unauthorized
{
"errorMessage" : "Illegal signature"
}
# HTTP 400 Bad Request
{
"errorMessage" : "sign is required field"
}
Notification Service
If payment point is configured as Web Service, CashBill Online Payments will communicate with shop using notification service. URL for notification service must be configured in CashBill Control Panel. Notification service can use HTTP or HTTPS protocol. Notification request consist no sensitive data, and consists of:
- name of notification
- attribute of notification
- digital signature
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 | Description |
|---|---|
| transactionStatusChanged | Status of transaction has changed. Attribute: ID of the transaction in question |
Response To Notification
Reception of request is confirmed by HTTP/200 OK status code, with body consisting of two bytes OK.
Any other reply will be treated as error, and request will be repeated.
Example Notification
https://shop_url.com/?cmd=transactionStatusChanged&args=asd34sf&sign=c8143d45bf2f76fd38a6a9d77feb1a79
Custom notification URL for each shop can be settled in CashBill Control Panel.
Available Transaction Statuses
| Status | Description |
|---|---|
| PreStart | Payment has been started. Customer has not yet choosen payment channel. |
| Start | Payment has been started. Customer has not yet paid. |
| NegativeAuthorization | Payment Channel has refused payment (ie. insufficient funds). |
| Abort | Customer has aborted the payment. |
| Fraud | Payment Channel has refused payment and classified is as fraudant. This is a final status and cannot change. |
| PositiveAuthorization | Payment Channel has accepted transaction for processing. |
| PositiveFinish | Payment Channel has confirmed transfer of funds. This is a final status and cannot change. |