Skip to main content
API docs by Redocly

CodePay Cloud Open Api (1.0.0)

Integration with Point of Sale

Create Order

The merchant backend calls this API and the CodePay server sends a message to the "CodePay Register" application on the payment terminal. This activates the application, displays the order for confirmation by the cashier and guides the user through the payment process.

For more information, see Cross-terminal Application Integration - Cloud Mode

Note: This API supports sale, void, refund, authorization, etc., not just the sale. Please refer to transtype

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string <= 32 characters

Interface method, fixed value for this API: wisehub.cloud.pay.order

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

store_no
string <= 32 characters

Store number, obtained after registering the store, see Parameters to get

terminal_sn
required
string <= 32 characters

Device hardware serial number

message_receiving_application
required
string <= 32 characters

The message receiving application, here fixed at "CodePay Register".

pay_scenario
string <= 32 characters
Default: "SWIPE_CARD"
Enum: "BSCANQR_PAY" "SCANQR_PAY" "SWIPE_CARD"

Payment scene, please refer to PayScenario

pay_method_id
string

To specify the use of a particular payment method, refer to PayMethod

card_type
integer

Type of bank card,please refer to CardType

price_currency
required
string <= 8 characters

Denominated currencies, conforming to ISO-4217, are described by a code based on three characters, e.g.: USD

order_amount
required
number <float>

The amount of the order, in the currency in which it is denominated, e.g., 1 USD for one U.S. dollar, not one U.S. cent.

tip_amount
number <float>

Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent.

Example: 34.50

on_screen_tip
boolean
Default: "false"

Whether or not to enter tips on the CodePay Rigister page, default is false, when "trans_type=1, 3, 4", this parameter can be set

Example: true

cashback_amount
number <float>

Cash back amount, order amount+cash back amount=transaction amount

When trans_type=11, the value of this parameter can be set

trans_type
required
integer

Transaction type, refer to TransType

merchant_order_no
required
string <= 32 characters

The internal order number of the merchant system must be within 32 characters and can only be a number, uppercase and lowercase letters _ - | * @, And unique under the same merchant
Example value: 1217752501201407033233368018

orig_merchant_order_no
string <= 32 characters

Original trading merchant system order number, required for trans_type = 2, 3, 6

description
required
string <= 128 characters

A brief description of the goods or services purchased by the customer

attach
string <= 128 characters

Allows the merchant to submit an additional data to the gateway, which will be returned unaltered for payment notifications and queries

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications, see Callback Notification Notes for details.

Please refer to transaction result notification for the notification message structure.

expires
required
integer

Order payment timeout period, after which the order can no longer be paid or cancelled and the order will be closed, the unit of this time is: second

order_queue_mode
string <= 8 characters
Deprecated
Default: "FIFO"
Enum: "FIFO" "FILO"

Order queue mode, which sets the sorting rules for orders. When pushing multiple orders, priority is given to new or old orders.

reject_trade_when_terminal_offline
boolean
Default: "false"

Whether to reject the transaction when the terminal is offline, default is false.

Please be careful to set this value, due to the instability of the terminal network, there is a delay in the online status of the device may be, use this function please test before deciding whether to apply in your production environment

required_terminal_authentication
boolean
Default: "false"

When refund or void a transaction, does the store manager role need to authorize this operation on the terminal? default value: false

on_screen_signature
boolean
Default: "true"

This parameter controls the display logic of electronic signatures:

  • true: Display the electronic signature page and print the signature information on the purchase order
  • false: The electronic signature page will not be displayed, but the signature area needs to be printed on the purchase order

But even if this parameter is set, CodePay Register still processes electronic signatures according to the following logic in the following situations:

  • Credit card network, APP does not display signature page, fixed on receipt to print signature column
  • Pin debit transactions do not require a signature, the APP does not display a signature page, and the receipt is not printed either
receipt_print_mode
integer
Default: 0

Receeipt printing mode
0: No printing, default value
1: Print merchant copy
2: Print customer copy
3: Print merchant copy + customer copy

confirm_on_terminal
boolean
Default: "false"

Before the transaction, do you need CodePay Register to display a confirmation interface? The cashier can only proceed with the transaction after clicking confirm. By default, no confirmation is required and you can directly enter the card reading interface

api_version
required
string

Version of this API, fixed value "2.0".

Value: "2.0"

Responses

Request samples

Content type
application/json
{
  • "charset": "UTF-8",
  • "pay_scenario": "SWIPE_CARD",
  • "sign": "S+CtwegIorhprPzMehjAXu6TwmMqDV16l7Pqy77BRaN6O8Ekh75UXr1RDob/1pgxz0RxHF8q8vJYsChPszjNiuVvISTZhs/4VPeLYT01VsCRHO2O9bzcnv9kss/h98Bb0KlRci7mBaSLPF0lmhWhsVhNlicx1k8nSs9VZSbqtLwsje1g+V3uXTosRG00WPkIYj0txGoZT7zgrzZZ/Yt8YqPqp8JpKFyx+DtCG+OdxjifXHMnmVr7epAyu+Qh0hmyODHfbdSGz8+QBqjPOZhmwN4UFdUTY5C5/8y8SeO1t3hNJ8l/i9+dUCbXEUM3+e0mnNWXZNGwAWXPRAGwoUHm4A==",
  • "description": "ECRCloudPurchase",
  • "on_screen_signature": false,
  • "merchant_order_no": "1709106082732",
  • "on_screen_tip": false,
  • "order_amount": 144.34,
  • "app_id": "wz6012822ca2f1as78",
  • "sign_type": "RSA2",
  • "price_currency": "USD",
  • "reject_trade_when_terminal_offline": true,
  • "terminal_sn": "WPYB002248000865",
  • "trans_type": 1,
  • "timestamp": "1709106082819",
  • "merchant_no": "302300000926",
  • "method": "wisehub.cloud.pay.order",
  • "format": "JSON",
  • "order_queue_mode": "FILO",
  • "api_version": "2.0",
  • "notify_url": "http://simulator.wisepaycloud.com/simulator/gateway/success",
  • "version": "1.0",
  • "confirm_on_terminal": false,
  • "message_receiving_application": "CodePay Register",
  • "tip_amount": 30
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Close Order

To close the order, the merchant's backend should call this API. Then, the payment gateway will close the order and send a message to the designated application on IoT devices (such as smart POS) to remove the order from the queue.

Note: Only pre paid orders (trans_status=9) should be closed using this API. The completed order (trans_status=2) should be cancelled through [Create Order API]

For more information, please refer to Cross Terminal Application Integration - Cloud Mode

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string <= 32 characters

Interface method, fixed value for this API: wisehub.cloud.pay.close

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

store_no
string <= 32 characters

Store number, obtained after registering the store, see Parameters to get

terminal_sn
required
string <= 32 characters

Intelligent financial terminal SN, need to be bound to the merchant store under the

merchant_order_no
required
string <= 32 characters

The internal order number of the merchant system must be within 32 characters and can only be a number, uppercase and lowercase letters _ - | * @, And unique under the same merchant
Example value: 1217752501201407033233368018

description
string <= 128 characters

Reasons for closing transactions

message_receiving_application
required
string

The message receiving application, here fixed at "CodePay Register".

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "312300000471",
  • "charset": "UTF-8",
  • "method": "wisehub.cloud.pay.close",
  • "store_no": "4123000005",
  • "format": "JSON",
  • "sign": "ArQMn/GstPdKNe3eXUSf6NpXuvxBp3oa7v7R38OviAcxmP10jVPhiuCiws6qtMDvFjJw/Ex39YMDy3+EYMXIyz4FMiMIB3TxVkCFna9i8vRhWpM4Ohdle7IRNyoOvWYHyZN5elRTaYr5SIRx/OOLYLRmIBt09zvPDkhSZ79JmfmvXxRHJrHyJBwYnvlI+63fe8bRb0VXqwD9aUCRI3AEYBuW1mZzI3HOtuwbfWFZr/oe42IrPAcYExPXJX6D32u2FrTbQHekuAtoaSGHzzImG7L5gxIfHIYLq6M1RTKDGq31pRcZuqvUW0SdwIiL2doKxJcVLsQmzBXz3CcwaBkKkQ==",
  • "version": "1.0",
  • "merchant_order_no": "1709188002729",
  • "message_receiving_application": "CodePay Register",
  • "app_id": "wz6012822ca2f1as78",
  • "sign_type": "RSA2",
  • "terminal_sn": "WPYB002248000865",
  • "timestamp": "1709188013826"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Checkout

CodePay Hosted Checkout

The merchant wants to use CodePay's hosted checkout for payment, redirecting users to CodePay's checkout page. To achieve this functionality, the merchant can request this API. It will collect the user's order information, save the order within the CodePay system, and synchronously return the checkout page URL "pay_url". The merchant can then redirect users to this page, where users will input their payment details and complete the payment.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format: only JSON is supported.

Value: "JSON"
charset
required
string <= 8 characters

Encoding format for requests: only UTF-8 is supported.

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

API message signature, used to verify the identity of the developer and to prevent message tampering. For more details, please refer to Signature Specification

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of the request sending, represented as a 13-digit number. It must not be earlier or later than the current time by 15 minutes.

method
required
string

Interface method, fixed value for this API: pay.checkout

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

store_no
string <= 32 characters

Store number, obtained after registering the store, see Parameters to get

merchant_order_no
required
string <= 32 characters

Merchant's internal order number, limited to 32 characters, can only consist of numbers, lowercase letters, uppercase letters, and the symbols _-|*@. It must be unique within the same merchant. Example: 1217752501201407033233368018

price_currency
required
string <= 8 characters

The currency in which the price is denominated, represented by its ISO-4217 currency code, consisting of three characters. For example: USD.

order_amount
required
number <float>

Order amount, expressed in the currency specified, for example: 15.43.

expires
required
integer

Order payment validity period, beyond which the order cannot be paid and will be closed. Time unit: seconds.

Please set an appropriate order timeout.Maximum expiration time is 7 days.

description
required
string <= 128 characters

Brief description of the goods or services purchased by the customer.

term_ip
string <= 32 characters

The IP address of the terminal.

longitude
string

Geographical longitude of the terminal

latitude
string

Geographical latitude of the terminal

return_url
string <= 256 characters

After successful/failure/cancellation of payment, CodePay redirects the user to the URL of the merchant's website. Upon redirection to this page, the merchant should query the backend for the order status instead of relying on the frontend page status as the payment result.

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications, see Callback Notification Notes for details.Please refer to transaction result notification for the notification message structure.

attach
string <= 128 characters

Merchants are allowed to submit additional data to the gateway, which will be returned as-is during payment notifications and queries.

object

Order details, including product list, logistics configuration, billing address settings, payment options, and interface theme configuration.

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302300000342",
  • "charset": "UTF-8",
  • "method": "pay.checkout",
  • "format": "JSON",
  • "description": "Iphone 16",
  • "order_detail": "{\"data\":{\"shipping\":{\"allow_regions\":\"[\\\"US\\\"]\"},\"payment\":{\"disallow_options\":\"[\\\"GooglePay\\\"]\",\"allow_options\":\"[\\\"Card\\\", \\\"ApplePay\\\"]\"},\"theme\":{\"palette\":{\"text\":{\"primary\":\"rgb(173,216,230)\"},\"primary\":{\"contrastText\":\"rgb(230,230,230)\",\"main\":\"rgb(255,0,0)\"}}},\"items\":[{\"image\":\"https://img0.baidu.com/it/u=451654732,3389558718&fm=253&fmt=auto&app=138&f=JPEG?w=607&h=443\",\"amount\":300.68,\"code\":\"C001787199\",\"quantity\":2,\"name\":\"Iphone 16\",\"unit_price\":150.34},{\"image\":\"https://img2.baidu.com/it/u=3979873743,2390981689&fm=253&fmt=auto&app=120&f=JPEG?w=889&h=500\",\"amount\":50.01,\"code\":\"C001787198\",\"quantity\":1,\"name\":\"AirPods 4\",\"unit_price\":50.01}],\"billing\":{\"allow_regions\":\"[\\\"US\\\"]\"}},\"type\":\"GENERAL\"}",
  • "version": "1.0",
  • "merchant_order_no": "TEST_1734343519886",
  • "order_amount": 150.34,
  • "app_id": "wze0fcae4016b4da15",
  • "sign_type": "NONE",
  • "price_currency": "USD",
  • "timestamp": "1734343520010"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Merchant Hosted Checkout

For merchants using the merchant-hosted checkout for payment, submit the order information and card details to CodePay. CodePay will process the payment immediately and return the payment result synchronously. If 3DS authentication is required, the redirect_url_3dsecure will be returned. Please redirect the user’s request to this URL. After completing the authentication, CodePay will redirect to the merchant’s return_url. Please handle asynchronous notifications and actively query the order to obtain the payment result.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format: only JSON is supported.

Value: "JSON"
charset
required
string <= 8 characters

Encoding format for requests: only UTF-8 is supported.

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

API message signature, used to verify the identity of the developer and to prevent message tampering. For more details, please refer to Signature Specification

version
required
string <= 16 characters

Version number: fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of the request sending, represented as a 13-digit number. It must not be earlier or later than the current time by 15 minutes.

method
required
string

The API name for the request, fixed value for this API: pay.merchant.checkout

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

store_no
string <= 32 characters

Store number, obtained after registering the store, see Parameters to get

required
object

Bank card payment details. Please encrypt the card_info using CodePay's public key, gateway_rsa_public_key. Convert the card to a string first, then encrypt the entire string.

For the encryption method, please refer to RSA encryption

required
object

Billing Address

merchant_order_no
required
string <= 32 characters

Merchant's internal order number, limited to 32 characters, can only consist of numbers, lowercase letters, uppercase letters, and the symbols _-|*@. It must be unique within the same merchant. Example: 1217752501201407033233368018

price_currency
required
string <= 8 characters

The pricing currency, described by a three-character code based on the ISO-4217 currency code. For example: USD.

order_amount
required
number <float>

Order amount, expressed in the currency specified, for example: 15.43.

expires
required
integer

The effective duration for payment of the order. Once this duration is exceeded, the order will no longer be payable and will be closed. The time unit is seconds. Please set an appropriate order timeout period.

description
required
string <= 128 characters

A brief description of the goods or services purchased by the customer.

term_ip
string <= 32 characters

The IP address of the terminal.

longitude
string

Geographical longitude of the terminal

latitude
string

Geographical latitude of the terminal

return_url
string <= 256 characters

After successful/failure/cancellation of payment, CodePay redirects the user to the URL of the merchant's website. Upon redirection to this page, the merchant should query the backend for the order status instead of relying on the frontend page status as the payment result.

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications, see Callback Notification Notes for details.Please refer to transaction result notification for the notification message structure.

attach
string <= 128 characters

Merchants are permitted to submit additional data to the gateway, which will be returned unchanged during payment notifications and queries.

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz3c35784c2cbe6f37",
  • "format": "JSON",
  • "charset": "UTF-8",
  • "sign_type": "RSA2",
  • "sign": "VD3AnpSR08BALF7U+A22kVCJOisv9WCCZJ1TGZSmM2lwhixKIi/uUPVYcB6gODbIsBmwJ2Cw9TtI/JiXJFPlJALLncrWTtxKeTxYWhkmnteiih6GhFw1hoFJqxJFgWoLXQI/pvZJr8NognBJjHE56uXBjqIyVanPaXvy3Xb47Cnbt29am7DuQJOyrylfGklbmZQW+kkMjrD4vhrPjvIaebSvkumL5CTOv5uXORYVVijd9UqOMZzTQjilpnH0In2+qZBsY/5if4ZCduFFItf31GRiJOh9WkR0nCiVJjt8y6eSs4Ms2FS9ZiISWgMMSwrkgqYAAJm4GpaP9UUAkmuGVg==",
  • "version": "1.0",
  • "timestamp": 1693280636972,
  • "method": "string",
  • "merchant_no": "string",
  • "store_no": "4021000008",
  • "card": {
    },
  • "billing_address": {
    },
  • "merchant_order_no": "1217752501201407033233368018",
  • "price_currency": "USD",
  • "order_amount": 34.5,
  • "expires": 5,
  • "description": "IPhone White X2",
  • "term_ip": "string",
  • "longitude": "string",
  • "latitude": "string",
  • "return_url": "string",
  • "notify_url": "http://www.mersite.com/pay/notify",
  • "attach": "{“key”:”value”, “key2”:”value2”}"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Reference Transaction

Capture Payment

Captures transactions are used to capture a previous AUTHORIZE. An Amount less than the amount authorized is accepted (for example, $100 bar tab may have been authorized, but only $85 captured)

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

merchant_order_no
required
string <= 32 characters

ECR system order number, each transaction must ensure a unique merchant_order_no

trans_no
required
string <= 32 characters

Unique transaction number of the original authorization.

trans_amount
required
number <double>

Amount to be captured

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "merchant_order_no": "1217752501201407033233368018",
  • "trans_no": "5021000010210602000003",
  • "trans_amount": 85
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Incremental Authorization

Used to increase the authorized amount. An example use might be a bar tab as more products are ordered, or a hotel stay as more nights are added. An incremental authorization increases the original authorization amount by the specified amount in the request. The new total authorized amount of a transaction is the sum of the original amount and all subsequent incremental authorizations.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

trans_no
required
string <= 32 characters

Unique transaction number of the original authorization.

trans_amount
required
number <double>

Additional amount to be authorized

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "trans_no": "5021000010210602000003",
  • "trans_amount": 85
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Cancel Payment

Cancels the authorisation on a payment that has not yet been captured

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

merchant_order_no
required
string <= 32 characters

ECR system order number, each transaction must ensure a unique merchant_order_no

trans_no
required
string <= 32 characters

Unique transaction number of the original authorization.

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "merchant_order_no": "1217752501201407033233368018",
  • "trans_no": "5021000010210602000003"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Refund Payment

Refunds a payment that has been captured

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

merchant_order_no
required
string <= 32 characters

ECR system order number, each transaction must ensure a unique merchant_order_no

trans_no
required
string <= 32 characters

Unique transaction number of the original authorization.

order_amount
number <double>

Order amount to be refunded

tip_amount
number <double>

Tip amount to be refunded

surcharge_amount
number <double>

Surcharge amount to be refunded

sales_tax_amount
number <double>

Sales tax amount to be refunded

service_charge_amount
number <double>

Service charge amount to be refunded

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "merchant_order_no": "1217752501201407033233368018",
  • "trans_no": "5021000010210602000003",
  • "order_amount": 2
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Tip Adjustment

Add a tip amount to or modify a tip amount on a transaction

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

trans_no
required
string <= 32 characters

Unique transaction number of the original authorization.

tip_amount
required
number <double>

Tip amount to be added or modified

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "trans_no": "5021000010210602000003",
  • "tip_amount": 1
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Recall transaction

Retrieve a previous transaction, using trans no or merchant order no.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

trans_no
string <= 32 characters

Unique transaction number of the original authorization.

merchant_order_no
string <= 32 characters

Unique merchant order number of the original authorization.

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "trans_no": "5021000010210602000003"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Settlement

Batch Close

Closes the merchant’s currently open batch and submits all included transactions for settlement. Once closed, the batch cannot be modified, and the processor/acquirer will initiate settlement of funds to the merchant’s account.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

store_no
string <= 32 characters

Store number, obtained after registering the store, see Parameters to get

terminal_sn_list
Array of strings

Terminal serial number list. If empty, the batch close will be performed for all terminals under the store

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "W6M/IZTN+tuvvAeIhUDFECeUTRzFszOOxM+ozIqUdWw2CENO9G2z9ehfMdrktNmlP7TjFr6Ind/6DO5ZPhWaVu6Nx7K8UkicNwlu/BK4j8s+K108hzYUNQsVEE3ScvB46vyrxUIXdqG83Zvw3rK+o56tnU7YGodOuqGP20nx/emuLPZj7GBZEGrdgY0mRUmJHw951Hc0BYKLqa9jBuJbQzu4AkymyCX/9/G2KrVsaFWxoc7KR0vA/K84pLSe+JFggS6P9Xq4xjZBWqsWN60a39FtGYS9g5/ETT+vvjmyDBOW2hvRzUiEOvos77L/RteRbVnPxcciC/6IP4YEg0Zq7Q==",
  • "merchant_no": "302100041048",
  • "store_no": "4021000008",
  • "terminal_sn_list": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Get Open Batch

Retrieves summary information about the merchant’s currently open batch, including the number of transactions and the total authorized amount. Allows to quickly check batch status without retrieving individual transaction details.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

sign
required
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

store_no
string <= 32 characters

Store number, obtained after registering the store, see Parameters to get

terminal_sn_list
Array of strings

Terminal serial number list. If empty, the batch close will be performed for all terminals under the store

Responses

Request samples

Content type
application/json
{
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign": "W6M/IZTN+tuvvAeIhUDFECeUTRzFszOOxM+ozIqUdWw2CENO9G2z9ehfMdrktNmlP7TjFr6Ind/6DO5ZPhWaVu6Nx7K8UkicNwlu/BK4j8s+K108hzYUNQsVEE3ScvB46vyrxUIXdqG83Zvw3rK+o56tnU7YGodOuqGP20nx/emuLPZj7GBZEGrdgY0mRUmJHw951Hc0BYKLqa9jBuJbQzu4AkymyCX/9/G2KrVsaFWxoc7KR0vA/K84pLSe+JFggS6P9Xq4xjZBWqsWN60a39FtGYS9g5/ETT+vvjmyDBOW2hvRzUiEOvos77L/RteRbVnPxcciC/6IP4YEg0Zq7Q==",
  • "merchant_no": "302100041048",
  • "store_no": "4021000008",
  • "terminal_sn_list": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Deprecated

Tip Adjustment

This API enables merchants to add or modify tip amounts in transactions, and mark transactions for settlement. If the transaction has already been settled or does not meet the modification conditions, the request will be rejected.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string <= 32 characters

Interface method, fixed value for this API: tip.adjustment

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

merchant_order_no
required
string <= 32 characters

The internal order number of the merchant system must be within 32 characters and can only be a number, uppercase and lowercase letters _ - | * @, And unique under the same merchant
Example value: 1217752501201407033233368018

tip_adjustment_amount
required
number <double>

Tip adjustment amount

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302100041048",
  • "charset": "UTF-8",
  • "method": "tip.adjustment",
  • "format": "JSON",
  • "sign": "W6M/IZTN+tuvvAeIhUDFECeUTRzFszOOxM+ozIqUdWw2CENO9G2z9ehfMdrktNmlP7TjFr6Ind/6DO5ZPhWaVu6Nx7K8UkicNwlu/BK4j8s+K108hzYUNQsVEE3ScvB46vyrxUIXdqG83Zvw3rK+o56tnU7YGodOuqGP20nx/emuLPZj7GBZEGrdgY0mRUmJHw951Hc0BYKLqa9jBuJbQzu4AkymyCX/9/G2KrVsaFWxoc7KR0vA/K84pLSe+JFggS6P9Xq4xjZBWqsWN60a39FtGYS9g5/ETT+vvjmyDBOW2hvRzUiEOvos77L/RteRbVnPxcciC/6IP4YEg0Zq7Q==",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "version": "1.0",
  • "merchant_order_no": "TEST_1654765371046",
  • "timestamp": "1693902797892",
  • "tip_adjustment_amount": "30.05"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": { }
}

Batch close

Close the current batch, and new transactions will proceed to a new batch. After the batch transaction, the current batch transaction can only be refunded and cannot be canceled. Closing the batch does not mean that settlement will be made immediately.

Only offline bank card transactions will be settled, and online bank card transactions and QR transactions will not be settled.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string <= 32 characters

Interface method, fixed value for this API: batch.close

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

terminal_sn
required
string <= 32 characters

Device hardware serial number

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302100041048",
  • "charset": "UTF-8",
  • "method": "batch.close",
  • "format": "JSON",
  • "sign": "W6M/IZTN+tuvvAeIhUDFECeUTRzFszOOxM+ozIqUdWw2CENO9G2z9ehfMdrktNmlP7TjFr6Ind/6DO5ZPhWaVu6Nx7K8UkicNwlu/BK4j8s+K108hzYUNQsVEE3ScvB46vyrxUIXdqG83Zvw3rK+o56tnU7YGodOuqGP20nx/emuLPZj7GBZEGrdgY0mRUmJHw951Hc0BYKLqa9jBuJbQzu4AkymyCX/9/G2KrVsaFWxoc7KR0vA/K84pLSe+JFggS6P9Xq4xjZBWqsWN60a39FtGYS9g5/ETT+vvjmyDBOW2hvRzUiEOvos77L/RteRbVnPxcciC/6IP4YEg0Zq7Q==",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "version": "1.0",
  • "timestamp": "1693902797892",
  • "terminal_sn": "P3171916581910"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": { }
}

Query Order

This interface provides query for all payment orders. Merchants can actively query the order status through this interface to complete the next step of business logic.

The scenarios for using this API include

  1. If there is any problem with your backend, it may lead to missed payment notification.
  2. If there is a system failure, or the transaction status remains unclear after payment.
  3. To monitor the payment status after triggering the "bscanc.pay.submit" API.
  4. if the transaction status is unclear, for example after calling the "cscanb.pay.getQRCode" or "pay.unifiedorder" APIs.
  5. confirm the payment status before launching the cancel order API.
Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string

Interface method, fixed value for this API: order.query

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

merchant_order_no
string <= 32 characters

Merchant system order number, each transaction must ensure a unique merchant_order_no and trans_no must be either, and when both exist, trans_no priority

trans_no
string <= 32 characters

CodePay transaction number, uniquely identifying a transaction transaction_order_no and trans_no must be either, and when both exist, trans_no priority

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "312100041048",
  • "charset": "UTF-8",
  • "method": "order.query",
  • "format": "JSON",
  • "sign": "D2mHAJWclOpKTEiqoNV12XCVJzhS3RefjZs/y2PgXxS6qLZklxP7odqb30BK5ZOf3PSXzPYielT7fL1CwNbdHSpOhrkkrOsLXYsEgL5dcrJEfiV8dYZWnTh8pdCe4RUW6AegITNXbiQdb6GdI1sEJIUbFZbFqtR5V8LQeUuXaqFp17sF/uN0RHkhIUthAFa5il8TGnUBPsqQVvjJhv10v/DhlQZ4PtIr6SGDqaFmSBWfUoESuq6Xs2v6TB7abzORoXhw0EyvIFDqYBJVERAFUHzPoJZZsVyJaXM4mn/MJ5hE9oUtKe6R+ergAfgPNFP5+Hp//PJjrMM5iK6MXE7j1Q==",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "version": "1.0",
  • "merchant_order_no": "TEST_1686732708342",
  • "timestamp": "1693898084054"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "data": {
    },
  • "msg": "success",
  • "psn": "09050714451053895687",
  • "sign": "X/kTK7T3fbUBeSAHU/F6KLcBYPouyEISuKqLBC8LnZ/IOQA1vhdfmK2fLiSv6OCEeB3Dm3fDOIpKQKhy15GgmxhDUiTEa0w3VwFbg1Qpo6eXd3MYw0vudPtBVcYeIOZNs653KshQzkIrSHLNZJhawd2Nl2E1utRmphNxqf13xQ9hFg9OQUZOiSl4zchDSiVfVlf03vIuh6Rswc7QXIVHlwTHmF1JV81x/986eV68pKIsekvn9V+qLIRJ0FpaIs5yGkDk6ZcXzAEHXwWX8k0/ntAyOz+TvpyjA6RRGt+jCTMdUlzJRINiIbFa4FzEWweUvyMVWy5fMHKzdvJyNqksrQ=="
}

Query Refund

If a refund is required after payment is completed, you can apply for a refund through this API. Once the payment gateway confirms the legality of the refund request, the amount will be refunded to the payer according to the established refund criteria.

  1. Multiple partial refunds can be made using the original order number. However, the total amount of all refunds should not exceed the original payment amount. Normally, a partial refund for an order should not exceed 50 transactions.
  2. After a refund, you should use the [Query Refund] API to check its status. Please remember that refunds may not be immediate and may be affected by specific payment channel policies.
Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string

Interface method, fixed value for this API: order.refund.query

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

merchant_order_no
string <= 32 characters

Merchant refund request order number merchant_order_no and trans_no cannot be empty at the same time and must choose between two. When both exist, trans_no priority

trans_no
string <= 32 characters

CodePay refund transaction number merchant_order_no and trans_no cannot be empty at the same time and must choose between two. When both exist, trans_no priority

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302100002572",
  • "charset": "UTF-8",
  • "method": "order.refund.query",
  • "format": "JSON",
  • "sign": "GutzRQrBW2ZLy3KssFocqpLIyV/Z8h1SDgg4uOZikC2HmbT2RvRpkpwUwmNs2riMNb44eiT/IP6RlRiD+h2wKXt66rjhIHEAbc/yB6ib4KGumsGwiC/+mFB+oo34AOBBbHS0wuGzwm764LAyaHkjmUNsC0ojBXtER3T2gpZq6KwchMv/Ecw5y3kbnGdidIvGcbcygEXnHktz4YEJEPisXfh6PH7etpzvWloZfBdLPY6EgQCLepFIbh0Cer44gLWcfgDuIFwp6NzaW/d+3LJKJxNTTXxjKrEtopjPGm4jpd2T52o5OeIlifFKLRT74R6H4w9t0ry/JxscwvySpqFFfg==",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "version": "1.0",
  • "merchant_order_no": "TEST_1623925902130_002",
  • "timestamp": "1693905451835"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "data": {
    },
  • "msg": "success",
  • "psn": "09050714451053895687",
  • "sign": "X/kTK7T3fbUBeSAHU/F6KLcBYPouyEISuKqLBC8LnZ/IOQA1vhdfmK2fLiSv6OCEeB3Dm3fDOIpKQKhy15GgmxhDUiTEa0w3VwFbg1Qpo6eXd3MYw0vudPtBVcYeIOZNs653KshQzkIrSHLNZJhawd2Nl2E1utRmphNxqf13xQ9hFg9OQUZOiSl4zchDSiVfVlf03vIuh6Rswc7QXIVHlwTHmF1JV81x/986eV68pKIsekvn9V+qLIRJ0FpaIs5yGkDk6ZcXzAEHXwWX8k0/ntAyOz+TvpyjA6RRGt+jCTMdUlzJRINiIbFa4FzEWweUvyMVWy5fMHKzdvJyNqksrQ=="
}

Cancel Order

If the payment transaction fails or the payment system times out, call the interface to cancel the transaction. If the user's payment for this order fails, the CodePay system will close the order; If the user pays successfully, the CodePay system will refund the funds for this order to the user.

If you encounter situations where the payment status is unclear, you should use this API to initiate cancellation. For transactions that have been successfully completed, if a refund is required, you should call [ Submit Order Refund API]. It is very important to call [Query Order API] after any transaction to confirm its status. If the status is still unclear, please wait for a 15 second window after creating the original order and call the cancel order API again.

Note: This API does not support cancel offline bank card transactions, only supports cancel QR transactions and online e-commerce transactions.

Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string <= 32 characters

Interface method, fixed value for this API: order.revoker

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

merchant_order_no
required
string <= 32 characters

The internal order number of the merchant system must be within 32 characters and can only be a number, uppercase and lowercase letters _ - | * @, And unique under the same merchant
Example value: 1217752501201407033233368018

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302100041048",
  • "charset": "UTF-8",
  • "method": "order.revoker",
  • "format": "JSON",
  • "sign": "W6M/IZTN+tuvvAeIhUDFECeUTRzFszOOxM+ozIqUdWw2CENO9G2z9ehfMdrktNmlP7TjFr6Ind/6DO5ZPhWaVu6Nx7K8UkicNwlu/BK4j8s+K108hzYUNQsVEE3ScvB46vyrxUIXdqG83Zvw3rK+o56tnU7YGodOuqGP20nx/emuLPZj7GBZEGrdgY0mRUmJHw951Hc0BYKLqa9jBuJbQzu4AkymyCX/9/G2KrVsaFWxoc7KR0vA/K84pLSe+JFggS6P9Xq4xjZBWqsWN60a39FtGYS9g5/ETT+vvjmyDBOW2hvRzUiEOvos77L/RteRbVnPxcciC/6IP4YEg0Zq7Q==",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "version": "1.0",
  • "merchant_order_no": "TEST_1654765371046",
  • "timestamp": "1693902797892"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
  • "psn": "08290344008038160280",
  • "data": {
    }
}

Submit Order Refund

If there's a need to issue a refund after a payment has been completed, you can request it through this API. Once the payment gateway confirms the legitimacy of the refund request, the amount will be returned to the payer in accordance with the established refund guidelines.

  1. It's possible to issue multiple partial refunds using the original order number. However, the combined amount of all refunds shouldn't surpass the original payment amount. Typically, you shouldn't have more than 10 partial refunds for a single order.
  2. After issuing a refund, you should utilize the [Query Refund] API to check on its status. Remember, refunds might not be instantaneous and can be influenced by the policies of the specific payment channel.
Request Body schema: application/json
app_id
required
string <= 32 characters

ID assigned by the gateway to the accessing application to identify the developer, see Parameters to get

format
required
string <= 4 characters

Request data format, only supports JSON

Value: "JSON"
charset
required
string <= 8 characters

The encoding format used for the request, only UTF-8 is supported

Value: "UTF-8"
sign_type
required
string <= 8 characters
Enum: "RSA2" "NONE"

Signature algorithm: The API authentication methods support RSA signature authentication and Basic Auth. If you choose to use Basic Auth, please set this value to: NONE.

sign
string <= 128 characters

Interface signature identifier, used to determine the authenticity of a merchant to prevent tampering with messages, see Signature Specification for more details

version
required
string <= 16 characters

Version number, fixed value: 1.0

Value: "1.0"
timestamp
required
integer <long>

Timestamp of when the request was sent, 13 digits in length, can't be more than 15 minutes ago or later

method
required
string <= 32 characters

Interface method, fixed value for this API: order.refund.submit

merchant_no
required
string <= 32 characters

Merchant number, obtained after registering as a merchant, see Parameters to get

orig_merchant_order_no
string <= 32 characters

Original CodePay transaction number orig_ Merchant_ Order_ No and orig_ Trans_ No must choose between two options

orig_trans_no
string <= 32 characters

Original CodePay transaction number orig_ Merchant_ Order_ No and orig_ Trans_ No must choose between two options

merchant_order_no
required
string <= 32 characters

Merchant refund request order number. Multiple refunds must have different serial numbers set and do not duplicate the original merchant order number

price_currency
required
string <= 8 characters

Denominated currencies, conforming to ISO-4217, are described by a code based on three characters, e.g.: USD

order_amount
required
number <float>

The amount of the refunded order, expressed in the currency of the price, e.g. 1 USD means 1 U.S. dollar, not 1 U.S. cent.

description
required
string <= 64 characters

Reason for refund

notify_url
string <= 256 characters

Callback address to receive CodePay refund notifications

Please refer to transaction result notification for the notification message structure.

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302100041048",
  • "charset": "UTF-8",
  • "method": "order.refund.submit",
  • "format": "JSON",
  • "sign": "E2QaYadyJr6mpa8iNhjaSPqvScTJ0cIaEmvhi2oljATNY+w56x6DMFesozLkcM5cKFi7Pb565ODMESr7WY9wDE+6egcy/uKlo7J1912rYvLVajrc1SZOsh6JbQEitClJCUaCIQQOV2enaKYsBfmmi0bM6aFra2G1m2Ik8yLi/k/PsM/BQQTSVc97wRUTHU+IG0GLWI3HkvH9zFA76xA6P+bX/UD6+Khw9C3Cwsaz4uJkGN+28BrUBVUCxiuLyRCOd7DCMTJ04lOU9oBe415wGof5IQku4VHlUaJ8djUOkB4Y0/+Xn7zzIivsUS9ueUbPcyoPor+JXhorK2zavpYXgA==",
  • "description": "test refund",
  • "trans_amount": 100,
  • "version": "1.0",
  • "merchant_order_no": "TEST_16547658746871_2",
  • "orig_merchant_order_no": "TEST_1654765874687",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "timestamp": "1693904002543"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "msg": "success",
  • "psn": "09050853244715542560",
  • "sign": "Z4FU2k2idXNJXriBLQd/Z8OLBeErxJeQvSlUqu1UpjY70C2MetBuxv7esK7M1VY7eepQ7+FVSo0dmx99tWp0lIXmka/gszkriA+RF11dom8vbbmlPNzCo3cVacTRvS8xjwVZDrk2+OhpGo3qRO+5rPRatiw/f04DNQyAC23nX7N5NS/Knq5STJTKHhj8yQUYqUD1TPbdvlCKgx12lP2VZTLEQfYWj+Av15VfCvy9EOwbcHhz6lVi127r6HlFgBxdWfrLPM5qxyK4QoAmUx7qg7XXq59Qo/IIDe6/9j9Wk5xvZ9gR0uoVJVUBc5UXNifXpJf/1PHlcSFMS9P7WwikNA==",
  • "data": {
    }
}