52API GIFT CARD

This topic is about an API for on-premise use. To learn about Fiftytwo cloud-based APIs, go to https://api.fiftytwo.com/.

52API GIFT CARD, commonly known as Gift card API, is typically used with retail systems like 52ViKING for sale and redemption of gift cards via web.

It provides features such as:

• Redemption of gift cards

• Recharging of gift cards

• Sale of new gift cards

• Activation of gift cards

• Balance inquiries

• Viewing postings

Prerequisites

In order to use a 52ViKINGL gift card from a webshop, a connection needs to be established between the web application and the 52ViKING gift card server. This connection must use the 52ViKING omnichannel controller.

In order to access 52ViKING omnichannel controller, a delivered 52ViKING-KEY must used. This 52ViKING-KEY must be part of the HTTP request header with the following attribute:

Name: 52ViKING-KEY, Value: the delivered key

The 52ViKING omnichannel controller then sends the received requests to the gift card server and returns the responses to the web application.

HTTP Return Codes

• 200 OK

  XML tag status that shows if request has gone well or not.

  Can assume the values OK or NOK.

• 400 Bad Request

  Returned if request is wrong or if request is missing information.

• 401 Unauthorized

  52ViKING-KEY missing or not correct

• 404 Not Found

  Resource not available

If queries are sent on gift cards that don't exist, or where different control data don't match 52ViKING Gift Card table, an XML response will be sent with the following content:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<Resurse>
  <status>NOK</status>
  <text>Card data not OK</text>
</Resurse>

Resource will contain the name of the initially called resource.

General information

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 (?).

All places where the attribute amount= is used, the attribute IsoCode= is used for the currency codes that the gift card server supports. If the attribute IsoCode= isn't specified, the gift card server’s own currency code is used for the transaction. The currency code is indicated with the numeric ISO value.

For all CGI calls, all parameters mentioned under QueryString must be entered. The only exceptions are IsoCode= as well as expYear= and expMonth= as the last two are only required for gift cards where the expiration date is created.

Responses are currently in XML format.

Use of gift card (redemption)

In the web application, when the customer selects payment with gift card, they'll be prompted for a gift card number (10 digits), possible expiration date (month and year), and a security code (3 digits). 

The web application sends a GiftVoucherRedeem request to the gift card server. This request contains gift card number, possible expiration month and year, security code as well as the amount requested from the gift card, though not a bigger amount than what is purchased for.

52ViKING gift card server returns either an OK or a NOK response. If it's an OK response, the response contains either the requested amount or, if there is not money enough available on the gift card, the maximum amount that can be used. The amount is reserved, so that it isn't possible to make any more purchases before the current purchase is completed.

When the purchase is completed, the web application sends a GiftVoucherComplete request to announce that the transaction is completed. This will remove the reservation and update the balance.

If for some reason the purchase isn't completed, the web application must send a GiftVoucherCancel request to remove the reservation. This also applies in the cases where the customer simply closes the web page.

Recharging of gift card

When a customer selects to recharge a gift card (also known as refill or top up) in the web application, they must enter the gift card number. 

After the customer has entered the gift card number, the web application must send a GiftVoucherExist request to control if the gift card number is correct. If this is the case, the customer must be prompted for the amount that is to be added to the gift card. After completed payment, the web application must send a GiftVoucherRefill request with gift card number and amount to the server. This will respond OK when the transaction is completed.

Sale of gift card in webshop

Sale of gift cards in webshop can be implemented in 4 different ways: 

• Customer gets a temporary gift card immediately

  In the web application there must be a feature that enables sale of new gift cards. When a gift card is sold, an amount is registered, and it is paid with the relevant payment card.

  When the payment is completed, the web application sends a GiftVoucherTemporary request to the 52ViKING gift card server and gets a 13-digit code in response. This code, together with a freely definable text, must be printable. The 13-digit code is an EAN-13 barcode to be printed. Technically, this barcode covers a one-time gift card that must be used to pay the actual gift card.   

  With this document in hand, the customer can contact any of the connected stores and get the document exchanged for a gift card with balance. 

  The exchange is done by switching between the temporary gift card and the gift card with balance. This will automatically transfer the value from the temporary gift card to the new gift card. The temporary gift card is then marked as redeemed and can no longer be used. 

• Customer gets a non-linked gift card sent in the same way as other goods

  This gift card is worthless until it's activated. With this method, an activation key is returned along with the amount for the calling webshop.

  The activation key will be saved in a special database table together with the required amount. The activation key is an 8-digit random unique key that can contain the numbers 0-9.

  The activation key is sent by the web application via e-mail to the customer together with the registered amount.

• Customer gets a linked gift card sent in the same way as other goods

  This gift card is worthless until the gift card is activated. With this method, the gift card number is loaded when packing the gift card, and the gift card number is sent together with an activation key to the 52ViKING server generated by the web application. The activation key will be saved in a special database table together with the gift card number and the required amount.

  The activation key is sent by the webshop application via e-mail to the customer together with the registered amount.

  As an alternative to the web application generating the activation key, the 52ViKING gift card server can generate the key. This happens if the key sent in the request is 0.

• Customer gets a ready to use electronic gift card sent

  This gift card is ready for use when the customer receives it electronically.

  When payment of gift card is received in the web application, a GiftVoucherCreate request is sent to 52ViKING gift card server. 52ViKING then generates a gift card number and activates the gift card immediately.

  The web application receives the gift card number, a 13-digit EAN code, a cv2 security code as well as a possible expiration date. The webshop send this finormation in an e-mail to the customer (the EAN code to be printed as barcode), who can then pay with the gift card.

  When paying in webshop, the gift card number is used with the cv2 security code (and possibly expiration date). When paying in a shop, the barcode is scanned, and the cv2 number (and possibly expiration date) is given to the salesperson.   

  This method places special demands on the infrastructure of the web solution.

Activation of gift card in webshop

When the customer receives the gift card as well as the e-mail with activation key, the customer must register the activation key, thegift card number, the security code, and possibly the expiration date via the webshop. This information is sent from the webshop to 52ViKING Sales Manager, which verifies that the gift card is not already activated. If this is OK, it controls that the security code and the possible expiration date is the same as the information of the gift card. It then verifies that the security code exists and isn't already used. If this is also OK, the gift card is activated with the registered amount, and the activation key is marked as already activated.

For not-linked gift cards, the activation key (8 digits) is saved together with the amount in a separate table, and when the customer makes the activation, the activation key in this table is checked. If there's a match, the gift card will be created in the gift card table with the saved amount, and the activation key is removed from the temporary table.

For linked gift cards, the gift card number, activation key (8 digits), and amount is saved in a separate table. When the customer makes the activation, it's verified if the gift card number is in this table, and that the correct activation key is listed. If this is OK, the gift card is created in the gift card table and is removed from the activation table. 

Gift Card status

52ViKING offers two different types of status information regarding gift cards:

• The current balance of the gift card

• Overview of all entries made on the gift card

To get access to this information, a valid gift card number, possible expiration date, and a correct security code is required.

API functions

Redemption of gift card (two steps) + possible cancellation of reservation

Redeem reserves an amount on the gift card along with a reservation ID (for capture/completion) and the total amount available.

XML reply example:

1
2
3
4
5
6
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherRedeem>
  <status>OK</status>
  <Amount>25.25 DKK</Amount>
  <ReservationId>1234</ReservationId>
</GiftVoucherRedeem>

ReservationId is only sent if reservation is activated on the gift card server.

For completing/capturing the transaction with a reservation ID, the following call is used:

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherComplete>
  <status>OK</status>
  <Amount>25.25</Amount>
</GiftVoucherComplete>

A reservation can also be canceled using the following call:

XML reply example:

1
2
3
4
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
  <status>OK</status>
</GiftVoucherBalance>

Topping up gift card

Before recharging a gift card (also known as refilling or topping up), it should be verified that the gift card exists:

XML reply example:

1
2
3
4
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
  <status>OK</status>
</GiftVoucherBalance>

Recharging a gift card uses the following method:

XML reply example:

1
2
3
4
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
  <status>OK</status>
</GiftVoucherBalance>

Sale of new gift card

Use one of the following four methods:

Method 1: Issue a temporary gift card that can be exchanged for a physical gift card in a store.

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherTemporary>
  <status>OK</status>
  <Barcode>9800000000076</Barcode>
</GiftVoucherTemporary>

Method 2: Sell a gift card that's initially not activated. 52ViKING sends a gift card activation code.

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
 <GiftVoucherSale>
  <status>OK</status>
  <ActivationKey>12345/ActivationKey>
</GiftVoucherSale>

Method 3: An issue request is sent from the webshop when a physical gift card has been packed and shipped.

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherIssue>
  <status>OK</status>
  <ActivationKey>12345</ActivationKey>
</GiftVoucherIssue>

Method 4: Issue an electronic gift card that's activated and ready for use.

XML reply example:

1
2
3
4
5
6
7
8
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherCreate>
  <status>OK</status>
  <GVno> 1577000026</GVno>
  <cv2>123</cv2>
  <Barcode>9815770000263</Barcode>
  <Expdate>0116</Expdate>
</GiftVoucherCreate>

Activation of gift card

When a customer has received a gift card, it must be activated using the activation key before it can be used:

XML reply example:

1
2
3
4
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
  <status>OK</status>
</GiftVoucherBalance>

Request for gift card balance

Get information about the current gift card balance:

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
  <status>OK</status>
  <balance>875.30 DKK</balance>
</GiftVoucherBalance>

Request for available gift card balance

Get information about a gift cards available balance, that is where reserved amounts are subtracted from result:

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherAvailable>
  <status>OK</status>
  <available>875.30 DKK</available>
</GiftVoucherAvailable>

List of gift card transactions

A complete list of transactions for a given gift card can be returned:

XML reply example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<?xml version="1.0" encoding='ISO-8859-1'?>
<GiftVoucherStatement>
  <status>OK</status>
  <Gvno>3000000020</Gvno>
  <Transaction>
    <TransactionTime>2009-11-27 09:38</TransactionTime>
    <TrancactionType>1</TrancactionType>
    <TrancactionText>issued</TrancactionText>
    <StoreId>0001</StoreId>
    <Till>224</Till>
    <Receipt>2</Receipt>
    <Correction>0</Correction>
    <Amount>200 DKK</Amount>
  </Transaction>
  <Transaction>
    <TransactionTime>2011-08-02 14:38</TransactionTime>
    <TrancactionType>3</TrancactionType>
    <TrancactionText>redemption</TrancactionText>
    <StoreId>5266</StoreId>
    <Till>1</Till>
    <Receipt>14</Receipt>
    <Correction>0</Correction>
    <Amount>-17.95 DKK</Amount>
  </Transaction>
  <Transaction>
    <TransactionTime>2011-08-03 09:10</TransactionTime>
    <TrancactionType>3</TrancactionType>
    <TrancactionText>redemption</TrancactionText>
    <StoreId>5266</StoreId>
    <Till>1</Till>
    <Receipt>8</Receipt>
    <Correction>0</Correction>
    <Amount>-3.15 DKK</Amount>
  </Transaction>
:
:  
  <Transaction>
    <TransactionTime>2011-08-08 09:43</TransactionTime>
    <TrancactionType>2</TrancactionType>
    <TrancactionText>recharging</TrancactionText>
    <StoreId>4711</StoreId>
    <Till>5</Till>
    <Receipt>17</Receipt>
    <Correction>0</Correction>
    <Amount>75.25 DKK</Amount>
  </Transaction>
</GiftVoucherStatement>

Gift card API revision history