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:

Copy 
<?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:

Copy 
<?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:

Copy 
<?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:

Copy 
<?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:

Copy 
<?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