沙箱环境是支付宝开放平台为开发者提供的与生产环境完全隔离的联调测试环境，开发者在沙箱环境中完成的接口调用不会对生产环境中的数据造成任何影响。
沙箱为开放的产品提供 **有限功能范围** 的支持，可以覆盖产品的绝大部分核心链路和对接逻辑，便于开发者快速学习、尝试、开发和调试。
沙箱环境会自动完成或忽略一些场景的业务门槛，例如：开发者无需等待产品开通，即可直接在沙箱环境调用接口，使得开发集成工作可以与业务流程并行，从而提高项目整体的交付效率。
**注意：**
- 由于沙箱环境并非 100% 与生产环境一致，接口的实际响应逻辑请以生产环境为准，沙箱环境开发调试完成后，**仍然需要在生产环境进行测试验收**。
- 沙箱环境拥有完全独立的数据体系，沙箱环境下返回的数据（例如用户 ID 等）在生产环境中都是不存在的，开发者不可将沙箱环境返回的数据与生产环境中的数据混淆。
# 操作指引
## 第一步：配置沙箱应用环境
1. 使用开发者账号登录 [开放平台控制台](https://openhome.alipay.com/develop/manage?form=payskill) > **开发工具推荐**，点击 **沙箱 **即可进入 [沙箱环境](https://openhome.alipay.com/develop/sandbox/app?form=payskill)。
**说明**：沙箱环境支持的产品，可以在沙箱控制台 **沙箱应用** > **产品列表** 中查看。
### 配置接口加签方式
在沙箱进行调试前需要确保已经配置密钥/证书用于加签，支付宝提供了 **系统默认密钥** 及 **自定义密钥** 两种方式进行配置。
#### 系统默认密钥
开发者如需使用系统默认密钥/证书，可在 **开发信息** 中选择 **系统默认密钥**。
**注意**：使用 [API 在线调试工具](https://open.alipay.com/dev/workspace/apidebug) 调试 OpenAPI 必须使用 **系统默认密钥**。
#### 自定义密钥
开发者如需自定义密钥/证书信息，可在 **开发信息** 中选择 **自定义密钥**。
**说明**：若开发者没有证书或者密钥对，可查看文末 **附录** > **获取加签密钥/证书。**
### 配置应用网关
应用网关用于接收支付宝沙箱环境的异步通知（对接 From 蚂蚁消息），如创建门店的被动通知。
**注意**：仅 HTTP 订阅模式的 From 蚂蚁消息才需要配置应用网关，WebSocket 订阅模式的 From 蚂蚁消息无需配置应用网关。
### 服务端代码配置
沙箱环境调试接口时，开发者需调整如下代码配置：
- **支付宝网关地址**：`https://openapi-sandbox.dl.alipaydev.com/gateway.do`
- **APPID** 切换为沙箱的 APPID
- **签名方式** 使用 RSA2
- 根据配置的密钥/证书，选择对应加签代码设置商户应用私钥和支付宝公钥。
具体如何调用开放接口，请查看各开放产品的快速接入或技术接入文档章节的沙箱调试文档。以 [alipay.trade.precreate](https://opendocs.alipay.com/open/02ekfg?scene=19)（统一收单线下交易预创建接口）Java 语言沙箱调用为例（其它语言请查看各自 SDK）。
```java
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipaydev.com/gateway.do","2016072200101XXXX","请复制第1步中生成的密钥中的商家应用私钥","json","utf-8","沙箱环境RSA2支付宝公钥","RSA2");
AlipayTradePrecreateRequest request = new AlipayTradePrecreateRequest();
AlipayTradePrecreateModel model = new AlipayTradePrecreateModel();
request.setBizModel(model);
model.setOutTradeNo(System.currentTimeMills());
model.setTotalAmount("88.88");
model.setSubject("Iphone6 16G");
AlipayTradePrecreateResponse response = alipayClient.execute(request);
System.out.print(response.getBody());
System.out.print(response.getQrCode());
```
### 订阅消息
在沙箱应用页面下拉到 **消息服务**，在 **From 平台** 和 **TO 平台** 标签页即可订阅所需监听的消息接口。
#### WebSocket 长连接接入
在沙箱环境使用 WebSocket 长链接接入需要将消息接口的订阅方式修改为 WebSocket，SDK 配置方式可以参考 [WebSocket 长连接接入](https://opendocs.alipay.com/common/02kiq1)。
**说明**：
- 沙箱环境的 `serverHost` 为 `openchannel-sandbox.dl.alipaydev.com`。
- 将连接支付宝网关代码修改为：`alipayMsgClient.setConnector(serverHost, false)`。
### 沙箱 SPI 配置
在沙箱产品列表的已发布产品中添加 SPI 产品。
完成产品添加后点击去开发，进入到 SPI 配置页。
在 API 列表中选择 SPI 接口并点击接入。
配置 SPI 测试地址并 **保存**。
实现所有必须实现的 SPI 接口后，点击 **上线**。
### 其它配置
- 授权回调地址：第三方应用授权或获取用户信息中用于接收授权回调信息的地址。使用相关产品时需进行配置：
- 第三方应用授权：授权 URL 中的 redirect_uri 必须与此值相同。
- 获取用户信息：授权 URL 中的 redirect_uri 的域名必须与此值相同(例如：授权回调地址配置：`https://auth.example.com/authCallBack` 高亮部分需和授权 URL 相同)。
- 接口内容加密方式：加密后，接口的请求内容和响应内容将会由明文内容变为密文内容，可以提升接口内容传输的安全性。若不设置，则接口内容不会被加密。更多信息请参见 [AES 加密说明](https://opendocs.alipay.com/common/02mse3)。
## 第二步：下载支付宝客户端
调试过程中需要支付宝 App 支持的功能，请使用沙箱提供的 Android 支付宝沙箱版，例如当面付的条码获取。
获取方式在开放平台控制台研发服务左侧，点击 **沙箱环境 **> **沙箱工具**。
## 第三步：获取账号
下载沙箱版支付宝 App 后，开发者需在 **沙箱账号** 中获取 **商家账号** 及 **买家账号**。
- 商家账号用于模拟商家/服务商的主账号。
- 买家账号用于模拟用户的账号。例如：测试当面付功能时，需要切换为买家账号登录沙箱支付宝钱包扫码支付。
**注意**：沙箱版支付宝客户端必须使用沙箱账号登录。
## 第四步：了解并调用接口
为了方便开发者使用，沙箱环境设置了独立于生产环境的配置，并提供了辅助开发者体验开放接口的配套测试账号和工具：
- 沙箱网关地址为：`https://openapi-sandbox.dl.alipaydev.com/gateway.do`
- 沙箱环境应用为上述沙箱环境为开发者自动创建的应用，对应的 APPID 可以在页面上找到。
- 沙箱平台提供了商家和买家的测试账号；点击 **沙箱环境** > **测试账号**；开发者可使用商家账号进行应用授权、使用买家账号进行付款等操作。
具体如何调用开放接口，请查看各开放产品的接入指南文档章节，其中会说明沙箱使用的特别说明，开发者可以根据产品文档进行各接口的开发，按照接口文档说明和沙箱使用说明填入正确的参数，完成沙箱功能的调用。
**沙箱调试常见错误 **
| **错误码** | **错误描述** | **排查方案** |
| --- | --- | --- |
| invalid-signature | 无效签名 | 签名校验失败。
1. 检查网关地址是生产环境还是沙箱环境，必须使用与之匹配的 app_id 与私钥。
2. 检查编码类型是否正确。
3. 检查私钥与开放平台上传的应用公钥是否匹配。
4. 检查签名类型 (sign_type) 设置是否正确。如果不传入 sign_type 参数，默认 RSA 类型。
5. 检查生成的待签名串是否符合要求：去掉值为空的参数、所有参数是否按照字母升序排序。
6. 检查签名之后是否对所有参数值做了 URL encode 操作才发起请求。
具体可以使用 [自助排查](https://opendocs.alipay.com/common/02kdnf)。 |
| ACQ.PAYMENT_AUTH_CODE_INVALID | 支付失败，获取用户账号信息失败，请用户刷新付款码后重新收款，如再次收款失败，请联系管理员处理（SOUNDWAVE_PARSER_FAIL）。 |
1. 沙箱环境需要使用支付宝客户端沙箱版的付款码进行调试，获取方式在控制台左侧，点击 **沙箱环境** > **沙箱工具。**
2. 如果已使用支付宝客户端沙箱版仍然报此错误，可以尝试将支付宝客户端卸载后重新安装。
|
| missing-signature | 缺少签名参数。 |
1. 检查请求时是否加上 sign 字段。
2. 使用非 Java 版本 SDK 开发时，请检查是否为代码中因私钥格式错误导致未签名就提交。
|
| missing-signature-config | 验签出错，未配置对应签名算法的公钥或者证书。 |
1. 检查是否在沙箱环境上传应用公钥。
2. 签名方式和实际配置的应用公钥是否匹配，即推荐使用的是上传 RSA2(SHA256) 密钥，并且签名时需要使用 RSA2 进行签名。
|
如排查后仍有问题，可点击页面右侧 **在线咨询** 进行排查。
## 第五步：线上验收
在沙箱环境完成功能调试后，必须将支付宝网关、APPID、应用私钥、支付宝公钥修改成生产环境的配置，并在生产环境进行完整的功能验收测试。
# 附录
## 获取加签密钥/证书
开发者可通过 [支付宝开放平台开发助手](https://opendocs.alipay.com/common/02kipk) 申请加签密钥或公钥证书 CRS 文件，再配置到沙箱应用中。
### 获取公钥
开发者使用普通公钥加签，可根据 [公钥方式](https://opendocs.alipay.com/common/02kipl#%E5%85%AC%E9%92%A5%E6%96%B9%E5%BC%8F) 指引获取密钥对。
### 获取公钥证书
开发者使用公钥证书加签，可根据 [公钥证书方式](https://opendocs.alipay.com/common/02kipl#%E5%85%AC%E9%92%A5%E8%AF%81%E4%B9%A6%E6%96%B9%E5%BC%8F) 指引获取公钥证书 CSR 文件，仅需在沙箱密钥配置中上传此文件即可获取证书。
**注意**：
- 配置 CSR 公钥证书时 2020-07-24 前获取的沙箱账号 **组织/公司** 需固定填写 **沙箱环境**。
- 若沙箱账号为 2020-07-24 后获取 **组织/公司** 需填写 **沙箱商家账号**，例如：沙箱商家账号为 xxx@sandbox.com，组织/公司就需要配置成 xxx@sandbox.com。
## 版本差异
新版沙箱和旧版沙箱是两个完全独立的沙箱环境，相较于旧版沙箱，新版沙箱的运行环境更加稳定。同时，新版沙箱的操作体验更贴近于线上环境。此外，新旧沙箱的差异还表现在沙箱应用、沙箱账号、沙箱钱包和支持的产品范围等方面。
### 沙箱应用差异
**沙箱应用**
新版沙箱环境为开发者分配了全新的网页/移动应用和小程序应用，并会默认启用系统密钥。
**注意**：使用老版本沙箱的 APPID 无法在新版沙箱正常调用。
**开发信息**
新版沙箱需要设置新的支付宝网关地址、消息网关地址以及接口加签方式等开发信息，请注意在编码中进行相关配置信息的调整：
- 支付宝网关地址：新版沙箱网关地址为 [https://openapi-sandbox.dl.alipaydev.com/gateway.do](https://openapi-sandbox.dl.alipaydev.com/gateway.do)。
- 消息网关地址：新版沙箱消息网关地址为 openchannel-sandbox.dl.alipaydev.com。
- 接口加签方式：新旧沙箱环境具有独立的证书/密钥配置和相应的启用状态。
### 沙箱账号差异
新版沙箱环境为开发者分配了全新的商家账号和买家账号，并会默认充值。
### 沙箱钱包差异
升级到新版本沙箱的用户，请从左边栏沙箱工具中下载最新版本的沙箱支付宝 App 安装使用。
**注意**：使用老版本沙箱的账号无法正常登录。
### 产品范围差异
新版沙箱在覆盖旧版沙箱支持的产品的基础上并支持了更多的开放产品，为开发者提供更加丰富的沙箱调试功能。具体支持的产品可以参考沙箱控制台的产品列表栏。
### IDE支持的差异
沙箱支付宝 APP 版本依赖：需确保沙箱支付宝 APP 版本为 10.3.90.8030 及以上版本（如果不是，可以去 [沙箱工具](https://open.alipay.com/develop/sandbox/tool) 下载）。
1. 打开小程序开发者工具，使用线上支付宝 APP 进行扫码登录。
- 如果已经安装 **环境切换插件**，请先将环境切换到线上环境后，重启 IDE，再扫码登录。
- 如果没有安装 **环境切换插件**，则不需要做任何操作。
2. 为了方便调试，可以在应用的详情中关闭或忽略各种权限校验。
3. 生成预览/真机调试码时，取消 **小程序自动推送支付宝** 选项，方便沙箱支付宝扫码调试。
4. 使用沙箱支付宝 APP 扫描预览/真机调试码，进行小程序或插件的预览/真机调试。
**说明**：新版本的沙箱支付宝主要面向的是小程序/插件预览或真机调试，所以暂不提供上传版本能力。但为了帮助开发者和支付宝的沙箱上线版本拉通联调诉求，未来我们将开放小程序/插件同步沙箱的能力。
## 常见问题
### 沙箱提示系统繁忙
老沙箱环境计划逐步暂停维护，建议您升级到新沙箱环境以获得更好的联调体验。
### 如何升级新沙箱环境
您只需要访问链接 [https://open.alipay.com/develop/sandbox/app](https://open.alipay.com/develop/sandbox/app?is_switch_sandbox=true)，点击右上角的升级沙箱环境，然后更换代码中的应用/网关/账号信息，并从左边栏沙箱工具中下载最新版本的沙箱支付宝 App 安装使用。
### 沙箱钱包无法登录
如果您无法登录沙箱钱包，请下载最新版本的沙箱支付宝 App，并使用新的沙箱账号进行登录。
### 沙箱环境新版会报错误代码 invalid-app-id
如果您在新沙箱环境中出现了错误代码 "invalid-app-id"，那么很可能是因为您使用了老沙箱环境的配置信息。为了解决这个问题，请在代码中更换新版本的应用/网关/账号信息。