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

message Common {
    string target_name = 1; // Payments
    string target_svc = 2; // payments.finenex.net
    string target_package = 3; // g00.payments.v1
    string target_api = 4;
    string source_svc = 5;
    string source_ver = 6;
    string source_addr = 7;
    string req_timestamp = 8;
    string language_code = 9;
    string rsp_timestamp = 10;
    string tran_no = 11;
    string res_code = 12;
    string res_message = 13;
}

message FINXPayData {
    enum State {
        START_PAY = 0;
        REQUEST_TRANSFER = 1;
        TRANSFER = 2;
        END_PAY = 3;
        START_REWARD = 4;
        END_REWARD = 5;
    }

    message Content {
        State state = 1;
        string tran_no = 2;
        string user_uuid = 3;
        string token_id = 4; // not used; only for compatibility
        string user_address = 5;
        int64 expiration_time = 6;
        string settlement_address = 7;
        string store_name = 8;
        string token_amount = 9;
        string transfer_key = 10;
        string transfer_signature = 11;
        string transfer_comment = 12;
        string transfer_transaction_id = 13;
        string approval_no = 14;
        string approval_date = 15;
        string exchange_date_index = 16;
        string exchange_rate = 17;
        string exchange_amount = 18;
        string exchange_currency = 19;
        string reward_id = 20;
        string reward_date = 21;
        string reward_reason = 22;
        string tid = 23;
        string contract_address = 24;
        string token_symbol = 25;
        string hash_key = 26;
    }

    Common common = 1;
    Content content = 2;
}

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 FINXData is used.

Field Name	Description
target_name	"Payment API"
target_svc	"payments.finenex.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

service PaymentsService {
    rpc StartFINXPayment(stream FINXPayData) returns (stream FINXPayData);

    rpc DoFINXPayment(stream FINXPayData) returns (stream FINXPayData);

    rpc CancelFINXPayment(FINXPayData) returns (FINXPayData);

    rpc IssueReward(FINXPayData) returns (FINXPayData);

    rpc CancelFINXReward(FINXPayData) returns (FINXPayData);
}

Payment

Approval

The POS uses StartFINXPayment method, while the TokenPay uses DoFINXPayment method. These methods are implemented as bidirectional streaming RPC.

DoFINXPayment(START_PAY)

The TokenPay connects to the Payment server.

Field Name	Description
target_api	"doFINXPayment"
state	State.START_PAY

StartFINXPayment(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	"startFINXPayment"
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

DoFINXPayment(REQUEST_TRANSFER)

The Payment server sends a token transfer request to the TokenPay.

Field Name	Description
target_api	"doFINXPayment"
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

StartFINXPayment(REQUEST_TRANSFER)

The POS is informed that the user is preparing a bank transfer.

Field Name	Description
target_api	"startFINXPayment"
state	State.REQUEST_TRANSFER
tran_no	Transaction number

DoFINXPayment(TRANSFER)

The user sends relevant information for transfer from the user account to the store account (settlement address).

Field Name	Description
target_api	"doFINXPayment"
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

StartFINXPayament(END_PAY)

If the transfer is successful, the approval result is returned.

Field Name	Description
target_api	"startFINXPayment"
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

DoFINXPayment(END_PAY)

If the transfer is successful, the approval result is returned.

Field Name	Description
target_api	"doFINXPayment"
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 CancelFINXPayment 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	"cancelFINXPayment"
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 StartFINXPayment method, while the TokenPay uses DoFINXPayment method. These methods are implemented as bidirectional streaming RPC.

DoFINXPayment(START_PAY)

The TokenPay app connects to the Payment server.

Field Name	Description
target_api	"doFINXPayment"
state	State.START_PAY (Not State.START_REWARD)

StartFINXPayment(START_REWARD)

Field Name	Description
target_api	"StartFINXPayment"
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

DoFINXPayment(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

StartFINXPayment(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.

DoFINXPayment(START_REWARD)

Field Name	Description
target_api	"StartFINXPayment"
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

DoFINXPayment(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 CancelFINXReward method. The request is as follows.

Field Name	Description
target_api	"cancelFINXReward"
rewar_id	Reward ID
token_amount	Token amount

The response is as follows.

Field Name	Description
contract_address	"cancelFINXReward"
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