跳到主要内容
API docs by Redocly

CodePay Cloud Open Api(ZH) (1.0.0)

POS集成

创建订单

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

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

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

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

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

Response samples

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

关闭订单

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

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

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

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

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

Response samples

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

扫码支付

扫码支付(客户呈现)

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

  1. 交易结果是同步返回的。如果出现 "系统错误"，请等待 5 秒钟，然后调用[查询订单API]，直到支付成功或超时（建议 30 秒，调用间隔为 5 秒）。
  2. 如果在调用[查询订单API]时返回不确定的交易状态，请取消订单。取消后，成功的订单将被退回，而失败的订单将关闭。如果对[取消订单API]的调用返回失败，请再次调用。请注意，应在创建订单后至少15秒调用[取消订单API]。

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

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的固定值：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

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

Response samples

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

扫码交易(商户呈现)

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

  1. 生成二维码并显示给客户扫描后，商家系统需要调用订单查询 API，直到支付成功或超时（建议超时 60 秒，调用频率 5 秒）。
  2. 如果超过超时时间后调用 [查询订单] 时交易状态仍然不确定，请取消订单。取消后，成功的订单将被退回，而失败的订单将关闭。 如果对 [取消订单] 的调用返回失败，请再次调用。

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

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 的固定值：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

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

Response samples

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

移动支付

手机网页支付

商户在移动端网页展示商品或服务，然后调用此接口，拿到CodePay支付收银台页面地址。用户进入CodePay移动收银台，确认订单，完成付款。CodePay移动收银台聚合了多个支付渠道提供的网页支付功能，可以完成各种支付方式的收款。

有关详细信息，请参阅手机网页支付产品介绍

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 的固定值：pay.unifiedorder

merchant_no
required
string <= 32 characters

商户编号，注册成为商户后获得，请参阅参数获取

store_no
string <= 32 characters

门店编号，注册门店后获得，请参阅参数获取

pay_method_id
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

地理维度

return_url
required
string <= 256 characters

前端重定向用户页面的 URL

notify_url
string <= 256 characters

商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。
有关通知消息的报文结构，请参阅交易结果通知。

terminal_type
required
string

终端类型，固定值： WAP

Value: "WAP"
language
string

收银界面上显示的语言 Language.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{}

在线支付

WEB网页支付

在实施在线支付时，您的后台系统应启动对该 API 的调用，以建立初步的支付交易。这将创建一个支付链接，用户可通过该链接完成支付。

通过这一过程，我们的网络收银界面简化了处理不同支付方式的各种步骤。这样，您就可以专注于您的主要业务功能，而不是错综复杂的支付处理。

有关详细信息，请参阅WEB网页支付产品介绍

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 的固定值：pay.unifiedorder

merchant_no
required
string <= 32 characters

商户编号，注册成为商户后获得，请参阅参数获取

store_no
string <= 32 characters

门店编号，注册门店后获得，请参阅参数获取

pay_method_id
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

地理维度

return_url
required
string <= 256 characters

前端重定向用户页面的 URL

notify_url
string <= 256 characters

商户系统接收CodePay支付通知的回调地址，请参阅回调通知说明了解详细信息。
有关通知消息的报文结构，请参阅交易结果通知。

terminal_type
required
string

终端类型，固定值： WEB

Value: "WEB"
language
string

收银界面上显示的语言 Language.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{}

批结算

批次关闭

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

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

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 <= 32 characters

接口方法，此API的固定值：batch.close

merchant_no
required
string <= 32 characters

商户编号，注册成为商户后获得，请参阅参数获取

terminal_sn
required
string <= 32 characters

设备终端序列号，交易发生的所在设备

Responses

Request samples

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

Response samples

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

小费

小费调整

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

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

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

Response samples

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

公共API

查询订单

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

使用此 API 的情况包括

  1. 如果您的后台出现任何问题，可能导致错过付款通知。
  2. 如果出现系统故障，或支付后交易状态仍不清晰。
  3. 要监控触发 "bscanc.pay.submit "API 后的付款状态。
  4. 如果交易状态不明确，例如调用 "cscanb.pay.getQRCode "或 "pay.unifiedorder "API后。
  5. 在启动取消订单 API 之前确认付款状态。
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 的固定值：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

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

Response samples

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

取消订单

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

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

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

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 <= 32 characters

接口方法，此API的固定值：order.revoker

merchant_no
required
string <= 32 characters

商户编号，注册成为商户后获得，请参阅参数获取

merchant_order_no
required
string <= 32 characters

商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|*@ ，且在同一个商户下唯一
示例值：1217752501201407033233368018

Responses

Request samples

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

Response samples

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

提交退款申请

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

  1. 可以使用原始订单号进行多次部分退款。但是，所有退款的总金额不应超过原始付款金额。通常情况下，一个订单的部分退款不应超过50笔。
  2. 退款后，您应使用[查询退款]API检查其状态。请记住，退款可能不是即时的，可能会受到特定支付渠道政策的影响。
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 <= 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

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

Response samples

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

查询退款

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

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的固定值：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

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

Response samples

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

交易结果通知

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

  1. 如果网关支付系统没有收到商户方面的确认（成功或超时），就会将其理解为错过通知。为确保商户收到这些通知，系统会定期重新发送通知，在 12 小时内共发送 15 次。但请注意，系统不能保证每次通知都能送达。提醒通知的发送间隔为 5s、10s、15s、30s、60s、3m、10m、15m、三个 30m 间隔和三个 3h 间隔。
  2. 商家的后台有可能多次收到相同的付款通知。因此，商家需要确保其系统具备处理此类重复通知的能力。
  3. 建议的方法是在收到任何通知时检查所附的付款信息。这样做是为了确定这些详细信息之前是否已被处理过。如果数据已被处理，则只需返回先前确定的结果。如果没有，则处理新数据，然后发送响应。为确保数据完整性，尤其是在并发交易的情况下，应在仔细检查付款数据之前使用交易锁。
  4. 为提高安全性，商家还应验证通知的签名。这意味着要检查通知中提到的订单总额是否与商家自己系统中记录的订单总额一致。
  5. 在未来的迭代中，可能会根据不断变化的业务需求为通知添加其他参数。因此，确保验证系统的适应性至关重要。与硬编码的验证参数列表不同，您的系统应能动态处理每份通知中提供的参数。
  6. 最后，可能会出现未收到付款通知或存在签名验证问题的情况。为了应对潜在的交易疏忽，强烈建议实施轮询机制作为保障措施。

确认： 如果准确接收并处理了通知，则返回字符串： 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

交易错误信息

electron_sign_url
string

持卡人电子签名图片URL

Responses

Request samples

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

Response samples

Content type
application/json
Example
"success"