52API VOUCHER

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

52API VOUCHER, commonly known as Voucher API, is a REST-based web API. It's typically used with retail systems like 52ViKING to ensure ability to use vouchers across physical stores, web, and other channels as well as to batch-issue unique vouchers (for example for e-mail marketing).

It provides features such as:

• Ability to use vouchers across physical stores, web, and other channels

• Reservation

• Redemption

• Viewing of individual voucher values

• Issuing of unique vouchers

• Can be used in conjunction with Order API and Basket API

Prerequisites

In general, 52ViKING operates with two types of vouchers (also referred to as coupons in the API and in 52ViKING):

• Generic vouchers, which can be used several times and distributed in various ways to a large amount of people. Generic vouchers trigger a certain discount, and the vouchers themselves carry no value.

• Unique vouchers, which have a value attached and can only be used once. The value can be either a fixed discount amount or a percentage. For example, a comeback voucher giving 5 euros off the next purchase above a certain amount.

Both voucher types can be printed as barcodes. It's also possible to map the barcodes to a more user-friendly short code for entering the voucher on a webshop.   

In order to use a 52ViKING voucher from a webshop, a connection needs to be established between the web application and the 52ViKING voucher server. This connection runs via the 52ViKING omnichannel controller (OC).

The API methods exposed in this API are general web methods as well as unique voucher methods that are only relevant for unique vouchers because generic vouchers can be used multiple times and don't contain a value.

HTTP return codes

Voucher API uses these HTTP status codes as return codes:

• 200 OK

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

  Can have 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 incorrect.

• 404 Not Found

  Resource not available.

• 500 Internal Server Error

  Unknown error or configuration on the server.    

Supported encoding

• UTF-8

API functions

When the API itself refers to coupons in the following, it means vouchers.

Vouchers for web use

To make it easy to enter vouchers on web stores, 52ViKING provides a mapping table that shortens the amount of characters to type.

Example: Instead of having to enter the unique voucher number 9891001123400000001794, the customer can enter a short name, like PFMQWZ.

The mapping table is also used for validating if a voucher is correctly entered by the user. Note, however, that even if a voucher has been entered correctly, it may not necessarily trigger a discount if selling conditions aren't met.

Voucher validation

Use to check if a voucher is valid and optionally its value if it’s a unique voucher.

XML reply example:

1
2
3
4
5
6
7
8
<?xml version='1.0' encoding='UTF-8'?>
<Coupon>
 <Coupon>1001123400000001794</Coupon>
 <CouponName>JUL2018</CouponName>
 <Value>25</Value>
 <Type>unique</Type>
 <DiscountCouponId>123</DiscountCouponId>
</Coupon>

The function may return 400 if CouponName doesn't comply with the allowed format. The format is configurable, defaulting to between 6 and 20 characters containing capital letters and digits.

If the voucher is unique, a value is returned, otherwise it’s a generic voucher. For unique vouchers that are reserved or completed, the value field will be empty.

CouponNumber can be passed with or without the 989 prefix. The returned Coupon element is always without the 989 prefix.

Link between barcode and short name

Use to create a link in the mapping table between a voucher barcode and an easy-to-enter short name.

The voucher ID can either be a unique or a generic voucher.

Unique vouchers

Redemption of voucher

Use to check if a voucher is valid, and to check its value.

XML reply example:

1
2
3
4
5
6
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponValue>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
 <Value>25</Value>
</CouponValue>

Unique vouchers are accepted both for 22 digits and 19 digits. When using 22 digits, the prefix must be 989. The returned voucher ID is only 19 digits.

The voucher isn't reserved, as that will be handled by the following call.

If the voucher isn't valid, the status NOK is returned.

To check if a voucher is valid and create a reservation:

XML reply example:

1
2
3
4
5
6
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponRedeem>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
 <Value>25</Value>
</CouponRedeem>

CouponRedeem reserves the voucher, so it can't be used again (only valid for unique vouchers). This is relevant when a webshop has added the voucher to the basket, but not completed the transaction yet.

To cancel voucher reservation:

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponCancel>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
</CouponCancel>

CouponCancel will remove the reservation of a voucher so it can be used again.

To capture a voucher for use (can be reserved):

XML reply example:

1
2
3
4
5
<?xml version='1.0' encoding='ISO-8859-1'?>
<CouponComplete>
 <status>OK</status>
 <Coupon>1001123400000001794</Coupon>
</CouponComplete>

CouponComplete should be used then the voucher is marked as used, that is when the order is shipped or completed.

Create vouchers

Use to create a number of vouchers and a link in the mapping table.

Issue of unique discount vouchers

Use to generate unique vouchers that may, for example, be used in conjunction with e-mail campaigns.

XML reply example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version='1.0' encoding='ISO-8859-1'?>
<IssueCoupons>
 <Coupon>
 <CouponId value='627'/>
 <Start value='161005'/>
 <Slut value='161010'/>
 <Value value='15'/>
 <CV2 value='921'/>
 <Barcode value='9891001000100000627921'/>
 </Coupon>
 <Coupon>
 <CouponId value='628'/>
 <Start value='161005'/>
 <Slut value='161010'/>
 <Value value='15'/>
 <CV2 value='525'/>
 <Barcode value='9891001000100000628525'/>
 </Coupon>
</IssuedCoupons>

Up to 5000 discount vouchers can be issued per request. Upon a completed successful request, the vouchers are created in the database and are ready for use (subject to start and end dates).

All fields are mandatory, otherwise HTTP status 400 is returned. 400 is also returned for invalid parameters.

Example of JSON output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
 "IssuedCoupons": {
 "Coupon": [
 {
 "CouponId": 629,
 "Start": 161005,
 "Slut": 161010,
 "Value": 15,
 "CV2": 408,
 "Barcode": "9891001000100000629408"
 },
 {
 "CouponId": 630,
 "Start": 161005,
 "Slut": 161010,
 "Value": 15,
 "CV2": 528,
 "Barcode": "9891001000100000630528"
 }
 ]
 }
}

Example of CSV output:

1
2
Coupon,611,161005,161010,15,448,"9891001000100000611448"
Coupon,612,161005,161010,15,231,"9891001000100000612231"

Error codes

The Voucher API functions listed in the previous, except CreateCoupons, can return:

• OK – when successful

• NOK – when not successful, with the following supplementary error code text:

  • Unknown number

  • Already used

  • Coupon not active

  • Coupon expired

  • Unknown coupon

Voucher type barcodes

52ViKING uses two types of vouchers.

Type 0 - Generic voucher: These are typically used in advertising materials or handed out as part of marketing campaigns.

Type 1 - Unique voucher: These are typically created as comeback vouchers, and each one has a unique voucher number and a value.

Generic voucher barcode structure

• 2-digit flag code (=98: voucher)

• 1-digit marking for discount voucher (=9: 52ViKING discount voucher)

• 1-digit discount voucher type (0=generic)

• 5-digit (always 0)

• 3-digit discount voucher ID

• 1 check digit

In total 13 digits.

Unique voucher barcode structure

• 2-digit flag code (=98: voucher)

• 1-digit marking for discount voucher (=9: 52ViKING discount voucher)

• 1-digit discount voucher type (1=unique)

• 3-digit discount voucher ID

• 4-digit shop ID

• 8-digit discount voucher number

• 3-digit security code

In total 22 digits.

Voucher API revision history