e-Buy 收银一体化 英文

Introduction

Purpose

This is a integration system protocol between Cashier Terminal and Backend system.

To enable the Cashier Terminal and e-Buy backend payment and redemption business real-time transaction process and synchronization, reduce reconciliation errors, facilitate business transaction in real-time integration to e-Buy backend system, in order to support multiple business transaction demand, such as multiple payment method and redemption method.

Physical Architecture

Network

Network illustration：

Logic Architecture

@startuml

skinparam monochrome reverse skinparam sequence { ParticipantFontSize 24 ActorFontSize 24 ArrowFontSize 22 GroupFontSize 20 }

participant "Cashier POS" participant "e-Buy Backend" #99FF99

"Cashier POS" -> "e-Buy Backend" : 1.Request　　　　　　　　　　　　　　　　 ||| "e-Buy Backend" -> "Cashier POS" : 2.Response　　　　　　　　　　 ||| ||| @enduml

Flow illustration:

Glossory

Socket

Communication is based on TCP/IP

MIS-POS

Installed in merchants in-store POS machine, providing the operation activity to support and exchange function

e-Buy POSP

A group / set of network equipment and server to process e-Buy POS all transaction activity

BCD

Binary numeric representation format, such as 0x99, it represents the value of 99

TLV

Communication protocol commonly used data formats, Comprise 3 parts: "Tag", "Length" & "Value"

PINPAD

PIN entry device

e-Buy POS

Same as MIS-POS, the device is installed in merchant on-site, providing the operation activity to support and exchange function

e-Buy Backend

A group /set of equipment / server to process all the transaction from e-Buy POS

Middleware

Individual operation in cashier terminal, monitoring the local port, it will also download the key and auto sign in, auto update and prompt transaction options

API Introduction

API Introduction

Invoke Method

Content Description
Protocal HTTP/HTTPS
HTTP Method POST (application/json)
Message Type JSON
Charset UTF-8
Signature Algorithm MD5
Signature Verify Request and Response are both required
API Introduction

Message Structure

Request and response message are both use following structure

No. Parameter Format Reference Description Memo
1 action String inquiry Transaction Type The specific interfaces with detail description
2 deviceNo String POS01 Cashier Terminal No. To identify the Cashier Terminal used in this transaction
3 shopNo String CN123456 Shop No. To identify the merchant / shop in this transaction
4 brand String 663 Brand No. To identify the Brand used in this transaction, allocated by e-Buy
5 body String BASE64 Message Detail The specific interfaces with detail description
6 mwVersion String 20161010 Middleware Version The Middleware is compatible to process with different backend system
7 ptlVersion String 20161010 Protocal Version The protocol is compatible to process with different backend system
8 posVersion String 20161010 e-Buy POS Version The e-Buy POS is compatible to process with different backend system
9 timestamp String 1483372334 Unix Format Unit : second，中间件需要在收到返回时同步该时间
10 sign String 7E65B60DCFA42B04 Signature See detail : Signature Algorithm

example

 {
     "action" : "inquiry",
     "deviceNo" : "POS01",
     "shopNo" : "CN123456",
     "brand" : "663",
     "body" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
     "mwVersion" : "20161010",
     "ptlVersion" : "20161010",
     "posVersion" : "20161010",
     "timestamp" : "1483372334",
     "sign" : "7E65B60DCFA42B04"
 }
API Introduction

Signature process

example

 {
     "action" : "inquiry",
     "deviceNo" : "POS01",
     "shopNo" : "CN123456",
     "brand" : "663",
     "body" : "ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==",
     "mwVersion" : "20161010",
     "ptlVersion" : "20161010",
     "posVersion" : "20161010",
     "timestamp" : "1483372334",
     "sign" : "F38545F4D74B5C10A9EBBC053ED9D1CF"
 }

mwMacKey

94365019BBF9CEEAB0DF658E67754A70

Combine message parameter

action=inquiry&body=ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==&brand=663&deviceNo=POS01&mwVersion=20161010&posVersion=20161010&ptlVersion=20161010&shopNo=CN123456&timestamp=1483372334

Combine KEY

action=inquiry&body=ewogICAgICAgICAidHJhY2VObyI6ICI5OTAwMDAwOTEwMDAxMDEwMTczMjEyMyIsCiAgICAgICAgICJvcmlnaW5hbFRyYWNlTm8iOiAiOTkwMDAwMDkxMDAwMTAxMDE3MzIxMjQiCiAgICAgfQ==&brand=663&deviceNo=POS01&mwVersion=20161010&posVersion=20161010&ptlVersion=20161010&shopNo=CN123456&timestamp=1483372334&KEY=94365019BBF9CEEAB0DF658E67754A70

Signature F38545F4D74B5C10A9EBBC053ED9D1CF

API Introduction

Encryption Algorithm

3DES Introduction

Algorithm

Triple DES uses a "key bundle" that comprises three DES keys, K1, K2 and K3, each of 56 bits (excluding parity bits). The encryption algorithm is:

ciphertext = EK3(DK2(EK1(plaintext))) I.e., DES encrypt with K1, DES decrypt with K2, then DES encrypt with K3.

Decryption is the reverse:

plaintext = DK1(EK2(DK3(ciphertext))) I.e., decrypt with K3, encrypt with K2, then decrypt with K1.

Each triple encryption encrypts one block of 64 bits of data.

In each case the middle operation is the reverse of the first and last. This improves the strength of the algorithm when using keying option 2, and provides backward compatibility with DES with keying option 3.

Keying options

The standards define three keying options:

Keying option 1 All three keys are independent. Keying option 2 K1 and K2 are independent, and K3 = K1. Keying option 3 All three keys are identical, i.e. K1 = K2 = K3. Keying option 1 is the strongest, with 3 × 56 = 168 independent key bits.

Keying option 2 provides less security, with 2 × 56 = 112 key bits. This option is stronger than simply DES encrypting twice, e.g. with K1 and K2, because it protects against meet-in-the-middle attacks.

Keying option 3 is equivalent to DES, with only 56 key bits. It provides backward compatibility with DES, because the first and second DES operations cancel out. It is no longer recommended by the National Institute of Standards and Technology (NIST),[5] and is not supported by ISO/IEC 18033-3.

Each DES key is nominally stored or transmitted as 8 bytes, each of odd parity,[12] so a key bundle requires 24 bytes for option 1, 16 for option 2, or 8 for option 3.

Encryption example

Set pinKey: 9D93D15D6A3913AB4151C456A80841EF:

K1 = 9D93D15D6A3913AB
K2 = 4151C456A80841EF
K3 = 9D93D15D6A3913AB

Data M in HEX：3132333435363738，encryption process：

DES1_RESULT = Ek(M，K1)
DES2_RESULT = Dk(DES1_RESULT，K2)
C = Ek(DES2_RESULT，K3)

Result C：C63AABF759BDE968

Decryption example

Set pinKey: 9D93D15D6A3913AB4151C456A80841EF:

K1 = 9D93D15D6A3913AB
K2 = 4151C456A80841EF
K3 = 9D93D15D6A3913AB

Data C in HEX：C63AABF759BDE968，decryption process：

DES1_RESULT = Dk(C，K3)
DES2_RESULT = Ek(DES1_RESULT，K2)
M = Dk(DES2_RESULT，K1)

Results M：3132333435363738

API Introduction

Password Encryption

ANSI X9.8 Format（带主帐号信息）

加密举例

Parameter Object

Parameter Object

Card Info

Field Type Mandatory Description Memo
cardNo String Yes Card No Mandated for Credit Card payment transaction
password String No Password Mandated when password is required, apply Financial encryption
valid String No Valid Date Mandated for Credit Card payment transaction, format : YYMM
track1 String No Track 1  
track2 String No Track 2 Mandated for Credit Card payment transaction, apply financial encryption
track3 String No Track 3  
cardSn String No IC Serial Mandated for credit card payment transaction, such as IC card, apply Financial encryption
icData String No IC Data Mandated for credit card payment transaction, such as IC card, apply Financial encryption
cardType String No Card Type See details
tc String No Transaction Certificate Transaction Certificate

cardNo encryption

password encryption

track1 encryption

track2 encryption

track3 encryption

cardType Details

Parameter Object

Goods Detail

Field Type Mandatory Description Memo
goodsCategory String Yes Goods Category  
goodsId String Yes Goods ID  
goodsName String Yes Goods Name Used for report , receipt, slip printing
goodsSpec String No Goods Spec Shows in report or receipt
price Price Yes Price Unit : dollar
quantity Integer Yes Quantity  
rebateCode String No Rebate Code Cashier Terminal has pre-set the discount, mandated
activityNo String No Activity No Once e-Buy backend system confirm transaction success, a transaction activity number will return back
memo String No Memo Once e-Buy backend system confirm transaction success, some information will return such as electronic voucher number
voucherId String No Voucher ID Return when have voucher_detail
Parameter Object

Fund Channel

Field Type Mandatory Description Memo
channelNo String Yes Channel No Channel No
channelName String Yes Channel Name Channel Name
channelAmount Price Yes Channel Amount Channel Amount
sectionNo String No Section no Distribution by financial staff, can be entry into the cash register after matching
channelNo channelName Description
user_real_money User paid real money Example：Alipay balance、Alipay Yuebao、Wechat balance、Debit Card or Credit card etc.
user_balance paid by user balance Example：Alipay balance、Alipay Yuebao、Wechat balance etc.
user_bank_card paid by user bank card Example：Debit Card or Credit card
user_credit paid by user e-Wallet credit Example：Alipay huabei，Jingdong credit
user_points paid by user points Example：Credit card points，Tmall Points etc.
merchant_benefit the benifit provided by merchant Example：Merchant discount，Merchant voucher etc.
platform_benefit the benifit provided by enterprise Example：Payment platform discount, Payment platform voucher etc.
ebuy_benefit the benifit provided by e-Buy Example：e-Buy discount, e-Buy voucher etc
Parameter Object

Print Detail

Field Type Mandatory Description Memo
cardNo64 String No The card number (first 6 digits and last 4 digits The card number (first 6 digits and last 4 digits) is required to print as part of return message
bank String No Credit Card issued organization The Credit Card issued organization is required to print as part of return message
bankTid String No Bank Terminal ID Responsed when UnionPay with JLCashPay
bankMid String No Bank Merchant ID Responsed when UnionPay with JLCashPay
paymentOrderNo String No Payment Order no. Payment order no. is required to print as part of return message
paymentUser String No User account User account need be printed.
pointSale String No Point deducted Point deducted is required to print as part of return message
qrCode1 String No Print QR code 1 QR code 1 is required to print as part of return message
qrCode2 String No Print QR code 2 QR code 2 is required to print as part of return message
qrCode3 String No Print QR code 3 QR code 3 is required to print as part of return message
barCode1 String No Print Bar Code 1 Bar Code code 1 is required to print as part of return message
barCode2 String No Print Bar Code 2 Bar Code code 2 is required to print as part of return message
barCode3 String No Print Bar Code 3 Bar Code code 3 is required to print as part of return message
content String No Print Content TLV Format，1F=Receipt title，2F=Receipt transtype
printMode String No Print Mode 1=1 Receipt，2=2 Receipts，3=3 Receipts
Parameter Object

Member Detail

Field Type Mandatory Description Memo
memberId String Yes Member ID  
memberCode String Yes Member Code  
memberName String Yes Member Name  
memberPhone String No Member Mobile  
grade String No Member Grade  
status String No Member Status  
balance String No Balance  
pointBalance String No Point Balance
Parameter Object

Settle Record

Field Type Mandatory Description Memo
activityNo String Yes Activity No  
activityName String Yes Activity Name  
productName String Yes Product Name  
customer String Yes Settle Customer  
isRefund Boolean Yes Is Refund  
volume Integer Yes Transaction Volume  
totalReceiptAmount Price Yes Merchant Receipt Amount  
totalAmount Price Yes Total Amount
Parameter Object

Trans Record

Field Type Mandatory Description Memo
traceNo String Yes Cashier terminal trace no.  
paidAmount String Yes Paid Amount  
status String Yes Match status See detail

status

Parameter Object

Activity Product List

Field Type Mandatory Description Memo
activityProductNo String Yes Activity Product No.  
activityProductName String Yes Activity Product Name  
command String No responsed commands in menus
showOrder String Yes Show order Show as A-Z
Parameter Object

Trans Timestamp

Field Type Mandatory Description Memo
traceNo String Yes Original trace no.  
send String Yes Send timestamp Unix Format,Unit：seconds
recv String Yes Receive timestamp Unix Format,Unit：seconds
Parameter Object

Trans Info

Field Type Mandatory Description Memo
action String Yes 交易action  
traceNo String Yes Cashier terminal trace no.  
orderNo String Yes 易百系统参考号  
transDate String Yes 交易时间 格式：yyyyMMddHHmmss
returnCode String Yes Return code 00 represent successful transaction, else represent fail
returnDesc String Yes Return message Detail explanation / error message per transaction result
paidAmount String Yes 交易成功金额  
activityProductNo String Yes 活动产品编号  
activityProductName String Yes 活动产品名称 活动名称+产品名称
bank String Yes 交易机构标识  
cardNo64 String Yes 卡号或串码  
printContent String Yes 小票打印数据
Parameter Object

Function Menu

Field Type Mandatory Description Memo
iconUrl String Yes icon URL variable-length field
title String Yes Function Name variable-length field
action String Yes Function Action variable-length field
command String Yes Commands in Menus Such as:04|00|Please Swipe card|1|08|00|Product XXX(M)$HDCP00000000072578|0|
childrenFunc List<function> No Nodes in Menus variable-length field
Parameter Object

Head Picture

Field Type Mandatory Description Memo
displayPicUrl String Yes Picture URL in Banner variable-length field
linkUrl String Yes Link URL variable-length field
Parameter Object

Package Detail

Field Type Mandatory Description Memo
packId String Yes Package ID variable-length field
packName String Yes Package Name  
goodsInfoList List<goodsDetail> Yes Goods Detail List
Parameter Object

Order Info

Field Type Mandatory Description Memo
appOrderNo String Yes APP Order No variable-length field
statusCode String Yes Order Status Code variable-length field
status String Yes Order Status Desc Order Status Desc
orderTime String Yes Order Time Format:HH:mm, shows in Order List
orderCreateTime String Yes Order Create Time Format:yyyy-MM-dd HH:mm:ss
orderAmount Price Yes Order Amount  
rcptName String Yes Receiver  
platformName String Yes Tokeout Platform variable-length field, Such as: Baidu, Meituan, less than 8 characters
packageDetailList List<packageDetail> No Package Detail Responsed when Order Detail API called
Parameter Object

Voucher Detail

Field Type Mandatory Description Memo
voucherId String Yes Voucher ID  
voucherName String Yes Voucher Name Used for reports, tickets, etc.
voucherType String Yes Voucher Type
voucherAmount Price Yes Price Unit : dollar
voucherCode String Yes Voucher Code