简介在开放银行与PSD2合规背景下第三方支付服务商TPP对接银行XS2A接口常面临真实沙箱申请周期长、限流严格、测试数据不可重置等痛点。动态沙箱作为一种本地化的接口模拟方案通过可控的假数据完整模拟银行侧ASPSP的支付发起、账户查询、交易明细等核心流程帮助开发者快速验证联调逻辑。基于Spring Boot实现的Java沙箱将认证、支付、账户、证书等模块封装为RESTful服务并利用H2内存数据库实现数据隔离与重置结合OAuth2授权、支付状态机、SCA强客户认证等关键机制还原NextGenPSD2规范下的真实交互链路。无论是TPP开发者、银行测试工程师还是规范学习者都能借助这套动态沙箱在本地高效验证支付流程、排查接口问题并平滑过渡到真实网关。本文详细拆解该沙箱的架构、启动步骤、证书配置、常见坑位及生产切换要点是一份可落地的工程实践参考。1. XS2A动态沙箱把 PSD2 联调从“求人”变成“本地跑”先说你最关心的问题你需要一个能反复蹂躏、随时重启、不担心把银行测试环境搞挂的 XS2A 接口模拟端这个 Java 实现的动态沙箱就是干这个的。它模拟的是 PSD2 里银行侧ASPSP的 XS2A 接口行为用一套可控的假数据把支付发起、账户信息查询、交易明细这些核心流程完整跑起来。适合三类人正在做 TPP第三方支付服务商对接的开发者、银行内部做联调前置验证的测试工程师、以及想搞懂 NextGenPSD2 规范但不想直接读几百页文档的学习者。它解决的最大痛点是真实银行沙箱往往要排队申请、限流、而且测试数据不能重置而这套本地沙箱完全由你控制坏了就重来。2. 沙箱的骨架一个 Java 后端如何模拟银行侧 XS2A 行为拿到这份资源后第一件事不是急着启动而是先理解它的代码组织方式。这样后面改参数、加接口、排查问题才能精准下手。它本质上是一个 Spring Boot 应用把 ASPSP 对外的 XS2A 接口全部收拢到一套 RESTful 服务里再通过内存数据库或可配置的文件存储来模拟银行的核心账务系统。2.1 模块划分认证、支付、账户、证书各管一摊常见的做法是把沙箱拆成四个核心服务模块认证授权模块负责处理 OAuth2 token 的签发与校验支付服务模块负责接收支付发起请求、校验支付参数、维护支付状态机账户信息服务模块处理账户列表、余额、交易明细的查询证书管理模块则专门处理 TLS 双向认证和 eIDAS 证书的验签。我的建议是先花二十分钟把源码包里的 controller 层扫一遍。你不需要看懂每个类的内部实现只要搞清每个 URL 对应哪个模块就足够。比如/v1/payments开头的基本是支付相关/v1/accounts开头的基本是账户信息相关/v1/oauth开头的是授权相关。这样当你用 Postman 打请求时能立刻定位到出问题的代码位置。顺便提一句这个沙箱并没有把 Berlin Group 规范的全部接口都实现它覆盖的是最常见的支付发起、账户信息查询、交易列表和余额查询这几个高频路径。那些需要银行核心系统深度参与的接口比如批量转账、周期性支付、资金确认大多是返回一个固定的假数据结构。这个边界从代码注释里能看得出来用之前先确认自己要测的接口在不在覆盖范围内。2.2 数据流链路从 TPP 请求到银行核心的完整旅程沙箱设计的关键在于数据流是否贴近真实银行环境。一条典型的支付请求会经过四个阶段首先 TPP 向沙箱的 OAuth2 端点发起授权请求拿到 access token接着带着 token 向/v1/payments/payment-initiation发送支付指令沙箱校验 token、验签、检查支付参数后把支付状态置为RCVD最后 TPP 轮询支付状态沙箱基于内部状态机逐步推进到ACTC或RJCT。// PaymentStatusEnum.java 中核心状态流转逻辑节选 public enum PaymentStatusEnum { RCVD, // 已接收等待内部处理 ACTC, // 已受理资金尚未清算 ACSC, // 清算完成 RJCT, // 被拒绝 public boolean canTransitTo(PaymentStatusEnum target) { // 状态机只允许合法跳转RCVD - ACTC - ACSC 或 RCVD - RJCT switch (this) { case RCVD: return target ACTC || target RJCT; case ACTC: return target ACSC || target RJCT; case ACSC: return target ACSC; // 终态不可再变 default: return false; } } }这段代码的关键在于canTransitTo方法中的状态流转规则。你在真实银行对接时也会遇到类似的状态机设计但银行端往往会有额外的中间状态比如PDNG等待资金、ACWP已接受并处理中。沙箱做了一个简化只保留四个核心状态。参数说明RCVD是 TPP 发起请求后的第一个响应状态此时银行只是收到了请求还没开始处理ACTC表示银行已受理ACSC表示资金已经完成清算。我一般会建议把RJCT的触发条件在配置里调得宽松一些方便测试异常分支否则你每次想测拒绝场景都要去改支付参数太麻烦。2.3 存储与数据隔离内存库与重置策略沙箱另一值得关注的部分是数据存储策略。多数实现会采用 H2 内存数据库每次服务重启后数据清空这正好满足测试环境需要“数据纯净”的场景。但它也带来一个副作用你没法在沙箱里跨重启保持测试数据的一致性。如果你的测试用例需要先创建一个账户然后再基于这个账户做交易查询那么重启后这个账户就消失了。# application.yml 中 H2 数据库与沙箱初始化配置 spring: datasource: url: jdbc:h2:mem:sandbox;DB_CLOSE_DELAY-1 driver-class-name: org.h2.Driver username: sa password: h2: console: enabled: true path: /h2-console sandbox: # 每次启动时加载的预置测试账户和 Token seed-data: enabled: true location: classpath:/seed-data/accounts.json # 自动推进支付状态的时间窗口毫秒0 表示手动触发 payment-status-advance-ms: 8000payment-status-advance-ms这个参数值得单独说。真实银行推进支付状态是异步的时间不确定但沙箱为了让你能测试轮询逻辑会模拟一个延迟推送。设成 8000 毫秒意味着你发起支付后约 8 秒状态会从RCVD推进到ACTC再过 8 秒推进到ACSC。如果你想测试超时场景把这个值调大到 60000 甚至更大就能模拟银行长时间不响应的情形。这个参数在生产对接时没有对应物但它是沙箱里模拟异步行为的关键。3. 本地拉起沙箱30 分钟跑通第一条支付链路环境准备是你能否顺利跑通的第一步。这个沙箱对 JDK 版本和构建工具都有要求源码包里一般会有明确的说明文件我自己在多个环境里试过的组合是 JDK 11 配合 Maven 3.6 以上基本没有兼容性问题。3.1 构建与启动命令行三步走拿到源码包后先在项目根目录确认pom.xml里的依赖树。你会看到 Spring Boot 版本、BCBouncy Castle加密库、以及某个轻量级 HTTP 客户端库。BC 库是必须的因为没有它就无法生成和解析 eIDAS 格式的证书。# 第一步编译打包 mvn clean package -DskipTests # 第二步启动沙箱 java -jar target/xs2a-sandbox.jar \ --server.port8443 \ --spring.profiles.activesandbox \ --server.ssl.key-storeclasspath:keystore/psd2-sandbox.p12 \ --server.ssl.key-store-passwordsandbox123 \ --server.ssl.keyAliassandbox-key这几行命令符合多数 XS2A 资源包的构建方式。需要说明的是沙箱默认用 HTTPS 协议启动端口 8443这是为了模拟真实银行环境中的 TLS 加密要求。key-store指向沙箱自己的服务端证书这个证书是给 TPP 客户端做服务端身份校验用的。sandbox123这个密码如果你拿到的包里不是这个词以包内说明文件为准不要强行套用。如果你在 Windows 环境下跑命令基本一致只要确保 JDK 的 PATH 环境变量配好即可。启动后如果看到日志里出现类似Started ... on port 8443的信息就说明服务已经起来了。这时先用浏览器访问一下https://localhost:8443/actuator/health如果返回{status:UP}就表示健康检查通过。3.2 生成自签名证书并配置客户端信任链在真实 PSD2 场景中TPP 需要持有 eIDAS 证书包括 QWAC 用于 TLS 连接、QSEAL 用于请求签名但本地沙箱里没法申请真证书。常见做法是用 keytool 生成两套自签名证书一套给沙箱当服务端证书一套给 TPP 当客户端证书。# 生成服务端自签名证书沙箱的 HTTPS 证书 keytool -genkey -alias sandbox-key \ -keyalg RSA -keysize 2048 -validity 365 \ -dname CNlocalhost, OUSandbox, OTestASPSP, CDE \ -keystore psd2-sandbox.p12 -storetype PKCS12 \ -storepass sandbox123 # 生成客户端自签名证书模拟 TPP 的 QWAC keytool -genkey -alias tpp-client-key \ -keyalg RSA -keysize 2048 -validity 365 \ -dname CNtest-tpp-client, OUDev, OTestTPP, CDE \ -keystore tpp-client.p12 -storetype PKCS12 \ -storepass tpp12345这里生成的 CN 值要特别注意。服务端证书的 CN 必须是localhost因为 TPP 客户端发起 HTTPS 请求时校验的就是这个域名写成127.0.0.1或其它值都会导致证书域名校验失败。客户端证书的 CN 在真实环境里要被放进 ASPSP 的可信列表沙箱里这个字段只做日志展示用途不需要额外配置。如果你拿到的包里有自带的证书生成脚本直接执行脚本会更省事。生成完客户端证书后把tpp-client.p12导入到你用来发测试请求的 HTTP 工具中比如 Postman 的 Certificate 设置里或者 Java 客户端的KeyStore配置中。这一步是沙箱双端 TLS 握手能成功的前提。3.3 获取 OAuth2 Token 并确认授权流程拿到 Token 是调用任何 XS2A 接口的前置条件。沙箱里多半已经预置了一组 OAuth2 客户端账号通常写在seed-data相关的配置里。你用这组账号去请求 Token 端点拿到的钱 Token 再放到后续请求的Authorization: Bearer头里。curl -k -v https://localhost:8443/v1/oauth/token \ -H Content-Type: application/x-www-form-urlencoded \ --cert tpp-client.p12:tpp12345 \ -d grant_typeclient_credentialsclient_idtest-tpp-clientscopepayments这里-k参数是跳过服务端证书校验我在测试阶段一般会带上因为自签名证书本来就无法从公网证书链验证。client_id用的是test-tpp-client这是沙箱预置的测试客户端标识如果你拿到的包内配置不同检查seed-data下的 JSON 文件确认正确的客户端 ID。请求成功后会返回一个 JSON 报文里面包含access_token、token_type和expires_in三个核心字段。3.4 发起首笔支付报文结构与响应分析拿到 token 后你现在可以发起第一笔支付请求了。这里构造的 JSON 报文需要符合 NextGenPSD2 的支付报文规范沙箱只认格式正确的报文。{ instructedAmount: { currency: EUR, amount: 125.00 }, debtorAccount: { iban: DE89370400440532013000 }, creditorAccount: { iban: DE02370500990000527500 }, creditorName: Test Merchant GmbH, remittanceInformationUnstructured: Order #12345 }把这个 JSON 保存为payment-request.json然后用以下命令发起支付请求curl -k -v https://localhost:8443/v1/payments/payment-initiation \ -X POST \ -H Authorization: Bearer YOUR_ACCESS_TOKEN \ -H Content-Type: application/json \ -H PSU-IP-Address: 192.168.1.100 \ -H TPP-Redirect-URI: https://tpp.example.com/callback \ --cert tpp-client.p12:tpp12345 \ --data payment-request.json响应码 201 表示支付请求已被接收返回的报文里会有paymentId和transactionStatus: RCVD这个paymentId是你后面轮询状态的唯一标识。注意PSU-IP-Address头在真实环境是必填项它代表最终用户PSU的 IP银行用它做风险分析。沙箱里也会校验这个头如果缺了可能直接返回 400。响应报文里通常还会带一个_links对象里面有scaRedirect或self链接。这是 Berlin Group 规范规定的 HATEOAS 风格通过链接引导 TPP 完成后续交互。沙箱里这个链接指向的是模拟的 SCA 页面点击后会自动通过授权流程。4. 深挖对接细节从沙箱行为反推 NextGenPSD2 规范要求沙箱不仅是测试工具它还能当学习规范的第二教材。当你在沙箱上把一个完整流程跑通后反过来再去读规范文档就能明白很多原本看不懂的字段和约束是什么含义。4.1 SCA 与显式授权理解 PSD2 的强客户认证规则XS2A 接口最独特的点是 SCAStrong Customer Authentication强客户认证的处理。真实银行里支付指令提交后如果金额超过阈值银行会要求 PSU 完成额外的认证比如短信验证码、指纹、或银行 App 确认这个流程在接口层表现为scaStatus字段和_links.scaRedirect链接。沙箱里模拟 SCA 分为两步发起支付时返回SCA状态而不是直接ACTC同时返回一个重定向链接TPP 引导 PSU 访问这个链接完成认证后再带着授权码调用一次状态查询接口。# 轮询支付状态观察 SCA 变化 curl -k https://localhost:8443/v1/payments/payment-initiation/{paymentId} \ -H Authorization: Bearer YOUR_ACCESS_TOKEN \ -H PSU-IP-Address: 192.168.1.100 \ --cert tpp-client.p12:tpp12345你会看到scaStatus的变化轨迹从received到finalised然后transactionStatus才从RCVD推进到ACTC。这就是 PSD2 规范中 SCA 与支付状态解耦的设计。我建议把轮询间隔设置为 5 秒因为沙箱的 SCA 推进也需要时间太快会浪费请求资源。4.2 用沙箱跑通一套完整的 PIS 支付全流程把支付、轮询、SCA 合并成一个端到端流程看你可以在这个沙箱里验证完整的 PIS 生命周期。我习惯用 Python 脚本把它们串起来这样不用手动在 Postman 和 curl 之间来回切换。# pisd_flow.py - PIS 支付全流程演示脚本Python 3 requests 库 import requests import json import time BASE_URL https://localhost:8443 # 第 1 步获取 token token_resp requests.post( f{BASE_URL}/v1/oauth/token, data{grant_type: client_credentials, client_id: test-tpp-client, scope: payments}, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) token token_resp.json()[access_token] # 第 2 步发起支付 payment_req { instructedAmount: {currency: EUR, amount: 125.00}, debtorAccount: {iban: DE89370400440532013000}, creditorAccount: {iban: DE02370500990000527500}, creditorName: Test Merchant GmbH } payment_resp requests.post( f{BASE_URL}/v1/payments/payment-initiation, jsonpayment_req, headers{ Authorization: fBearer {token}, PSU-IP-Address: 192.168.1.100, Content-Type: application/json }, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) payment_id payment_resp.json()[paymentId] # 第 3 步模拟 PSU 完成 SCA沙箱有默认的虚拟授权接口 requests.post( f{BASE_URL}/v1/sandbox/sca/{payment_id}/approve, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) # 第 4 步轮询最终支付状态 for _ in range(10): status_resp requests.get( f{BASE_URL}/v1/payments/payment-initiation/{payment_id}, headers{Authorization: fBearer {token}, PSU-IP-Address: 192.168.1.100}, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) transaction_status status_resp.json()[transactionStatus] print(f当前状态: {transaction_status}) if transaction_status in (ACSC, RJCT): break time.sleep(3)这段脚本的价值在于它展示了 PIS 流程的四个核心环节。verifyFalse是为了跳过自签名证书校验在真实环境绝不能这么写。tpp-client.pem是刚在前面生成的客户端证书的 PEM 格式如果你的 keytool 步骤只生成了 p12需要先转换一下格式。轮询用了 10 次循环每次间隔 3 秒理论上最多等待 30 秒覆盖沙箱默认的 8 秒推进时间状态最终一定会推进到终态一个是成功清算一个是拒绝。4.3 AIS 账户信息接口数据模型与字段对照账户信息服务的逻辑比支付接口相对简单但它对数据准确性要求更高。你调用/v1/accounts获取账户列表、调用/v1/accounts/{accountId}/transactions获取交易明细沙箱会从预置的accounts.json文件中返回固定数据。{ accounts: [ { resourceId: acc-001, iban: DE89370400440532013000, currency: EUR, name: John Doe, product: Current Account, balances: [ { type: interimAvailable, amount: {currency: EUR, amount: 1250.00} } ] } ] }这个数据结构和 Berlin Group 规范里的AccountDetails响应模型几乎一一对应。需要注意balances是一个数组因为规范允许多种余额类型并存比如可用余额、账面余额、预期余额。沙箱只预置了interimAvailable一种但结构上没有做简化。如果你在真实联调中收到多个余额对象处理逻辑要考虑最匹配的余额类型不要硬编码取第一个。调用 AIS 接口需要一个额外的授权范围token 获取时 scope 要包含ais不能只用payments。另外 AIS 的 token 与 PIS 的 token 在沙箱里是分开的你拿做支付的 token 去查账户信息大概率会被拒。5. 避坑与排查证书、请求头、时间窗口和状态机沙箱跑得通不代表真实对接就顺利但沙箱本身也有自己的坑。下面把我实际遇到过的高频问题按现象、原因、解决整理出来你遇到同类问题时可以直接对号入座。5.1 双端 TLS 握手失败证书链不完整现象是 curl 报错unable to verify the first certificate或者 Java 客户端报sun.security.validator.ValidatorException。原因是沙箱的 HTTPS 端口要求双向 TLS也就是服务端要验证客户端证书客户端也要验证服务端证书。如果你只传了--cert但没带--cacert指定服务端证书的公钥客户端就没法验证服务端身份。另外客户端证书放在 p12 里时密钥库密码不要报错否则 TLS 层就挂。解决方法是把服务端证书导出一份 PEM 文件然后在 curl 的--cacert参数指明它。反之亦然如果你的 HTTP 工具只配置了服务端信任书忘了客户端证书同样握手失败。从那次之后我养成的习惯是所有 curl 命令强制带三个证书相关参数--cert、--key、--cacert少一个都不发请求。5.2 409 冲突重复发起同一笔支付现象是支付接口返回 409 Conflict响应体提示payment with same paymentId already exists。原因是沙箱对同一笔支付的去重逻辑比较严格它用paymentId作为唯一索引。如果你在脚本循环里重复提交相同内容第二次就会撞上这个冲突。解决方法有两种一是手动在请求体里加入一个唯一性的业务字段比如endToEndIdentification不同值会产生不同的paymentId二是发起前先查一下已有支付避免重复创建。沙箱这么做其实是在模拟真实银行的行为——真实银行为了防止重复扣款会有同样的幂等控制逻辑只是错误码可能换成 400 或 403。5.3 401 但 token 没过期请求头签名问题现象是 token 明明刚获取但访问 XS2A 接口一直 401 Unauthorized。原因是 XS2A 规范还强制要求 TPP 每个请求都带请求签名证书QSEAL签名值放在Digest和Signature头里。沙箱如果开启了签名校验缺少这两个头就会直接拒绝。解决方法是在发请求前用 QSEAL 私钥对请求体做 SHA-256 摘要然后拼装Signature头。如果你只是想快速测流程可以在沙箱配置里关掉签名校验开关但如果你在练真实对接的签名逻辑就保持开启。我一般会先关掉把流程跑通再打开做签名验证避免两个坑同时出现时难排查。5.4 状态卡在 RCVD 不动时间推进开关没打开现象是支付发起后transactionStatus一直停在RCVD轮询半小时也没有变成ACTC。原因是配置文件里的payment-status-advance-ms被设为 0 或负值状态推进逻辑被禁用了。解决方法是把它改回 8000 这样的正数值然后重启沙箱。另外还有一种可能你改了配置文件后没有重启服务Spring Boot 的Scheduled任务不会热加载配置。踩过这个坑之后我都会确认三件事配置值是否为正值、服务是否重启、日志里有没有Payment status advancing的关键字。5.5 响应时间异常沙箱“太快”导致轮询逻辑测不准现象是支付请求返回几乎瞬间transactionStatus已经是ACSC。原因是某些版本沙箱把状态推进做成了同步执行发起请求时直接跑完整个状态机。解决方法是去配置里检查推进参数把它调大。真实银行从发起到清算通常以秒级甚至分钟级计算不建议你按着沙箱的即时响应去设计 TPP 端的轮询超时策略。沙箱不是越慢越好但要把合理的时间差留出来才能模拟真实节奏。6. 进阶把沙箱验证过的代码切换到真实网关的三个关键动作当你在沙箱上把所有流程跑通、信心满满准备切到真实网关时有三个动作能帮你减少“本地好好的、一上线就挂”的尴尬。第一个动作是证书替换。沙箱里用的是自签名证书但真实网关需要 eIDAS 证书。你需要在代码里预留一套证书加载接口把证书路径和密码做成配置项而不是写死在代码里。切换时只改配置不改逻辑。// CertificateProvider.java - 证书加载的抽象接口 public interface CertificateProvider { KeyStore getClientKeyStore(); KeyStore getTrustKeyStore(); }沙箱环境里这个接口的实现类读取的是tpp-client.p12生产环境实现类读取的是硬件加密模块里的真实证书这样整个代码库不用做结构改动只替换实现类即可。这个接口在你接手维护的任何对接模块里都应该存在如果没有我建议业务开始前就补上不然后面替换证书的成本会非常高。第二个动作是 URL 重写。沙箱的 base URL 是https://localhost:8443真实网关的 base URL 是银行提供的固定域名。所有请求 URL 都应该通过配置文件维护写代码时严禁硬编码。我自己吃过一次亏在支付状态回调的配置文件里写了测试地址上线后回调全部打到沙箱里找了一下午才发现是少了环境切换逻辑。从那次开始我在所有对接模块中强制约定一个环境变量来控制 base URL上线只改环境变量不碰业务代码。第三个动作是接口兼容面的回归验证。切真实网关前把沙箱里已经跑通的测试用例再跑一遍重点看请求头完整度和响应字段兼容性。你可以顺手写一个断言脚本把关键字段transactionStatus、scaStatus、paymentId的取值跑出来做一个沙箱与真实网关的差异对比表这样哪些字段真实环境填的是空值、哪些字段需要额外处理一目了然。最后说一个我的习惯每次切环境的当天我都把沙箱和真实网关的所有响应日志存一份原始 JSON 按日期命名归档——这批记录既是排查依据也是后来同事接手时的救命稻草。建议你在自己的项目里也顺手留一步希望帮到你。本文还有配套的精品资源点击获取 简介在开放银行与PSD2合规背景下第三方支付服务商TPP对接银行XS2A接口常面临真实沙箱申请周期长、限流严格、测试数据不可重置等痛点。动态沙箱作为一种本地化的接口模拟方案通过可控的假数据完整模拟银行侧ASPSP的支付发起、账户查询、交易明细等核心流程帮助开发者快速验证联调逻辑。基于Spring Boot实现的Java沙箱将认证、支付、账户、证书等模块封装为RESTful服务并利用H2内存数据库实现数据隔离与重置结合OAuth2授权、支付状态机、SCA强客户认证等关键机制还原NextGenPSD2规范下的真实交互链路。无论是TPP开发者、银行测试工程师还是规范学习者都能借助这套动态沙箱在本地高效验证支付流程、排查接口问题并平滑过渡到真实网关。本文详细拆解该沙箱的架构、启动步骤、证书配置、常见坑位及生产切换要点是一份可落地的工程实践参考。1. XS2A动态沙箱把 PSD2 联调从“求人”变成“本地跑”先说你最关心的问题你需要一个能反复蹂躏、随时重启、不担心把银行测试环境搞挂的 XS2A 接口模拟端这个 Java 实现的动态沙箱就是干这个的。它模拟的是 PSD2 里银行侧ASPSP的 XS2A 接口行为用一套可控的假数据把支付发起、账户信息查询、交易明细这些核心流程完整跑起来。适合三类人正在做 TPP第三方支付服务商对接的开发者、银行内部做联调前置验证的测试工程师、以及想搞懂 NextGenPSD2 规范但不想直接读几百页文档的学习者。它解决的最大痛点是真实银行沙箱往往要排队申请、限流、而且测试数据不能重置而这套本地沙箱完全由你控制坏了就重来。2. 沙箱的骨架一个 Java 后端如何模拟银行侧 XS2A 行为拿到这份资源后第一件事不是急着启动而是先理解它的代码组织方式。这样后面改参数、加接口、排查问题才能精准下手。它本质上是一个 Spring Boot 应用把 ASPSP 对外的 XS2A 接口全部收拢到一套 RESTful 服务里再通过内存数据库或可配置的文件存储来模拟银行的核心账务系统。2.1 模块划分认证、支付、账户、证书各管一摊常见的做法是把沙箱拆成四个核心服务模块认证授权模块负责处理 OAuth2 token 的签发与校验支付服务模块负责接收支付发起请求、校验支付参数、维护支付状态机账户信息服务模块处理账户列表、余额、交易明细的查询证书管理模块则专门处理 TLS 双向认证和 eIDAS 证书的验签。我的建议是先花二十分钟把源码包里的 controller 层扫一遍。你不需要看懂每个类的内部实现只要搞清每个 URL 对应哪个模块就足够。比如/v1/payments开头的基本是支付相关/v1/accounts开头的基本是账户信息相关/v1/oauth开头的是授权相关。这样当你用 Postman 打请求时能立刻定位到出问题的代码位置。顺便提一句这个沙箱并没有把 Berlin Group 规范的全部接口都实现它覆盖的是最常见的支付发起、账户信息查询、交易列表和余额查询这几个高频路径。那些需要银行核心系统深度参与的接口比如批量转账、周期性支付、资金确认大多是返回一个固定的假数据结构。这个边界从代码注释里能看得出来用之前先确认自己要测的接口在不在覆盖范围内。2.2 数据流链路从 TPP 请求到银行核心的完整旅程沙箱设计的关键在于数据流是否贴近真实银行环境。一条典型的支付请求会经过四个阶段首先 TPP 向沙箱的 OAuth2 端点发起授权请求拿到 access token接着带着 token 向/v1/payments/payment-initiation发送支付指令沙箱校验 token、验签、检查支付参数后把支付状态置为RCVD最后 TPP 轮询支付状态沙箱基于内部状态机逐步推进到ACTC或RJCT。// PaymentStatusEnum.java 中核心状态流转逻辑节选 public enum PaymentStatusEnum { RCVD, // 已接收等待内部处理 ACTC, // 已受理资金尚未清算 ACSC, // 清算完成 RJCT, // 被拒绝 public boolean canTransitTo(PaymentStatusEnum target) { // 状态机只允许合法跳转RCVD - ACTC - ACSC 或 RCVD - RJCT switch (this) { case RCVD: return target ACTC || target RJCT; case ACTC: return target ACSC || target RJCT; case ACSC: return target ACSC; // 终态不可再变 default: return false; } } }这段代码的关键在于canTransitTo方法中的状态流转规则。你在真实银行对接时也会遇到类似的状态机设计但银行端往往会有额外的中间状态比如PDNG等待资金、ACWP已接受并处理中。沙箱做了一个简化只保留四个核心状态。参数说明RCVD是 TPP 发起请求后的第一个响应状态此时银行只是收到了请求还没开始处理ACTC表示银行已受理ACSC表示资金已经完成清算。我一般会建议把RJCT的触发条件在配置里调得宽松一些方便测试异常分支否则你每次想测拒绝场景都要去改支付参数太麻烦。2.3 存储与数据隔离内存库与重置策略沙箱另一值得关注的部分是数据存储策略。多数实现会采用 H2 内存数据库每次服务重启后数据清空这正好满足测试环境需要“数据纯净”的场景。但它也带来一个副作用你没法在沙箱里跨重启保持测试数据的一致性。如果你的测试用例需要先创建一个账户然后再基于这个账户做交易查询那么重启后这个账户就消失了。# application.yml 中 H2 数据库与沙箱初始化配置 spring: datasource: url: jdbc:h2:mem:sandbox;DB_CLOSE_DELAY-1 driver-class-name: org.h2.Driver username: sa password: h2: console: enabled: true path: /h2-console sandbox: # 每次启动时加载的预置测试账户和 Token seed-data: enabled: true location: classpath:/seed-data/accounts.json # 自动推进支付状态的时间窗口毫秒0 表示手动触发 payment-status-advance-ms: 8000payment-status-advance-ms这个参数值得单独说。真实银行推进支付状态是异步的时间不确定但沙箱为了让你能测试轮询逻辑会模拟一个延迟推送。设成 8000 毫秒意味着你发起支付后约 8 秒状态会从RCVD推进到ACTC再过 8 秒推进到ACSC。如果你想测试超时场景把这个值调大到 60000 甚至更大就能模拟银行长时间不响应的情形。这个参数在生产对接时没有对应物但它是沙箱里模拟异步行为的关键。3. 本地拉起沙箱30 分钟跑通第一条支付链路环境准备是你能否顺利跑通的第一步。这个沙箱对 JDK 版本和构建工具都有要求源码包里一般会有明确的说明文件我自己在多个环境里试过的组合是 JDK 11 配合 Maven 3.6 以上基本没有兼容性问题。3.1 构建与启动命令行三步走拿到源码包后先在项目根目录确认pom.xml里的依赖树。你会看到 Spring Boot 版本、BCBouncy Castle加密库、以及某个轻量级 HTTP 客户端库。BC 库是必须的因为没有它就无法生成和解析 eIDAS 格式的证书。# 第一步编译打包 mvn clean package -DskipTests # 第二步启动沙箱 java -jar target/xs2a-sandbox.jar \ --server.port8443 \ --spring.profiles.activesandbox \ --server.ssl.key-storeclasspath:keystore/psd2-sandbox.p12 \ --server.ssl.key-store-passwordsandbox123 \ --server.ssl.keyAliassandbox-key这几行命令符合多数 XS2A 资源包的构建方式。需要说明的是沙箱默认用 HTTPS 协议启动端口 8443这是为了模拟真实银行环境中的 TLS 加密要求。key-store指向沙箱自己的服务端证书这个证书是给 TPP 客户端做服务端身份校验用的。sandbox123这个密码如果你拿到的包里不是这个词以包内说明文件为准不要强行套用。如果你在 Windows 环境下跑命令基本一致只要确保 JDK 的 PATH 环境变量配好即可。启动后如果看到日志里出现类似Started ... on port 8443的信息就说明服务已经起来了。这时先用浏览器访问一下https://localhost:8443/actuator/health如果返回{status:UP}就表示健康检查通过。3.2 生成自签名证书并配置客户端信任链在真实 PSD2 场景中TPP 需要持有 eIDAS 证书包括 QWAC 用于 TLS 连接、QSEAL 用于请求签名但本地沙箱里没法申请真证书。常见做法是用 keytool 生成两套自签名证书一套给沙箱当服务端证书一套给 TPP 当客户端证书。# 生成服务端自签名证书沙箱的 HTTPS 证书 keytool -genkey -alias sandbox-key \ -keyalg RSA -keysize 2048 -validity 365 \ -dname CNlocalhost, OUSandbox, OTestASPSP, CDE \ -keystore psd2-sandbox.p12 -storetype PKCS12 \ -storepass sandbox123 # 生成客户端自签名证书模拟 TPP 的 QWAC keytool -genkey -alias tpp-client-key \ -keyalg RSA -keysize 2048 -validity 365 \ -dname CNtest-tpp-client, OUDev, OTestTPP, CDE \ -keystore tpp-client.p12 -storetype PKCS12 \ -storepass tpp12345这里生成的 CN 值要特别注意。服务端证书的 CN 必须是localhost因为 TPP 客户端发起 HTTPS 请求时校验的就是这个域名写成127.0.0.1或其它值都会导致证书域名校验失败。客户端证书的 CN 在真实环境里要被放进 ASPSP 的可信列表沙箱里这个字段只做日志展示用途不需要额外配置。如果你拿到的包里有自带的证书生成脚本直接执行脚本会更省事。生成完客户端证书后把tpp-client.p12导入到你用来发测试请求的 HTTP 工具中比如 Postman 的 Certificate 设置里或者 Java 客户端的KeyStore配置中。这一步是沙箱双端 TLS 握手能成功的前提。3.3 获取 OAuth2 Token 并确认授权流程拿到 Token 是调用任何 XS2A 接口的前置条件。沙箱里多半已经预置了一组 OAuth2 客户端账号通常写在seed-data相关的配置里。你用这组账号去请求 Token 端点拿到的钱 Token 再放到后续请求的Authorization: Bearer头里。curl -k -v https://localhost:8443/v1/oauth/token \ -H Content-Type: application/x-www-form-urlencoded \ --cert tpp-client.p12:tpp12345 \ -d grant_typeclient_credentialsclient_idtest-tpp-clientscopepayments这里-k参数是跳过服务端证书校验我在测试阶段一般会带上因为自签名证书本来就无法从公网证书链验证。client_id用的是test-tpp-client这是沙箱预置的测试客户端标识如果你拿到的包内配置不同检查seed-data下的 JSON 文件确认正确的客户端 ID。请求成功后会返回一个 JSON 报文里面包含access_token、token_type和expires_in三个核心字段。3.4 发起首笔支付报文结构与响应分析拿到 token 后你现在可以发起第一笔支付请求了。这里构造的 JSON 报文需要符合 NextGenPSD2 的支付报文规范沙箱只认格式正确的报文。{ instructedAmount: { currency: EUR, amount: 125.00 }, debtorAccount: { iban: DE89370400440532013000 }, creditorAccount: { iban: DE02370500990000527500 }, creditorName: Test Merchant GmbH, remittanceInformationUnstructured: Order #12345 }把这个 JSON 保存为payment-request.json然后用以下命令发起支付请求curl -k -v https://localhost:8443/v1/payments/payment-initiation \ -X POST \ -H Authorization: Bearer YOUR_ACCESS_TOKEN \ -H Content-Type: application/json \ -H PSU-IP-Address: 192.168.1.100 \ -H TPP-Redirect-URI: https://tpp.example.com/callback \ --cert tpp-client.p12:tpp12345 \ --data payment-request.json响应码 201 表示支付请求已被接收返回的报文里会有paymentId和transactionStatus: RCVD这个paymentId是你后面轮询状态的唯一标识。注意PSU-IP-Address头在真实环境是必填项它代表最终用户PSU的 IP银行用它做风险分析。沙箱里也会校验这个头如果缺了可能直接返回 400。响应报文里通常还会带一个_links对象里面有scaRedirect或self链接。这是 Berlin Group 规范规定的 HATEOAS 风格通过链接引导 TPP 完成后续交互。沙箱里这个链接指向的是模拟的 SCA 页面点击后会自动通过授权流程。4. 深挖对接细节从沙箱行为反推 NextGenPSD2 规范要求沙箱不仅是测试工具它还能当学习规范的第二教材。当你在沙箱上把一个完整流程跑通后反过来再去读规范文档就能明白很多原本看不懂的字段和约束是什么含义。4.1 SCA 与显式授权理解 PSD2 的强客户认证规则XS2A 接口最独特的点是 SCAStrong Customer Authentication强客户认证的处理。真实银行里支付指令提交后如果金额超过阈值银行会要求 PSU 完成额外的认证比如短信验证码、指纹、或银行 App 确认这个流程在接口层表现为scaStatus字段和_links.scaRedirect链接。沙箱里模拟 SCA 分为两步发起支付时返回SCA状态而不是直接ACTC同时返回一个重定向链接TPP 引导 PSU 访问这个链接完成认证后再带着授权码调用一次状态查询接口。# 轮询支付状态观察 SCA 变化 curl -k https://localhost:8443/v1/payments/payment-initiation/{paymentId} \ -H Authorization: Bearer YOUR_ACCESS_TOKEN \ -H PSU-IP-Address: 192.168.1.100 \ --cert tpp-client.p12:tpp12345你会看到scaStatus的变化轨迹从received到finalised然后transactionStatus才从RCVD推进到ACTC。这就是 PSD2 规范中 SCA 与支付状态解耦的设计。我建议把轮询间隔设置为 5 秒因为沙箱的 SCA 推进也需要时间太快会浪费请求资源。4.2 用沙箱跑通一套完整的 PIS 支付全流程把支付、轮询、SCA 合并成一个端到端流程看你可以在这个沙箱里验证完整的 PIS 生命周期。我习惯用 Python 脚本把它们串起来这样不用手动在 Postman 和 curl 之间来回切换。# pisd_flow.py - PIS 支付全流程演示脚本Python 3 requests 库 import requests import json import time BASE_URL https://localhost:8443 # 第 1 步获取 token token_resp requests.post( f{BASE_URL}/v1/oauth/token, data{grant_type: client_credentials, client_id: test-tpp-client, scope: payments}, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) token token_resp.json()[access_token] # 第 2 步发起支付 payment_req { instructedAmount: {currency: EUR, amount: 125.00}, debtorAccount: {iban: DE89370400440532013000}, creditorAccount: {iban: DE02370500990000527500}, creditorName: Test Merchant GmbH } payment_resp requests.post( f{BASE_URL}/v1/payments/payment-initiation, jsonpayment_req, headers{ Authorization: fBearer {token}, PSU-IP-Address: 192.168.1.100, Content-Type: application/json }, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) payment_id payment_resp.json()[paymentId] # 第 3 步模拟 PSU 完成 SCA沙箱有默认的虚拟授权接口 requests.post( f{BASE_URL}/v1/sandbox/sca/{payment_id}/approve, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) # 第 4 步轮询最终支付状态 for _ in range(10): status_resp requests.get( f{BASE_URL}/v1/payments/payment-initiation/{payment_id}, headers{Authorization: fBearer {token}, PSU-IP-Address: 192.168.1.100}, verifyFalse, cert(tpp-client.pem, tpp-client-key.pem) ) transaction_status status_resp.json()[transactionStatus] print(f当前状态: {transaction_status}) if transaction_status in (ACSC, RJCT): break time.sleep(3)这段脚本的价值在于它展示了 PIS 流程的四个核心环节。verifyFalse是为了跳过自签名证书校验在真实环境绝不能这么写。tpp-client.pem是刚在前面生成的客户端证书的 PEM 格式如果你的 keytool 步骤只生成了 p12需要先转换一下格式。轮询用了 10 次循环每次间隔 3 秒理论上最多等待 30 秒覆盖沙箱默认的 8 秒推进时间状态最终一定会推进到终态一个是成功清算一个是拒绝。4.3 AIS 账户信息接口数据模型与字段对照账户信息服务的逻辑比支付接口相对简单但它对数据准确性要求更高。你调用/v1/accounts获取账户列表、调用/v1/accounts/{accountId}/transactions获取交易明细沙箱会从预置的accounts.json文件中返回固定数据。{ accounts: [ { resourceId: acc-001, iban: DE89370400440532013000, currency: EUR, name: John Doe, product: Current Account, balances: [ { type: interimAvailable, amount: {currency: EUR, amount: 1250.00} } ] } ] }这个数据结构和 Berlin Group 规范里的AccountDetails响应模型几乎一一对应。需要注意balances是一个数组因为规范允许多种余额类型并存比如可用余额、账面余额、预期余额。沙箱只预置了interimAvailable一种但结构上没有做简化。如果你在真实联调中收到多个余额对象处理逻辑要考虑最匹配的余额类型不要硬编码取第一个。调用 AIS 接口需要一个额外的授权范围token 获取时 scope 要包含ais不能只用payments。另外 AIS 的 token 与 PIS 的 token 在沙箱里是分开的你拿做支付的 token 去查账户信息大概率会被拒。5. 避坑与排查证书、请求头、时间窗口和状态机沙箱跑得通不代表真实对接就顺利但沙箱本身也有自己的坑。下面把我实际遇到过的高频问题按现象、原因、解决整理出来你遇到同类问题时可以直接对号入座。5.1 双端 TLS 握手失败证书链不完整现象是 curl 报错unable to verify the first certificate或者 Java 客户端报sun.security.validator.ValidatorException。原因是沙箱的 HTTPS 端口要求双向 TLS也就是服务端要验证客户端证书客户端也要验证服务端证书。如果你只传了--cert但没带--cacert指定服务端证书的公钥客户端就没法验证服务端身份。另外客户端证书放在 p12 里时密钥库密码不要报错否则 TLS 层就挂。解决方法是把服务端证书导出一份 PEM 文件然后在 curl 的--cacert参数指明它。反之亦然如果你的 HTTP 工具只配置了服务端信任书忘了客户端证书同样握手失败。从那次之后我养成的习惯是所有 curl 命令强制带三个证书相关参数--cert、--key、--cacert少一个都不发请求。5.2 409 冲突重复发起同一笔支付现象是支付接口返回 409 Conflict响应体提示payment with same paymentId already exists。原因是沙箱对同一笔支付的去重逻辑比较严格它用paymentId作为唯一索引。如果你在脚本循环里重复提交相同内容第二次就会撞上这个冲突。解决方法有两种一是手动在请求体里加入一个唯一性的业务字段比如endToEndIdentification不同值会产生不同的paymentId二是发起前先查一下已有支付避免重复创建。沙箱这么做其实是在模拟真实银行的行为——真实银行为了防止重复扣款会有同样的幂等控制逻辑只是错误码可能换成 400 或 403。5.3 401 但 token 没过期请求头签名问题现象是 token 明明刚获取但访问 XS2A 接口一直 401 Unauthorized。原因是 XS2A 规范还强制要求 TPP 每个请求都带请求签名证书QSEAL签名值放在Digest和Signature头里。沙箱如果开启了签名校验缺少这两个头就会直接拒绝。解决方法是在发请求前用 QSEAL 私钥对请求体做 SHA-256 摘要然后拼装Signature头。如果你只是想快速测流程可以在沙箱配置里关掉签名校验开关但如果你在练真实对接的签名逻辑就保持开启。我一般会先关掉把流程跑通再打开做签名验证避免两个坑同时出现时难排查。5.4 状态卡在 RCVD 不动时间推进开关没打开现象是支付发起后transactionStatus一直停在RCVD轮询半小时也没有变成ACTC。原因是配置文件里的payment-status-advance-ms被设为 0 或负值状态推进逻辑被禁用了。解决方法是把它改回 8000 这样的正数值然后重启沙箱。另外还有一种可能你改了配置文件后没有重启服务Spring Boot 的Scheduled任务不会热加载配置。踩过这个坑之后我都会确认三件事配置值是否为正值、服务是否重启、日志里有没有Payment status advancing的关键字。5.5 响应时间异常沙箱“太快”导致轮询逻辑测不准现象是支付请求返回几乎瞬间transactionStatus已经是ACSC。原因是某些版本沙箱把状态推进做成了同步执行发起请求时直接跑完整个状态机。解决方法是去配置里检查推进参数把它调大。真实银行从发起到清算通常以秒级甚至分钟级计算不建议你按着沙箱的即时响应去设计 TPP 端的轮询超时策略。沙箱不是越慢越好但要把合理的时间差留出来才能模拟真实节奏。6. 进阶把沙箱验证过的代码切换到真实网关的三个关键动作当你在沙箱上把所有流程跑通、信心满满准备切到真实网关时有三个动作能帮你减少“本地好好的、一上线就挂”的尴尬。第一个动作是证书替换。沙箱里用的是自签名证书但真实网关需要 eIDAS 证书。你需要在代码里预留一套证书加载接口把证书路径和密码做成配置项而不是写死在代码里。切换时只改配置不改逻辑。// CertificateProvider.java - 证书加载的抽象接口 public interface CertificateProvider { KeyStore getClientKeyStore(); KeyStore getTrustKeyStore(); }沙箱环境里这个接口的实现类读取的是tpp-client.p12生产环境实现类读取的是硬件加密模块里的真实证书这样整个代码库不用做结构改动只替换实现类即可。这个接口在你接手维护的任何对接模块里都应该存在如果没有我建议业务开始前就补上不然后面替换证书的成本会非常高。第二个动作是 URL 重写。沙箱的 base URL 是https://localhost:8443真实网关的 base URL 是银行提供的固定域名。所有请求 URL 都应该通过配置文件维护写代码时严禁硬编码。我自己吃过一次亏在支付状态回调的配置文件里写了测试地址上线后回调全部打到沙箱里找了一下午才发现是少了环境切换逻辑。从那次开始我在所有对接模块中强制约定一个环境变量来控制 base URL上线只改环境变量不碰业务代码。第三个动作是接口兼容面的回归验证。切真实网关前把沙箱里已经跑通的测试用例再跑一遍重点看请求头完整度和响应字段兼容性。你可以顺手写一个断言脚本把关键字段transactionStatus、scaStatus、paymentId的取值跑出来做一个沙箱与真实网关的差异对比表这样哪些字段真实环境填的是空值、哪些字段需要额外处理一目了然。最后说一个我的习惯每次切环境的当天我都把沙箱和真实网关的所有响应日志存一份原始 JSON 按日期命名归档——这批记录既是排查依据也是后来同事接手时的救命稻草。建议你在自己的项目里也顺手留一步希望帮到你。本文还有配套的精品资源点击获取