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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

QR Code Payment

QR Pay(Customer-presented)

After the cashier reads the barcode or QR code in the user's wallet APP with the code scanning device, the payment voucher information is transmitted to the merchant's cashier, and the merchant's cashier or merchant's back office calls this interface to initiate payment.

  1. The transaction result is returned synchronously. If a "system error" occurs, please wait for 5 seconds, and then call [Query Order API] until payment is successful or timeout occurs (30 seconds is recommended, and the call interval is 5 seconds).
  2. If an uncertain transaction status is returned when calling [Query Order API] , please cancel the order. After cancellation, successful orders will be returned, while failed orders will be closed. If the call to [Cancel Order API] returns a failure, please call again. Please note that at least 15 seconds after creating the order, the [Cancel Order API] should be called.

For detailed information, please refer to the QR Code Payment - Customer Presentation QR Code Product Introduction

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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: bscanc.pay.submit

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

auth_code
required
string <= 128 characters

Mobile wallet payment code, number or string obtained by scanning QR code/barcode

pay_method_id
required
string

Specify the use of a certain payment method, refer to PayMethod

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

price_currency
required
string <= 8 characters

List currency, in accordance with ISO-4217 standard, described using a three character code, such as USD

order_amount
required
number <float>

The order amount is expressed in the listed currency, for example, 1 USD represents 1 USD instead of 1 cent

expires
required
integer

Order payment timeout. If the validity period is exceeded, the order cannot be paid again and will be closed. The unit of this time value is seconds

description
required
string <= 128 characters

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

attach
string <= 128 characters

Allow merchants to submit an additional data to the gateway, which will be returned as is during payment notifications and queries

terminal_sn
string <= 32 characters

The SN of an intelligent financial terminal needs to be bound to the merchant's store

term_ip
required
string <= 32 characters

The IP address of the terminal. If there is no terminal, the IP address of the server can be submitted

longitude
string <= 16 characters

Geographical longitude of the terminal

latitude
string <= 16 characters

Geographical latitude of the terminal

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications. For details, please refer to theCallback Notification Precautions

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

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "302110041048",
  • "charset": "UTF-8",
  • "expires": 300,
  • "method": "bscanc.pay.submit",
  • "store_no": "4021000201",
  • "format": "JSON",
  • "sign": "Q3v4mjwRmZfuNeRi6uoFH8GKmPzUqpy5htuhVoZ5FlKXS4dhNIZ3SgD7CPRfy5L5FQ4djmnmy0zKTFM7KwU+QqfJ2znsvj4KlWqxWNnMBxMy2TyQfwBAyydffTVMi9OZBqEqCns69y5PLlEzi8poBHZhVYY8kPgCXQGe8GLXMg7x3AHWsOqgnzFhFj5B/Z8zUMaz6sKHEW+VV+7QmazrbhIulXVmCnpdHdNo1QAW19ZerJ+gallyOjFx2xvXiAfnx9EUcSDU0pzBF2kzdb8LuCloGo7jYfKewEwLyDV3UQbZ/i3UgP1rQxIg0bFVTMRfoeeA2/FuOw3rAoH3OH841g==",
  • "description": "IPhone 12 5G White",
  • "pay_method_id": "Alipay+",
  • "notify_url": "https://www.baidu.com",
  • "trans_amount": 200,
  • "version": "1.0",
  • "merchant_order_no": "TEST_1693882417637",
  • "auth_code": "281666029913682898991367",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "price_currency": "JPY",
  • "timestamp": "1693882417747"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "data": {
    },
  • "msg": "success",
  • "psn": "09050257284550801420",
  • "sign": "OpmXLxxMjZYjNo+Vk7cd8EpGzZsl6qQLHBq4wdvZt2MQ6QPzUc5sZ8xfOn2y+BC1mNnEQ473gKrbubVxSheeMy+KjVECM8KVdVRrmALuIdbCyY98aBHQOQidgwY2cER15JbAl/Ts7jHV1sJXbXyrrY/Puksmr82LB+e7srbtHvkDrUpvh4kp/72V5Tqxbsvi/VKiX5QWuZgXTSV4dWGg+hsbLPsi7zWb3vQUO7PnNaASnt+N+RLnkuVnAe8qlt4Wj181Y/a9Eu2DgZUY+qgdcl8AglaLRD7J2Q65bkVcdDueT9En6oIx09jLzbp6swihmdM/lmUwOgrxh3xcbC6uRQ=="
}

QR Pay(Merchant-presented)

The merchant backend calls this API to create a prepayment transaction on CodePay. CodePay returns the QR code image link, and customers can complete the payment by scanning the QR code using their mobile wallet.

  1. After generating a QR code and displaying it to the customer for scanning, the merchant system needs to call the order query API until the payment is successful or times out (it is recommended to timeout for 60 seconds, with a call frequency of 5 seconds).
  2. If the transaction status is still uncertain when calling [Query Order] after the timeout period expires, please cancel the order. After cancellation, successful orders will be returned, while failed orders will be closed. If the call to [Cancel Order] returns a failure, please call again.

For detailed information, please refer to QR Code Payment - Merchant Present QR Code Product Introduction

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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: cscanb.pay.getqrcode

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

pay_method_id
required
string

Specify the use of a certain payment method, refer to PayMethod

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

price_currency
required
string <= 8 characters

List currency, in accordance with ISO-4217 standard, described using a three character code, such as USD

order_amount
required
number <float>

The order amount is expressed in the listed currency, for example, 1 USD represents 1 USD instead of 1 cent

expires
required
integer

Order payment timeout. If the validity period is exceeded, the order cannot be paid again and will be closed. The unit of this time value is seconds

description
required
string <= 128 characters

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

attach
string <= 128 characters

Allow merchants to submit an additional data to the gateway, which will be returned as is during payment notifications and queries

terminal_sn
string <= 32 characters

The SN of an intelligent financial terminal needs to be bound to the merchant's store

term_ip
required
string <= 32 characters

The IP address of the terminal. If there is no terminal, the IP address of the server can be submitted

longitude
string <= 16 characters

Geographical longitude of the terminal

latitude
string <= 16 characters

Geographical latitude of the terminal

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications. For details, please refer to theCallback Notification Precautions

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

Responses

Request samples

Content type
application/json
{
  • "merchant_no": "312100041048",
  • "charset": "UTF-8",
  • "method": "cscanb.pay.getqrcode",
  • "store_no": "4021000201",
  • "format": "JSON",
  • "sign": "EJML4t1EbY8BvUwruveoLTqwgXfgB/52nuH1x20FV9eEOBftqvZ5vmtmjhxT9HcrhKKoT10FVZHMyFSzYhL2rIMm+8Pn9ItCalKcca/0HuH8vJ4BHKAiIsgkbruE8HhG4cnQ4Tfd7h+wqT/d4cZH7f7oDMNbgy1DsbuebBAhygIbPGxF3PQNQD9zDM95jYmYLBc5EcUulHXAeZ/hU9/4QpVcKzJ9nzFpwvCeii6vGVVS8gxJmUL9lwiIXW6V5Gshvp/cmDT9jTswhd/a11l2wtbtHscrdZi63E3Tt5lAtz+yr+DV8pp0TJMG5CLMqaznsXNcI5r4tnxuMuK8ff2AXw==",
  • "description": "test",
  • "pay_method_id": "Alipay+",
  • "trans_amount": 1,
  • "version": "1.0",
  • "merchant_order_no": "TEST_1693895595408",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "price_currency": "JPY",
  • "timestamp": "1693895595505"
}

Response samples

Content type
application/json
Example
{
  • "code": "0",
  • "data": {
    },
  • "msg": "success",
  • "psn": "09050257284550801420",
  • "sign": "OpmXLxxMjZYjNo+Vk7cd8EpGzZsl6qQLHBq4wdvZt2MQ6QPzUc5sZ8xfOn2y+BC1mNnEQ473gKrbubVxSheeMy+KjVECM8KVdVRrmALuIdbCyY98aBHQOQidgwY2cER15JbAl/Ts7jHV1sJXbXyrrY/Puksmr82LB+e7srbtHvkDrUpvh4kp/72V5Tqxbsvi/VKiX5QWuZgXTSV4dWGg+hsbLPsi7zWb3vQUO7PnNaASnt+N+RLnkuVnAe8qlt4Wj181Y/a9Eu2DgZUY+qgdcl8AglaLRD7J2Q65bkVcdDueT9En6oIx09jLzbp6swihmdM/lmUwOgrxh3xcbC6uRQ=="
}

Mobile Payment

Wap Payment

The merchant displays goods or services on the mobile website, and then calls this interface to get the page address of the CodePay payment cashier. The user enters the CodePay mobile checkout, confirms the order, and completes the payment. The CodePay mobile checkout platform aggregates web payment functions provided by multiple payment channels, allowing for the collection of various payment methods.

For detailed information, please refer to the Mobile Web Payment Product Introduction

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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: pay.unifiedorder

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

pay_method_id
string

Specify the use of a certain payment method, refer to PayMethod

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

price_currency
required
string <= 8 characters

List currency, in accordance with ISO-4217 standard, described using a three character code, such as USD

order_amount
required
number <float>

The order amount is expressed in the listed currency, for example, 1 USD represents 1 USD instead of 1 cent

expires
required
integer

Order payment timeout. If the validity period is exceeded, the order cannot be paid again and will be closed. The unit of this time value is seconds

description
required
string <= 128 characters

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

attach
string <= 128 characters

Allow merchants to submit an additional data to the gateway, which will be returned as is during payment notifications and queries

terminal_sn
string <= 32 characters

The SN of an intelligent financial terminal needs to be bound to the merchant's store

term_ip
required
string <= 32 characters

The IP address of the terminal. If there is no terminal, the IP address of the server can be submitted

longitude
string <= 16 characters

Geographical longitude of the terminal

latitude
string <= 16 characters

Geographical latitude of the terminal

return_url
required
string <= 256 characters

URL of front-end redirect user page

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications. For details, please refer to theCallback Notification Precautions

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

terminal_type
required
string

Terminal type, fixed value: WAP

Value: "WAP"
language
string

The language displayed on the cashier interface is referenced in Language.

Responses

Request samples

Content type
application/json
{
  • "terminal_type": "WAP",
  • "merchant_no": "302100041048",
  • "charset": "UTF-8",
  • "expires": 300,
  • "method": "pay.unifiedorder",
  • "store_no": "4022000019",
  • "format": "JSON",
  • "sign": "Gfv1kSMeNHFISPhOEU3dTJlBnqBlCJ6c1f5jU2e7Foco5gFNvBJn9iocLq2tGf3hNWYbgqpk35Jl0dDYKPTgDtmoTxW2M//aPGWsDxfdLaOz5NUgwx2G9uMWydfGxQA3QYzC6FLq58YLF4SzDCXASvT2Zlvy2KcAR/loFCITOpjtP5O1W50nWZepTprhIZAqpBC5Tvq9TKcj+Lb2IJAqrJkKliFzYxR2nu+tsfXoyME37VtNaj1WFY8sGbrzU9PNdL2lm/H94IUFM2mSRu1lc77lDOysxZwLEiyN8mQq2LgRrPlTyMQ3SHRvrB9joIA1kx91FFPsU6PqgTD8augO9g==",
  • "description": "IPhone 12 5G White",
  • "pay_method_id": "Alipay+",
  • "trans_amount": 1,
  • "version": "1.0",
  • "merchant_order_no": "TEST_1693979057469",
  • "return_url": "https://www.baidu.com",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "price_currency": "JPY",
  • "timestamp": "1693979057656"
}

Response samples

Content type
application/json
Example
{}

Online Payment

Web Payment

When implementing online payment, your backend system should initiate a call to the API to establish preliminary payment transactions. This will create a payment link through which users can complete their payments.

Through this process, our online cashier interface simplifies various steps for handling different payment methods. In this way, you can focus on your main business functions rather than complex payment processing.

For detailed information, please refer to the WEB webpage payment product introduction

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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: pay.unifiedorder

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

pay_method_id
string

Specify the use of a certain payment method, refer to PayMethod

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

price_currency
required
string <= 8 characters

List currency, in accordance with ISO-4217 standard, described using a three character code, such as USD

order_amount
required
number <float>

The order amount is expressed in the listed currency, for example, 1 USD represents 1 USD instead of 1 cent

expires
required
integer

Order payment timeout. If the validity period is exceeded, the order cannot be paid again and will be closed. The unit of this time value is seconds

description
required
string <= 128 characters

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

attach
string <= 128 characters

Allow merchants to submit an additional data to the gateway, which will be returned as is during payment notifications and queries

terminal_sn
string <= 32 characters

The SN of an intelligent financial terminal needs to be bound to the merchant's store

term_ip
required
string <= 32 characters

The IP address of the terminal. If there is no terminal, the IP address of the server can be submitted

longitude
string <= 16 characters

Geographical longitude of the terminal

latitude
string <= 16 characters

Geographical latitude of the terminal

return_url
required
string <= 256 characters

URL of front-end redirect user page

notify_url
string <= 256 characters

The callback address for the merchant system to receive CodePay payment notifications. For details, please refer to theCallback Notification Precautions

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

terminal_type
required
string

Terminal type, fixed value: WEB

Value: "WEB"
language
string

The language displayed on the cashier interface is referenced in Language.

Responses

Request samples

Content type
application/json
{
  • "terminal_type": "WEB",
  • "merchant_no": "302100041048",
  • "charset": "UTF-8",
  • "expires": 300,
  • "method": "pay.unifiedorder",
  • "store_no": "4022000019",
  • "format": "JSON",
  • "sign": "Gfv1kSMeNHFISPhOEU3dTJlBnqBlCJ6c1f5jU2e7Foco5gFNvBJn9iocLq2tGf3hNWYbgqpk35Jl0dDYKPTgDtmoTxW2M//aPGWsDxfdLaOz5NUgwx2G9uMWydfGxQA3QYzC6FLq58YLF4SzDCXASvT2Zlvy2KcAR/loFCITOpjtP5O1W50nWZepTprhIZAqpBC5Tvq9TKcj+Lb2IJAqrJkKliFzYxR2nu+tsfXoyME37VtNaj1WFY8sGbrzU9PNdL2lm/H94IUFM2mSRu1lc77lDOysxZwLEiyN8mQq2LgRrPlTyMQ3SHRvrB9joIA1kx91FFPsU6PqgTD8augO9g==",
  • "description": "IPhone 12 5G White",
  • "pay_method_id": "Alipay+",
  • "trans_amount": 1,
  • "version": "1.0",
  • "merchant_order_no": "TEST_1693979057469",
  • "return_url": "https://www.baidu.com",
  • "app_id": "wz9f2a175d0e0ef632",
  • "sign_type": "RSA2",
  • "price_currency": "JPY",
  • "timestamp": "1693979057656"
}

Response samples

Content type
application/json
Example
{}

Batch Settlement

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

Tip

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

Public API

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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

Transaction Result Notification

Upon the completion of a payment or refund, CodePay will forward the transaction results and associated user details to the merchant. In such cases, it's imperative for the merchant's backend system to acknowledge this data by sending a response to the gateway payment system.

  1. If the gateway payment system doesn't receive a confirmation (either a success or a timeout) from the merchant's side, it will interpret this as a missed notification. To ensure the merchant receives these notifications, the system will resend the notice periodically, with a total of 15 attempts over a 12-hour span. However, do note that the system cannot guarantee the delivery of every notification. The reminders will be sent at intervals of: 5s, 10s, 15s, 30s, 60s, 3m, 10m, 15m, three 30m intervals, and three 3h intervals.
  2. Given the system's approach, there's a possibility that the merchant's backend will receive the same payment notification multiple times. As such, merchants need to ensure their systems are equipped to handle such duplicate notices.
  3. The recommended way to manage this is to examine the attached payment information upon receipt of any notification. This is to determine if these details have been processed previously. If the data was already processed, simply return the previously established result. If not, process the new data and then send the response. To ensure data integrity, especially in the face of concurrent transactions, employ a transaction lock before scrutinizing the payment data.
  4. For added security, merchants should also validate the notification's signature. This means checking if the order total mentioned in the notification matches the one recorded in the merchant's own system.
  5. In future iterations, additional parameters may be added to notifications based on evolving business requirements. Hence, it's crucial to ensure your validation system is adaptable. Instead of having a hardcoded list of parameters for verification, your system should be able to dynamically handle parameters as provided in each notification.
  6. Lastly, there might be instances where payment notifications are either not received or where there are signature verification issues. To counteract potential transaction oversights, it's strongly advised to implement a polling mechanism as a safeguard

Acknowledgment: If notifications are received and processed accurately, return the string: success

path Parameters
merchant_website
required
string
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

Signature algorithm, currently only RSA2 is supported

Value: "RSA2"
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

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: payment.result.notify

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

trans_no
required
string <= 32 characters

CodePay transaction number that uniquely identifies a transaction

trans_type
required
integer

Transaction type, refer to TransType .

price_currency
required
string <= 8 characters

List currency, in accordance with ISO-4217 standard, described using a three character code, such as USD

order_amount
required
number <float>

The order amount is expressed in the listed currency, for example, 1 USD represents 1 USD instead of 1 cent

tip_amount
number <float>

Tip amount, expressed in the currency of the bid, for example, 1 USD represents 1 USD instead of 1 cent

cashback_amount
number <float>

Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent

Example: 10.00

trans_amount
required
number <double>

In most cases, the order amount and transaction amount are equal. When customers are required to pay service fees and consumption taxes, the transaction amount is greater than the order amount

trans_fee_c
number <double>

Service fees that customers need to pay

vat_amount
number <double>

VAT: Abbreviation for Value added Tax, which is a payment channel that collects value-added tax from merchants in accordance with local government laws and regulations

attach
string <= 128 characters

Allow merchants to submit an additional data to the gateway, which will be returned as is during payment notifications and queries

store_no
string <= 32 characters

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

terminal_sn
string <= 32 characters

The SN of an intelligent financial terminal needs to be bound to the merchant's store

pay_scenario
required
string

Transaction type, refer to PayScenario .

trans_status
required
integer

Transaction status, please refer to TransStatus

pay_channel_trans_no
string <= 64 characters

Transaction serial number of payment channel, such as WeChat, Alipay, Visa, MasterCard and other payment platforms

pay_user_account_id
string <= 64 characters

Buyer User ID

paid_amount
number <double>

Customer's actual payment amount

discount_bmopc
number <double>

Merchants provide customers with preferential amounts through payment channels, which will not be settled to merchants

discount_bpc
number <double>

Discount the payment channel amount to the customer, and this portion of the funds will be settled into the merchant account

trans_end_time
string <date-time>

Time of successful transaction, time zone: UTC/GMT 0, format: YYYY-MM-DD HH: mm: ss Example: 2021-06-03 12:48:51

ref_no
string <= 64 characters

Reference number for bank card transactions

pay_method_id
string

Payment method, refer to PayMethod

trans_error_code
string

Transaction error code

trans_error_msg
string

Short explanation of transaction errors

electron_sign_url
string

Cardholder Electronic Signature Image URL

Responses

Request samples

Content type
application/json
{
  • "trans_end_time": "2023-03-28 10:54:48",
  • "charset": "UTF-8",
  • "store_no": "4100006443",
  • "pay_scenario": "SWIPE_CARD",
  • "sign": "xwJo6NU00GeoQMe0630kaXO7kYVM55/5DRSxXnPWTTXOgxeTTsXol39WhAyWiiJchKyT3fw3LSiLXBW+AP3YH/Oj7920JnVc7WHTMEhfGhuRHUbcoHyE0VpMTgFpltCFA6lECt2TWDD3JHt72rbYvsmDrOEH4Fd8aV0ZceJSqwr2qJBoYtxhlxuFoLgC8k5RIsPrbkT1ypCaSyL0+zynhLo6IkmtKV7U22Mb+fMcIjK9wMZbWiUGJQq4dMyUX90m2oLD5EWgCdcitwxzScJlkpEwJOE4ZnDpFwV2lwQJacqIBtHYTvpq4b21e62pwausxu7S4SUxrhU+BH1z8vJxkQ==",
  • "trans_fee_c": "0",
  • "discount_bpc": "0",
  • "vat_amount": "0",
  • "order_amount": "10",
  • "app_id": "wza61f2e0da88ff7f8",
  • "sign_type": "RSA2",
  • "trans_status": 2,
  • "price_currency": "ZAR",
  • "terminal_sn": "PP30002209005865",
  • "trans_type": 1,
  • "timestamp": "1680001064206",
  • "trans_no": "51220064312303280787009",
  • "merchant_no": "317700643123",
  • "method": "payment.result.notify",
  • "pay_user_account_id": "430011******6161",
  • "format": "JSON",
  • "pay_method_id": "Visa",
  • "trans_amount": "10",
  • "http_request_id": "03281057441217642320",
  • "version": "1.0",
  • "pay_channel_trans_no": "00777000284306837100005105865001097",
  • "paid_amount": "10",
  • "discount_bmopc": "0"
}

Response samples

Content type
*/*
Example
success