eCards
Introduction
Bovertis Resolut eCard server provides services for loyalty card, prepaid gift cards and credit gift cards over internet.
A test environment is available and Bovertis can provide barcodes for testing.
Functional description
Giftcard description
The gift card contains a unique barcode and optional a security (or pin) code behind a scratch layer. The security code is used for card non-present environments like web shops.
The barcode is scannable on a point of sale system, below the barcode digits are printed that should be entered when using the gift card in a web shop environment.
The gift card is branded and has a unique identifier equals to credit card brands like AMEX, Eurocard, VISA or DINERS.
Per brand is configured which clients (logins) are allowed to accept the brand.
The brand is returned in the payment response.
Security
The test and productional environment accept connections from specific IP addresses, so keep in mind a change of IP address would cause malfunction of the service.
Bovertis eCard server monitors activities to detect tamper (brute force attempt to find valid barcodes). In case of tamper the incoming IP address will be blocked. The user of our webservice should prevent automated scripts or other methods that allows unlimited calls to our webservice.
Session token
It is advised to use a session token in the webservice calls when card is used in non-present environments, this will help the eCard server to detect tampers on user/session level.
Good session tokens are shopping card transaction ID, IP address or username of the visitor, or other session token that belongs to the session of the visitor.
Do not use session tokens that are unique on every call like GUIDs, date/time stamps and do not use session tokens that are shared between visitors.
If no session token is used all attempts are counted towards the IP address, this would quicker block an IP address if some tamper is detected.
Configuration
It is recommended that the login token and URL of the webservice are configurable in your application i.e. in the App.config or other external repository.
Technical description
All our web services are using HTTPS protocol.
Service result codes
| Result codes | |
|---|---|
| 0 | Successful – successful operation result |
| 1 | Failed - general operation failure |
| 2 | UnknownToken - invalid gift card barcode |
| 3 | InvalidToken - invalid gift card |
| 4 | OutOfBalance – card is out of balance |
Result message
The web service expects a correct request parameters and replies with a result message of type CardResult or TransactionResult.
CardResult
The response message is returned for GetCard web service method. CardResult contains gift card details information. Response message has the following fields.
| Result message | ||
|---|---|---|
| Result | enum | See service result codes in 4.1 |
| CardName | string | Card`s brand name |
| Balance | decimal | Current card balance |
| AccountId | int | Card is assigned to some account. This is ID of the account. |
| AccountName | string | Name of the account which card is assigned to |
| DepartmentId | string | Department ID or 0 if department is not assigned |
| DepartmentName | string | Department name or empty string |
| ErrorMessage | string | Error message details in case of failure |
| ErrorException | string | Additional exception details for logging purposes |
TransactionResult
The response message is returned for other web service methods. Response message has the following fields.
| Result message | ||
|---|---|---|
| Result | enum | See service result codes in 4.1 |
| TransactionId | int | ID of the transaction |
| Balance | decimal | Current card balance |
| Amount | decimal | Transaction amount |
| AccountId | int | Card is assigned to some account. This is ID of the account. |
| AccountName | string | Name of the account which card is assigned to |
| CardName | string | Card`s brand name |
| DepartmentId | string | Department ID or 0 if department is not assigned |
| DepartmentName | string | Department name or empty string |
| ErrorMessage | string | Error message details in case of failure |
| ErrorException | string | Additional exception details for logging purposes |
Webservice methods
Fields that must be filled are marked as mandatory others are optional depending on web service method.
| Legend | |
|---|---|
| X | Mandatory |
| O | Optional |
GetCard
This method is used to get the card balance information and it returns also other card details if specified.
| GetCard method request parameters | |||
|---|---|---|---|
| LoginToken | string | X | Login token (API key) |
| Barcode | string | X | Gift card barcode |
| GetCard method response message | ||
|---|---|---|
| Result | X | See service result codes in 4.1 |
| CardName | O | Only set if the result is successful |
| Balance | O | Only set if the result is successful |
| AccountId | O | Only set if the result is successful |
| AccountName | O | Only set if the result is successful |
| DepartmentId | O | Only set if the result is successful |
| DepartmentName | O | Only set if the result is successful |
| ErrorMessage | O | Optional but only set in case of failure |
| ErrorException | O | Optional but only set in case of failure |
ActivateCard
This method is used for activation of the specified gift card. Amount to which it should be activated can be set in method parameter. If it is not set card will be activated to amount which was set during gift card creation.
| ActivateCard method request parameters | |||
|---|---|---|---|
| LoginToken | string | X | Login token (API key) |
| Barcode | string | X | Gift card barcode |
| Amount | decimal | O | If set card will be activated to this amount. If set to null Otherwise |
| ShopId | int | O | Optional Shop ID from where the gift card was activated |
| PosId | int | O | Optional POS ID on which gift card was activated |
| EmployeeId | long | O | Optional Employee ID who activated gift card |
| ActivateCard method response message | ||
|---|---|---|
| Result | X | See service result codes in 4.1 |
| TransactionId | O | Only set if the result is successful |
| Balance | O | Only set if the result is successful |
| Amount | O | Only set if the result is successful |
| AccountId | O | Only set if the result is successful |
| AccountName | O | Only set if the result is successful |
| CardName | O | Only set if the result is successful |
| DepartmentId | O | Only set if the result is successful |
| DepartmentName | O | Only set if the result is successful |
| ErrorMessage | O | Optional but only set in case of failure |
| ErrorException | O | Optional but only set in case of failure |
Purchase
The purchase method is used for purchasing with the gift card and it will withdraw the specified amount directly from the gift card balance if it is not out of balance.
| Purchase method request parameters | |||
|---|---|---|---|
| LoginToken | string | X | Login token (API key) |
| Barcode | string | X | Gift card barcode |
| Amount | decimal | X | Amount to be withdrawn from the gift card balance |
| ShopId | int | O | Optional shop ID from where the purchase was executed |
| PosId | int | O | Optional POS ID on which purchase was executed |
| EmployeeId | long | O | Optional employee ID who executed the purchase |
| ReceiptId | string | O | Optional POS receipt ID |
| Purchase method response message | ||
|---|---|---|
| Result | X | See service result codes in 4.1 |
| TransactionId | O | Only set if the result is successful |
| Balance | O | Only set if the result is successful |
| Amount | O | Only set if the result is successful |
| AccountId | O | Only set if the result is successful |
| AccountName | O | Only set if the result is successful |
| CardName | O | Only set if the result is successful |
| DepartmentId | O | Only set if the result is successful |
| DepartmentName | O | Only set if the result is successful |
| ErrorMessage | O | Optional but only set in case of failure |
| ErrorException | O | Optional but only set in case of failure |
CancelTransaction
This method cancels the last transaction specified by transaction ID. A purchase can be cancelled only once.
| CancelTransaction method request parameters | |||
|---|---|---|---|
| LoginToken | string | X | Login token (API key) |
| TransactionId | int | X | ID of the transaction to be cancelled |
| ShopId | int | O | Optional shop ID from where the transaction was cancelled |
| PosId | int | O | Optional POS ID on which transaction was cancelled |
| EmployeeId | long | O | Optional employee ID who cancelled the transaction |
| CancelTransaction method response message | ||
|---|---|---|
| Result | X | See service result codes in 4.1 |
| TransactionId | O | Only set if the result is successful |
| Balance | O | Only set if the result is successful |
| Amount | O | Only set if the result is successful |
| AccountId | O | Only set if the result is successful |
| AccountName | O | Only set if the result is successful |
| CardName | O | Only set if the result is successful |
| DepartmentId | O | Only set if the result is successful |
| DepartmentName | O | Only set if the result is successful |
| ErrorMessage | O | Optional but only set in case of failure |
| ErrorException | O | Optional but only set in case of failure |
GetBarcode
This method is used by POS to get a newly generated barcode which can be used as a discount code in the next sale. POS must provide a card scheme ID as the input parameter based on which barcode with configured discount is generated.
