• Python
  • Golang
  • Java

# 1. Introduction to Cashier Functionality

Gate Pay provides a dynamic and hosted cashier service. After placing an order in the app, the user can jump to the embedded Gate Pay cashier H5 page to complete the payment:

To complete the payment, users can open the Gate App and scan the code, or they can transfer money to the address through other third-party wallets. In the future, there will be more payment methods available for users, such as call payment.

收银台介绍

# 2. Cashier’s operating process

# 2.1 Flow chart

收银台流程图

# 2.2 Call process

Steps 1-6: After the user creates an order request in the merchant’s App, the merchant‘s App calls the cashier’s prepaid order creation interface (/v1/pay/checkout/order). After the prepaid order is successfully created, Gate Pay returns the order information to the merchant.

Steps 7-11: After the merchant successfully creates an order, the page will jump to the cashier according to the address described in the location field (the address is the one specified in the location field of the returned message after a prepaid order is prepaid). GatePay will verify the legitimacy of the redirected order, and if the verification is successful, it will return the order details, and pull up the register.

Steps 12-14: At the register, the user can choose to pay by scanning the code or by transferring funds to the recipient’s address. After the payment is completed and confirmed by GatePay, the order status will be asynchronously notified to the merchant's backend.

# 3.Steps for merchants to access the cashier

# 3.1 Gate Pay’s preparation for accessing

Please refer to the Gate Pay Access Preparation

# 3.2 Get chain information for address payment

To call the cashier order placing interface (/v1/pay/checkout/order), merchants need to provide the chain and chain network information. The process is as follows.

  1. Use the interface(/v1/pay/address/currencies) to query the list of supported currencies for the address payment.
  2. Then use the interface(/v1/pay/address/chains) to acquire the currency’s chain network information.

# 3.3 Merchant calls up Gate Pay cashier

After the merchant's backend service places an order successfully via the cashier’s order interface(/v1/pay/checkout/order), the page will jump to the cashier services according to the address specified in the location field returned by the order placing interface.

# 3.4 Merchant backend obtains order information

After the user completes the payment, Gate Pay will asynchronously notify the order status to the merchant. For detailed information about asynchronous status notification of paid orders, please refer to Gate Pay Access Preparation

Below is the format of cashier-jumping address:

https://www.gate.com/cashier?prepayid=65466648727916544

# 3.5.1 Place an order at the cashier

  • Data type:JSON (content-type: application/json)
  • Method of request:POST
  • Path: /v1/pay/checkout/order
  • Verification method: signature verification
  • Content of request body:
Field Name Type Required Description
merchantTradeNo string Yes Merchant order number
currency string Yes Order currency in uppercase form, such as USDT, BTC, etc.
orderAmount string Yes Order amount, with a maximum precision of 6 digits
payCurrency string No Payment currency for address payment. If not passed, it is the same as currency.
env Env type Yes Transaction source
goods goods type Yes Description of the goods
orderExpireTime int64 No Order expiration time in milliseconds. When not set, the default is 1 hour, and the maximum expiration time is 1 hour.
returnUrl string No Return jump address after the order payment is successful, with a maximum length of 256 characters.
cancelUrl string No Return jump address after the order payment fails, with a maximum length of 256 characters.
merchantUserId int64 Yes Unique consumer ID from the merchant’s platform.
chain string Yes Selected chain name.
fullCurrType string Yes Currency field containing the chain name, corresponding to the specific currency on the specific chain.
channelId string No Client Name.

Env type

Field Name Type Required Description
terminalType string Yes Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS

Goods type

Field Name Type Required Description
goodsName string Yes Goods name, maximum length of 160 characters
goodsDetail string No Goods description, maximum length of 256 characters
goodsType string No Goods category

Response :

Field Name Type Required Description
status string Yes SUCCESS or FAIL
code string Yes Error code
data data type No Refund information
errorMessage string No Error message

data type:

Field Name Type Description
prepayId string Pre-order ID created successfully
terminalType string Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS
expireTime int64 Order expiration time, UTC timestamp in milliseconds. When not set, the default is 1 hour, and the maximum expiration time is 1 hour.
qrContent string Order QR code (valid for 1 hour) returned as a string. Developers need to use tools to generate a QR code image based on the content.
location string Redirect address for launching the cashier after placing an order successfully
payCurrency string Payment currency for address payment
payAmount string Amount to be paid for address payment
chain chain type Address payment chain information structure
chain_type string Chain name
address string Receiving address bound to the order on the chain
fullCurrType string Currency field containing the chain name, corresponding to the specific currency on the specific chain
channelId string Client Name

Example of request:

curl --location 'https://openplatform.gateapi.io/v1/pay/checkout/order' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "merchantTradeNo": "163",
    "env": {
        "terminalType": "APP"
    },
    "currency": "USDT",
    "orderAmount": "118.75",
    "merchantUserId": 123,
    "goods": {
        "goodsType": "02",
        "goodsName": "Sipariş Ödemesi - 177",
        "goodsDetail": "Sipariş No : 160"
    },
    "returnUrl": "https://lotkeys.com/tr/gate-payment-response",
    "cancelUrl": "https://lotkeys.com/tr/gate-payment-response",
    "chain": "MATIC",
    "fullCurrType": "USDT_MATIC",
    "channelId": "123456"
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "65466648727916544",
        "terminalType": "APP",
        "expireTime": 1677573665219,
        "qrContent": "http://openplatform.gate.io/qr/GA0cskPehKxQpshvm3Goeve8dHpwCl6yCHLSWUYrLqo=",
        "location": "https://www.gate.com/cashier?prepayid=65466648727916544",
        "payCurrency": "USDT",
        "payAmount": "1",
        "chain": {
            "chain_type": "BSC",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "fullCurrType": "USDT_EOS"
        },
        "channelId": "123456"
    }
}

# 3.5.2 Cashier’s refund interface

  • Data type:JSON (content-type: application/json)

  • Method of request:POST

  • Path: /v1/pay/checkout/refund

  • Verification method: signature verification

  • Request body’s content:

Field Name Type Required Description
refundRequestId string Yes Merchant refund ID, a unique ID generated by the merchant with a maximum length of 32 bytes
prepayId string Yes Order ID, only orders that have completed payment can initiate a refund
refundOrderCurrency string Yes Refund order currency
refundOrderAmount string Yes Total amount paid by the user and received by the merchant.
refundPayCurrency string Yes pay currency for address payment
refundPayAmount string Yes The refunded amount that remains on-chain after the user makes a payment. The merchant did not receive these funds (in cases of Convert).
refundReason string Yes Reason for the refund
receiverId int64 Yes User ID of the recipient for the address payment refund in the gate system.

Response fields:

Field Name Type Description
refundRequestId string Merchant refund request ID
prepayId string ID of the order to be refunded
orderCurrency string Order currency
orderAmount string Order amount
refundOrderAmount string Total amount paid by the user and received by the merchant.
payCurrency string Payment currency
payAmount string Amount that the user should pay in the order
refundPayAmount string The refunded amount that remains on-chain after the user makes a payment. The merchant did not receive these funds (in cases of Convert).

# 3.5.3 checkout order details

Due to the fact that the cashier possesses all the features of an address payment order, its order status is more comprehensive compared to conventional payment methods such as QR code payment. Therefore, please refer to 6.5 Address Payment Order Details Query for details.

# 4. Notifications for Checkout Counter Payment

Checkout Counter Payment includes payment via Gate Pay and Web3 payment (address payment).

For notifications for payment via Gate Pay, see Common - 4. Asynchronous notification of order status

For notifications for address payment, see Address Payment - 4. Notification

Example of request:

curl --location 'https://openplatform.gateapi.io/v1/pay/checkout/refund' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1697517106839' \
--header 'X-GatePay-Nonce: 3867712705' \
--header 'X-GatePay-Signature: 9f0532870be67e51ccf5adb3f7ce4532d7b0ec692b53ed94654f8b5c6fb257d8c1e60d1d074ea783c7f10ea2dc479e43b4989ff8efaed22aec5c67e797424b93' \
--data '{
    "refundRequestId": "100036668891329",
    "prepayId": "93752669101887488",
    "refundOrderCurrency": "USDT",
    "refundOrderAmount": "100",
    "refundPayCurrency": "USDT",
    "refundPayAmount": "50",
    "refundReason": "test refund",
    "receiverId": 6790011
}'

Response:

{
    "status": "SUCCESS",
    "code": "00000",
    "errorMessage": "",
    "data": {
        "refundRequestId": "32111114322523534534",
        "prepayId": "50620368071692288",
        "orderCurrency": "BTC",
        "orderAmount": "2",
        "refundOrderAmount": "1",
        "payCurrency": "BTC",
        "payAmount": "2",
        "refundPayAmount": "0"
    }
}

# 5. FAQ

# Q:How long is the order valid for?

A: Merchants can set the expiration time for the order at the interface when creating prepaid orders. By default, the expiration time is one hour and the maximum expiration time can't exceed one hour.

# Q:How to calculate the signature in the interface?

A:For details, please refer to the security specification chapter in the GatePay Access Preparation

# Q:What is address payment delayed payment?

A: Definition: Delayed payment refers to the payment with the broadcasting time recorded on the chain later than the expiration time or termination time of the order.

Delayed non-convert payment order: deposit the user's fund to the merchant's payment account

Delayed convert payment order: keep the user's payment funds within the Gate, and do not deposit the funds to the merchant's payment account

# Q: How does the merchant's backend obtain the order payment result?

A:After the payment is successful, Gate Pay will asynchronously notify the merchant's backend of the order status. For detailed information about asynchronous notification of order status, please refer to Gate Pay Access Preparation