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:
- Create SOAP reference
- Add values to API functions
- Configure POS for login
- 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!
- Reserve voucher, calling reserveVoucher. If this fails, return error message to customer.
- Confirm the purchase with the customer, if cancelled the voucher reservation should be cancelled with cancelVoucherReservation.
- 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.
- Buy the reserved voucher using buyReservedVoucher.
- 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:
- Getting product list using getProductList.
- Reserving a voucher and buying it.
- Reserving a voucher and canceling reservation.
- Reserving and buying a voucher then refunding it using cancelTransaction (using ersReference from buyReservedVoucher response).
- Getting reports using executeReport method (if implemented).
- Error handling.
- Printed voucher receipt verification. There should be a way to scan and send the printed receipt to Seamless during the certification.