Overview
This guide is intended to Nets terminals such as Viking payment terminals
With E-receipt API by Storebox, you can digitize and connect your members store-receipts with their payment cards. In combination with other services this allows you to:
-
Provide E-receipts to your member profiles (Requires Loyalty API & Receipt data API)
-
Track members across your stores. (Requires Loyalty API)
-
Provide discounts / coupons / points on specific goods/services. (Requires Loyalty API)
-
Use transaction data for user-analytics. (user segmentation, purchasing behavior, frequency and preferences) (Requires Receipt data API)
-
Create personalized marketing campaigns (Requires Receipt data API)
-
Reduce store receipt-paper waste (using our green profile)
-
Improve customer satisfaction by storing receipts for warranty issues (Requires Loyalty API)
Technically the service works by the POS system packaging the purchase receipt data and a card token (from customer payment card) into a JSON format which is sent to Storebox, where the receipt is mathed to the member with the specific card-token.
The API also offers functions such as Create-, Read-, Update- Present receipt.
This document only covers the creation of receipts using a Viking payment terminal and Storebox POS API.
API Documentation:
POS API - Create New Receipt
For more documentation on the Viking payment terminal integration please refer to the Baxi Application Programmers guide
Implementation Steps
-
Get Token from Terminal
-
Viking Payment terminal LocalModeResult - Token/PAR
-
-
Create E-receipt
-
Create E-Receipt
-
Match on Token/PAR
-
Get Token From Terminal
To activate automation of tokens in transaction response, a function has to be enabled in the TMS (Baxbis) for the Viking Terminal. Please consult your technical contact in Nets or reach out to Storebox for enabling in test/prod.
-
When you receive a “LocalModeResult” from the Viking payment terminal after a purchase there should be a card-token attached in the “optional data”.
This card-token is used to match e-receipts with users/membersExample with card token:
0c33b432-42cc-11ec-a45a-5c4242545600
: in the optional data:
D30957852*******00108;20190228101431;2;941;733500165748;;;;;;;70990501;709905;BankAxept;00;KC1;D5780000021010;8000008000;;00067;171201;0000000000;;;;Undefined; {"od":{"ver":"1.03","xfer2ecr":{"ver":"1.00","sbox":{"ver":"1.01","id":"0c33b432-42cc-11ec-a45a-5c4242545600"}}}};001
The “optional data” field contains the Storebox token, this token can be used to match created e-receipts
{
"od": {
"ver": "1.03",
"xfer2ecr": {
"ver": "1.00",
"sbox": {
"ver": "1.01",
"id": "0c33b432-42cc-17ec-a45a-5c4242535600"
}
}
}
}
2. PAR token
If the PSP/Payment terminal has PAR available this should also be returned in the LocalModeResult as well.
D 04540812******0241;20240430074450;2;992;921415766052;;;;;;;15198354;620089;MASTERCARD;00;KC1;A0000000041010;0000008001;;01106;210901;0000000000;5562973320;MS Handelsban SE;;Undefined;{"od":{"ver":"1.04","xfer2ecr":{"ver":"1.00","sbox":{"ver":"1.00","id":"0c33b432-42cc-11ec-a45a-5c4242545600"}}}};;0;5000000J7S26L5XX5OS5TYBX91PVL;01
PAR: 5000000J7S26L5XX5OS5TYBX91PVL
Create E-Receipt
API credentials for the Storebox POS API (create new receipt) can be requested to Storebox.
-
Using the Storebox API you can perform the “Create New Receipt” request.
API: POS API Documentation ← Please refer to this API. - When requesting “Create New Receipt” you have to define the user-type. Reference:
This field determines what Storebox will try to match the receipt with.
User Type = ‘pan’ | Use this to match members using card-token / PAR token from the payment terminal. |
User Type = ‘cid’ (customer ID) | Use this to match on the merchants member id.* |
*requires configuration by Storebox
User Type = PAN → is the correct option in most cases.
3. Wallet Support (PAN vs PAR token)
There are two different tokens available.
Tokens | Description |
PAN Token | Token based on the PAN (Primary Account Number/Card number) |
PAR Token | Token based on the Visa/Mastercard scheme |
When a cardholder inputs their PAN into a digital wallet (x-pay device) like Apple Pay or Google Pay, the original PAN (FPAN) is converted to a token PAN (TPAN). This creates some issues with recognizing cards if the PAN token is used as there’s now two different PAN’s representing the same card.
The way we solve this issue is by having integrations directly to Visa, Mastercard and Dankort to be able to gather all the needed data when a card is added to by a Storebox user or a merchants member.
We collect the necessary tokens and store them so that the POS can use the PAR token in the Create new receipt request and match the receipts to the cardholder when they choose to use their digital wallet as the payment instrument.
We recommend the POS to have a priority when selecting which token to use:
1. PAR TOKEN - If PAR token is received use PAR token
2. PAN TOKEN - If PAR token is not received use PAN token
Diagram
Credentials in test/prod for the Storebox POS API is created by Storebox, please reach out to your contact if you want access to the API.