TYRIOS eCash - Point Of Sales integration

Beschreibung:

The eCash system provides an easy to use terminal which can be used by any participating company to lookup, search and create users and at the same time create transactions for selling products and coupons. However, the separate usage of the terminal is time consuming and causes a not-integrated process. Therefore integrating the eCash system into the own POS software not only speeds up the usage of the system, it also reduces incorrect data inputs, integrates the eCash handling in the own customer handling process and thus improves the overall marketing potential of the complete system.

There are three main categories a POS system can integrate the TYRIOS eCash system. The minimum requirement is to integrate the transaction generation (point 2)

user management
1. user lookup by user hash
2. user search by query
3. user creation
transaction creation
1. selling transaction creation with specified user (by user lookup, user search or user creation)
2. selling transaction creation without specified user, however with coupon code
3. selling transaction creation with specified user AND coupon code
4. coupon transaction to sell a coupon without specified user
5. coupon transaction to sell a coupon with specified user
transaction overview

It is possible to investigate the requests in the eCash terminal as the terminal is using the same API requests. A test system and a test account can be requested by the development.

Version

Version	Changelog
2.0	rewrote complete POS integration to provide more implementation scenarios and example code.
3.0	changed coupon handing to support multiple coupons in one transaction

Authentication

The TYRIOS eCash system provides a RESTfull API interface to interact with. The interface format is JSON and UTF-8 encoded. The general endpoint is:

https://[instance]/service/BonusPointManagement

All interactions with the eCash system requires valid credentials. The credentials are user-specific, so it is possible to have multiple users with access to the eCash interfaces. The users are associated by the company settings and are not part of this integration documentation.

The user credentials need to be provided as BASIC AUTHENTICATION.

Basic eCash handling

Whenever a user wants to buy something, the TYRIOS eCash system creates a transaction. There is no money transfer without a corresponding transaction. Every company has a transaction overview, in which all transactions related to the company are listed. Integrating the eCash system to a POS system therefore requires the creation of a transaction.

TYRIOS eCash supports two different ways to buy items within a transaction

by using coupons, identified by a unique coupon hash
by using a user account, identified by a unique user identification hash.

Both approaches can be combined.

User Account Management

Every user in TYRIOS eCash has an own user account with points stored to the user account. Every point corresponds to 1 Cent. Similar to companies, every user has its transaction overview in which all transactions with the user account are listed. A central functionality for creating a transaction is therefore to be able to identify a user.

Users are identified with a unique, not guessable user hash. This user hash is typically provided by the customer as barcode (CODE-128 encoded) using his mobile phone or by a plastic card. For each user, the system can provide following data:

firstname
lastname
birthdate (if provided)
profile image (if provided)
current points
eMail address (if provided)

The eMail address is not available for all users, only for these users with access to the online portal / app. Especially older users potentially only have the user hash for identification.

Notice

Please keep in mind that the user has accepted that participating companies are allowed to use this data to keep their customer data up to date. Please also keep in mind that this does not mean, that you are allowed to send newsletters to the customer as for this you need to get individual permission by the customer. However, you can request this permission during the payment process.

The user management can be optionally integrated in the POS system. It is not necessary. However, integrating the user management makes following use cases possible:

You can keep your customer data up to date.
You can request the permission to send the customer newsletters.
You can enrich your customer data with relevant sales statistics.
It is possible to tell the customer his current amount of points in the eCash system. This is especially valuable for older generations who are not using the web or app interface to check there transactions.
It is possible to search for customers. This is valuable if the customer has forgotten his customer card / mobile phone and is thus not able to tell the customer hash. You can search for a customer by first- and lastname. (Please keep in mind that in this context, the user should be validated by his passport).
It is possible to create new users for the eCash system and to give the user his individual customer card. Thus your company not only accepts eCash, it also provides the possibility to register for the complete system.

User lookup by Hash

The most typical process is to lookup user data by the user hash. The user hash is a unique combination of letters with exactly 15 characters. You need to call call following GET endpoint

https://[instance]/BonusPointManagement/UserData/[userHash]

If the user is valid, you will get the UserData object, including following fields:

the 4 last digits of the unique user hash.
the user id
the first name (preName)
the surname (name)
the e-mail address (if provided)
the amount of current points
the birthday (if provided, as unix timestamp incl. microseconds)

The request response format is:

{"id":1,"preName":"Max","name":"Mustermann","eMail":"max.mustermann@repalogic.com","currentBonusPoints":213,"uniqueUserHashPart":"WXYC","birthday":976116400000}

Security: Providing the user hash is seen as the most secure method to identify the user. As the user hash is not guessable, the transaction shows that the user was identified using his barcode.

User search by query

If you want to search for a user, you can use following GET endpoint:

https://[instance]/BonusPointManagement/UserData/?query=[searchQuery]

You have to provide the searchQuery (url encoded) so that the system can suggest possible UserData objects (50 suggestions at maximum). Each object includes

the 4 last digits of the unique user hash so that a basic authentication is possible.
the user id
the first name
the surname
the e-mail address
the amount of current points

The request response format is:

{"suggestions": 
 [
  {
   "id":241,
   "preName":"Max",
   "name":"Mustermann",
   "eMail":null,
   "currentBonusPoints":50,
   "uniqueUserHashPart":"S5FA","birthday":0
  },
  ...
 ]
}

Please keep in mind that in case of a searched user, you should apply an additional user validation (e.g. check the user passport). Otherwise it might be possible that the user is claiming a missusage of his account and you cannot prove the correct usage.

Security: Providing the user as search object is less secure than using the user hash. As a user name is guessable, the POS assistant should ask for additional verification, e.g. an identification card.

User creation

If you want to support the user creation, you can check if the provided e-mail address is already in use using the following GET endpoint:

https://[instance]/BonusPointManagement/UserData/eMail?email=[email]

You have to provide a valid e-mail address (url encoded). The system provides you the information if the e-mail address is already in use (in this case, searching for the correct user is recommended).

{"emailInUse":true}

To create a new user, you can send a POST request to the endpoint:

https://[instance]/BonusPointManagement/UserData/

You need to provide following JSON object as POST body:

{
"preName":"Maria",
"name":"Musterfrau",
"eMail":"maria@repalogic.com",
"uniqueUserHash":"4MDQAP8ZK2M4GT6"
}

In the post body, the eMail or the uniqueUserHash is required. If the eMail address is not empty, the user gets a registration eMail notification with which he can create an individual login to the web portal. If the unique user hash is empty, it will be automatically generated. With this approach, you can assign a unique user hash explicitly to the user (e.g. by scanning an already printed customer card with given hash value).

The response provides the saved data:

{"id":255,"preName":"Maria","name":"Musterfrau","eMail":"maria@repalogic.com","currentBonusPoints":0,"uniqueUserHashPart":"4MDQ","birthday":0}

Coupon management

TYRIOS coupons supports digital and analog coupons. Both are typically available as printed coupons (so they are provided physically). The difference is the handling:

Digital coupons must be checked in the POS process to know the amount of available money for the coupon. Digital coupons can be partially redeemed and it is possible for the customer to load the money from the coupon to the user account.
Analog coupons cannot be partially redeemed. Only he complete coupon value can be used. Thus, analog coupons must be taken by the company and the coupon must be centrally redeemed. After that process, the coupon must be deleted.

TYRIOS eCash supports both types in parallel by using separate coupon code patterns. With the coupon code, a coupon is identified.

A coupon has typically following data structure:

{
  "id": 123,
  "couponCode": "ABCDEFGU", //unique coupon code
  "couponValue": 12, //the current value of the coupon
  "originalValue": null, //the original value of he coupon
  "validUntil": 1735686000000, //unix timestamp with milliseconds until the coupon is invalid.
}

Depending on the transaction mode, it is however enough to simply provide the couponCode. This will be discussed in the following in detail.

Coupon value definition

In most cases, a coupon value is predefined. So whenever you use a coupon code, you also get the corresponding coupon value by the system. It is however possible that you create your own coupons using the API and if you use a coupon code which was not used so far, you are free to specify an individual coupon code. This is possible in all three modes.

TYRIOS eCash automatically checks the coupon. So when your used coupon code has already a value, it is not possible to overwrite it.

Transaction creation

The transaction service provides an interface to directly create transactions. By default, the transaction is immediately validated and saved. It is however possible to provide a transaction in draft mode so that it is evaluated first. In this case, the eCash system checks if the user is correct (if provided), if the coupon codes are correct (if provided) and what would happen when the transaction is saved.

This approach is very helpful when you want to integrate the eCash system to your POS system. You can always go to the eCash terminal and simulate the transaction in the browser. So you see, what the terminal sends and what the system provides as a result. The webdeveloper toolbar in Chrome and Firefox give you all required information to debug a transaction.

Notice

The transaction service itself is atomic. If you provide a request, it is evaluated and saved. It is therefore ensured that at the time of evaluation the available points are available and that the transaction can be executed as provided. The same is to the final execution of the transaction. It is however possible that there is too much time between a check in draft mode and the final transaction execution, and that the final transaction might fail while the draft transaction was successful. This needs to be considered during implementation as this is the only possibility to prevent any fraud attempts.

The eCash system supports 5 different transaction types

pos mode: this is the most used mode in which the customer is buying some item and wants to use his bonus point account for reducing the payment amount. In addition, this method supports buying with a coupon code
1. If the user is not provided, the coupon is directly used for the payment. If the payment amount is less than the coupon value, the remaining coupon value is still available on the coupon code.
2. If the user is provided, but no coupon code, the amount of bonus points of the user is taken into account for the payment (it is not possible to NOT take the available bonus points into account).
3. If the user and a coupon code is provided, the coupon value is transformed into bonus points and the total available points (account + coupon value) are used. The coupon is completely moved to the user account, the coupon is thus deactivated.
4. If the user and coupon is provided, but no totalValue is given, the coupon value is assigned to the user account and the coupon code gets invalidated (this is a special case of c).
coupon mode: in this case the customer wants to book a coupon to his user account. This is the same like 1.4, however without providing a total value. The implementation is optional.
coupon activation: activated a freely provided, but unique coupon code (8 characters). If the UserData is provided, the available amount of bonus points of the user can be used as payment for the new coupon.
cash mode: in this mode, the user is able to increase the available points on his account by buying the points. This request can also be used Integration is optional
special points mode: in this mode, it is possible to directly assign points to the eCash account of the user. Integration is optional

General Workflow

Basically, it is possible to directly create a transaction without the need to search for a user or to validate data before. In this case it can be assumed however that there might be an error in the transaction generation. This might be ok, depending on the integration.

In general, we recommend an integration with three steps:

customer selection / validation
transaction simulation
transaction execution

This workflow can be seen in the following diagram:

Die required data for transaction provisioning / transaction confirmation depends on the transaction type and is described below. It is recommended to have a look at the bonus point terminal to get an impression how the system works.

Endpoint

There are 4 different transaction types supported, each one with a separate endpoint

https://[instance]/BonusPointManagement/BonusPointTransaction/(cash|specialPoints|pos|coupon|couponActication)

All endpoints have in common that they support a draft mode by extending the endpoint with the GET parameter "draft=true". The draft mode specifies that the data should be validated and the transaction is simulated, but not executed. This makes it possible to use the same logic for simulation and execution.

User assignment

In most cases, the transaction is created between an end user (the customer) and a company (BonusPointSharingCompany). The user information is saved in the field "UserData". There are three different methods to assign the UserData:

In the most simple case you just provide a unique user hash. This user hash is typically provided by customer cards, the bonus points app or similar techniques. It can be scanned using a barcode (Code128 encoded). The userMode is "HASH".
If you don't know the user hash, you can search for a user using the first name and the surname (There is a separate endpoint for searching). In this case, you need to provide a user object in combination with userMode="SEARCH"
It is also possible to directly create a new end user using the transaction service. Thus, a customer can directly take part in the bonus point system without the need to sign separate documents. The user will get an invitation mail in this case. Similar to the search case, you provide a full user object as UserData in combination with userMode="CREATE"

Transaction Data

Transactions are handled by transaction objects. From implementation point of view, you are creating a transaction object, sending this object to the server and you will get a validated and completed transaction object in return.

A transaction object can have the following data

field	type	description	pos mode	coupon mode	coupon activation mode	cash mode	special points
UserData	unique user hash (15 characters) or UserData object	the user who is the counterpart of the transaction. User Hash is required for userMode="HASH", else UserData object is required	required, if no coupon is provided in addition.	optional. If provided, the coupon is first assigned to the user and then the payment transaction is done.	optional. If provided the coupon can be buyed with bonus points of the user	required	required
userMode	enum: HASH / SEARCH / CREATE	mode of the user association. HASH specifies, that the hash was provided, search: customer was searched, CREATE: new customer should be created	required	required	required	required	required
transactionTime	bigint (unix timestamp)	The time, the transaction is created	automatically created	automatically created	automatically created	automatically created	automatically created
BonusPointSharingCompany	object	transaction owner	automatically assigned	automatically assigned	automatically assigned	automatically assigned	automatically assigned
productGroup	varchar(255)	description of the transaction, typically a product group. Appears as description in the transaction overview	required	required	required	required	required
totalAmount	double with two decimals	the amount of the payment	required	automatically set to 0	automatically set to coupon value	required	not used
BonusPointCouponData	array of CouponData object	the objects reflecting the coupon code. Multiple coupons are supported at once. Thus an array is required.	optional, if provided, couponCode needs to be provided, rest is automatically checked	required, depending on the system condiguration, couponCode and couponValue needs to be provided	required, depending on the system condiguration, couponCode and couponValue needs to be provided	not used	not used
couponValue	double, 2 decimals	the coupon value, which should be assigned to a coupon	not-used	not-used	required	not-used	not-used
startPoints	int	the start points before the transaction is created	automatically calculated based on UserData. If UserData is not set, coupon start value is used	automatically calculated	automatically calculated, 0 if UserData is not set	automatically calculated	automatically calculated
redeemedPoints	int	the number of points the user is providing to the company	automatically calculated based on on the total amount and the available startPoints	automatically set to 0	automatically calculated based on on the total amount and the available startPoints	not used as the customer is not providing any points. Instead he receives new points	not used as the customer is not providing any points. Instead he receives new points
remainingAmount	double (with two digits)	the remaining amount the user has to pay	automatically calculated	automatically set to 0	automatically calculated	not used	not used
obtainedPoints	int	the number of points which are assigned to the user with this transaction	automatically calculated based on the properties of the company	automatically calculated	automatically set to 0, no points are given for buying a coupon	automatically calculated	required
resultingPoints	int	the final point value of the user	automatcially calculated:	automatcially calculated	automatcially calculated	automatically calculated	automatically calculated
transactionFee	double (with two digits)	The fee the company has to pay with this transaction (if supported by the platform)	automatically calculated	automatically calculated	automatically calculated	automatically calculated	automatically calculated
enablePointRedemption	boolean	Specifies, if available points should be redeemed
availableObtainedPoints	int	The user can use is obtained points for new transactions. As points are expiring after 3 years, old points are used first. This field tracks, which points are still available. On transaction creation time, this number is equal to obtained points.

Transaction Examples

We will go into detail now to create different transaction types for the most relevant use cases. All requests are created with draft=true (and thus the transaction is not persisted).

The BonusPointSharingCompany is automatically assigned by the system using the login credentials. So each transaction has a user (optionally) and a BonusPointSharingCompany as transaction partners

Standard Transaction with User Hash

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
UserData: "UQBUFDJALK4WXYC",
enablePointRedemption: true,
productGroup: "Hose",
totalAmount: 33,
userMode: "HASH",
}

{
BonusPointCouponData: null,
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: {id: 1, preName: "Max", name: "Mustermann", eMail: "max.mustermann@repalogic.com",…},
availableObtainedPoints: 62,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 62,
obtainedPointsValidUntil: 1672527600000,
productGroup: "Hose",
redeemedPoints: 213,
remainingAmount: 30.87,
resultingPoints: 62,
startPoints: 213,
totalAmount: 33,
transactionFee: 0.22,
transactionTime: 1572351844000,
transactionType: "bonuspoint",
use4Clearing: null,
use4Invoice: null,
userMode: "HASH"
}

Standard Transaction with user object (provided by user search)

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
UserData: {id: 1, preName: "Max", name: "Mustermann", eMail: "max.mustermann@repalogic.com",…},
enablePointRedemption: true,
productGroup: "Hose",
totalAmount: 33,
userMode: "SEARCH"
}

{
BonusPointCouponData: null,
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: {id: 1, preName: "Max", name: "Mustermann", eMail: "max.mustermann@repalogic.com",…},
availableObtainedPoints: 62,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 62,
obtainedPointsValidUntil: 1672527600000,
productGroup: "Hose",
redeemedPoints: 213,
remainingAmount: 30.87,
resultingPoints: 62,
startPoints: 213,
totalAmount: 33,
transactionFee: 0,
transactionTime: 1572351844000,
transactionType: "bonuspoint",
use4Clearing: null,
use4Invoice: null,
userMode: "SEARCH"
}

Standard Transaction with user creation

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
UserData: {preName: "Maria", name: "Mustermann", eMail: "maria.mustermann@repalogic.com"},
enablePointRedemption: true,
productGroup: "Hose",
totalAmount: 33,
userMode: "CREATE"
}

{
BonusPointCouponData: null
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: {id: null, preName: "Maria", name: "Mustermann", eMail: "maria.mustermann@repalogic.com",…},
availableObtainedPoints: 66,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 66,
obtainedPointsValidUntil: 1672527600000,
productGroup: "Hose",
redeemedPoints: 0,
remainingAmount: 33,
resultingPoints: 66,
startPoints: 0,
totalAmount: 33,
transactionFee: 0,
transactionTime: 1572352154000,
transactionType: "bonuspoint",
use4Clearing: null,
use4Invoice: null,
userMode: "CREATE"
}

Standard Transaction with coupon (without user)

Please take into account. This example uses an fully digitalized environment in which it is possible to use coupons with bigger value than the bought items. In a partially digitalized environment, the system will not accept the coupon.

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
BonusPointCouponData:[{couponCode: "AB4DEFGH"}],
enablePointRedemption: true,
productGroup: "Hose",
totalAmount: 33,
useCouponData: true,
userMode: "HASH"
}

{
BonusPointCouponData: [{couponCode: "AB4DEFGH", couponValue: 17, validUntil: 1672527600000}],
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: null,
availableObtainedPoints: 0,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 0,
obtainedPointsValidUntil: 1672527600000,
productGroup: "Hose",
redeemedPoints: 3300,
remainingAmount: 0,
resultingPoints: 1700,
startPoints: 5000,
totalAmount: 33,
transactionFee: 0,
transactionTime: 1572352589000,
transactionType: "bonuspoint",
use4Clearing: null,
use4Invoice: null,
userMode: "HASH"
}

Standard Transaction with coupon and user

Please take into account. As the user is mentioned in the request, the remaining value of the coupon is directly assigned to the user, the coupon value is set to 0 and thus the coupon gets deactivated. This use case is thus available in partially digitalized environments, too. The user is thus able to pay with coupons which are bigger than the selling amount. With this approach it is possible to support customers paying with bigger coupon values.

https://[instance]/service/BonusPointManagement/BonusPointTransaction/pos?draft=true

{
BonusPointCouponData:[{couponCode: "AB4DEFGH"}],
enablePointRedemption: true,
productGroup: "Hose",
totalAmount: 33,
useCouponData: true,
UserData: "UQBUFDJALK4WXYC",
userMode: "HASH"
}

{
BonusPointCouponData: [{couponCode: "AB4DEFGH", couponValue: 0, validUntil: 1672527600000}],
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: {id: 1, preName: "Max", name: "Mustermann", eMail: "max.mustermann@repalogic.com",…},
availableObtainedPoints: 1700,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: 5000,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 0,
obtainedPointsValidUntil: 1672527600000,
productGroup: "Hose",
redeemedPoints: 3300,
remainingAmount: 0,
resultingPoints: 1913,
startPoints: 213,
totalAmount: 33,
transactionFee: 0,
transactionTime: 1572352930000,
transactionType: "bonuspoint",
use4Clearing: null,
use4Invoice: null,
userMode: "HASH"
}

Coupon Transaction (selling a coupon) without user and coupon creation

https://[instance]/service/BonusPointManagement/BonusPointTransaction/couponActivation?draft=true

{
UserData: null
BonusPointCouponData:[{couponCode: "AB4DEFGH", "couponValue": 50}],
couponValue: 50,
enablePointRedemption: true,
userMode: "HASH"
}

{
BonusPointCouponData: [{couponCode: "AB4DEFGH", couponValue: 50, validUntil: 1672527600000, mode: "creation"}],
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: null,
availableObtainedPoints: 0,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 5000,
obtainedPointsValidUntil: 0,
productGroup: "Gutschein aktivieren",
redeemedPoints: 0,
remainingAmount: 50,
resultingPoints: 0,
startPoints: 0,
totalAmount: 50,
transactionFee: 0,
transactionTime: 1572352284000,
transactionType: "coupon-activation",
use4Clearing: null,
use4Invoice: false,
userMode: "HASH"
}

Coupon Transaction (selling a coupon) without user and coupon activation (coupon is already registered with a value)

https://[instance]/service/BonusPointManagement/BonusPointTransaction/couponActivation?draft=true

{
UserData: null
BonusPointCouponData:[{couponCode: "AB4DEFGH","couponValue":50}],
enablePointRedemption: true,
userMode: "HASH"
}

{
BonusPointCouponData: [{couponCode: "AB4DEFGH", couponValue: 50, validUntil: 1672527600000, mode: "activation"}],
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: null,
availableObtainedPoints: 0,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 5000,
obtainedPointsValidUntil: 0,
productGroup: "Gutschein aktivieren",
redeemedPoints: 0,
remainingAmount: 50,
resultingPoints: 0,
startPoints: 0,
totalAmount: 50,
transactionFee: 0,
transactionTime: 1572352284000,
transactionType: "coupon-activation",
use4Clearing: null,
use4Invoice: false,
userMode: "HASH"
}

Coupon Transaction (selling a coupon) with user

The difference to the request above is, that the user is able to use his available points to pay a part of the coupon

https://[instance]/service/BonusPointManagement/BonusPointTransaction/couponActivation?draft=true

{
UserData: "UQBUFDJALK4WXYC",
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
BonusPointCouponData:[{couponCode: "AB4DEFGH", "couponValue":50}],
enablePointRedemption: true,
obtainedPoints: 5000,
redeemedPoints: 0,
remainingAmount: 50,
resultingPoints: 0,
startPoints: 0,
totalAmount: 50,
userMode: "HASH"
}

{
BonusPointCouponData: [{couponCode: "AB4DEFGH", couponValue: 50, validUntil: 1672527600000}]
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null
UserData: {id: 1, preName: "Max", name: "Mustermann", eMail: "max.mustermann@repalogic.com",…},
availableObtainedPoints: 0,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 5000,
obtainedPointsValidUntil: 0,
productGroup: "Gutschein aktivieren",
redeemedPoints: 213,
remainingAmount: 47.87,
resultingPoints: 0,
startPoints: 213,
totalAmount: 50,
transactionFee: 0,
transactionTime: 1572352395000,
transactionType: "coupon-activation",
use4Clearing: null,
use4Invoice: false,
userMode: "HASH"
}

Point Transaction with user

https://[instance]/service/BonusPointManagement/BonusPointTransaction/specialPoints?draft=true

{
UserData: "UQBUFDJALK4WXYC"
couponCode: null,
enablePointRedemption: true,
obtainedPoints: 50,
productGroup: "Sonderaktion Wettbewerb",
userMode: "HASH"
}

{
BonusPointCouponData: null,
BonusPointSharingCompany: {id: 6, companyName: "...", street: "...", streetNo: "...", postCode: "...", city: "...",…},
BonusPointTransactionDataDetail: null,
ClearingBillData: null,
FeeBillData: null,
UserData: {id: 1, preName: "Max", name: "Mustermann", eMail: "max.mustermann@repalogic.com",…},
availableObtainedPoints: 50,
bonusPointMode: "percentage",
bonusPointPercentage: 0.02,
clearingCreated: null,
couponPoints: null,
employeeNumber: null,
enablePointRedemption: true,
id: null,
obtainedPoints: 50,
obtainedPointsValidUntil: 1672527600000,
productGroup: "Sonderaktion Wettbewerb",
redeemedPoints: 0,
remainingAmount: 0,
resultingPoints: 263,
startPoints: 213,
totalAmount: 0,
transactionFee: 0,
transactionTime: 1572353121000,
transactionType: "specialPoints",
use4Clearing: null,
use4Invoice: null,
userMode: "HASH"
}

Error handling

If the system fails to process provided data, it is returning an appropriate error message and a http status code 400.

The response body contains an error type and an error message. The message is translated according to the language settings of the user (provided by the credentials).

{
error: "Exception",
message: "Es existiert bereits ein identischer Eintrag."
}