eProducts introduction

Prepaid topup, e-products, electronic distribution of all kinds of services – Seamless offers possibilities to boost your revenues with low capital investment and no shelf space. We are present through subsidiaries and partners in many countries and we are expanding fast.

On this page you will find information how to set up integration of Seamless eProducts system with Point of Sales (POS) clients. POS refers to the merchant’s cash registers as well as terminals.

Actors

The following terms are used for the different actors involved in the integration process:

  • eProducts – the Seamless electronic products distribution system
  • ERS server – Seamless backend/server performing the service and the API
  • ERS Client Interface – Seamless API
  • Client – the type of system integrating with eProducts, such as POS, cash register and terminal
  • Merchant - the company selling vouchers (can be vendor and/or cashier)
  • Reseller – the retailer, selling vouchers to subscribers/customers
  • Subscriber/Customer - the consumer buying vouchers

Overview of integration steps

To achieve a full integration between eProducts and POS client these steps must be covered:

  1. Create SOAP reference
  2. Add values to API functions
  3. Configure POS for login
  4. Test that integration works

Create SOAP reference

Get started with the integration by creating SOAP reference. Use a SOAP library to create a SOAP reference in your code. eProducts API description and test endpoint URL can be found here. Test creadentials can be found here.

Function requests used for POS client integration

Mandatory Methods Description
getProductList Returns list of available products
reserveVoucher Used for purchasing a voucher in a two-phase commit manner. ERS will only keep the reservation for a limited time (configurable on the ERS, typically a few minutes) after which a buyReservedVoucher might fail
buyReservedVoucher The second step in the two-phase commit procedure for buying a voucher. Can only be called after getting a successful response from a reserveVoucher call
cancelVoucherReservation Used to cancel a reservation of a voucher after a successful response from a reserveVoucher call and should be called if the purchase is to be aborted
cancelTransaction Allows to cancel transaction that has been finished. Using ersReference from buyReservedVoucher response (not voucher)
Optional Methods Description
executeReport Allows to generate reports

Although other functions are avaliable on the WSDL on the testing environment, those should not be used for eProducts integration.

Configure printer for receipts

The receipt file is part of the response code. Configure the printer to include the data as shown in the sample code below, which is valid for buyVoucherResponse with FormatId as “TEXT” (HTML and VML are also supported). The information shown on receipt is configured according to each telecom operator’s specification. There are special tags that should be replaced with supported characters on POS side.

Tag Description
<large> Set large text size
<normal> Set normal text size
<small> Set small text size
<left> Left align text
<center> Center align text
<right> Right align text
<br> Break line
<vs> Add vertical space
<hs> Add horizontal space
<img src=”logo.bmp”> Print image logo.bmp
<barcode digits=”$EAN_code$”> Print product barcode

Product EAN barcodes

Replace product EAN code from <barcode digits=”$EAN_code$”> tag with barcode. If it’s not possible to generate barcodes within your system you can use:

https://se.kontantkort.nu/eproducts/eproducts/ean-barcode-gen?eanCode=<EAN code value>

Example:

https://se.kontantkort.nu/eproducts/eproducts/ean-barcode-gen?eanCode=7340040308036

Operator logos

Logos that should be printed on voucher depending on retuned img tag. All logos can be downoaded from HERE.

atribute value
Max-width 384px
Max-height No larger then Max-width
Colour Monochrome

List of operator logos

Operator img tag Country
Telia <img src=”telia_se.bmp”> Sweden
Tele2 <img src=”tele2_se.bmp”> Sweden
Telenor <img src=”telenor_se.bmp”> Sweden
TRE <img src=”3_se.bmp”> Sweden
IDT <img src=”idt_se.bmp”> Sweden
Lebara <img src=”lebara_se.bmp”> Sweden
Mundio <img src=”mundio_se.bmp”> Sweden
LycaMobile <img src=”lyca_se.bmp”> Sweden
Lebara <img src=”lebara_dk.bmp”> Denmark
TDC <img src=”tdc_dk.bmp”> Denmark
Telia <img src=”telia_dk.bmp”> Denmark
Oister <img src=”oister_dk.bmp”> Denmark
Telenor <img src=”telenor_dk.bmp”> Denmark
CBB <img src=”cbb_dk.bmp”> Denmark
One Mobile <img src=”one_dk.bmp”> Denmark
Colour Mobile <img src=”colour_dk.bmp”> Denmark
LycaMobile <img src=”lyca_dk.bmp”> Denmark
IDT <img src=”idt_dk.bmp”> Denmark
Mundio <img src=”mundio_dk.bmp”> Denmark
Telepost <img src=”telepost_dk.bmp”> Denmark

Sample voucher

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:buyVoucherResponse xmlns:ns2="http://externalws.client.ers.seamless.com/">
<return>
<errorDescription>SUCCESS</errorDescription>
<ersReference>2013071914473764701002923</ersReference>
<resultCode>0</resultCode>
<productEAN>7330596001123</productEAN>
<productName><name of product> 100KR</productName>
<productSKU>10053</productSKU>
<receipt>
	<img src="telia_se.bmp">
	Värdebevis
<vs>
---------
2013/07/19 14:47:37
<vs>
<name of voucher> 100KR
<vs>
EAN:7330596001123
<vs>
Värdebevis: 100 SEK
<vs>
SÄKERHETSKOD <vs>
-------------------------<vs>
9140000014 <vs>
-------------------------<vs>
FÖR ATT TANKA PÅ DITT KORT SLÅ *110*SÄKERHETSKOD# OCH LUR
Giltigt fram till:2014/01/01
<vs>
Serienumber: 9140014
<vs>
VID PROBLEM MED
<vs>
LADDNING KONTAKTA 13
<vs>
<Operator> KUNDTJÄNST PÅ 
<barcode digits="7330596001123">
<phone number>
</receipt>
<voucher>
 <code>9140000014</code>
 <expiryDate>2014-01-01T00:00:00+01:00</expiryDate>
 <serial>9140014</serial>
</voucher>
</return>
</ns2:buyVoucherResponse>
</soap:Body>
</soap:Envelope>

Two step voucher purchase

In a realistic scenario, the POS client wants to be very sure that the purchase goes through after it has received the payment/allocated the funds. This can be accomplished by using a two-phase commit procedure using reserveVoucher and buyReservedVoucher. Note! Although this procedure minimizes the risk that the purchase fails this is no 100% guarantee. This means that the POS client must always have a procedure for handling a failed purchase, even if it is a manual procedure!

  1. Reserve voucher, calling reserveVoucher. If this fails, return error message to customer.
  2. Confirm the purchase with the customer, if cancelled the voucher reservation should be cancelled with cancelVoucherReservation.
  3. Complete and verify the customer payment. How this is done is up to the client, but it will typically send a payment request to a payment system. If the payment fails, the voucher reservation should be cancelled with cancelVoucherReservation and the purchase be aborted.
  4. Buy the reserved voucher using buyReservedVoucher.
  5. Print/present the voucher returned by eProducts.

Verification

When merchant has notified Seamless that all work is done, a certification test is performed by Seamless together with the merchant/vendor. The certification flows are the following:

  1. Getting product list using getProductList.
  2. Reserving a voucher and buying it.
  3. Reserving a voucher and canceling reservation.
  4. Reserving and buying a voucher then refunding it using cancelTransaction (using ersReference from buyReservedVoucher response).
  5. Getting reports using executeReport method (if implemented).
  6. Error handling.
  7. Printed voucher receipt verification. There should be a way to scan and send the printed receipt to Seamless during the certification.