CodePay Cloud Open Api (1.0.0)
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. |
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 |
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 |
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:
But even if this parameter is set, CodePay Register still processes electronic signatures according to the following logic in the following situations:
|
receipt_print_mode | integer Default: 0 Receeipt printing mode |
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
- Payload
{- "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",
- "version": "1.0",
- "confirm_on_terminal": false,
- "message_receiving_application": "CodePay Register",
- "tip_amount": 30
}
Response samples
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": {
- "message_id": "M021000010210602000003",
- "trans_no": "5021000010210602000003",
- "terminal_online_status": "online"
}
}
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 |
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
- Payload
{- "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
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": {
- "message_id": "M021000010210602000003",
- "trans_no": "5021000010210602000003"
}
}
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.
- 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).
- 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 |
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
- Payload
{- "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+",
- "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
- 200
{- "code": "0",
- "data": {
- "trans_no": "50210004102309050000002",
- "trans_end_time": "2023-09-05 02:57:30",
- "pay_user_account_id": "2102209000001474545H6",
- "trans_fee_c": "0",
- "trans_amount": "200",
- "pay_channel_trans_no": "20230905190741010000G0004578720",
- "discount_bpc": "0",
- "vat_amount": "0",
- "pay_platform_trans_no": "20230905198881010004H0000505133",
- "paid_amount": "200",
- "trans_amount_cny": "9.95",
- "trans_status": 2,
- "discount_bmopc": "0"
}, - "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.
- 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).
- 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 |
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
- Payload
{- "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
- 200
{- "code": "0",
- "data": {
- "trans_no": "50210004102309050000002",
- "trans_end_time": "2023-09-05 02:57:30",
- "pay_user_account_id": "2102209000001474545H6",
- "trans_fee_c": "0",
- "trans_amount": "200",
- "pay_channel_trans_no": "20230905190741010000G0004578720",
- "discount_bpc": "0",
- "vat_amount": "0",
- "pay_platform_trans_no": "20230905198881010004H0000505133",
- "paid_amount": "200",
- "trans_amount_cny": "9.95",
- "trans_status": 2,
- "discount_bmopc": "0"
}, - "msg": "success",
- "psn": "09050257284550801420",
- "sign": "OpmXLxxMjZYjNo+Vk7cd8EpGzZsl6qQLHBq4wdvZt2MQ6QPzUc5sZ8xfOn2y+BC1mNnEQ473gKrbubVxSheeMy+KjVECM8KVdVRrmALuIdbCyY98aBHQOQidgwY2cER15JbAl/Ts7jHV1sJXbXyrrY/Puksmr82LB+e7srbtHvkDrUpvh4kp/72V5Tqxbsvi/VKiX5QWuZgXTSV4dWGg+hsbLPsi7zWb3vQUO7PnNaASnt+N+RLnkuVnAe8qlt4Wj181Y/a9Eu2DgZUY+qgdcl8AglaLRD7J2Q65bkVcdDueT9En6oIx09jLzbp6swihmdM/lmUwOgrxh3xcbC6uRQ=="
}
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 Signature algorithm: currently, only RSA2 is supported. Value: "RSA2" |
sign required | 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 |
pay_options | string To specify certain payment options, the CodePay checkout will only display the corresponding payment methods to the user. If this parameter is not set, all payment options already enabled by the merchant will be displayed. Please refer to the PayOption for the enumeration values of payment options. Multiple values should be separated by commas. Example: Card,WeChatPay,Alipay |
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. |
collect_shipping | boolean Default: "false" Specify whether to collect the shipping address on the checkout page:
|
billing_regions | Array of strings The billing address for the specified bank card is limited to supported countries and regions, such as restricting the use of foreign cards. |
shipping_regions | Array of strings The shipping address is restricted to supported countries and regions, such as allowing only addresses within the United States. |
Array of objects Submit the product list in JSON array format. Example values: [ { "goods_id": "12345", "goods_name": "Product 1", "quantity": 2, "price": 10.99, "total_price": 21.98, "goods_image": "http://example.com/images/product1.jpg" }, { "goods_id": "67890", "goods_name": "Product 2", "quantity": 1, "price": 15.49, "total_price": 15.49, "goods_image": "http://example.com/images/product2.jpg" } ] |
Responses
Request samples
- Payload
{- "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",
- "pay_options": "Visa",
- "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",
- "attach": "{“key”:”value”, “key2”:”value2”}",
- "collect_shipping": "false",
- "billing_regions": [
- "string"
], - "shipping_regions": [
- "string"
], - "goods_detail": [
- {
- "goods_id": "string",
- "goods_name": "string",
- "quantity": "string",
- "price": 0.1,
- "total_price": 0.1,
}
]
}
Response samples
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": {
- "pay_url": "string"
}
}
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 Signature algorithm: currently, only RSA2 is supported. Value: "RSA2" |
sign required | 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
- Payload
{- "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": {
- "pan": "string",
- "holder": "string",
- "cvv": "stri",
- "expiry": "stri"
}, - "billing_address": {
- "name": "string",
- "country": "string",
- "province": "string",
- "city": "string",
- "address1": "string",
- "address2": "string",
- "zip": "string",
- "phone": "string"
}, - "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",
- "attach": "{“key”:”value”, “key2”:”value2”}"
}
Response samples
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": {
- "trans_no": "5021000010210602000003",
- "trans_status": 0,
- "pay_channel_trans_no": "string",
- "pay_user_account_id": "string",
- "trans_end_time": "2019-08-24T14:15:22Z",
- "ref_no": "string",
- "pay_method_id": "Visa",
- "redirect_url_3dsecure": "string"
}
}
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
- Payload
{- "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
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": { }
}
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 |
tip_adjustment_amount required | number <double> Tip adjustment amount |
Responses
Request samples
- Payload
{- "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
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": { }
}
Query Order
This interface provides query for all payment orders. Merchants can actively query the order status through this interface to complete the next step of business logic.
The scenarios for using this API include
- If there is any problem with your backend, it may lead to missed payment notification.
- If there is a system failure, or the transaction status remains unclear after payment.
- To monitor the payment status after triggering the "bscanc.pay.submit" API.
- if the transaction status is unclear, for example after calling the "cscanb.pay.getQRCode" or "pay.unifiedorder" APIs.
- 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
- Payload
{- "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
- 200
{- "code": "0",
- "data": {
- "trans_no": "50210004102306140000003",
- "trans_end_time": "2023-06-14 08:51:51",
- "pay_user_account_id": "2102209000000858994F9",
- "store_no": "4021000201",
- "pay_scenario": "BSCANQR_PAY",
- "pay_method_id": "Alipay+",
- "trans_fee_c": "0",
- "trans_amount": "200",
- "merchant_order_no": "TEST_1686732708342",
- "pay_channel_trans_no": "20230614190741010007G0004187182",
- "discount_bpc": "0",
- "vat_amount": "0",
- "pay_platform_trans_no": "20230614198881010003B0000463071",
- "order_amount": "200",
- "paid_amount": "200",
- "trans_status": 2,
- "price_currency": "JPY",
- "trans_type": 1,
- "discount_bmopc": "0"
}, - "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 |
Responses
Request samples
- Payload
{- "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
- 200
{- "code": "0",
- "msg": "success",
- "sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
- "psn": "08290344008038160280",
- "data": {
- "message_id": "M021000010210602000003",
- "trans_no": "5021000010210602000003"
}
}
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.
- 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.
- 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
- Payload
{- "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
- 200
{- "code": "0",
- "msg": "success",
- "psn": "09050853244715542560",
- "sign": "Z4FU2k2idXNJXriBLQd/Z8OLBeErxJeQvSlUqu1UpjY70C2MetBuxv7esK7M1VY7eepQ7+FVSo0dmx99tWp0lIXmka/gszkriA+RF11dom8vbbmlPNzCo3cVacTRvS8xjwVZDrk2+OhpGo3qRO+5rPRatiw/f04DNQyAC23nX7N5NS/Knq5STJTKHhj8yQUYqUD1TPbdvlCKgx12lP2VZTLEQfYWj+Av15VfCvy9EOwbcHhz6lVi127r6HlFgBxdWfrLPM5qxyK4QoAmUx7qg7XXq59Qo/IIDe6/9j9Wk5xvZ9gR0uoVJVUBc5UXNifXpJf/1PHlcSFMS9P7WwikNA==",
- "data": {
- "trans_no": "519018719199919",
- "trans_amount": "100.00",
- "trans_fee_c": "0",
- "vat_amount": "0"
}
}
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.
- 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.
- 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
- Payload
{- "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
- 200
{- "code": "0",
- "data": {
- "trans_no": "50210004102306140000003",
- "trans_end_time": "2023-06-14 08:51:51",
- "trans_fee_c": "0",
- "trans_amount": "200",
- "merchant_order_no": "TEST_1686732708342",
- "pay_channel_trans_no": "20230614190741010007G0004187182",
- "vat_amount": "0",
- "order_amount": "200",
- "trans_status": 2,
- "price_currency": "JPY",
- "trans_type": 3
}, - "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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 |
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 |
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 |
object The billing address, when using card payments or Apple Pay/Google Pay, will be returned to the merchant by CodePay Checkout. The merchant can use it to send bills to the cardholder, contact the cardholder, or handle disputes. | |
object Shipping address: When collect_shipping=true, the merchant will use the shipping address collected via CodePay Checkout to ship products to customers, calculate shipping fees, and other related purposes. |
Responses
Request samples
- Payload
{- "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
- 200
success