52API BONUS
This topic is primarily for administrators and other people who manage a Fiftytwo solution
This topic is about an API for on-premise use. To learn about Fiftytwo cloud-based APIs, go to https://api.fiftytwo.com/ .
52API BONUS, commonly known as Bonus API, is typically used with retail systems like 52ViKING for bonus point systems with accounts. It provides features such as:
-
View balance
-
Reserve and use bonus points
-
Move bonus points between accounts
-
View “exchange rate”
-
Transaction history
Bonus API is part of the 52MASTERPRICER suite of APIs.
Bonus API uses these HTTP status codes as return codes:
-
200 OK
Returned with response in either XML or JSON format, depending on acceptance of the request
-
204 No Content
No response will be returned.
-
400 Bad Request
Returned if request is wrong or if request is missing information.
-
404 Not Found
Returned if resource isn't available
If you request bonus accounts that don't exist, or where possible control data don't match the 52ViKING bonus table, the server will respond with HTTP 400, but the name of the resource will match the name that was sent.
In order to use the 52ViKING loyalty system from a webshop or an app, a connection needs to be established between the web application and the 52ViKING loyalty server. This connection can run via the 52ViKING commerce server.
The bonus point server can be installed either per country or installed centrally and be used across borders, provided that the member number is unique across the countries. Notice that points will be moved 1 to 1 between accounts and that they can represent different value depending on in which country they are earned/used.
The resources assume that the user using the webshop is approved so the following resource calls are not required to perform a verification test of the user.
When a customer logs on to the webshop, this must begin by picking up BonusPointsStatus, so it can be verified that the member number is created in the 52ViKING table. Together with status, the balance of earned points and their current counter value will possibly be returned.
Bonus account only contains points and their counter value will be calculated at the time of use, so that a “rate” will be used for the points.
Counter value means the actual value of the used currency, where a given rate in 52ViKING is used to convert between bonus points and the actual value (for example 25 bonus points = 1 EUR).
The resources are called by adding the defined attributes to the resource. All calls are made as CGI calls, which means that the resource is separated from the attributes with a question mark (?). For all CGI calls, all parameters mentioned under Query string must be entered.
Responses can be in XML or JSON format, which will depend on the HTTP header's accept.
Verify if member number is created
As the first thing after login to the webshop and the customer being verified, a request for BonusPointsStatus must be sent. The purpose of this request is to:
-
Verify that the member number is created in the 52ViKING member table
-
Retrieve the balance of bonus points in both points and value.
Use (redemption) of bonus points
When a customer chooses to use bonus points in the web application, the customer must register the number of points to be used.
The web application must send a BonusPointsRedeem request to the bonus server. This request contains the member number as well as the number of bonus points to be used.
The 52ViKING bonus server returns either an OK or a NOK response. If it's an OK response, it contains the requested number of bonus points as well as the corresponding amount, or if there aren't enough points on the bonus account, the maximum number of points that can be used as well as the corresponding maximum amount. The number of points that is returned in the response will be reserved. For points and corresponding amount, an internal reference number will be also be sent. That reference number must be sent along in the following requests.
When the purchase is completed, the web application must send a BonusPointsComplete request to announce that the transaction is completed. This will remove the reservation and update the balance. This request must contain the sent reference number. The call of this function should only be done if the Order API function WebOrderNew containing the bonus transaction isn't used.
If for some reason the purchase isn't completed, or if the customer simply closes the web page, the web application must send a BonusPointsCancel request to remove the reservation. This request must contain the sent reference number. If a BonusPointsCancel request isn't sent, the reservation will not be released until after a defined number of days.
Earning of bonus points
Earning of bonus points is based on completed purchases, regardless whether purchases happen in a physical store or via the webshop, as the transactions being made must contain a member number. If the Order API function WebOrderNew is used for sale via the webshop, this module will automatically make the necessary transactions.
Transfer of bonus points between accounts
Transfer of bonus points between two accounts is only possible when points are withdrawn from the account that the member is logged in on, so that the transferred points will be deposited on another account. The maximum possible amount of points that can be transferred is the balance of the logged-in member's account.
Only points, not their counter value, can be transferred, and the transferred points will be deposited on the receiving account. This is because only points can be recorded, and their counter value is calculated at the time of the request.
Before any transfer of points, the receiving account must be verified.
Bonus account statement
This resource provides an overview of entries made on the bonus account for a defined period. The function takes year-month as parameter if other than the current month is to be used.
Creation and editing of members
A CRUD (Create/Read(Get)/Update/Delete) interface for managing member information on the bonus server is displayed.
Request of point exchange rate per country
Resources are displayed to request the actual point exchange rate of a country. This way the point value can be calculated in different countries.
Use to verify that member number exists as well as to check the current balance of the bonus account in question.
URI |
/BonusPointsStatus? |
Method |
GET |
Query string |
MemberNo= Member number (max. 10 digits) |
Example |
/BonusPointsStatus?MemberNo=1234567890&Month=2010 |
Returns |
200 OK & XML reply |
Reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<BonusPointsStatus>
<MemberNo>1234567890</MemberNo>
<Points>20</Points>
<ReservedPoints>805</ReservedPoints>
<BalancePoints>99195</BalancePoints>
<ReservedAmount>1300</ReservedAmount>
<BalanceAmount>48700</BalanceAmount>
<Amount>200</Amount>
</BonusPointsStatus>
If the account doesn't exist, or the customer has a status that is different from 0, HTTP 400 will be returned.
Use for reservation of points. Returns the maximum number of points that can be used.
This method is part of a two-step process that is typically completed with BonusPointsComplete.
URI |
/BonusPointsRedeem? |
Method |
GET |
Query string |
MemberNo= Member number Amount= Amount that customer wants to buy for (the total purchase, not converted to points) Points= Number of points that customer wants to use |
Example |
/BonusPointsRedeem?Memberno=1234567890&amount=175&points=10 |
Returns |
200 OK & XML reply |
Reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<BonusPointsRedeem>
<Status>OK</Status>
<></ReferenceId>
<Points>10</Points>
<Amount>100,00</Amount>
</BonusPointsRedeem>
When a transaction has been finalized, a completion message is sent.
URI |
/BonusPointsComplete? |
Method |
GET |
Query string |
MemberNo= Member number ReferenceId = The ID under which the reservation is saved Points= Number of points that was used |
Example |
/BonusPointsComplete?MemberNo=1234567890&points=10 |
Returns |
204 OK |
Alternatively, a cancellation message is sent.
URI |
/BonusPointsCancel? |
Method |
GET |
Query string |
MemberNo= Member number |
Example |
/BonusPointsCancel?MemberNo=1234567890& |
Returns |
204 OK |
If the 52ViKING NewWebOrder resource is used to complete the purchase, BonusPointsComplete shouldn't be used becauseNewWebOrder will contain a payment transaction for the points used. The reserved points will not be released until the transaction has been recorded in the 52ViKING store in question.
Before transferring points from one member account to another, it must be verified that the receiving account exists.
URI |
/BonusAccountExist? |
Method |
GET |
Query string |
MemberNo= Member number that should receive the points |
Example |
/BonusAccountExist?MemberNo=1234567891 |
Returns |
200 OK |
Reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<BonusAccountExist>
<Status>OK</Status>
</BonusAccountExist>
When the transaction is completed, a transfer transaction is sent:
URI |
/BonusPointsTransfer? |
Method |
GET |
Query string |
MemberNo= Member number that should hand over points ReceiverNo= Member number that should receive points Points= The number of points that should be transferred Optional: TransferType= Type that refers to a text in f353tt; value can be 0-255 |
Example |
/BonusPointsTransfer?MemberNo=1234567890&ReceiverNo=1234567891&points=10 |
Returns |
204 OK |
Returns a list of transactions that have taken place on the bonus account. You can define the period of interest per month. If you don't specify a period of interest, you'll get a list of transactions that covers the period since the start of the account.
URI |
/BonusPointsStatement? |
Method |
GET |
Query string |
MemberNo= Member number (if omitted, all registered transactions are returned) Month= Month of interest in the format YYMM |
Example |
/BonusPointsStatement?MemberNo=1234567890&Month=0911 |
Returns |
200 OK & XML reply |
Reply example:
<?xml version="1.0" encoding='ISO-8859-1'?>
<BonusPointsStatement>
<MemberNo>1234567990</MemberNo>
<Transaction>
<TransactionTime>2009-11-27 09:38</TransactionTime>
<TrancactionType>1</TrancactionType>
<TrancactionText>earned</TrancactionText>
<StoreId>0001</StoreId>
<Till>224</Till>
<Receipt>2</Receipt>
<Correction>0</Correction>
<Points>1500</Points>
<Amount>30.00</Amount>
<BalancePoints>3,000</BalancePoints>
<BalanceAmount>60</BalanceAmount>
<PurchaseAmount>1,000</PurchaseAmount>
<TransferType>5</TransferType>
<TransferTypeText>Summer discount</TransferTypeText>
</Transaction>
</BonusPointsStatement>
PurchaseAmount only has value !=0 when TransactionType is 1 and 4.
URI |
/BonusPointsExchangeRate? |
Method |
GET |
Query string |
CountryCode= Country code (ISO standard) |
Example |
/BonusPointsExchangeRate?CountryCode=208 |
Returns |
200 OK |
Reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<BonusPointsExchangeRate>
<ExchangeRate>
<Rate>25</Rate>
<Currency>DKK</Currency>
</ExchangeRate>
</BonusPointsExchangeRate>
If CountryCode is blank, omitted, or not found in the system, HTTP 400 is returned.
Version |
Date |
Change |
Author |
---|---|---|---|
1.04 |
2021-05-31 |
Following review, added information about Month= parameter in the functions BonusPointsStatus and BonusPointsStatement. |
MOM |
1.03 |
2021-04-06 |
Transfer to Fiftytwo help & knowledge center. Applied layout changes, added introduction text, introduced copyable examples in online versions, changed product name from ViKING to 52ViKING, performed minor language optimizations, removed defunct information about the diamonds virtual currency, and changed revision history sorting to display most recent changes at top of table. |
MOM |
1.02 |
2017-05-19 |
Layout |
PHJ |
1.01 |
2014-06-25 |
Adjustment of document layout |
APE |
1.0 |
|
Creation of document |
PEH |
© 2024 Fiftytwo A/S • Disclaimer
Last update: 29 November, 2024 13:22:48 CET
Share this page with your colleagues: