沙箱

Liqfy 沙箱让你可以演练完整的集成流程——创建收款、读取二维码、轮询状态、测试幂等性——无需实际转移资金,也无需等待收单机构凭证。

沙箱没有单独的主机。URL 相同,契约与生产环境相同;唯一不同的是密钥。

#进入沙箱

在控制台中(或通过 API 密钥端点)签发一个测试密钥,然后照常使用:

请求体中没有用于选择环境的字段——由密钥决定,且仅由密钥决定。手动发送环境请求头不会产生任何效果:网关会将其丢弃,并把该请求视为真实收款。

curl -X POST https://api.liqfy.com.br/v1/charges \
  -H "Authorization: Bearer lq_test_YOUR_KEY" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15000, "currency": "BRL", "payment_method": "pix"}'

响应(节选):

{
  "id": "ch_a4521699-89a6-44a1-adb6-745862875e95",
  "object": "charge",
  "amount": 15000,
  "status": "pending",
  "payment_method": "pix",
  "pix": {
    "br_code": "00020126SANDBOX-PIX-8494424468F862C5DE279BA25204000053039865802BR",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2026-07-30T18:14:12.338Z"
  }
}

#关于各类凭证数据的预期

每个沙箱凭证数据都在其自身的值中带有 SANDBOX 标记——BR Code、条形码、参考号均如此。这是有意为之:如果其中某个值泄露到界面、电子邮件或报表中,文本本身就能表明其来源,而不会看起来像一笔无人能结算的真实收款。

二维码图片会正常生成并可正常显示;但用银行应用扫描会失败,因为该 BR Code 不是有效的 Pix 码。

凭证数据是确定性的。 同一笔收款始终返回相同的值。正因如此,重试和幂等性才可以被测试:重复使用相同的 Idempotency-Key 会返回同一笔收款,而不是新建一笔。

#确认沙箱支付

你唯一可以强制触发的结果是 paid,这是商户自行端到端测试 webhook 的手段:

POST /v1/payments/{id}/confirm-sandbox

对于使用测试密钥创建的收款(即沙箱收款),该操作会将其变为 PAID 并触发常规 webhook——你的端点将收到与生产环境中相同的 charge.paid 投递。响应:{ "confirmed": true, "status": "PAID" };已处于终态的收款返回 { "confirmed": false, "status": "…", "reason": "ALREADY_TERMINAL" },非沙箱收款则会被拒绝并返回 400。

各 SDK 将其封装为 payments.confirmSandbox(id)(node 为 client.payments.confirmSandbox(id),python 为 client.payments.confirm_sandbox(id),php 为 $client->payments->confirmSandbox($id),dotnet 为 client.Payments.ConfirmSandboxAsync(id))。控制台的测试环境页面具有相同功能,还可以模拟一笔已完成的付款;这些投递带有 X-Liqfy-Test: true(参见测试投递)。端点的测试按钮会发送一次示例投递,不会影响任何收款。

#尚未支持的功能

无论你在测试什么,请注意以下几点:

• 收款永远不会自动完成支付。 状态保持为 pending,不会随时间推进——只有在你确认它时(见上文)才会变化。这是有意为之:一个在 N 秒后自动"支付"的模拟器会让测试依赖时钟,并且会妨碍最重要的场景——从未被支付并最终过期的收款。
• 只能强制触发 paid。 refused、chargeback 及其他负面结果无法通过 API 设置。已在计划中,尚未实现。
• 公共 API 仅支持 Pix,目前以 Pix 为优先。模拟器内部也支持银行卡、boleto 和 Multibanco;待公共契约开放后,它们会在此处提供。

#隔离性

沙箱与你的真实业务共用同一账户和同一账本——它不是拥有独立数据的单独环境。测试收款会与真实收款一同出现在你的列表中,可通过凭证数据中的 SANDBOX 标记加以区分。

如果这会影响你的工作流程,请另建一个专门用于测试的账户。

泄露 lq_test_ 密钥不会造成财务影响——它无法向任何人扣款。但仍请将其视为凭证妥善保管:它可以读取你账户的数据。