SnapPay 开放服务

阅读对象

商户系统（在线购物平台、人工收银系统、自动化智能收银系统或其他）承建的技术方，涉及产品、研发、测试的工程师，系统运维工程师。通过本文的指导，接入SnapPay开放服务网关（Open Service Gateway），实现微信/支付宝/银联二维码，网页，手机应用等方式的支付能力。

开发指南

开发前，首先确认您的业务适用哪种支付场景，仔细阅读开放服务文档，用我们的测试商户评估和测试，上线前用真实参数替换测试参数。

测试参数

为了评估和测试，可以先使用我们的测试商户，包含：

测试商户号
测试门店号（只适用于线下支付场景）
测试AppID
测试MD5 Sign key

如何找到这些参数，请点击这里。

商户参数

在商户支付系统上线之前，需要将商户的真实参数替换测试参数。

这些参数 (Merchant ID, AppID, MD5 Sign Key) 可以在商户的管理平台中找到。步骤如下:

用email地址登陆商户管理平台
在左边菜单点击 ‘支付业务’
再点击 ‘业务开通’
点击 ‘Open API Integration’ 。在 ‘密钥管理’ 模块, 点击 ‘点击查看’
输入登录密码
就能看到App ID 和 MD5 Sign key.

如何找到商户号（Merchant ID）:

在左边菜单点击 ‘账户中心’
再点击 ‘商户信息’
在这页就能找到商户号

如果您有疑问获得上述参数，请联系SnapPay客服。

技术支持

如有技术问题，商户设置问题，请联系SnapPay客服邮件 [email protected] 或客服电话 1(888) 660-7729。

文档更新历史

December, 2018.
Uploaded the API documents.
March, 2019.
Updated the Website payment scenario, WeChat H5 Payment scenario.
June, 2019.
Added the WeChat and Alipay In-app Purchase support.
November, 2019.
Reformated API document in API Blueprint.
Added WeChat Mini program payment scenarios.

1. 条码(刷卡)支付

条码支付也称刷卡支付、被扫支付、B扫C支付，是传统行业采用的一种线下二维码收款方式。

商家使用POS机，扫码枪等条码识别设备扫描用户微信/支付宝上的条码/二维码，完成收款。用户仅需出示付款码，所有收款操作由商家完成。

场景介绍

以下以微信支付为例，说明条码支付的使用场景，支付宝二维码场景和微信类似：

步骤1：用户选择刷卡支付付款并打开微信，进入“我”->“钱包”->“收付款”条码界面；

步骤2：收银员在商户系统操作生成支付订单，用户确认支付金额；

步骤3：商户收银员用扫码设备扫描用户的条码/二维码，商户收银系统提交支付给开放服务网关；

步骤4：微信支付后台系统收到支付请求，根据验证密码规则判断是否验证用户的支付密码，不需要验证密码的交易直接发起扣款，需要验证密码的交易会弹出密码输入框。支付成功后微信端会弹出成功页面，支付失败会弹出错误提示。

业务流程

流程详细说明

收银员使用扫码设备扫码用户微信支付宝客户端展示的条码；
扫码设备上传条码信息给商户收银台应用；
收银员在商户收银台应用创建订单；
用户确认订单，商户收银台提交支付请求到商户后台；
商户后台调用发起条码（刷卡）支付API提交支付请求给开放服务网关后台；
开放服务网关验证支付请求，请求微信支付宝后台进行支付；
处理支付，如果需要验证用户交易密码，则通知用户输入密码；
微信支付宝后台同步返回支付结果给开放服务网关（需要验密的交易，则返回状态为交易中）；
开放服务网关后台同步返回支付结果给商户后台（需要验密的交易，则返回状态为交易中）；
商户后台同步返回支付结果给商家收银台，展示支付结果给用户；
微信支付宝异步通知用户APP支付结果；
对于交易状态不明确的交易，开放服务网关通过主动查询获取支付结果。
对于交易状态不明确的交易，商家后台通过主动查询获取支付结果，请参考查询订单API。
支付成功后，开放服务网关后台会异步通知商户后台支付成功,请参考异步通知。

2. 扫码支付

扫码支付也称主扫支付、C扫B支付，指用户打开支付宝/微信中的“扫一扫”功能，扫描商家展示在某收银场景下的二维码并进行支付的模式。该模式适用于线下实体店支付、面对面支付等场景。

场景介绍

以下以微信支付为例，说明扫码支付的使用场景（支付宝二维码场景和微信类似）

用户扫描商户展示在各种场景的二维码进行支付。

步骤1：商户根据支付的规则，为不同商品生成不同的二维码，展示在各种场景，用于用户扫描购买。

步骤2：用户使用微信“扫一扫”扫描二维码后，获取商品支付信息，引导用户完成支付。

步骤3：用户确认支付，输入支付密码。

步骤4：支付完成后会提示用户支付成功，商户后台得到支付成功的通知，然后进行发货处理。

业务流程

流程详细说明

收银员在商户收银台应用创建订单；
用户确认订单，商户收银台提交支付下单请求到商户后台；
商户后台使用扫码支付下单API提交预支付下单请求给开放服务网关后台；
开放服务网关验证支付请求，请求微信支付宝后台预支付下单；
微信支付宝后台同步返回二维码信息给开放服务网关；
开放服务网关后台同步返回二维码信息给商户后台；
商户后台同步返回二维码信息给商家收银台；
商家收银台生成二维码图片，展示给用户；
用户使用微信/支付宝扫码商家二维码，发起支付；
微信/支付宝后台处理支付，如果需要验证用户交易密码，则通知用户输入密码；
微信支付宝异步通知用户APP支付结果；
对于交易状态不明确的交易，开放服务网关通过主动查询获取支付结果。
对于交易状态不明确的交易，商家后台通过主动查询获取支付结果，请参考查询订单API。
支付成功后，开放服务网关后台会异步通知商户后台支付成功,请参考异步通知。

3. 公众号/H5支付

公众号/H5支付是微信支付宝给到线下/线上行业的一种收款方式。

用户使用微信支付宝APP扫码商家提供的聚合二维码或通过访问商家手机H5网站，在微信支付宝APP内通过JSSDK调起支付控件完成支付。

场景介绍

以下以微信支付为例，说明H5支付的使用场景，支付宝场景和微信类似：

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

步骤1：商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页，商户也可以把商品网页的链接生成二维码，用户扫一扫打开后即可完成购买支付。

步骤2：进入商户网页，用户选择购买，完成选购流程。

步骤3：商户前端页面调用开放服务网关H5支付地址，开放服务网关H5调起微信支付控件，用户开始输入支付密码。

步骤4：密码验证通过，支付成功。商户后台得到开放服务网关支付成功的通知。

交互细节

以下是支付场景的交互细节，请认真阅读，设计商户页面的逻辑：

用户打开商户网页选购商品，发起支付，在网页通过JavaScript调用开放服务网关接口，发起微信支付请求，用户进入支付流程。
用户成功支付点击完成按钮后，会重定向到商家网页，商户可直接跳转到支付成功的静态页面进行展示（注：支付宝境外暂不支持此功能）。
商户后台收到来自开放服务网关支付成功回调通知，标志该笔订单支付成功。

注：（2）和（3）的触发不保证遵循严格的时序。前端跳转作为触发商户网页跳转的标志，但商户后台应该只在收到开放服务网关后台的支付成功回调通知后，才能做真正的支付成功的处理。

业务流程

流程详细说明

用户在微信支付宝内置浏览器内访问商户H5页面浏览商品创建订单；
商户提交订单，商户H5提交下单请求到商户后台；
商户后台使用H5支付下单API提交预支付下单请求给开放服务网关后台；
开放服务网关验证支付请求，保存订单信息，同步返回开放服务网关H5收银台页面地址给商户后台；
商户后台同步返回开放服务网关H5收银台页面地址给商家H5页面；
商家H5页面请求服务商返回的开放服务网关H5收银台页面地址；
开放服务网关H5收银台页面地址请求开放服务网关后台预支付下单；
开放服务网关后台请求微信/支付宝后台预支付下单；
微信/支付宝后台同步返回开放服务网关后台支付相关信息；
开放服务网关后台同步返回H5收银台支付相关信息；
开放服务网关H5收银台使用JS SDK调起微信支付宝APP支付控件；
微信支付宝APP调用后台进行支付；
微信/支付宝后台处理支付，如果需要验证用户交易密码，则通知用户输入密码；
微信支付宝异步通知用户APP支付结果；
对于交易状态不明确的交易，开放服务网关通过主动查询获取支付结果；
对于交易状态不明确的交易，商家后台通过主动查询获取支付结果，请参考查询订单API；
支付成功后，开放服务网关后台会异步通知商户后台支付成功,请参考异步通知。

4. Native App支付

适用于商家在手机App应用中集成支付宝/微信支付功能。

商家APP调用支付宝/微信提供的SDK，SDK再调用支付宝/微信内的支付模块。支付完后跳回到商家APP内，最后展示支付结果。

目前支持手机系统有：iOS（苹果）、Android（安卓）。

场景介绍

以下以支付宝支付为例，说明in-app支付的使用场景，微信场景和支付宝类似：

步骤1：用户在商家App中选择商品下单、确认购买，进入支付环节，选择支付宝，用户点击确认支付，如图1；

步骤2：进入到支付宝页面，调起支付宝支付，出现确认支付界面，如图2；

步骤3：用户确认收款方和金额，点击立即支付后出现输入密码界面，如图3；

步骤4：输入正确密码后，支付宝端显示支付结果，如图4；

步骤5：自动回跳到商家App中，商家根据付款结果个性化展示订单处理结果，如图5。

交互细节

以下是支付场景的交互细节，请认真阅读，设计商户页面的逻辑：

用户打开商户APP选购商品，发起支付，商户后台调用开放服务网关接口，发起支付宝支付请求，用户进入支付流程。
用户完成支付后，商户后台调用开放服务网管接口查询支付结果，如果支付成功，展示支付成功页面，如果支付失败，展示支付失败页面。
商户后台可以收到来自开放服务网关支付成功回调通知，标志该笔订单支付成功。

注：（2）和（3）的触发不保证遵循严格的时序，都能做真正的支付成功的处理。

业务流程

支付宝流程

流程详细说明

用户在商户APP内浏览商品并向商户后台发送创建订单请求；
商户后台使用Native APP支付下单API提交预支付下单请求给开放服务网关后台；
开放服务网关后台同步返回支付订单信息给商户后台；
商户后台同步返回支付订单信息给商家APP；
商家APP利用同步返回的订单信息调起支付宝APP；
支付宝客户端SDK将会按照订单信息向支付宝后台发送支付请求；
支付宝后台处理支付，如果需要验证用户交易密码，则通知用户输入密码；
接口返回支付结果给支付宝SDK；
支付宝SDK将支付结果返回给商户app；
商户app发送订单查询请求给商户后台；
商户后台发送订单查询请求给开放服务网关，请参考查询订单API；
开放服务网关后台发送查询请求给支付宝；
支付宝同步返回支付结果；
开放服务网关后台将支付结果返回给商户后台；
商户后台将支付结果返回给商户app，商户app展示支付结果给客户；
支付成功后，支付宝同时会异步通知开放服务网关后台支付结果；
开放服务网关后台会异步通知商户后台支付结果,请参考异步通知；

微信流程图

流程详细说明

用户在商户APP内浏览商品并向商户后台发送创建订单请求；
商户后台使用Native APP支付下单API提交预支付下单请求给开放服务网关后台；
开放服务网关验证支付请求，请求微信支付后台预支付下单；
微信后台同步返回预支付订单号给开放服务网关；
开放服务网关后台同步预支付订单信息给商户后台；
商户后台同步返回支付订单信息给商家APP；
商家APP利用同步返回的订单信息调起微信APP；
微信客户端SDK将会按照订单信息向微信后台发送支付请求；
微信后台处理支付，如果需要验证用户交易密码，则通知用户输入密码；
接口返回支付结果给微信SDK；
微信SDK将支付结果返回给商户app；
商户app发送订单查询请求给商户后台；
商户后台发送订单查询请求给开放服务网关，请参考查询订单API；
开放服务网关后台发送查询请求给微信后台；
微信同步返回支付结果；
开放服务网关后台将支付结果返回给商户后台；
商户后台将支付结果返回给商户app，商户app展示支付结果给客户；
支付成功后，微信同时会异步通知开放服务网关后台支付结果；
开放服务网关后台会异步通知商户后台支付结果,请参考异步通知；

微信Native App支付接入流程

商户需要在微信的开放平台申请入驻: https://open.weixin.qq.com/
审批通过之后，注册移动应用，通过后会得到移动APPID: https://pay.weixin.qq.com/wiki/doc/api/app/app_sl.php?chapter=8_5
商户得到APPID后，发送APPID和企业名称（建议申请微信APPID时的企业名称和注册SnapPay商户时的名称一致）给SnapPay客服 [email protected] 。SnapPay需要联系微信将移动APPID与服务商的商户ID做授权绑定。
商户开始接入开发

在微信开放平台找到手机应用的企业名称

SnapPay将发送下面的信息给微信进行绑定

    服务商信息：
    商户号：1509049871 
    机构商户名称：Snappay
    公众号：wxb6ca1d115e8cbd4f
    
    移动app信息： 
    移动应用AppID：wxba68e393b65f5d9b
    子商户号:123456789
    企业名称：Super Merchant Inc.

5. Web网页支付

Web网页支付是支付宝/银联国际给到线上商家提供的一种收款方式。

用户点击商家支付按钮跳转到支付宝/银联国际网站的收银台，登录自己的账户完成支付。

场景介绍

以下以支付宝支付为例，说明PC网站支付的使用场景，银联国际的场景和支付宝类似：

步骤1：买家在商户网站选择需购买的商品，填写订单信息后，点击立即购买。

步骤2：网页跳转到支付宝收银台页面。

步骤3：

用户可以使用支付宝App扫一扫屏幕二维码，待手机提示付款后选择支付方式输入密码即可完成支付；
如果不使用手机支付，也可以点击上图右侧的“登录账户付款”，输入支付宝账号和支付密码登录PC收银台。
用户选择付款方式，输入支付密码后点击“确认付款”。

步骤4：付款成功。

选择商品并添加至购物车

扫描QR码

登录支付宝账户付款

业务流程

流程详细说明

用户在商户网站浏览商品创建订单；
商户网站提交支付下单请求到商户后台；
商户后台使用Web网页支付下单API提交预支付下单请求给开放服务网关后台；
开放服务网关验证支付请求，请求银联国际/支付宝后台预支付下单；
银联国际/支付宝后台同步返回支付信息给开放服务网关；
开放服务网关后台同步返回银联国际/支付宝支付网站地址给商户后台；
商户后台同步返回银联国际/支付宝支付网站地址给商家网站；
商家网站重定向到银联国际/支付宝支付网站地址；
银联国际/支付宝后台处理支付，支付成功，回调请求商户页面地址；
对于交易状态不明确的交易，开放服务网关通过主动查询获取支付结果；
对于交易状态不明确的交易，商家后台通过主动查询获取支付结果，请参考查询订单API；
支付成功后，开放服务网关后台会异步通知商户后台支付成功,请参考异步通知。

6. 微信小程序支付

微信小程序支付是专门被定义使用在小程序中的支付产品。目前在小程序中能且只能使用小程序支付的方式来唤起微信支付。

场景介绍

步骤1：买家在商户的微信小程序中选择需购买的商品，点击立即支付。

步骤2：商户的微信小程序调起微信支付控件，用户开始输入支付密码。

步骤3：密码验证通过，支付成功。商户后台得到开放服务网关支付成功的通知。

选择购买的商品

微信支付控件

流程详细说明

用户在商户的微信小程序浏览商品创建订单；
商户小程序提交支付下单请求到商户后台；
商户后台获得Openid使用微信小程序支付下单API提交预支付下单请求给开放服务网关后台；
开放服务网关验证支付请求，请求微信后台预支付下单；
微信后台同步返回支付信息给开放服务网关；
开放服务网关后台同步返回微信小程序支付信息给商户后台；
商户后台同步返回支付信息给商家微信小程序；
商家微信小程序调起微信支付控件；
微信后台处理支付，支付成功，支付结果返回给商户小程序；
对于交易状态不明确的交易，开放服务网关通过主动查询获取支付结果；
对于交易状态不明确的交易，商家后台通过主动查询获取支付结果，请参考查询订单API；
支付成功后，开放服务网关后台会异步通知商户后台支付成功,请参考异步通知。

微信小程序支付接入流程

商户需要在微信公众平台申请入驻: https://mp.weixin.qq.com
审批通过之后，注册小程序应用，通过后会得到小程序APPID: https://developers.weixin.qq.com/miniprogram/introduction
商户得到APPID后，发送APPID和企业名称（建议申请微信APPID时的企业名称和注册SnapPay商户时的名称一致）给SnapPay客服 [email protected] 。SnapPay需要联系微信将小程序APPID与服务商的商户ID做授权绑定。
商户开始接入开发

在微信开放平台找到小程序的企业名称

SnapPay将发送下面的信息给微信进行绑定

    服务商信息：
    商户号：1509049871 
    机构商户名称：Snappay
    公众号：wxb6ca1d115e8cbd4f
    
    小程序信息： 
    小程序AppID：wxba68e393b65f5d9b
    子商户号:123456789
    企业名称：Super Merchant Inc.

SnapPay 开放服务

简介