快速入门

只需五分钟，即可创建您的第一笔收款（Cobrança，charge）。

#1. 获取 API 密钥

您将获得如下格式的密钥：

text

lq_test_8f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c

lq_test_* 密钥访问同一套生产基础设施，但具备适用于集成开发的测试安全行为；lq_live_* 密钥会产生真实的资金流动。请像对待密码一样保管这两类密钥。任何持有密钥的人都可以创建计入您账户的收款。仅在服务端存储密钥——切勿将其下发到浏览器或移动应用。明文密钥仅在签发时显示一次——如果遗失，请参阅 API 密钥了解如何轮换。

#2. 选择环境

环境	Base URL	说明
生产环境	`https://api.liqfy.com.br/v1`	真实资金，真实结算。
沙箱环境	暂未开放	专用测试环境已在规划中，但尚未上线——目前还没有独立的沙箱主机。请在生产环境中使用小额金额和 `lq_test_*` 密钥进行测试。

本指南中的所有示例均使用生产环境的 Base URL。

#3. 发起第一次调用

bash

curl -X POST https://api.liqfy.com.br/v1/charges \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Idempotency-Key: order-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "payment_method": "pix",
    "description": "Pedido #12345",
    "customer": { "name": "Maria Silva", "document": "12345678901" },
    "metadata": { "order_id": "12345" }
  }'

成功响应（201 Created）：

json

{
  "id": "ch_a1b2c3d4-0000-0000-0000-000000000009",
  "object": "charge",
  "amount": 1000,
  "currency": "BRL",
  "status": "pending",
  "payment_method": "pix",
  "customer": { "name": "Maria Silva", "document": "12345678901" },
  "pix": {
    "br_code": "000201BRCODEPIX",
    "qr_code_url": "https://qr.example/img.png",
    "expires_at": "2026-07-23T15:00:00.000Z"
  },
  "settlement": {},
  "metadata": { "order_id": "12345" },
  "created_at": "2026-07-23T14:30:00.000Z"
}

id（ch_…）是您的收款句柄——可用于查询状态和对账 webhook。对于 Pix，BR Code 和二维码（QR Code）已包含在创建响应中：无需后续轮询即可渲染收银台。

pix.txid 和 settlement.end_to_end_id 是 BACEN 语境下的 Pix 数据，而非标识符——请参阅 PIX。settlement 会一直保持为 {}，直到收款状态变为 paid。

#4. 约定

以下规则适用于所有 Liqfy /v1/charges 系列端点。

#身份验证

每个商户范围端点的请求都必须在 Authorization: Bearer 请求头中携带您的 API 密钥：

text

Authorization: Bearer lq_live_...

为保持兼容，旧版 apikey: lq_live_... 请求头仍被接受——新集成应只使用 Bearer。

缺少密钥或密钥无效时返回 401 Unauthorized。

#金额为最小货币单位的整数

货币	`1000` 的含义
`BRL`	R$ 10,00

目前 Pix 收款仅以 BRL 结算。切勿发送小数——10.00 会被拒绝。

#写操作必须提供幂等键

每个 POST /v1/charges 都必须包含 Idempotency-Key 请求头（任意非空字符串，按 (merchant, key) 隔离——不同商户使用相同的键绝不会冲突）。在 POST /payments 上，请求体字段 idempotencyKey 可作为该请求头的别名。

使用相同的键和相同的请求体重放请求时，将返回已存储的响应，确保网络重试、移动应用重复点击或后台任务重启都绝不会造成重复扣款。使用相同的键但请求体不同时，将返回 409 和 error.code: "idempotency_key_reused"（参阅错误）。服务器会将该记录保留至少 24 小时。

建议：使用您内部的订单 ID（例如 order-12345）或 UUID v4。

#时间戳采用 ISO 8601 UTC 格式

text

2026-07-23T14:30:00.000Z

#标识符

收款 ID 始终以 ch_ 为前缀，后跟一个不透明的 UUID 形式字符串——例如 ch_a1b2c3d4-e5f6-4789-9abc-def012345678。请将其视为不透明字符串：不要解析，不要按字典序排序，也不要根据其值推断先后顺序。ch_… 始终是 Liqfy ID；BACEN 的 pix.txid 和 settlement.end_to_end_id 是 Pix 语境数据，绝不能替代它。

#错误

所有错误均返回规范的响应信封：

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Validation failed",
    "details": [
      { "param": "amount", "message": "must be a positive integer" }
    ]
  },
  "request_id": "req_01J..."
}

每个响应——无论成功还是错误——都会携带 X-Request-Id。完整的信封结构和状态码对照请参阅错误。

#速率限制

默认情况下，每个已认证的 API 密钥限额为 200 req/sec、5000 req/min、50000 req/hour（由 Kong 的 rate-limiting 插件按消费者（consumer）维度实施）。需要更高限额？请发送邮件至 suporte@liqfy.com.br。

#5. 收款生命周期

text

                  ┌──────────────────────┐
                  │        pending        │  ← created, awaiting payer
                  └──────────┬───────────┘
                             │
                ┌────────────┼────────────┐
                ▼            ▼            ▼
          ┌─────────┐  ┌──────────┐  ┌─────────┐
          │  paid   │  │ expired  │  │ failed  │
          └────┬────┘  └──────────┘  └─────────┘
               │
               ▼
          ┌──────────┐
          │ refunded │
          └──────────┘

公开状态词汇：pending、processing、paid、failed、expired、cancelled、refunded、disputed。这些都是稳定状态，可以据此编写分支逻辑；它们所映射的内部状态绝不会出现在 /v1/charges 响应中。

您的履约钩子应在 paid 时触发。其余状态仅供参考——对于该状态转换，建议使用 webhooks 而非轮询。

#6. 查询余额

收款开始结算后，只需一次调用即可获取可用余额——使用同一密钥，无需请求体。currency 查询参数为可选；不传时将返回账户中的所有币种：

bash

curl "https://api.liqfy.com.br/v1/wallets/balance" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

json

{
  "available": 880,
  "pending": 0,
  "total": 880,
  "retained": 0,
  "currency": "BRL",
  "next_release_at": null,
  "next_release_amount": null,
  "balances": [
    { "currency": "BRL", "available": 880, "held": 0, "pending": 0, "total": 880 }
  ],
  "primary": { "currency": "BRL", "available": 880, "held": 0, "pending": 0, "total": 880 }
}

金额以分（centavos）为单位（880 = R$ 8,80）。available 是您当前可以使用或提现的金额（带符号——可能为负数；为该币种下所有钱包的合计）；held 是正在冻结的在途资金；pending 是已结算但尚未释放的金额，并包含在途退款冻结，因此可能大于 retained。total 为 available + held + pending。当已安排释放时，next_release_at / next_release_amount 会告诉您释放的时间和金额。账户中的每个币种都会出现在 balances[] 中。

只需要一个币种？添加 ?currency=BRL 即可获得扁平结构。需要所有钱包（按类型）？GET /v1/wallets 会返回完整列表。请参阅 API 参考。

#下一步

→ 构建 PIX 流程