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.vixco.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 PayData {
    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 PayData is used.

Services

service PaymentsService {
    rpc StartPayment(stream PayData) returns (stream PayData);

    rpc DoPayment(stream PayData) returns (stream PayData);

    rpc CancelPayment(PayData) returns (PayData);

    rpc IssueReward(PayData) returns (PayData);

    rpc CancelReward(PayData) returns (PayData);
}

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.

StartPayment(START_PAY)

The POS connects to the Payment server and starts a payment transaction. The QR code is read from the TokenPay application.

DoPayment(REQUEST_TRANSFER)

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

StartPayment(REQUEST_TRANSFER)

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

DoPayment(TRANSFER)

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

StartPayament(END_PAY)

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

DoPayment(END_PAY)

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

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.

The response is as follows.

Reward

Issuance

The POS uses IssueReward method. The request is as follows.

The response is as follows.

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.

StartPayment(START_REWARD)

DoPayment(END_REWARD)

StartPayment(END_REWARD)

The second way is to reward from receipts printed at the POS.

DoPayment(START_REWARD)

DoPayment(END_REWARD)

Cancellation

The POS uses CancelReward method. The request is as follows.

The response is as follows.

Error

For each request, the Payment server sends a response with resCode and resMessage.