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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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).
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
target_api | "issueReward" |
tid | Store TID |
reward_reason | Reward reason to avoid reward duplication |
exchange_amount | Reward amount |
The response is as follows.
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
target_api | "doPayment" |
state | State.START_PAY (Not State.START_REWARD) |
StartPayment(START_REWARD)
Field Name | Description |
---|---|
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)
Field Name | Description |
---|---|
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)
Field Name | Description |
---|---|
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)
Field Name | Description |
---|---|
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)
Field Name | Description |
---|---|
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.
Field Name | Description |
---|---|
target_api | "cancelReward" |
rewar_id | Reward ID |
token_amount | Token amount |
The response is as follows.
Field Name | Description |
---|---|
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.
Type | resCode | 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