menu

支付相关接口

更新时间: 2019-12-24 18:10:38 · 编辑者:宇链科技

创建预支付单

创建各类预支付单。若不提供相应参数,默认的支付方式为微信支付。

支持 POS 机支付、扫码支付、App 支付、JSSDK 支付、小程序支付等各类支付方式。

支持两个层级的商户,但支付只和第二层(子商户)直接相关。

小程序支付

子商户通过 POS 机扫描动态生成的小程序码,用户扫码进入微信小程序特定支付的 page。该 page 获取小程序码中携带的 scene 参数并进行解析后,通过宇链提供的接口可获取到这次支付的金额、商家等信息。用户在该小程序页面中点击“支付”后,小程序调用宇链接口获取 支付参数和签名信息,并调用小程序支付功能进行支付即可。

小程序获取到的小程序码中携带的 scene 参数是如下类型的字符串:

sm.pay?prepayid=SMP1029348576

其中 SMP1029348576 为子商户预支付单号,用其作为参数即可获取到这次支付的详细信息。注意,这个子商户预支付单号的位数和前缀未来有可能变化,请仔细解析,不要依赖于长度和前缀。举个例子,假如未来我们升级为这样的字符串:

sm.pay?prepayid=SMFP10293485763&f=2

依然应该可以解析出单号为 SMFP10293485763

其他支付

其他各类支付方式,都可以直接将通过宇链云获取到的支付参数提供给微信接口即可。例如,若要进行微信扫码支付,则只需调用“创建微信扫码支付参数”,然后生成二维码即可让用户扫描。

接口地址

POST https://v1.api.tc.vastchain.ltd/submerchant-pay/

本请求需要携带签名。请参考 API 签名算法

请求参数

POST 内容请使用 JSON(请使用 Content-Type: application/json 头)。

body 例子及解释:

{
    "subMerchantId": "发起支付的子商户号",
    "totalAmount": "交易金额", // 以字符串形式发送,最多精确到分
    "orderId": null, // 该交易所关联的订单号,这个版本暂时不使用,为 null 即可
    "extraInfo": null, // 该交易所关联的额外信息,可以任意设置,建议使用 JSON 格式
}

返回值说明

{
    "version": 1,
    "status": "success",
    "prepayId": "PP102990890" // 预支付单号
}

获取子商户支付详情

接口地址

GET https://v1.api.tc.vastchain.ltd/submerchant-pay/prePay/[prepayid]

本请求需要携带签名。请参考 API 签名算法

请求参数

  • URL 参数:
    • prepayid:二维码 scene 里解析出的子商户预支付单号;
  • 可选 Query 参数:
    • waitForFinish:可选值为 0 或 1,默认为 0,代表是否阻塞以等待实时的支付成功通知(强烈推荐);
  • 返回值:
    • 一个 JSON,含有详细信息。

例子

/prePay/SMFP10293485763?waitForFinish=1

返回值

{
    "version": 1,
    "status": "finish",  // 可能为 cancel, finish 或 active 三种状态之一
    "merchantDisplayName": "小黄烧卖",
    "totalAmount": "15.50", // 注意这里指的是用户要支付的价格,而不是优惠前的价格
    "disconut": "0",
    "createTime": "2019-04-29T19:45:39.819Z",
    "paymentTime": "2019-04-29T19:46:23.313Z"
}

如果你是想查询交易是否成功,强烈建议使用 waitForFinish 参数实现高性能和低消耗。在这个参数为 1 的时候,系统并不会立即返回响应(Response),而是会等待 4 秒。在 4 秒内,如果用户支付成功,系统会立即返回。如果支付失败,系统会继续等待,除非超时。使用这个参数可以避免你频繁调用接口,并且得到的回复更加及时。

若使用 waitForFinish,则客户端流程如下:

  1. 调用该接口,并设置 waitForFinish = 1;等待该接口返回结果(最长可能需要 55 秒返回);
  2. 检查结果的 status 是否是 finish
  3. 如果结果不是 finish,或者调用失败(如网络错误或返回非 HTTP 200 的响应),立即循环执行第一步(不用在调用之间手工增加延迟,应立即调用)。

如果 status 不是 active,则代表该支付单号已经过期或不存在,请勿使用。只有 active 状态的二维码可以使用,请在小程序界面上显示相应信息,用户点击支付即可使用微信支付。

创建微信扫码支付参数

通过这个 API 可以获取到所有进行支付时所需要的参数,可以直接用返回值来发起微信支付。不需要再调用微信的统一下单接口。

接口地址

POST https://v1.api.tc.vastchain.ltd/submerchant-pay/wechatPayNative

请求参数

  • 参数:
    • prepayId:创建预支付单得到的预支付单号
  • 返回值:
    • 一个 JSON,含有详细信息。

例子:

{
    "prepayId": "SMFP10293485763"
}

返回值说明

{
    "version": 1,
    "status": "success",
    "args": {
        "return_code": "SUCCESS",
        "return_msg": "OK",
        "appid": "wx10605cb9bfd471c1",
        "mch_id": "1532974421",
        "nonce_str": "keTW6RACDb1tZTOR",
        "sign": "CF9B68A2E057414166CBBAC55DC93C0E",
        "result_code": "SUCCESS",
        "prepay_id": "wx30014205874265a5a7b291583079258361",
        "trade_type": "NATIVE",
        "code_url": "weixin://wxpay/bizpayurl?pr=VQxYAXQ"  // 以此生成二维码。返回值中的其他多余字段将在未来版本中移除
    }
}

code_url 生成二维码进行支付。

创建微信小程序支付参数

POST https://v1.api.tc.vastchain.ltd/submerchant-pay/wechatPay

请求参数

通过这个 API 可以获取到所有进行支付时所需要的参数,可以直接用返回值来发起微信支付。不需要再调用微信的统一下单接口。

  • 参数:
    • prepayId:创建预支付单得到的预支付单号
    • openId:下单用户的 openid。为了安全,openid 应该是后端得到,不传递给小程序,且该 API 也应该是后端调用后将结果返回给前端小程序。
  • 返回值:
    • 一个 JSON,含有详细信息。

例子:

{
    "prepayId": "SMFP10293485763",
    "openId": "sadfasfasfasdf"
}

返回值说明

{
    "version": 1,
    "status": "success",
    "args": {
        "timeStamp": 1556186032,
        "package": "",
        "nonceStr": "VK4d0DaLN9nzgU6pYn9qr7MH9nxboxfr",
        "signType": "MD5",
        "paySign": "9A0A8659F005D6984697E2CA0A9CF3B7"
    }
}

返回值的 args 里正好涵盖了小程序支付接口 所需要的所有参数。小程序端无需进行任何操作,可以直接调起微信支付。

必须先检查 status,如果 status 不是 success,说明支付已经过期,请提示用户发起支付。

创建微信 App 支付参数

POST https://v1.api.tc.vastchain.ltd/submerchant-pay/wechatPayApp

请求参数

通过这个 API 可以获取到所有进行支付时所需要的参数,可以直接用返回值来发起微信支付。不需要再调用微信的统一下单接口。

  • 参数:
    • prepayId:创建预支付单得到的预支付单号
  • 返回值:
    • 一个 JSON,含有详细信息。

例子:

{
    "prepayId": "PP10293485763",
    "enableProfitSharing": true // 是否启用订单分润(可选参数),只有和宇链签约的分润商户才支持该选项,否则设置无效;如果分润打开,则该订单的资金不会直接到账,需要调用分润接口进行后续处理
}

返回值说明

{
    "version": 1,
    "status": "success",
    "args": {
        // xxxxxxx
    }
}

返回值的 args 里正好涵盖了App 支付接口所需要的所有参数。App 端无需进行任何操作,可以直接调起微信支付。

必须先检查 status,如果 status 不是 success,说明支付已经过期,请提示用户重新扫码进行支付。

支付成功回调

当你在宇链云设置好支付成功的回调方法之后,系统会在每次支付成功或退款完成时进行回调,回调采用 POST 方法,并使用与你调用宇链云的签名方式相同的签名方法进行签名。

你也可以用 获取子商户支付详情 接口来主动调取指定的预支付单的支付详情。

注意:
1. 请务必按照要求返回 OK,否则系统会认为回调异常并继续重复调用该回调。
2. 系统可能会多次调用回调,所以请务必做好重复判断,要能正确处理回调多次被调用的情况。
3. 为了防止假冒的回调,请务必验证宇链云发给你的请求中的签名(也就是调用回调时地址中附带的查询字段 _s 字段)是否正确。同时必须验证 notifyTime 不能和当前时间差距太大(推荐 3 分钟内作为合法)。具体请参考签名说明。
4. 如果回调不成功会自动重试至少 12 次以上,每次时间间隔逐步增加,以尽量确保回调成功。

调用形如:

POST https://example.xxx/wechatCallback?_appid=aaaa&_t=1559706602937&_s=a9c4adb283b2beb26d62cef9db04086eb9f7742fab4bb378aed4b39d29ace62b

会附带 JSON 格式的 body,举例如下:

{"notifyTime":"2019-06-05T03:50:02.877Z","prepayId":"PP5555555555","status":"finish","subMerchantId":"SM0000000000","merchantId":"PM0000000000"}

请求参数

  • 参数:
    • notifyTime:回调时间
    • prepayId:相关的预支付单号
    • status:可能为 finish(代表支付完成)或者 refunded(代表退款完成)
    • subMerchantId:对应的子商户号
    • merchantId:对应的父商户号

返回值说明

处理成功的返回值是字符串 OK,返回任何其他内容代表处理失败。

退款接口

POST https://v1.api.tc.vastchain.ltd/submerchant-pay/refund

本请求需要携带商户登录凭证及签名。商户登录凭证通过 query 传递,key 为 loginToken。关于签名,请参考 API 签名算法

请求参数

通过这个 API 可以对已支付的订单进行全额退款。

注意:若这个订单已经分润,退款将不能从分润接收方中返回,将由商户自身承担。

  • 参数:
    • id:要退款的预支付订单号(prepayId)。
  • 返回值:
    • 一个 JSON。

例子:

{
    "id": "PP10293485763"
}

返回值说明

{
    "version": 1,
    "status": "success"
}

返回值为 200statussuccess 代表成功。如不成功,请先检查 status,如果 status 不是 success,说明支付尚未成功或已过期。

设置商户支付参数

PUT https://v1.api.tc.vastchain.ltd/merchant/paymentParams

本请求需要携带签名。签名的 appId 必须是创建该商户的 appId,否则将返回未授权(401)错误。关于签名,请参考 API 签名算法

注意:商户支付参数具有继承关系。例如:当你设置了父商户号的某项具体的支付参数,同时子商户号没有设置该支付参数时,如果支付时需要用到这个参数,将自动使用父商户设置的参数。这有助于实现统一收银系统。

请求参数

通过这个 API 可以设置商户在某个支付通道上的支付参数,如该通道中商户的商户账号等。

  • 参数:
    • id:要修改支付参数的商户号或子商户号;
    • paymentChannel:要修改参数的支付通道,目前支持 WechatNative(微信支付)、WechatUnionPayBizSmall(银联微信小程序支付)两种。
    • parameters:支付参数,每个通道都有自己不同的支付参数。具体请参考下面的例子。

修改 WechatUnionPayBizSmall(银联微信小程序支付)参数的例子:

{
    "id": "SM0105000000",    // 商户号或子商户号
    "paymentChannel": "WechatUnionPayBizSmall", // 支付通道名称
    "parameters": {
        "unionPayBizMchId": "898991870111287", // 银联商户号
        "terminalId": "00000001",  // 支付终端 Id
        "notifyCallbackUrl": "https://v1.ruida-pay.api.vastchain.ltd/unionpay/vastchain/wechatPayBack" // 支付回调地址
    }
}

修改 WechatNative(微信支付)参数的例子:

{
    "id": "SM0105000000",    // 商户号或子商户号
    "paymentChannel": "WechatNative", // 支付通道名称
    "parameters": {
        "profitSharing": true,                        // 是否允许分润(如无需求或尚未开通此业务,请不要设置为 true,否则会导致支付无法入账)
        "wechatAppId": "",                            // 该宇链云子商户或父商户所对应的微信商户在支付时使用的 AppId(比如微信开放平台里的移动应用的 appid 或者微信小程序/公众号的 AppId,注意:如使用分润功能,则这些 Appid 必须和宇链进行微信平台上的绑定,否则无法使用;具体请咨询技术支持)
        "wechatMchId": "",                            // 该宇链云子商户或父商户收款的微信商户的商户号
        "notifyCallbackUrl": "http://127.0.0.1/null"  // 支付成功的回调接口
    }
}

返回值说明

{
    "version": 1,
    "status": "success"
}

智能分润接口

智能分润接口的具体参数说明目前只向我们已签约的合作伙伴开放。此处只表述主要的对接步骤。

前置条件

  1. 目前最大的分润比例限制为 30%。剩余 70% 会进入原先的收款账号。因此,这个收入 >= 30% 部分金额的企业,可称之为“主收款企业”。主收款企业可以是单个,也可以是多个。但是,每次支付时只能以某一个作为主收款企业。智能分润接口对接前,该企业请先根据宇链云商务人员的要求企业营业执照/法人资料/对公账号等,以便开通企业付款账号。
  2. 参与分润的其他人员或组织,只需拥有微信个人账号即可参与,也可以使用企业账号。
  3. 分润接口为异步接口,请做好各类操作的后续处理。
  4. 收到的款项可以设置为自动提现至企业对公银行账户上,到款时间一般为 T+1。

对接步骤

智能分润步骤图

接口说明

支付类接口,请参考本文档中本页面上部的内容。分润接口请在签订合作协议后索要。