沙盒测试
====

沙盒测试允许开发者在接入华为应用内支付调测过程中对订单进行虚拟支付。

推荐您在提交数字商品审核前、即商品处于草稿/待提交状态下，使用沙盒测试进行调测。您可以通过设置沙盒测试账户，来模拟真实环境下数字商品的交易过程，在测试期间发现问题可以及时进行修复，这样确保了在商品上架生效以后可以提供给用户稳定流畅的商品购买体验。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/78/v3/s6_5_3kqRN26inB6DJV7bg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=8E551E74B2E2C681E653D887A9629E81BBE06563E14D1BA131CFEC61AA038FAB)

沙盒订单并非真实订单，无法在\[开发者中心\]->\[我的报表\]->\[支付报表\]中查询。

#### 配置沙盒测试

*   添加测试账号
    
    在进行测试前，需要在[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)中的“用户与访问”中添加测试账号，这些测试账号必须是真实的华为账号。开发者在接入IAP Kit沙盒测试时，需要在测试设备上登录已添加的测试账号。添加沙盒测试账号步骤如下：
    
    1.  登录[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站，选择“用户与访问”。
        
    2.  左侧导航栏选择“沙盒测试 > 测试账号”，点击“新增”。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/92/v3/yrcT9sS-RXW3IqejdijxOA/zh-cn_image_0000002625108743.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=82B44FF74A88EAAE34AB1DD890A36A0E8B1FDD50CE8E792223B814A376D7BD35)
        
    3.  填写测试账号信息后，点击“确认”。
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b6/v3/7F9L8G9dSry0qm8fMpF8lQ/zh-cn_image_0000002594669226.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=705A2B79E7777B60299AE587B481DAA6566AE1444702DAAE46DEE0C285E1E0DB)
        
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/94/v3/qC68KeRPSOqYi4__pmj2mA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=21421F3193C9B3488AAD60391C1FA8018AF4B59A56BCAC3256756C004A4005EE)
    
    此配置需要5~10min才能生效。
    
*   构建debug签名的应用
    
    接入的应用必须是debug签名的应用。构建debug签名应用步骤如下：
    
    1.手动签名：您需要在AGC中[申请调试证书](https://developer.huawei.com/consumer/cn/doc/app/agc-help-debug-cert-0000002283256797)、[注册调试设备](https://developer.huawei.com/consumer/cn/doc/app/agc-help-add-device-0000002283189937)、[申请调试Profile](https://developer.huawei.com/consumer/cn/doc/app/agc-help-debug-profile-0000002248181278)后，再[手动签名](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing#section297715173233)。
    
    2.在[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)中[配置公钥指纹](https://developer.huawei.com/consumer/cn/doc/app/agc-help-cert-fingerprint-0000002278002933)。
    

#### 沙盒测试能力未生效自检

如果配置的沙盒账号未生效，可参见[配置沙盒测试](#配置沙盒测试)检查当前是否满足沙盒测试的两个条件：

*   是否已在[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)添加测试账号。
    
*   应用是否是debug签名。
    

此外也可在应用中使用[isSandboxActivated](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-iap#iapissandboxactivated)接口来检查当前沙盒环境不可用的原因。

#### 测试消耗型/非消耗型商品购买

在满足沙盒测试条件下，开发者调用[createPurchase](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-iap#iapcreatepurchase)接口拉起收银台，用户按照正常流程完成购买，但实际不会产生真实扣费。

*   沙盒环境下的购买流程与正式环境的购买流程一致，仍需要完成绑定付款方式，但该过程不会真实扣费。
    
*   IAP购买成功后的收据信息[PurchaseOrderPayload](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-data-model#purchaseorderpayload)中，会携带值为"SANDBOX"的environment字段，标识此次购买为沙盒测试的记录。
    
*   沙盒环境下购买非消耗型商品，在确认发货之后可以再次测试购买。确认发货后该笔订单将无法通过[queryPurchases](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-iap#iapquerypurchases)接口查询返回。
    
*   沙盒测试拉起收银台时，会在收银台展示沙盒测试提示语，支付结果页也有沙盒环境的提示语，如下图所示。
    

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/76/v3/zmxPYwD4RLi5U4iwBokaPw/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=819D924D950D2440E5FCA9093995FFF93E2C6A595C2403C2F1A521826C6AD160)

如果未显示截图的提示页面，表示本次交易未进入沙盒测试环境，继续测试会实际扣费，请参照[沙盒测试能力未生效自检](#沙盒测试能力未生效自检)。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d0/v3/olq5BI-IST66SUCYB0TWeg/zh-cn_image_0000002594829154.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=19F0CD8575173C993A1BE0A73154A99E5AF528E30FB7301D2FFFA4E418D5E26C) ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cc/v3/7owGDaCtQ-iBobOAkWuwIw/zh-cn_image_0000002625188601.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=96C8FBD48F9B0E3358FA23FA818C86AB701606342F581284803D5476DBDCCAEC)

#### 测试自动续期订阅商品

自动续期订阅商品的购买流程和消耗型/非消耗型商品的购买流程类似，但订阅还有其他细节场景，比如续订成功或失败，续订周期时长。为了帮助开发者快速测试应用的订阅场景，沙盒环境下的订阅续订时间会比正常情况更快，引入“时光机”概念，沙盒环境中的订阅换算时间为10秒/天。比如订阅周期为1周，商品将在首次购买成功70秒后发生续期。

*   沙盒环境下的订阅流程与正式环境的订阅流程一致，仍需要完成绑定付款方式，但该过程不会真实扣费。
    
*   IAP扣费成功后的收据信息[PurchaseOrderPayload](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-data-model#purchaseorderpayload)中，会携带值为"SANDBOX"的environment字段，标识此次购买为沙盒测试的记录。
    
*   自动续期处理不需要完成真实扣款，IAP会直接返回成功。
    
*   在沙盒测试环境下，用户发起订阅首期会自动续期五次（累计共六期），后续需用户手动操作以恢复订阅。若同时涉及[促销场景](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/iap-subscription-functions#提供优惠)，系统将优先完成优惠周期内的自动续期，再继续进行六次续期，此场景下总续期次数为优惠周期数与六次续期之和。
    
*   沙盒测试拉起收银台时，会在收银台展示沙盒测试提示语，支付结果页也有沙盒环境的提示语，如下图所示。
    

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/69/v3/DOqBUAO8Q4OFKlO2-vSvSA/zh-cn_image_0000002625108745.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=34510BF823207BB7A70EB3A83EE321A410907C1D9E846BDDC6E73D1A14E7C9B5) ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1b/v3/xY7PBFBwQB6AJo3T7lztpg/zh-cn_image_0000002594669228.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=39F3CD84B5EBE741FA7815291D1EB3E2C3649FAAC1C9576E0AFF6A175DC14190)

#### 测试非续期订阅商品购买

在满足沙盒测试条件下，开发者调用[createPurchase](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-iap#iapcreatepurchase)接口拉起收银台，用户按照正常流程完成购买，但实际不会产生真实扣费。

*   沙盒环境下的购买流程与正式环境的购买流程一致，仍需要完成绑定付款方式，但该过程不会真实扣费。
    
*   IAP购买成功后的收据信息[PurchaseOrderPayload](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-data-model#purchaseorderpayload)中，会携带值为"SANDBOX"的environment字段，标识此次购买为沙盒测试的记录。
    
*   沙盒测试拉起收银台时，会在收银台展示沙盒测试提示，结果页也有沙盒环境的标志，如下图所示。
    

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0b/v3/lDN8lJ-XR82H_x7k_u5o0w/zh-cn_image_0000002594829156.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=F1742BB939B173BFC2A8AC307BD0EC7D1A847C5F35C074FBA05A52A58ECA0DDD) ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/21/v3/ALTIMQnRRgmIgTiNN0I_Ig/zh-cn_image_0000002625188603.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=56B1265755B2F3327438FBBDC22E45C29772B084C652C4638F9D6F9ED3457684)

#### 测试退款请求

开发者可以使用沙盒账号，针对在沙盒环境下购买商品产生的订单交易提交退款申请。该退款申请默认跳过退款审核和款项原路退回流程（沙盒环境下不真实扣费），IAP服务器会在沙盒环境中默认自动同意退款申请，同时给开发者服务器发送退款成功事件通知，以便开发者在收到退款事件通知后，测试应用内权益回收等场景。

具体操作步骤如下：

1.  在应用沙盒测试环境使用沙盒账号购买商品后，在测试设备上“手机设置 > 华为账号 > 付款与账单 > 购买记录”中会自动生成沙盒订单。
    
2.  点击待测试退款请求的沙盒订单，跳转至详情页面，点击“对订单有疑问”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e6/v3/HUkDQchGRl66Sl48ji0KCA/zh-cn_image_0000002625108747.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=184154D1A5B5D269DD2F06F06ECFB9E2E3763FE50F08C0EEE091F96641443C31)
    
3.  在“对订单有疑问”页面，点击“申请退款”，选择任意的退款原因和填写任意必填资料后，提交退款申请。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/83/v3/Vj2DcCxcTsOWmmq_Xu9S1w/zh-cn_image_0000002594669230.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=A231D2455E43995F4546779DF7010CAB967DF69050CA0C16E9ACE827E676E532)![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/79/v3/29a0n6OpTuWvkMqe3EvvEw/zh-cn_image_0000002594829158.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=C7162459C70BF5F447CA3FA0580BD04714ABEB9768E4CCE4E62815EFDAA11258)
    
4.  退款申请提交后，IAP服务器默认跳过退款审核和款项原路退回流程，自动同意该笔退款申请，同时给开发者服务器发送退款成功事件通知（NotificationSubtype：REFUND\_TRANSACTION）。如果开发者配置了沙盒环境服务器地址，则该笔通知发送至沙盒环境服务器，详情请参考“[事件通知配置](https://developer.huawei.com/consumer/cn/doc/app/parameters-0000001931995692)”。
    
5.  开发者收到退款成功事件通知后，在测试环境中模拟应用内对该沙盒账号进行权益回收等操作，以实现测试目的。
    

#### 清除沙盒账号的购买历史记录

开发者可以清除沙盒账号的购买历史记录，以便继续使用同一个沙盒账号进行测试。清除购买历史记录后，该测试账号在沙盒环境中产生的所有商品购买记录（包括自动续期订阅和消耗型/非消耗型商品）都将被删除，删除后该账号即可在沙盒环境中重新购买自动续期订阅商品、消耗型/非消耗型商品。清除购买历史记录后无法撤销操作。此操作不会影响生产环境数据。

清除沙盒账号购买历史记录的操作步骤如下：

1.  登录[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)网站，选择“用户与访问”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/65/v3/Q0A54YcaSIOZFMovqCmZ0Q/zh-cn_image_0000002625188605.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=41F6ECD0CA9745218627D29DF2B130332940E956FE67A2647BBE1DFD64BE5291)
    
2.  左侧导航栏选择“沙盒测试 > 测试账号”，勾选对应的测试账号，点击右上角的“清除购买历史记录”按钮。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6f/v3/bE4dY9MHSc2PjXVeHkB0Rw/zh-cn_image_0000002625108749.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=C066D42A72DD47B54170CF6CCA3C9306459B775D90033426460007CB78DD223A)
    
3.  在出现的提示弹窗中，点击“确认”按钮，随后该账号在沙盒环境中产生的购买历史记录将被清除，此操作无法被撤销。如果该沙盒账号的购买次数较多，则清除其购买历史记录可能需要更长时间。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2a/v3/ZkMLk_jDQ6W_NQvKhIoFHw/zh-cn_image_0000002594669232.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=6837655A5163646ABF6D7B546B5CC00BA76363B68E70810C8815B5FBC0A508A3)
    

#### 测试商品购买失败场景

在满足沙盒测试条件下，开发者调用[createPurchase](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-iap#iapcreatepurchase)接口拉起收银台。如果当前应用的“中断此测试账号的购买流程”配置项已配置，则用户将会在订单确认购买后被拦截。开发者可以测试该场景下应用的错误处理流程。具体模拟购买失败操作步骤如下：

1.  开发者在[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)上配置“[中断此测试账号的购买流程](https://developer.huawei.com/consumer/cn/doc/app/agc-help-testaccount-0000001146438651#section9546175114555)”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0e/v3/ADWP3ZNIT0mu12wLP7yI2Q/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=105DA1320ABD3ABB9E1F9CC1AA556BBCB5244CEB90CCEA1A31F61E140C6FE73E)
    
    当开发者在AppGallery Connect中更改了“中断此测试账号的购买流程”配置，需要等待3~5分钟后可尝试进行商品购买以触发数据刷新。
    
2.  用户选择购买消耗型/非消耗型/非续期订阅型/自动续期订阅型商品，按照正常流程进行拉起收银台下单。
    
3.  当用户确认购买后将会收到“服务暂不可用，请稍后重试”的错误提示，而开发者应用将会收到“[1001860056 用户交易被拒绝](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-iap#section1001860056-用户交易被拒绝)”的错误。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a0/v3/0NhlRABZRZS07712sQp1oA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=34EE61A8290BBA1AC1D7A77696F624DF063C272F4BD99AEBD7E03EB52E429BE0)
    
    若购买结果与预期不一致，可尝试等待1分钟后继续购买。
    

#### 测试自动续期订阅型商品续期失败场景

在满足沙盒测试条件下，当沙盒用户已购买自动续期订阅型商品，则开发者可以在App Gallery Connect中配置“中断此测试账号的购买流程”，模拟沙盒用户续期失败的场景。当沙盒用户持续地续期失败后订阅将会过期，IAP服务器将会向开发者服务器发送用户订阅过期的通知，开发者在收到订阅过期事件通知后，可测试应用内权益回收等场景。

具体操作步骤如下：

1.  沙盒用户按照正常流程购买自动续期订阅型商品。
    
2.  开发者在[AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)上配置“[中断此测试账号的购买流程](https://developer.huawei.com/consumer/cn/doc/app/agc-help-testaccount-0000001146438651#section9546175114555)”。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/82/v3/CsnZsnCIRYOEg3RUdrIZMg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073619Z&HW-CC-Expire=86400&HW-CC-Sign=57FA0396D1DF2A770DE4E6B7D973269A2FE1302C2C46A0D8E4D47EB9858ACCB3)
    
    当开发者在AppGallery Connect中更改了“中断此测试账号的购买流程”配置，需要等待3~5分钟后可尝试进行商品购买以触发数据刷新。
    
3.  在测试设备上“系统设置-->华为账号->付款与账单->订阅->订阅详情”，预期会出现用户订阅续期异常的提示。