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.

Below is the format of cashier-jumping address:

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

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

3.5 Cashier’s related API list

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

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"
    }
}

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

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.

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"
    }
}

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.1 Asynchronous notification of order status, orderAmount indicates the paid amount for orders with a successful payment status.

For notifications for address payment, see Address Payment - 4.3 Message structure, Within the on-chain validity period, waitAmountOnChain indicates the amount pending confirmation, while doneAmountOnChain indicates the confirmed amount.

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