JSAPI支付简介和如何使用操作流程

2023-09-07 10:05·机智思图

简介

JSAPI支付是指商户通过调用微信支付提供的JSAPI接口，商户的支付场景是在微信内置浏览器打开调起支付完成收款。

应用场景

JSAPI支付适用于线下场所、公众号场景和PC网站场景。

商户已有H5商城网站，用户通过消息或扫描二维码在微信内打开网页时，可以调用微信支付完成下单购买的流程。具体操作流程如下：

第一步：如图2.1，商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页。

第二步： 如图2.2，进入商户网页，用户选择购买，完成选购流程。

第三步： 如图2.3，调起微信支付控件，用户开始输入支付密码。

第四步：如图2.4，密码验证通过，支付成功。商户后台得到支付成功的通知。

第五步：如图2.5，返回商户页面，显示购买成功。该页面由商户自定义。

第六步：如图2.6，微信支付公众号下发支付凭证。

JSAPI支付接入前准备

1.选择接入模式

商户/服务商在接入前首先要判断自己公司注册区域适用的接入模式，微信支付目前提供两种接入方式：直连模式和服务商模式。

● 直连模式：

信息、资金流：微信支付—>直连商户

直连模式，商户自行申请入驻微信支付，无需服务商协助。（商户平台申请）成为直连商户

直连模式相关说明详见：直连模式介绍

● 服务商模式：

服务商模式，商户申请成为微信支付服务商，服务商自身无法作为一个直连商户直接发起交易，其发起交易必须传入相关特约商户商户号的参数信息。（服务商平台申请）成为服务商，请结合自身实际情况来选择接入模式。

2.参数申请

1.申请APPID

由于微信支付的产品体系全部搭载于微信的社交体系之上，所以直连商户或服务商接入微信支付之前，都需要有一个微信社交载体，该载体对应的ID即为APPID。

目前服务商的社交载体只能是公众号，服务商可通过公众平台完成公众号注册申请。

公众号申请成功后，服务商可登录公众号平台即可获取对应的APPID，具体查阅目录为 【开发-> 基本配置-> 公众号开发信息】，如下图所示。通常情况下，一个服务商只需申请一个公众号即可。

申请mchid

服务商的收款账号即是mchid，申请mchid和APPID的操作互不影响，可以并行操作，申请地址如下： 商户号申请指引。

mchid申请成功后，微信支付将下发通知邮件至机构填写的联系邮箱，内容包含申请成功的mchid及其登录账号密码，请妥善保存。

注意：一个mchid只能对应一个结算币种，若需要使用多个币种收款，需要申请对应数量的mchid。

绑定APPID及mchid。

APPID和mchid全部申请完毕后，需要建立两者之间的绑定关系。

服务商可登录服务商平台，【产品中心-> AppID管理】目录下即可完成绑定。

服务商模式下，一个APPID下可绑定多个mchid，一个mchid可绑定3个APPID。

入驻子商户

上述步骤操作完成后，即会向服务商开放入驻子商户权限。

服务商可登录服务商平台进入【服务商功能】界面完成子商户入驻。

完成

3.配置API key

API v3密钥主要用于平台证书解密、回调信息解密，具体使用方式可参见接口规则文档中证书和回调报文解密章节。

请根据以下步骤配置API key：

1.登录微信服务商平台，进入【账户中心 > API安全】目录，设置APIV3密钥。

在弹出窗口中点击【已沟通】。

输入API密钥，内容为32位字符，包括数字及大小写字母。点击获取短信验证码。

完成

4.下载并配置商户证书

商户API证书具体使用说明可参见接口规则文档中私钥和证书章节

服务商可登录微信服务商平台，在【账户中心 -> API安全】目录下载证书

以下为具体下载步骤：

5.从2018年底开始，微信支付新入驻机构及商户都将使用CA签发证书，在证书申请页面上点击“申请证书”。

在弹出窗口中点击“确定”。

在证书工具中，将复制的商户信息粘贴并点击“下一步”。

获取请求串

生成证书串

第一步：在商户平台】-“复制证书串”环节，点击“复制证书串”按钮后；

第二步：在【证书工具】-“复制请求串”环节，点击“下一步”按钮进入“粘贴证书串”环节；

第三步： 在【证书工具】-“粘贴证书串”环节，点击“粘贴”按钮后；

第四步：点击“下一步”按钮，进入【证书工具】-“生成证书”环节。


在【证书工具】-“生成证书”环节，已完成申请证书流程，点击“查看证书文件夹”，查看已生成的证书文件。

完成

5.配置应用

5.1. 设置支付授权目录

5.1.1. 支付授权目录说明

1)服务商最后请求拉起微信支付收银台的页面地址我们称之为“支付授权目录”，例如：https://www.weixin.com/pay.php的支付授权目录为：https://www.weixin.com/。

2)服务商实际的支付授权目录必须和在微信支付服务商平台设置的一致，否则会报错“当前页面的URL未注册：”

3)服务商模式支付授权目录设置可分为2种方式：

● 服务商为全体子商户设置支付授权目录

● 服务商为某一子商户单独设置支付授权目录

5.1.2. 支付授权目录设置说明

1).服务商为全体子商户设置支付授权目录

登录【微信服务商平台—>产品中心—>开发配置】，设置后一般5分钟内生效。

2).服务商为某一子商户单独设置支付授权目录

登录【微信服务商平台—>服务商功能—>特约商户管理】，设置后一般5分钟内生效。


5.1.3. 支付授权目录校验规则说明

1)如果支付授权目录设置为顶级域名（例如：https://www.weixin.com/ ），那么只校验顶级域名，不校验后缀；

2)如果支付授权目录设置为多级目录，就会进行全匹配，例如设置支付授权目录为https://www.weixin.com/abc/123/，则实际请求页面目录不能为https://www.weixin.com/abc/，也不能为https://www.weixin.com/abc/123/pay/，必须为https://www.weixin.com/abc/123/

5.2. 设置授权域名


开发JSAPI支付时，在JSAPI下单接口中要求必传用户openid，而获取openid则需要您在微信公众平台设置获取openid的域名，只有被设置过的域名才是一个有效的获取openid的域名，否则将获取失败。具体界面如图所示：




开通流程：服务商在 微信支付服务商平台 - 产品中心 - 特约商户授权产品 中发起申请，获得商户授权后，可以替商家发起JSAPI支付。


JSAPI支付开发指引


1. 接口规则


为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考“APIv3接口规则”


2. 开发准备


2.1. 搭建和配置开发环境


为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传等基础功能（更多语言版本的开发库将在近期陆续提供）


测试步骤：


1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：


• wechatpay-java（推荐）wechatpay-apache-httpclient，适用于Java开发者。


• wechatpay-php（推荐）、wechatpay-guzzle-middleware，适用于PHP开发者


注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本


• wechatpay-go，适用于Go开发者


更多资源可前往微信支付开发者社区搜索查看


2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法


JSAPI支付开发指引


1. 接口规则


为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考“APIv3接口规则”



3、基于接口的示例代码，替换请求参数后可发起测试


说明：


• 上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性


通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试


• 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：


1.签名生成


2.签名验证


3.敏感信息加解密


4.merchantPrivateKey（私钥）


5.wechatpayCertificates（平台证书）


6.APIV3Key（V3 key）


• 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档


2.2. 业务开发配置


2.2.1. 设置支付目录


• 支付授权目录说明：


a、商户最后请求拉起微信支付收银台的页面地址我们称之为“支付目录”，例如：https://www.weixin.com/pay.php。


b、商户实际的支付目录必须和在微信支付商户平台设置的一致，否则会报错“当前页面的URL未注册：”


• 支付授权目录设置说明：


登录【微信支付商户平台-->产品中心-->开发配置】，设置后一般5分钟内生效。



• 支付授权目录校验规则说明：


a、如果支付授权目录设置为顶级域名（例如：https://www.weixin.com/ ），那么只校验顶级域名，不校验后缀；


b、如果支付授权目录设置为多级目录，就会进行全匹配，例如设置支付授权目录为https://www.weixin.com/abc/123/，则实际请求页面目录不能为https://www.weixin.com/abc/，也不能为https://www.weixin.com/abc/123/pay/，必须为https://www.weixin.com/abc/123/



2.2.2. 设置授权域名


• 授权域名说明：开发JSAPI支付时，在JSAPI下单接口中要求必传用户openid，而获取openid则需要您在公众平台设置获取openid的域名，只有被设置过的域名才是一个有效的获取openid的域名，否则将获取失败。具体配置页如图2所示


• 授权域名设置说明：登录【微信公众平台-->公众号设置-->功能设置】




3. 快速接入


3.1. 业务流程图



重点步骤说明：


步骤3 用户下单发起支付，商户可通过JSAPI下单创建支付订单。


步骤8 商户可在微信浏览器内通过JSAPI调起支付API调起微信支付，发起支付请求。


步骤15 用户支付成功后，商户可接收到微信支付支付结果通知支付结果通知API。


步骤20 商户在没有接收到微信支付结果通知的情况下需要主动调用查询订单API查询支付结果。


3.2. API接入（含示例代码）


文档展示了如何使用微信支付服务端 SDK 快速接入JSAPI支付产品，完成与微信支付对接的部分。


注意：



  • 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。

  • 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。


3.2.1. 【服务端】JSAPI下单


步骤说明：用户通过商户下发的模板消息或扫描二维码在微信内进入商户网页，当用户选择相关商户购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单。


示例代码



重要入参说明：


• out_trade_no：商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一


• description：商品描述


• notify_url：支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串


• total：订单总金额，单位为分


• openid：openid是微信用户在appid下的唯一用户标识（appid不同，则获取到的openid就不同），可用于永久标记一个用户。openid获取方式请参考以下文档小程序获取openid、公众号获取openid、APP获取openid


更多参数、响应详情及错误码请参见JSAPI下单接口文档


3.2.2.【客户端】JSAPI调起支付


步骤说明：通过JSAPI下单API成功获取预支付交易会话标识（prepay_id）后，需要通过JSAPI调起支付API来调起微信支付收银台


注意：


• WeixinJSBridge内置对象在其他浏览器中无效


•此API需要将请求参数进行签名（参与签名的参数为：appId、timeStamp、nonceStr、package，参数区分大小写）


示例代码：



重要入参说明：


• package：JSAPI下单接口返回的prepay_id参数值，提交格式如：prepay_id=***


• signType：签名类型，该接口V3版本仅支持RSA


• paySign：签名


paySign生成规则、响应详情及错误码请参见 JSAPI调起支付接口文档


3.2.3.【服务端】接收支付结果通知


步骤说明：当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答


注意：



  • 支付结果通知是以POST 方法访问商户设置的通知url，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情

  • 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。

  • 支付通知http应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx

  • 商户成功接收到回调通知后应返回成功的http应答码为200或204

  • 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱

  • 对后台通知交互时，如果微信收到商户的应答不符合规范或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）


更多参数、响应详情及错误码请参见 JSAPI / APP / H5 / Native / 小程序支付通知API接口文档


3.2.4. 【服务端】查询订单


步骤说明：当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知时，商户可通过查询订单接口核实订单支付状态


示例代码(通过微信订单号查询)：



注意：



  • 查询订单可通过微信支付订单号或商户订单号两种方式查询，两种查询方式返回结果相同


更多参数、响应详情及错误码请参见 JSAPI / APP / H5 / Native / 小程序查询订单API接口文档


3.2.5. 【服务端】关闭订单


步骤说明：当商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口


示例代码：



注意：



  • 关单没有时间限制，建议在订单生成后间隔几分钟（最短5分钟）再调用关单接口，避免出现订单状态同步不及时导致关单失败。

  • 已支付成功的订单不能关闭


更多参数、响应详情及错误码请参见 JSAPI / APP / H5 / Native / 小程序接口文档


3.2.6. 【服务端】申请交易账单


步骤说明：微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址


示例代码：



注意：


更多参数、响应详情及错误码请参见 JSAPI / APP / H5 / Native / 小程序接口文档


3.2.7. 【服务端】下载账单


步骤说明：通过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况


示例代码：



注意：


• 账单文件的下载地址的有效时间为30s


• 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性


更多参数、响应详情及错误码请参见 JSAPI / APP / H5 / Native / 小程序下载账单API接口文档


4. 常见问题


Q：获取OPENID接口报“此公众号并没有这些scope的权限，错误码10005”，如下图所示



A：请按以下步骤进行排查：


1. 建议检查一下公众号的功能。比如是不是在订阅号/未认证的公众号里面尝试调用认证服务号的功能。


2. 确认APPID是否认证过期或者APPID填写错误。


3. 请尝试使用snsapi_userinfo的授权登录方式。


Q：JSAPI调起支付接口报“商家暂时没有此类交易权限，请联系商家客服”



A：请按以下步骤进行排查：


1. 请检查你的下单接口是否指定了支付用户的身份，该功能需单独开通指定身份支付权限方可使用


2. 请确认你使用的商户号是否有jsapi支付的权限，可登录商户平台-产品中心查看


Q：JSAPI调起支付接口报“当前页面的URL未注册”



A：请检查下单接口中使用的商户号是否在商户平台配置了对应的支付目录，可参考“1.2.1设置支付目录”章节说明


Q：获取OPENID接口报“redirect_url域名与后台配置不一致，错误码：10003”



A：请按以下步骤进行排查：


1. 检查下单接口传的appid与获取openid接口的appid是否同一个（需一致）


2. 检查appid对应的公众号后台，是否配置的授权域名和获取openid的域名一致。授权域名配置路径：【公众平台->设置->公众号设置->功能设置–>网页授权域名】


Q：JSAPI调起支付接口报“该商户暂不支持通过外部拉起微信完成支付”



A：JSAPI支付只能从微信浏览器内发起支付请求


JSAPI支付API列表


以上内容是JSAPI支付简介和如何使用操作流程，如有不明白之处可咨询我们。

举报
评论 0
    热门：