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

store_no
string <= 32 characters

Store number, obtained after registering the store

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

store_no
string <= 32 characters

Store number, obtained after registering the store

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 Transaction List

Retrieves transactions information about the merchant’s currently open batch.

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

store_no
string <= 32 characters

Store number, obtained after registering the store

terminal_sn_list
Array of strings

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

page_num
number

Page number

page_size
number

Page size

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": [
    ],
  • "page_num": 1,
  • "page_size": 10
}

Response samples

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