CodePay Cloud Open Api(ZH) (1.0.0)

POS集成

创建订单

商户后端调用此API，CodePay服务器将向支付终端上的“CodePay Register”应用程序发送消息。这将激活应用程序，显示订单供收银员确认并引导用户完成付款。

注意：此API支持多种交易的下单功能，包括消费/撤销/退款/预授权等，而不仅仅是支付下单，请参阅 transtype

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持JSON Value: "JSON"
charset required	string <= 8 characters 用于请求的编码格式，仅支持UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 发送请求的时间戳，长度为13位，不能超过15分钟之前或之后
method required	string <= 32 characters 接口方法，此API的固定值：wisehub.cloud.pay.order
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
terminal_sn required	string <= 32 characters 智能金融终端SN，需要绑定到商户店铺下
message_receiving_application required	string <= 32 characters 消息接收应用程序，此处固定为“CodePay Register”
pay_scenario	string <= 32 characters Default: "SWIPE_CARD" Enum: "BSCANQR_PAY" "SCANQR_PAY" "SWIPE_CARD" 支付场景，请参阅 payscenario
pay_method_id	string 要指定特定支付方式的使用，请参阅paymethod
card_type	integer 银行卡类型，请参阅cardtype
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 订单金额，以其标价的货币表示，例如，1USD表示1美元，而不是1美分。
tip_amount	number <float> 小费金额。示例：34.50
on_screen_tip	boolean Default: "false" 是否在CodePay Rigister页面上输入小费，默认为false，当“trans_type=1，3，4”时，可以设置此参数示例：true
cashback_amount	number <float> 返现金额，订单金额+返现金额=交易金额当 trans_type = 11 时，可以传递此参数
trans_type required	integer 交易类型，请参阅transtype
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
orig_merchant_order_no	string <= 32 characters 原始交易商户系统订单号，trans_type=2、3、6需要
description required	string <= 128 characters 客户购买的商品或服务的简要说明
attach	string <= 128 characters 允许商家向网关提交额外的数据，这些数据将被原封不动地返回用于支付通知和查询
notify_url	string <= 256 characters 商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。有关通知消息的报文结构，请参阅交易结果通知。
expires required	integer 订单付款超时时期，超过此时间后，订单将无法再付款或取消，订单将被关闭，此时间的单位为：秒请设置合适的订单超时时间
order_queue_mode	string <= 8 characters Deprecated Default: "FIFO" Enum: "FIFO" "FILO" 订单队列模式，用于设置订单的排序规则，当推送多个订单时，优先处理新订单还是旧订单
reject_trade_when_terminal_offline	boolean Default: "false" 终端离线时是否拒绝交易，默认为false。请小心设置此值，由于终端网络的不稳定，设备的联机状态可能会延迟，使用此功能之前请先进行测试，然后再决定是否在您的生产环境中应用
required_terminal_authentication	boolean Default: "false" 当退款或取消交易时，商店经理角色是否需要在终端上授权此操作？默认值：false
on_screen_signature	boolean Default: "true" 此参数控制电子签名的显示逻辑： true：显示电子签名页并打印采购订单上的签名信息 false：不会显示电子签名页，但需要在采购订单上打印签名区域但即使设置了此参数，在以下情况下，CodePay Register仍会根据以下逻辑处理电子签名：信用卡网络，APP不显示签名页，固定在收据上打印签名栏 Pin借记交易不需要签名，APP不显示签名页面，收据也不打印
receipt_print_mode	integer Default: 0 小票打印模式 0: 不打印，默认值 1：打印商户联 2：打印客户联 3：打印商户联+客户联
confirm_on_terminal	boolean Default: "false" 交易前，是否需要CodePay Register展示确认界面，收银员点击确认后才能继续进行交易，默认不需要确认，直接进入读卡界面
api_version required	string 此API的版本，固定值为“2.0”。 Value: "2.0"

Responses

Request samples

Payload

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

Successful Example

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

关闭订单

要关闭订单，商家的后端应调用此API。然后，支付网关将关闭订单，向物联网设备（如智能POS）上的指定应用程序发送消息，以从队列中清除订单。

注意：只有预支付状态订单（trans_status=9）才应使用此API主动关闭订单。已完成订单（trans_status=2）应通过[创建订单API]进行取消。

有关详细信息，请参阅跨终端应用集成-云端模式

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持JSON Value: "JSON"
charset required	string <= 8 characters 用于请求的编码格式，仅支持UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 发送请求的时间戳，长度为13位，不能超过15分钟之前或之后
method required	string <= 32 characters 接口方法，此API的固定值：wisehub.cloud.pay.close
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
terminal_sn required	string <= 32 characters 智能金融终端SN，需要绑定到商户店铺下
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
description	string <= 128 characters 关闭交易记录的原因
message_receiving_application required	string 消息接收应用程序，此处固定为“CodePay Register”

Responses

Request samples

Payload

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

Successful Example

{"code": "0",
"msg": "success",
"sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
"psn": "08290344008038160280",
"data": {"message_id": "M021000010210602000003",
"trans_no": "5021000010210602000003"
}
}

扫码支付

扫码支付(客户呈现)

收银员使用扫码设备读取用户钱包APP中的条形码或二维码以后，付款凭证信息传送至商户收银台，由商户收银台或者商户后台调用此接口发起支付。

交易结果是同步返回的。如果出现 "系统错误"，请等待 5 秒钟，然后调用[查询订单API]，直到支付成功或超时（建议 30 秒，调用间隔为 5 秒）。

如果在调用[查询订单API]时返回不确定的交易状态，请取消订单。取消后，成功的订单将被退回，而失败的订单将关闭。如果对[取消订单API]的调用返回失败，请再次调用。请注意，应在创建订单后至少15秒调用[取消订单API]。

有关详细信息，请参阅扫码支付-客户呈现二维码产品介绍

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持JSON Value: "JSON"
charset required	string <= 8 characters 用于请求的编码格式，仅支持UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 发送请求的时间戳，长度为13位，不能超过15分钟之前或之后
method required	string 接口方法，此API的固定值：bscanc.pay.submit
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
auth_code required	string <= 128 characters 通过扫描二维码/条形码获得的移动钱包支付代码、号码或字符串
pay_method_id required	string 指定特定支付方式的使用，请参阅paymethod
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 订单金额，以其标价的货币表示，例如，1USD表示1美元，而不是1美分。
expires required	integer 订单付款超时时期，超过此时间后，订单将无法再付款或取消，订单将被关闭，此时间的单位为：秒请设置合适的订单超时时间
description required	string <= 128 characters 客户购买的商品或服务的简要说明
attach	string <= 128 characters 允许商家向网关提交额外的数据，这些数据将在付款通知和查询过程中原样返回
terminal_sn	string <= 32 characters 智能金融终端的SN需要绑定到商家的店铺
term_ip required	string <= 32 characters 终端的IP地址。如果没有终端，则可以提交服务器的IP地址
longitude	string <= 16 characters 地理经度
latitude	string <= 16 characters 地理纬度
notify_url	string <= 256 characters 商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。有关通知消息的报文结构，请参阅交易结果通知。

Responses

Request samples

Payload

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

Success Example

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

扫码交易(商户呈现)

商家后台调用此API在 PayCloud 上创建预付款交易。PayCloud 返回二维码图片链接，客户使用手机钱包扫描二维码即可完成支付。

生成二维码并显示给客户扫描后，商家系统需要调用订单查询 API，直到支付成功或超时（建议超时 60 秒，调用频率 5 秒）。

如果超过超时时间后调用 [查询订单] 时交易状态仍然不确定，请取消订单。取消后，成功的订单将被退回，而失败的订单将关闭。如果对 [取消订单] 的调用返回失败，请再次调用。

有关详细信息，请参阅扫码支付-商户呈现二维码产品介绍

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string 接口方法，此 API 的固定值：cscanb.pay.getqrcode
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
pay_method_id required	string 指定使用某种付款方式，请参阅 PayMethod
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 订单金额，以其标价的货币表示，例如，1USD表示1美元，而不是1美分。
expires required	integer 订单付款超时时期，超过此时间后，订单将无法再付款或取消，订单将被关闭，此时间的单位为：秒请设置合适的订单超时时间
description required	string <= 128 characters 客户所购商品或服务的简要说明
attach	string <= 128 characters 允许商家向网关提交附加数据，这些数据将在付款通知和查询时原样返回
terminal_sn	string <= 32 characters 智能金融终端的 SN 需要与商家的店铺绑定
term_ip required	string <= 32 characters 终端的 IP 地址。如果没有终端，可提交服务器的 IP 地址
longitude	string <= 16 characters 地理经度
latitude	string <= 16 characters 地理纬度
notify_url	string <= 256 characters 商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。有关通知消息的报文结构，请参阅交易结果通知。

Responses

Request samples

Payload

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

Success Example

{"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托管收银台支付下单

要使用 CodePay 的托管结账支付，商户需要将用户重定向到 CodePay 的结账页面。为实现这一点，商户可以调用此 API。该 API 会收集用户的订单信息，将订单保存在 CodePay 系统中，并返回结账页面的 URL "pay_url"。然后，商户可以将用户重定向到这个 URL，用户将在该页面输入支付信息以完成交易。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string 接口方法，本 API 的固定值：pay.checkout
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 订单金额，以其标价的货币表示，例如: 15.43
expires required	integer 订单付款有效时长，超过此时长设置后，订单将无法再进行付款，订单将被关闭，时间单位：秒请设置合适的订单超时时间，不能超过7天
description required	string <= 128 characters 顾客所购商品或服务的简要说明
term_ip	string <= 32 characters 终端的 IP 地址
longitude	string 地理经度
latitude	string 地理纬度
return_url	string <= 256 characters 支付成功/失败/取消后，PayCloud重定向用户到商户网站页面地址URL, 商户被重定向此页面后，应该查询后台的订单状态，而不能以此前端页面的状态作为付款结果。
notify_url	string <= 256 characters 商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。有关通知消息的报文结构，请参阅交易结果通知。
attach	string <= 128 characters 允许商家向网关提交附加数据，这些数据将在付款通知和查询时原样返回
	object 订单详细信息，包括商品列表，物流配置，账单地址配置，支付选项设置，界面主题配置等

Responses

Request samples

Payload

Content type

application/json

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

Response samples

Content type

application/json

{"code": "0",
"msg": "success",
"sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
"psn": "08290344008038160280",
"data": {"pay_url": "string"
}
}

商家托管收银台支付下单

商家要使用商家托管的收银台支付，将订单信息和卡信息提交给CodePay，CodePay将立即处理支付，同步返回支付结果。如果还需要进行3DS认证，将返回redirect_url_3dsecure, 请将用户请求重定向到该页面，完成认证后，CodePay将重定向到商户的return_url，请接收异步通知和主动查询订单，获取支付结果。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string 接口方法，本 API 的固定值：pay.merchant.checkout
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
required	object 银行卡付款详情，请使用CodePay的公钥gateway_rsa_public_key，对card进行加密 card需要转成字符串后，对整个字符串进行加密加密方法请参考加密算法
required	object 账单地址
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 订单金额，以其标价的货币表示，例如: 15.43
expires required	integer 订单付款有效时长，超过此时长设置后，订单将无法再进行付款，订单将被关闭，时间单位：秒请设置合适的订单超时时间，不能超过7天
description required	string <= 128 characters 顾客所购商品或服务的简要说明
term_ip	string <= 32 characters 终端的 IP 地址
longitude	string 地理经度
latitude	string 地理纬度
return_url	string <= 256 characters 支付成功/失败/取消后，CodePay重定向用户到商户网站页面地址URL, 商户被重定向此页面后，应该查询后台的订单状态，而不能以此前端页面的状态作为付款结果。
notify_url	string <= 256 characters 商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。有关通知消息的报文结构，请参阅交易结果通知。
attach	string <= 128 characters 允许商家向网关提交附加数据，这些数据将在付款通知和查询时原样返回

Responses

Request samples

Payload

Content type

application/json

{"app_id": "wz3c35784c2cbe6f37",
"format": "JSON",
"charset": "UTF-8",
"sign_type": "RSA2",
"sign": "VD3AnpSR08BALF7U+A22kVCJOisv9WCCZJ1TGZSmM2lwhixKIi/uUPVYcB6gODbIsBmwJ2Cw9TtI/JiXJFPlJALLncrWTtxKeTxYWhkmnteiih6GhFw1hoFJqxJFgWoLXQI/pvZJr8NognBJjHE56uXBjqIyVanPaXvy3Xb47Cnbt29am7DuQJOyrylfGklbmZQW+kkMjrD4vhrPjvIaebSvkumL5CTOv5uXORYVVijd9UqOMZzTQjilpnH0In2+qZBsY/5if4ZCduFFItf31GRiJOh9WkR0nCiVJjt8y6eSs4Ms2FS9ZiISWgMMSwrkgqYAAJm4GpaP9UUAkmuGVg==",
"version": "1.0",
"timestamp": 1693280636972,
"method": "string",
"merchant_no": "string",
"store_no": "4021000008",
"card": {"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",
"notify_url": "http://www.mersite.com/pay/notify",
"attach": "{“key”:”value”, “key2”:”value2”}"
}

Response samples

Content type

application/json

{"code": "0",
"msg": "success",
"sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
"psn": "08290344008038160280",
"data": {"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"
}
}

批结算

批次关闭

关闭当前批次，新的交易将进行新的批次，批次交易后，当前批次的交易只能退款，不能撤销。关闭批次并不意味着会马上会进行结算。

只会对线下银行卡交易进行结算，银行卡线上交易和扫码交易不会进行结算。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string <= 32 characters 接口方法，此API的固定值：batch.close
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
terminal_sn required	string <= 32 characters 设备终端序列号，交易发生的所在设备

Responses

Request samples

Payload

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

Successful Example

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

小费

小费调整

此API使商家能够在交易中添加小费金额或修改小费金额，并标记交易以进行结算。如果交易已经结算或不符合修改条件，会拒绝请求。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string <= 32 characters 接口方法，此API的固定值：tip.adjustment
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
tip_adjustment_amount required	number <double> 小费调整金额

Responses

Request samples

Payload

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

Successful Example

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

公共API

查询订单

该接口提供所有支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。

使用此 API 的情况包括

如果您的后台出现任何问题，可能导致错过付款通知。

如果出现系统故障，或支付后交易状态仍不清晰。

要监控触发 "bscanc.pay.submit "API 后的付款状态。

如果交易状态不明确，例如调用 "cscanb.pay.getQRCode "或 "pay.unifiedorder "API后。

在启动取消订单 API 之前确认付款状态。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string 接口方法，本 API 的固定值：order.query
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
merchant_order_no	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一 merchant_order_no和trans_no，至少需要二选一，如果两者都存在，则trans_no优先。示例值：1217752501201407033233368018
trans_no	string <= 32 characters CodePay 交易编号，唯一标识交易。 merchant_order_no和 trans_no 必须任选其一，当两者都存在时，trans_no 优先

Responses

Request samples

Payload

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

Success Example

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

撤销订单

支付交易返回失败或支付系统超时，调用该接口撤销交易。如果此订单用户支付失败，CodePay系统会将此订单关闭；如果用户支付成功，CodePay系统会将此订单资金退还给用户。

如果您遇到付款状态不清楚的情况，您应该使用此API启动取消。对于已成功完成的交易，如果需要退款，您应调用[提交退款申请API] 。在任何交易后调用[查询订单API]以确认其状态非常重要。如果状态仍然不清楚，请在原始订单创建后等待15秒窗口后再次调用取消订单API。

注意：此API不支持撤销线下银行卡交易，只支持撤销扫码交易和线上E-commerce交易。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string <= 32 characters 接口方法，此API的固定值：order.revoker
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018

Responses

Request samples

Payload

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

Successful Example

{"code": "0",
"msg": "success",
"sign": "ARdktgKALtjqOoE9iPBcIt4n9jCz1VDV5q/qTRkmDMzU85xsf4RE4Mhffo4ccq95WBfu9sWQd2JswQKI9Qhln9qH/FzatuddMdfMCkOCO5i4L67A4RZEmF3+32XX6HzKOSPgzsV6syJ56EUu6ivFNPznJn6bt8buG4hljzoEc5ogEl+kn87EhXA+LpEyzJkgLI8ZhH7j6iMQlOeyYRjJ0pVMe7OZfIYOeULp3GfsUamj3ezWVZS/70d2irtxg4c9wsTcBe3dusmQpFfdzAUNuILINWFRj/LEiYWOIeU4DyAU9wBKLWJpyEtok1EUFpWmJJwhEeNQen5mwsJq4Nwv7Q==",
"psn": "08290344008038160280",
"data": {"message_id": "M021000010210602000003",
"trans_no": "5021000010210602000003"
}
}

提交退款申请

如果付款完成后需要退款，可以通过此 API 申请退款。一旦支付网关确认了退款请求的合法性，就会根据既定的退款准则将金额退还给付款人。

可以使用原始订单号进行多次部分退款。但是，所有退款的总金额不应超过原始付款金额。通常情况下，一个订单的部分退款不应超过50笔。

退款后，您应使用[查询退款]API检查其状态。请记住，退款可能不是即时的，可能会受到特定支付渠道政策的影响。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string <= 32 characters 接口方法，此API的固定值：order.refund.submit
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
orig_merchant_order_no	string <= 32 characters 原商户订单编号，"orig_merchant_order_no"和"orig_trans_no"至少传递一个，同时存在时，"orig_trans_no"优先
orig_trans_no	string <= 32 characters 原交易编号，"orig_merchant_order_no"和"orig_trans_no"至少传递一个，同时存在时，"orig_trans_no"优先
merchant_order_no required	string <= 32 characters 商户系统内部退款订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 退款订单的金额，以标价货币表示，例如 1 USD 表示 1 美元，而不是 1 美分。
description required	string <= 64 characters 退款原因
notify_url	string <= 256 characters 商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。有关通知消息的报文结构，请参阅交易结果通知。

Responses

Request samples

Payload

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

Successful Example

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

查询退款

启动退款后，可使用此 API 检查并确认其当前状态。值得注意的是，退款到账时间可能会有所不同，可能会根据付款渠道的实际退款处理时间而出现延迟。

Authorizations:

basic

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters Default: "RSA2" Enum: "RSA2" "NONE" 签名算法，目前只支持RSA2, API认证方式支持RSA签名认证和Basic Auth,如果你选择使用Basic Auth，请设置此值为：NONE
sign	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string 接口方法，此API的固定值：order.refund.query
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
merchant_order_no	string <= 32 characters merchant_order_no 和 trans_no 不能同时为空，至少二选一，当两者都存在时，trans_no 优先示例值：1217752501201407033233368018
trans_no	string <= 32 characters CodePay 退款交易号， merchant_order_no 和 trans_no 不能同时为空，至少二选一，当两者都存在时，trans_no 优先

Responses

Request samples

Payload

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

Success Example

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

交易结果通知

付款或退款完成后，CodePay 会将交易结果和相关用户详细信息转发给商家。在这种情况下，商家的后台系统必须通过向网关支付系统发送响应来确认这些数据。

如果网关支付系统没有收到商户方面的确认（成功或超时），就会将其理解为错过通知。为确保商户收到这些通知，系统会定期重新发送通知，在 12 小时内共发送 15 次。但请注意，系统不能保证每次通知都能送达。提醒通知的发送间隔为 5s、10s、15s、30s、60s、3m、10m、15m、三个 30m 间隔和三个 3h 间隔。

商家的后台有可能多次收到相同的付款通知。因此，商家需要确保其系统具备处理此类重复通知的能力。

建议的方法是在收到任何通知时检查所附的付款信息。这样做是为了确定这些详细信息之前是否已被处理过。如果数据已被处理，则只需返回先前确定的结果。如果没有，则处理新数据，然后发送响应。为确保数据完整性，尤其是在并发交易的情况下，应在仔细检查付款数据之前使用交易锁。

为提高安全性，商家还应验证通知的签名。这意味着要检查通知中提到的订单总额是否与商家自己系统中记录的订单总额一致。

在未来的迭代中，可能会根据不断变化的业务需求为通知添加其他参数。因此，确保验证系统的适应性至关重要。与硬编码的验证参数列表不同，您的系统应能动态处理每份通知中提供的参数。

最后，可能会出现未收到付款通知或存在签名验证问题的情况。为了应对潜在的交易疏忽，强烈建议实施轮询机制作为保障措施。

确认：如果准确接收并处理了通知，则返回字符串： success

path Parameters

merchant_website

required

string

Request Body schema: application/json

app_id required	string <= 32 characters 由网关分配给访问应用程序以识别开发者的ID，请参阅参数获取
format required	string <= 4 characters 请求数据格式，仅支持 JSON Value: "JSON"
charset required	string <= 8 characters 请求使用的编码格式，仅支持 UTF-8 Value: "UTF-8"
sign_type required	string <= 8 characters 签名算法，目前仅支持 RSA2 Value: "RSA2"
sign required	string <= 128 characters 接口签名标识符，用于确定商家的真实性，以防止篡改消息，有关详细信息，请参阅签名规范
version required	string <= 16 characters 版本号，固定值：1.0 Value: "1.0"
timestamp required	integer <long> 请求发送时间的时间戳，长度为 13 位数字，不能超过 15 分钟或更晚。
method required	string 接口方法，此API的固定值：payment.result.notify
merchant_no required	string <= 32 characters 商户编号，注册成为商户后获得，请参阅参数获取
merchant_order_no required	string <= 32 characters 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*@ ，且在同一个商户下唯一示例值：1217752501201407033233368018
trans_no required	string <= 32 characters 唯一标识交易的 CodePay 交易编号
trans_type required	integer 交易类型，请参阅 TransType .
price_currency required	string <= 8 characters 标价币种，ISO-4217货币编码，由基于三个字符的代码描述，例如：USD
order_amount required	number <float> 订单金额，以其标价的货币表示，例如，1USD表示1美元，而不是1美分。
tip_amount	number <float> 小费金额。示例：34.50
cashback_amount	number <float> 返现金额. 用标价货币表示，例如，1 USD 代表 1 美元，而不是 1 美分例: 10.00
trans_amount required	number <double> 在大多数情况下，订单金额和交易金额相等，当客户需要支付服务费和消费税时，交易金额会大于订单金额
trans_fee_c	number <double> 客户需要支付的服务费
vat_amount	number <double> VAT：Value added Tax（增值税）的缩写，是一种根据当地政府法律法规向商家收取增值税的支付渠道
attach	string <= 128 characters 允许商家向网关提交附加数据，这些数据将在付款通知和查询时原样返回
store_no	string <= 32 characters 门店编号，注册门店后获得，请参阅参数获取
terminal_sn	string <= 32 characters 智能金融终端的 SN 需要与商家的店铺绑定
pay_scenario required	string 交易类型，请参阅 PayScenario 。
trans_status required	integer 交易状态，请参阅 TransStatus
pay_channel_trans_no	string <= 64 characters 支付渠道的交易序列号，如微信、支付宝、Visa、万事达卡和其他支付平台
pay_user_account_id	string <= 64 characters 买家用户 ID
paid_amount	number <double> 客户实际付款金额
discount_bmopc	number <double> 商户通过支付渠道向客户提供优惠金额，这些金额不会结算给商户
discount_bpc	number <double> 将付款渠道的金额折算给客户，这部分资金将存入商家账户
trans_end_time	string <date-time> 交易成功的时间，时区 UTC/GMT 0，格式：YYYY-MM-DD HH:mm:ss 示例：2021-06-03 12:48:51
ref_no	string <= 64 characters 银行卡交易参考编号
pay_method_id	string 付款方式，请参阅 PayMethod
trans_error_code	string 交易错误码
trans_error_msg	string 交易错误信息
	object 账单地址，当使用卡付或者Apple Pay，Google Pay时，CodePay Checkout会将收集到的账单地址返回给商家，商家可用于给持卡人发送账单，联系持卡人或处理争议。
	object 送货地址，当collect_shipping=true时，商家将使用CodePay Checkout收集的送件地址，给消费者发货、计算物流费用等

Responses

Request samples

Payload

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

application/json

Example

Success Example

"success"