52API GIFT CARD
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 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
Gift card API is part of the 52MASTERPRICER suite of APIs.
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.
-
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:
<?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.
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.
Redeem reserves an amount on the gift card along with a reservation ID (for capture/completion) and the total amount available.
URI |
/GiftVoucherRedeem? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) expYear= Expiry year expMonth= Expiry month cv2= Security code amount= Amount to reserve for usage IsoCode= Currency code |
Example |
/GiftVoucherRedeem?GVno=7000000001&cv2=123&amount=100 |
Returns |
200 OK & XML reply |
XML reply example:
<?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:
URI |
/GiftVoucherComplete? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) amount= Amount actually used (must be equal or less than reserved amount) IsoCode= Currency code OrderNo= Optional order ID (9 digits) ReservationId= Optional previously received reservation ID |
Example |
/GiftVoucherComplete?GVno=7000000001&amount=25.25&OrderNo=1234567890 |
Returns |
200 OK & XML reply |
XML reply example:
<?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:
URI |
/GiftVoucherCancel? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) amount= Reserved amount IsoCode= Currency code ReservationId= Previously received reservation ID |
Example |
/GiftVoucherCancel?GVno=7000000001&amount=25.25&ReservationId=1234 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
<status>OK</status>
</GiftVoucherBalance>
Before recharging a gift card (also known as refilling or topping up), it should be verified that the gift card exists:
URI |
/GiftVoucherExist? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) |
Example |
/GiftVoucherExist?GVno=7000000001 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
<status>OK</status>
</GiftVoucherBalance>
Recharging a gift card uses the following method:
URI |
/GiftVoucherRefill? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) amount= Amount to insert/top up IsoCode= Currency code OrderNo= Optional orderid |
Example |
/GiftVoucherRefill?GVno=7000000001&amount=500&OrderNo=1234567890 |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
<status>OK</status>
</GiftVoucherBalance>
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.
Method |
GET |
Query string |
amount= The issued amount IsoCode= Currency code |
Example |
/GiftVoucherTemporary?amount=500 |
Returns |
200 OK & XML reply |
XML reply example:
<?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.
URI |
/GiftVoucherSale? |
Method |
GET |
Query string |
amount= The issued amount IsoCode= Currency code OrderNo= Optional order ID |
Example |
/GiftVoucherSale?amount=500&OrderNo=1234567890 |
Returns |
200 OK & XML reply |
XML reply example:
<?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.
URI |
/GiftVoucherIssue? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) Activationkey= Activation code amount= The issued amount IsoCode= Currency code OrderNo= Optional order ID |
Example |
/GiftVoucherIssue?GVno=7000000001&ActivationKey=12345&amount=500 |
Returns |
200 OK & XML reply |
XML reply example:
<?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.
URI |
/GiftVoucherCreate? |
Method |
GET |
Query string |
amount= The issued amount IsoCode= Currency code |
Example |
/GiftVoucherCreate?amount=500 |
Returns |
200 OK & XML reply Expdate is only returned if an expiry date is registered on the gift card |
XML reply example:
<?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>
When a customer has received a gift card, it must be activated using the activation key before it can be used:
URI |
/GiftVoucherActivate? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) expYear= Expiry year expMonth= Expiry month cv2= Security code activationkey= Received activation key |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
<status>OK</status>
</GiftVoucherBalance>
Get information about the current gift card balance:
URI |
/GiftVoucherBalance? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) expYear= Expiry year expMonth= Expiry month cv2= Security code |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherBalance>
<status>OK</status>
<balance>875.30 DKK</balance>
</GiftVoucherBalance>
Get information about a gift cards available balance, that is where reserved amounts are subtracted from result:
URI |
/GiftVoucherAvailable? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) expYear= Expiry year expMonth= Expiry month cv2= Security code |
Returns |
200 OK & XML reply |
XML reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<GiftVoucherAvailable>
<status>OK</status>
<available>875.30 DKK</available>
</GiftVoucherAvailable>
A complete list of transactions for a given gift card can be returned:
URI |
/GiftVoucherStatement? |
Method |
GET |
Query string |
GVno= Gift voucher ID (10 digits) expYear= Expiry year expMonth= Expiry month cv2= Security code |
Returns |
200 OK & XML reply |
XML reply example:
<?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>
Version |
Date |
Change |
Author |
---|---|---|---|
1.07 |
2021-04-06 |
Transfer to Fiftytwo help & knowledge center. Applied layout changes, added introduction text, introduced copyable examples in online versions, performed minor language optimizations, and changed revision history sorting to display most recent changes at top of table. |
MOM |
1.06 |
2020-01-06 |
Layout |
MIE |
1.05 |
2017-05-19 |
Layout and translation |
PHJ |
1.04 |
2017-05-09 |
Moved Voucher/Coupon to Voucher API document |
PEH |
1.03 |
2016-01-11 |
GiftVoucherAvailable |
APE |
1.02 |
2014-10-21 |
52ViKING-Key > 52ViKING-KEY (as in code) |
BER |
1.01 |
2014-09-08 |
New resources – DiscountVoucherValue |
APE |
1.00 |
|
Creation of document |
APE |
© 2024 Fiftytwo A/S • Disclaimer
Last update: 29 November, 2024 13:22:48 CET
Share this page with your colleagues: