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.
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.
Please refer to the Gate Pay Access Preparation
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.
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.
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
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"
}
}
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). |
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.
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"
}
}
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.
A:For details, please refer to the security specification chapter in the GatePay Access Preparation。
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
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