Payment (gRPC)
Protocol
We use gRPC/Protocol buffers to communicate with the POS application (for a store), the TokenPay application (for a user), and the Payment server.
Messages
A message consists of a "common" and a "content" fields. Fields in the "common " are fields commonly used in all APIs. Fields in the "content" are different depending on how API is used. However currently only PayData is used.
target_name
"Payment API"
target_svc
"payments.vixco.net"
target_package
Should be "g00.payments.v2"
target_api
API name
source_svc
Source service name
source_ver
Source version
source_addr
Source address, for example IP
req_timestamp
Request timestamp
rsp_timestamp
Response timestamp (only set on the response)
tran_no
Request serial number
res_code
Response code (only set on the response)
res_message
Response message (only set on the response)
Services
Payment
Approval
The POS uses StartPayment method, while the TokenPay uses DoPayment method. These methods are implemented as bidirectional streaming RPC.
DoPayment(START_PAY)
The TokenPay connects to the Payment server.
target_api
"doPayment"
state
State.START_PAY
StartPayment(START_PAY)
The POS connects to the Payment server and starts a payment transaction. The QR code is read from the TokenPay application.
target_api
"startPayment"
state
State.START_PAY
tid
Store TID
tran_no
Transaction number created by POS
exchange_amount
Currency amount
user_uuid
User ID in the QR code read from the TokenPay
contract_address
Token contract address in the QR code
token_symbol
Token symbol in the QR code
user_address
User account address in the QR
expiration_time
Transaction expiration time in the QR code
DoPayment(REQUEST_TRANSFER)
The Payment server sends a token transfer request to the TokenPay.
target_api
"doPayment"
state
State.REQUEST_TRANSFER
tran_no
Transaction number
contract_address
Token contract address
token_amount
Token amount
settlement_address
Store account address to transfer
store_name
Store name to transfer
transfer_comment
Transfer comment
exchange__date_in_dex
Exchange rate notice date and index (yyyyMMdd + NNNNN)
exchange_rate
Exchange rate
exchange_amount
Currency amount
StartPayment(REQUEST_TRANSFER)
The POS is informed that the user is preparing a bank transfer.
target_api
"startPayment"
state
State.REQUEST_TRANSFER
tran_no
Transaction number
DoPayment(TRANSFER)
The user sends relevant information for transfer from the user account to the store account (settlement address).
target_api
"doPayment"
state
State.TRANSFER
tran_no
Transaction number
transfer_key
Temp key for token transfer
hash_key
Hash key for token transfer
transfer_signature
Signature for token transfer
transfer_comment
Transfer comment
StartPayament(END_PAY)
If the transfer is successful, the approval result is returned.
target_api
"startPayment"
state
State.END_PAY
tran_no
Transaction number
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address transferred
token_amount
Token amount
transfer__transaction__id
Transaction ID in the block-chain
approval_no
Approval number
approval_date
Approval date (yyyyMMddHHmmss)
exchange__date__index
Exchange rate notice date and index
exchange_rate
Exchange rate
exchange_amount
Currency amount
DoPayment(END_PAY)
If the transfer is successful, the approval result is returned.
target_api
"doPayment"
state
State.END_PAY
tran_no
Transaction number
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address transferred
token_amount
Token amount
transfer__transaction__id
Transaction ID in the block-chain
exchange__date__index
Exchange rate notice date and index
exchange_rate
Exchange rate
exchange_amount
Currency amount
Cancellation
The POS uses CancelPayment method. If successful, the token from the store account is transferred to the user account. The request is as follows.
target_api
"cancelPayment"
tid
Transaction number created by POS
transfer__transaction__id
Transaction ID of token transfer of the approval
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address
token_amount
Token amount
exchange_amount
Currency amount
The response is as follows.
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address to be transferred
token_amount
Token amount
transfer__transaction__id
Transaction ID of the transfer from the store account to the user account
approval_no
Approval cancellation number
approval_date
Approval cancellation date (yyyyMMddHHmmss)
Reward
Issuance
The POS uses IssueReward method. The request is as follows.
target_api
"issueReward"
tid
Store TID
reward_reason
Reward reason to avoid reward duplication
exchange_amount
Reward amount
The response is as follows.
contract_address
Token contract address
token_symbol
Token symbol
token_amount
Token amount as a reward
exchange__date__index
Exchange rate notice date and index
exchange_rate
Exchange rate
exchange_amount
Currency amount
reward_id
Reward ID which is used for a reward request
reward_date
Rewarded date (yyyyMMddHHmmss)
Reward
There are two ways to reward. The first is to reward at the POS.
The POS uses StartPayment method, while the TokenPay uses DoPayment method. These methods are implemented as bidirectional streaming RPC.ima
DoPayment(START_PAY)
The TokenPay app connects to the Payment server.
target_api
"doPayment"
state
State.START_PAY
(Not State.START_REWARD)
StartPayment(START_REWARD)
target_api
"StartPayment"
state
State.START_REWARD
tid
Store TID
tran_no
Transaction number create by POS
reward_id
Reward ID
token_amount
Token amount as a reward
user_uuid
User ID in the QR code read by the TokenPay
user_address
User account address in the QR code
DoPayment(END_REWARD)
state
State.END_REWARD
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address to be rewarded
token_amount
Token amount as a reward
exchange_date_index
Exchange rate notice date and index
exchange_rate
Exchange rate
exchange_amount
Currency amount
StartPayment(END_REWARD)
state
State.END_REWARD
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address to be rewarded
token_amount
Token amount as a reward
exchange_date_index
Exchange rate notice date and index
exchange_rate
Exchange rate
exchange_amount
Currency amount
The second way is to reward from receipts printed at the POS.
DoPayment(START_REWARD)
target_api
"StartPayment"
state
State.START_REWARD
reward_id
Reward ID read from the receipt
token_amount
Token amount read from the receipt
token_symbol
Token symbol read from the receipt
user_address
User account address
DoPayment(END_REWARD)
state
State.END_REWARD
contract_address
Token contract address
token_symbol
Token symbol
user_address
User account address to be rewarded
token_amount
Token amount as a reward
exchange_date_index
Exchange rate notice date and index
exchange_rate
Exchange rate
exchange_amount
Currency amount
Cancellation
The POS uses CancelReward method. The request is as follows.
target_api
"cancelReward"
rewar_id
Reward ID
token_amount
Token amount
The response is as follows.
contract_address
"cancelReward"
token_symbol
Token symbol
user_address
User account address to be rewarded
token_amount
Token amount
transfer__transaction__id
Transaction ID of the transfer for reward cancellation
approval_no
Approval cancellation number
approval_date
Approval cancellation date (yyyyMMddHHmmss)
Error
For each request, the Payment server sends a response with resCode and resMessage.
Common
00
Success
10
Internal server error
Payment
01
Canceled by the user
02
Insufficient balance
03
Transaction time expired
04
Token API error
Reward
01
Reward not issued
02
Reward expired
03
Reward already canceled
04
Bad reward amount
05
Already rewarded
Last updated