{ "openapi": "3.1.0", "info": { "title": "Lunium — 巴西加密资产 ⇄ Pix 结算", "version": "1.45.0", "summary": "巴西加密资产与 Pix 双向结算。", "x-lunium-partners": { "name": "Lunium Partners — 官方接入者社区", "url": "https://t.me/+FerOZMRRP_g5MDk5", "description": "运行通告、接口契约变更及合作伙伴交流。不要在群组公开 API 密钥。" }, "description": "Lunium API 支持 Pix 收款、BRL 资金托管、加密资产交付、外部加密资产兑换 Pix，以及余额支付 Pix。托管收款须明确发送 destino=saldo，HTTP 收款单默认仍为 cripto。托管无需固定结算钱包。资产 / 网络可用性、费用、限额及资金冻结会动态变化，须查询对应密钥、余额、目录及预览接口。付款完成、结算及余额可用是不同状态。Pix 在可用时提供凭证 / E2E，不代表每笔加密资产交易都有这些字段。认证使用 X-API-Key。重试保持稳定 external_id 及相同 payload。公开付款核验：GET /v1/verificar/{e2e}。测试环境模拟 cash-in、资金托管、加密资产提现、Pix 对外付款、内部转账及 cash-out；通过 POST /sandbox/cashin/{cashin_id}/pay 确认不可真实付款的测试 Pix，不执行银行、交易所或链上交易。详见 https://docs.luniumpay.com/zh/sandbox 。错误可能包含 erro/acao/detail 及 request_id/agent_guidance，须兼容未知字段、事件及错误码。MCP：https://api.luniumpay.com/mcp，通过 tools/list 发现工具。手册：https://docs.luniumpay.com/zh/manual；英文版：https://docs.luniumpay.com/en/manual。本次文档对照已部署行为，金融请求字段保持原规范。AI 接入：https://docs.luniumpay.com/zh/integrar-com-ia；仅供测试的公共 MCP：https://api.luniumpay.com/mcp/onboarding；机器可读接入方案：https://docs.luniumpay.com/zh/integration.json 。2026年10月15日费率政策：余额充值每笔 R$ 1.00，无比例费用及佣金；直接购买 3.3% + R$ 1.00；余额兑换加密资产 3.3%，不再收取固定费用；余额通过 Pix 提现 1.5%。购买及转出另计合作伙伴佣金。参考汇率为 Binance 卖一价（ask），不加溢价；适用网络及处理成本在预览中列明。", "contact": { "name": "Lunium", "email": "contato@luniumpay.com", "url": "https://luniumpay.com/integrar?utm_source=openapi&utm_medium=spec" }, "x-documentation-revision": "2026-09-17.4" }, "servers": [ { "url": "https://api.luniumpay.com", "description": "生产环境" } ], "tags": [ { "name": "Cash-out", "description": "接收加密资产，支付 Pix。" }, { "name": "Cash-in", "description": "接收 Pix，交付加密资产。" }, { "name": "Catálogo", "description": "当前可结算的资产与路由，以此接口为准，不要固定保存列表。" }, { "name": "Verificação", "description": "公开核验 Pix，无需成为客户或提供密钥。" }, { "name": "Conta", "description": "密钥、限额及使用情况。" }, { "name": "Mesh · Discovery", "description": "智能体自动发现 Lunium 及其能力，无需人工沟通。" }, { "name": "Mesh · Identity", "description": "智能体注册、凭证及生产激活生命周期。" }, { "name": "Mesh · Policy", "description": "智能体自身的 mandate 授权及结算配置。" }, { "name": "Mesh · Network", "description": "可验证的推荐关系、关系图及网络交易量。" }, { "name": "Mesh · Economy", "description": "按直接推荐方实际结算交易量的 0.10% 计奖，注册本身不产生奖励。" }, { "name": "Contato", "description": "将按量报价、合同、合作或文档未覆盖的场景转交人工。" }, { "name": "Comissão (sub fee)", "description": "合作伙伴在 Lunium 费用之外另计、由最终用户承担的佣金，以及以加密资产形式提取该佣金。" }, { "name": "Sandbox", "description": "模拟资金流程及确定性的场景控制。" }, { "name": "Carteira USDT", "description": "项目 USDT 余额：通过多网络充值 USDT 或 USDC，再使用余额通过 Pix 收款标识或 Copia e Cola 付款。lun_test_ 密钥使用模拟器，接口、结构及状态相同，不移动真实资金。" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "通过 POST /keys 创建的密钥，完整值仅显示一次，请在创建时保存。" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "您的密钥。lun_test_… 为测试环境，不移动真实资金；新生产密钥使用 lun_live_…，旧版 lun_… 生产密钥仍有效。" } }, "schemas": { "CotacaoSaqueCriptoCarteira": { "type": "object", "required": [ "quote_id", "funding_source", "amount", "usdt_total", "asset", "network", "address", "minimum_received", "amount_estimated", "expires_at", "sandbox" ], "properties": { "funding_source": { "type": "string", "enum": [ "crypto_usdt" ] }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "asset": { "type": "string", "enum": [ "USDT", "USDC" ] }, "network": { "type": "string", "enum": [ "polygon", "bsc", "tron", "eth", "arbitrum", "optimism", "base", "avalanche", "solana" ] }, "address": { "type": "string" }, "quote_id": { "type": "string", "pattern": "^uq_[a-f0-9]{24}$" }, "usdt_total": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "amount_estimated": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "minimum_received": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "network_fee": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "conversion_fee_estimated": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "fee_mode": { "type": "string", "enum": [ "deducted" ] }, "expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean" }, "note": { "type": "string" } } }, "SaqueCriptoCarteira": { "type": "object", "required": [ "withdrawal_id", "external_id", "quote_id", "funding_source", "amount", "asset", "network", "address", "status", "final", "sandbox" ], "properties": { "funding_source": { "type": "string", "enum": [ "crypto_usdt" ] }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "asset": { "type": "string", "enum": [ "USDT", "USDC" ] }, "network": { "type": "string", "enum": [ "polygon", "bsc", "tron", "eth", "arbitrum", "optimism", "base", "avalanche", "solana" ] }, "address": { "type": "string" }, "quote_id": { "type": "string", "pattern": "^uq_[a-f0-9]{24}$" }, "withdrawal_id": { "type": "string" }, "external_id": { "type": "string" }, "network_name": { "type": "string" }, "status": { "type": "string", "enum": [ "reserved", "funding", "converting", "processing", "under_review", "completed", "failed" ] }, "final": { "type": "boolean" }, "amount_estimated": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "minimum_received": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "amount_received": { "type": [ "string", "null" ] }, "network_fee": { "type": [ "string", "null" ] }, "usdt_reserved": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "usdt_debited": { "type": [ "string", "null" ] }, "tx_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sandbox": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "duplicate_prevented": { "type": "boolean" }, "requested_external_id": { "type": "string" } } }, "Erro": { "type": "object", "description": "API 错误，字段可能因接口或基础设施响应而异。结合 HTTP 状态码及返回的 erro、acao 判断；detail 用于展示，不用于业务分支。须兼容新增错误码。", "properties": { "erro": { "type": "string", "description": "稳定错误码，应据此编写分支，不根据 detail 文本判断。本列表来自 API 实际使用的错误码。", "x-known-values": [ "amount_invalido", "asset_invalido", "br_code_indisponivel", "br_code_invalido", "br_code_sem_valor", "brl_amount_invalido", "campos_conflitantes", "campos_obrigatorios", "carencia_primeiro_deposito", "carteira_indisponivel", "carteira_nao_liberada", "cashin_indisponivel", "cashout_indisponivel", "catalogo_indisponivel", "chave_ausente", "chave_desconhecida", "chave_incorreta", "chave_nao_encontrada", "chave_obrigatoria", "conflito", "consulta_indisponivel", "corpo_grande_demais", "cotacao_divergente", "cotacao_expirada", "cotacao_indisponivel", "cotacao_recusada", "custodia_desligada", "deposit_obrigatorio", "destino_invalido", "devolucao_indisponivel", "documento_invalido", "em_processamento", "email_invalido", "email_obrigatorio", "endpoint_nao_respondeu", "erro_interno", "external_id_divergente", "formato_invalido", "funding_source_invalido", "ja_entregue", "limite_consultas", "limite_de_chaves_teste", "limite_diario", "limite_diario_recebedor", "limite_do_pagador", "limite_indisponivel", "liquidante_indisponivel", "mandate_contraparte_nao_autorizada", "mandate_valor_acima_do_teto", "memo_obrigatorio", "metodo_nao_permitido", "muitas_tentativas", "muitos_pedidos_abertos", "nao_autenticado", "nao_encontrado", "nao_permitido", "nao_processavel", "origem_igual_destino", "outcome_invalido", "pagador_bloqueado", "pagador_recusado_pelo_provedor", "pagamentos_indisponiveis", "payer_tax_invalido", "payer_tax_number_invalido", "payout_address_invalido", "payout_address_obrigatorio", "payout_nao_liberado", "payout_recusado", "pix_key_invalida", "pix_key_obrigatoria", "provedor_indisponivel", "provedor_sem_resposta", "rate_limit", "rede_indisponivel", "refund_address_imutavel", "refund_address_invalida", "requisicao_invalida", "saldo_insuficiente", "sandbox_sem_cashin", "sandbox_sem_saldo", "sandbox_sem_saque", "saque_comissao_diario", "saque_indisponivel", "status_invalido", "tax_number_obrigatorio", "taxa_alterada", "tempo_esgotado", "temporariamente_indisponivel", "tipo_ambiguo", "valor_abaixo_do_minimo", "valor_acima_do_maximo", "valor_invalido", "webhook_nao_configurado", "webhook_url_invalida" ] }, "acao": { "type": "string", "enum": [ "corrigir", "repetir", "esperar", "parar", "falar_com_suporte" ], "description": "corrigir = 请求有误，原样重试无效；repetir = 暂时故障，可用相同请求重试；esperar = 等待配额恢复；parar = 不要重试，请联系团队；falar_com_suporte = 不循环重试，保留 request_id 及 external_id 并联系 Lunium，例如 config_provedor。" }, "detail": { "type": "string", "description": "面向人工阅读的说明，不用于业务分支判断。" }, "limits": { "type": "object", "description": "限额错误中可能提供，已换算为订单币种。" }, "docs": { "type": "string", "format": "uri" }, "request_id": { "type": "string", "description": "本次请求标识，同时出现在 X-Request-ID 响应头中，联系支持时请提供。若请求头 X-Request-ID 符合 [A-Za-z0-9._:-]{8,64}，将全程保留原值。", "examples": [ "req_62f05f21b3794830a241" ] }, "code": { "type": "string", "deprecated": true, "description": "erro 的旧别名，计划于2026年11月9日停止返回。不要依赖此字段，使用规范字段 erro；它不会脱离 erro 单独出现。" } } }, "CashOut": { "type": "object", "properties": { "cashout_id": { "type": "string", "description": "不透明订单标识，生产环境可能为 UUID，测试环境以 sbx_ 开头。原样保存，不做类型转换。" }, "state": { "type": "string", "enum": [ "QUOTE_CREATED", "AWAITING_DEPOSIT", "DEPOSIT_DETECTED", "DEPOSIT_CONFIRMED", "SELLING", "SOLD", "FORWARDING", "PAYING_OUT", "COMPLETED", "MANUAL_REVIEW", "REFUNDING_CRYPTO", "REFUNDED", "EXPIRED", "FAILED", "DELAYED", "AWAITING_REFUND_ADDRESS", "PROCESSING", "REFUNDING" ], "description": "订单状态。COMPLETED 确认 Pix 已付款，中间阶段因渠道而异，DELAYED 属于测试场景。AWAITING_REFUND_ADDRESS 表示须退款但尚无钱包，通过 POST /cash-outs/{cashout_id}/refund-address 提交；适用于加密资产卖出，以及自 1.44.0 起的 DePix 卖出。DePix 成功流程为 QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED。Pix 无法支付时进入 REFUNDING → REFUNDED，缺少钱包则 AWAITING_REFUND_ADDRESS。若 DePix 已发送至服务商，须确认资金返还后才可退款；此前保持 MANUAL_REVIEW，退款最高为实际返还金额。" }, "path": { "type": [ "string", "null" ], "enum": [ "FAST", "DEX", "CONVERT", null, "depix_liquid" ], "description": "FAST、DEX 或 CONVERT 渠道。时效取决于路由、确认及处理。DePix/Liquid 使用 depix_liquid。" }, "asset": { "type": "string", "examples": [ "USDT" ], "description": "卖出的资产。必须使用 GET /catalog 中完全一致的 id，例如 \"usdt\"。须与 network 组合使用，且 (asset, network) 必须存在于目录。" }, "network": { "type": "string", "examples": [ "polygon" ], "description": "目录列出的充值区块链网络，例如 \"polygon\"。返回地址仅对该网络有效。" }, "amount": { "type": "string", "description": "加密资产数量，以十进制字符串表示，绝不使用浮点数。" }, "brl_amount": { "type": [ "string", "null" ], "description": "Pix 收款账户将收到的巴西雷亚尔（BRL）金额。" }, "pix_key": { "type": "string", "description": "响应中经遮盖的收款人 Pix 标识。请求传入完整标识，不要将遮盖后的响应与原值逐字比较。" }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "phone", "email", "random" ], "description": "通常可省略，邮箱、CNPJ、随机标识及带 +55 的手机号可根据格式推断。11 位纯数字无法区分 CPF 与手机号，必须明确指定类型，以免付错收款人。显式类型优先于推断。" }, "deposit_address": { "type": [ "string", "null" ], "description": "客户发送加密资产的地址，仅在接受报价后提供。测试环境 DePix 返回不可付款标记 SANDBOX:LIQUID:NAO_ENVIAR:…，切勿发送真实资产。" }, "deposit_tag": { "type": [ "string", "null" ], "description": "接受报价时返回的 memo/tag，充值须一并填写。仅使用 GET /catalog 中的网络。" }, "external_id": { "type": [ "string", "null" ], "description": "每个业务意图的持久标识，最多 64 个字符。相同请求体重试复用原订单；更改网络、资产、token、目的地、Pix 类型、金额或退款钱包会产生 409 冲突。须先恢复原订单，再决定是否新建。旧订单若缺少可验证请求身份，可能须按 cashout_id/external_id 恢复。", "maxLength": 64 }, "refund_address": { "type": [ "string", "null" ], "description": "客户确认的退款钱包，缺失时不代表可以使用 deposit_from。订单可能停留于 AWAITING_REFUND_ADDRESS。自 1.44.0 起，DePix 卖出也适用，须提供客户 Liquid 地址 lq1…。 " }, "refund_tx_hash": { "type": [ "string", "null" ], "description": "退款完成后的交易哈希，不代表所有退款均有固定金额或时限。" }, "deposit_from": { "type": [ "string", "null" ], "description": "充值的链上来源，仅供参考，可能为交易所共用钱包。绝不能自动将其选为退款目的地。" }, "br_code": { "type": [ "string", "null" ], "description": "报价时提供的 Copia e Cola 支付码（如有），brl_amount 为二维码金额。" }, "merchant_name": { "type": [ "string", "null" ], "description": "从收款二维码中读取的收款人姓名。" }, "copia_e_cola_buffer_usd": { "type": [ "string", "null" ], "description": "R$ 1 运营预留款的 USDT 等值金额，报价时换算，已包含在总额中，不要重复加上。已有订单保留其原金额。", "example": "0.200000" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "报价到期时间，ISO 8601 UTC，例如 2026-09-02T14:03:00Z。过期后接受报价返回 erro=cotacao_expirada，应重新报价，不要反复提交。" }, "pix_e2e": { "type": [ "string", "null" ], "description": "Pix 完成后的巴西央行端到端标识，可通过 GET /v1/verificar/{e2e} 无需密钥公开核验。可向最终客户提供。测试环境为虚构 E2E，ISPB 为 00000000，不能证明银行付款。", "examples": [ "E37293930202607312006361894c4a82" ] }, "pix_paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "receipt_url": { "type": [ "string", "null" ], "description": "可分享的凭证页面链接，生成后提供。cashout.completed 事件中可能仍为 null，后续 cashout.receipt_ready 或同一订单查询会提供链接。", "examples": [ "https://app.luniumpay.com/comprovante/uwscff6ASNS1oUcH2LHbvw" ] }, "receipt_pdf_url": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "description": "PDF 凭证文件，可附至工单、发送给客户或留作会计档案，核查时不依赖在线凭证页面。包含收款人姓名、证件及机构、金额、日期、E2E 和核验链接，与在线页面使用同一数据源。在订单尚未达到对应阶段时为 null。凭证内容及 API、webhook、控制台、Telegram 等获取方式详见 https://docs.luniumpay.com/zh/manual#comprovante 。", "example": "https://app.luniumpay.com/comprovante/qigpnCTx3gM-Ge7hN27Mvw.pdf" }, "verify_url": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "description": "公开核验直达链接，无需密钥，可交给交易对方独立确认付款。不会展示 Pix 收款标识、完整姓名或完整证件。订单尚未达到相应阶段时为 null。", "example": "https://api.luniumpay.com/v1/verificar/E3729393020260731214021222ac6ff1" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "timeline": { "type": "array", "description": "服务器在状态变化时记录的时间线，来自网关时间而非轮询时间：AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED →（SELLING → SOLD → FORWARDING，仅交易所渠道）→ PAYING_OUT → COMPLETED。用于客户交易跟踪界面。", "items": { "type": "object", "properties": { "state": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } } }, "confirmations": { "type": [ "integer", "null" ], "description": "当前已观察到的充值确认数，仅在订单等待网络确认时返回，不持久保存，会随区块变化。结合 confirmations_required 展示实际进展，不要编造进度。" }, "confirmations_required": { "type": [ "integer", "null" ], "description": "交易所对该网络充值入账所要求的确认数。" }, "failure_reason": { "type": [ "string", "null" ], "description": "返回的失败原因，包括测试环境场景。" }, "sandbox": { "type": "boolean", "description": "模拟交易时为 true。" }, "simulation": { "type": "object", "additionalProperties": true }, "partner_fee_bps": { "type": "integer", "nullable": true, "description": "该笔卖出创建时保存的合作伙伴 sub fee，单位 bps。早于此字段的旧订单或 DePix 卖出可能为 null。" }, "partner_fee_brl_cents": { "type": "integer", "nullable": true, "description": "Pix 确认时确定的合作伙伴份额，以分计，即记入佣金账本的金额。" }, "refund_address_required": { "type": "boolean", "description": "AWAITING_REFUND_ADDRESS 时为 true。查询退款资料，并通过 POST /cash-outs/{cashout_id}/refund-address 提交客户确认的钱包。" }, "refund_amount": { "type": [ "string", "null" ], "description": "核算后的实际退款数量，不要默认等于最初充值量。DePix 全部由 Lunium 持有时，AWAITING_REFUND_ADDRESS 已提供 refund_amount、refund_asset（DEPIX）及 refund_network（liquid）。若已转交服务商，MANUAL_REVIEW 中这些字段保持 null，直至确认返还；之后 refund_amount 最高为实际返还金额加未转交部分，且不超过订单金额。" }, "refund_asset": { "type": [ "string", "null" ], "description": "实际退款资产，可能与充值资产不同。" }, "refund_network": { "type": [ "string", "null" ], "description": "实际退款网络，须使用客户确认且兼容的钱包。" }, "provider_return_txid": { "type": [ "string", "null" ], "description": "合作服务商向 Lunium 返还资金的参考标识，不是向客户完成退款的证明。" }, "fee_bps": { "type": "integer", "description": "DePix 卖出费率，单位 bps。" }, "fee_fixed_cents": { "type": "integer", "description": "DePix 卖出固定费用，以分计。" }, "fee_total_cents": { "type": "integer", "description": "总费用，以分计，在 DePix 报价及模拟订单中提供。" }, "net_cents": { "type": "integer", "description": "Pix 净额，以分计，在 DePix 报价及模拟订单中提供。" }, "pix_key_reserve_usd": { "type": [ "string", "null" ], "description": "R$ 1 运营预留款的 USDT 等值金额，报价时换算，已包含在总额中，不要重复加上。已有订单保留其原金额。", "example": "0.200000" }, "reserve_brl": { "type": [ "string", "null" ], "example": "1.00", "description": "新订单固定 R$ 1 运营预留款，已包含在总额中。旧订单保留原预留金额。" } } }, "EventoWebhook": { "type": "object", "description": "Lunium 发送至您接收端的请求体。事件类型可能新增，未知事件不应触发资金业务效果；应兼容并保存记录，以便之后核查。", "properties": { "event": { "type": "string", "enum": [ "cashin.paid", "cashin.delayed", "cashin.held", "cashin.settled", "cashin.settlement_failed", "cashin.expired", "cashin.refunded", "cashin.failed", "cashout.awaiting_deposit", "cashout.deposit_detected", "cashout.confirming", "cashout.processing", "cashout.under_review", "cashout.awaiting_refund_address", "cashout.refunding", "cashout.completed", "cashout.receipt_ready", "cashout.refunded", "cashout.expired", "cashout.failed", "payout.sent", "payout.failed", "payout.refunded", "webhook.test", "saldo.liberado", "saldo.congelado", "saldo.transferido", "wallet.deposit_credited", "wallet.payment_completed", "wallet.payment_failed", "wallet.withdrawal.completed", "wallet.withdrawal.failed" ], "description": "按事件类型处理。cashin.settled 是入账 / 交付完成信号，托管可用金额仍须查询余额。cashout.confirming 表示交易所等待充值确认的进展，仅在需要较长等待、至少 120 次确认的网络中，于 25%、50% 及 75% 阶段发送，payload 提供 confirmations 与 confirmations_required，用于补充 cashout.deposit_detected 后可能较长的等待。cashin.held 表示 Pix 已付款但按密钥策略本地冻结，data 提供 liberar_em；不同于服务商冻结的 status: delayed。cashin.delayed 表示 Pix 已付款且服务商冻结 24 小时，见 delay_until。cashout.awaiting_refund_address 表示须退款但缺少钱包，state: AWAITING_REFUND_ADDRESS、refund_address_required: true；向客户索取钱包后，通过 POST /cash-outs/{cashout_id}/refund-address 提交，绝不自动退至充值来源。适用于加密资产卖出及自 1.44.0 起的 DePix 卖出，data 与 GET /cash-outs/{cashout_id} 的订单格式相同。USDT 钱包事件：wallet.deposit_credited 的 data 包含 deposit_id、amount_received、asset、network、balance_available、credited_at；wallet.payment_completed 包含 payment_id、brl_amount、cashout_id、usdt_debited；wallet.payment_failed 包含 payment_id、brl_amount、cashout_id、status、refunded，其中 refunded: true 表示预留款已释放回余额。测试环境的相同事件带 sandbox: true。" }, "event_id": { "type": "string", "pattern": "^evt_[0-9a-f]{24}$", "description": "稳定的事件标识，所有重试保持相同。保存并对重复事件去重，避免重复入账。", "examples": [ "evt_9c3f21a70b5e4d8812ff0a63" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "与对应交易状态接口使用相同基础格式。" } }, "required": [ "event", "created_at", "data" ] }, "EntregaWebhook": { "type": "object", "properties": { "event_id": { "type": "string" }, "event": { "type": "string", "enum": [ "cashin.paid", "cashin.delayed", "cashin.held", "cashin.settled", "cashin.settlement_failed", "cashin.expired", "cashin.refunded", "cashin.failed", "cashout.awaiting_deposit", "cashout.deposit_detected", "cashout.confirming", "cashout.processing", "cashout.under_review", "cashout.awaiting_refund_address", "cashout.refunding", "cashout.completed", "cashout.receipt_ready", "cashout.refunded", "cashout.expired", "cashout.failed", "payout.sent", "payout.failed", "payout.refunded", "webhook.test", "saldo.liberado", "saldo.congelado", "saldo.transferido", "wallet.deposit_credited", "wallet.payment_completed", "wallet.payment_failed", "wallet.withdrawal.completed", "wallet.withdrawal.failed" ] }, "operation_id": { "type": "string", "description": "产生此事件的交易 ID。" }, "status": { "type": "string", "enum": [ "pending", "sent", "failed" ], "description": "failed 表示 12 次尝试已耗尽，可通过 retry 恢复。" }, "attempts": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TitularPix": { "type": "object", "required": [ "pix_key", "pix_key_type", "owner_name", "verified", "source", "checked_at" ], "properties": { "pix_key": { "type": "string", "description": "规范化后的 Pix 收款标识，手机号格式为 +55…。" }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "phone", "email", "random" ], "description": "所查询收款标识类型：\"cpf\"、\"cnpj\"、\"phone\"、\"email\" 或 \"random\"。" }, "owner_name": { "type": [ "string", "null" ], "description": "DICT 中的持有人姓名。", "examples": [ "João Silva" ] }, "owner_tax_number": { "type": [ "string", "null" ], "description": "已遮盖的 CPF/CNPJ，绝不返回完整值。", "examples": [ "***.202.745-**" ] }, "institution_name": { "type": [ "string", "null" ], "description": "收款标识登记的金融机构。", "examples": [ "NU PAGAMENTOS - IP" ] }, "ispb": { "type": [ "string", "null" ], "description": "机构 ISPB，8 位数字。", "examples": [ "18236120" ] }, "verified": { "type": "boolean", "description": "已查询收款人或在测试环境模拟时为 true（source=sandbox）；未核验时为 false。" }, "source": { "type": "string", "enum": [ "dict", "sandbox", "disabled" ] }, "checked_at": { "type": "string", "format": "date-time" }, "cached": { "type": "boolean", "description": "响应来自缓存时为 true。" }, "sandbox": { "type": "boolean", "description": "仅测试密钥提供，表示虚构收款人。" }, "available": { "type": "boolean", "description": "查询不可用时为 false，也可能同时返回 HTTP 200。" }, "optional": { "type": "boolean", "description": "查询为辅助功能，不是付款前提。" }, "verification_status": { "type": "string", "description": "未执行核验时为 not_performed。" }, "detail": { "type": "string" } } }, "NextAction": { "type": "object", "description": "下一步操作，以可调用结构表示，使智能体无需依赖人工说明继续流程。", "properties": { "method": { "type": "string", "example": "POST" }, "endpoint": { "type": "string", "example": "/mesh/agents/{agent_id}/settlement" }, "why": { "type": "string", "example": "sem rota de liquidacao o dinheiro nao tem para onde ir" } } }, "ErroAutocorrigivel": { "type": "object", "description": "智能体可处理的错误。acao 为稳定枚举：corrigir（请求有误）、esperar（等待配额）、parar（停止重复）、repetir（暂时故障）。", "properties": { "erro": { "type": "string", "example": "mandate_valor_acima_do_teto" }, "acao": { "type": "string", "enum": [ "corrigir", "esperar", "parar", "repetir" ] }, "detail": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } }, "required": [ "erro", "acao" ] }, "Capability": { "type": "object", "description": "按属性而非内部名称描述 Lunium 的能力，让智能体根据自身目标匹配，无需预先了解平台术语。", "properties": { "descricao": { "type": "string" }, "intent": { "type": "array", "items": { "type": "string" }, "example": [ "sell_crypto", "receive_fiat", "offramp", "cash_out" ] }, "input_assets": { "type": "array", "items": { "type": "string" }, "example": [ "USDT" ] }, "input_networks": { "type": "array", "items": { "type": "string" }, "example": [ "polygon" ] }, "output_currencies": { "type": "array", "items": { "type": "string" }, "example": [ "BRL" ] }, "payment_rails": { "type": "array", "items": { "type": "string" }, "example": [ "PIX" ] }, "endpoint": { "type": "string", "example": "/cash-outs" }, "direction": { "type": "string", "example": "crypto->fiat" }, "settlement_speed": { "type": "string", "enum": [ "seconds", "minutes" ] } } }, "MeshDiscovery": { "type": "object", "description": "智能体接入前的统一发现文档，由当前配置生成，用于查询服务能力及规则。", "properties": { "quem_somos": { "type": "object" }, "como_falar_comigo": { "type": "object", "description": "REST、OpenAPI、MCP、A2A 及 Mesh。" }, "capacidades": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Capability" } }, "como_escolher_capacidade": { "type": "object", "description": "业务意图 → 能力的反向索引，以及按属性筛选的说明。", "properties": { "por_intencao": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "execucao": { "type": "object", "description": "每项能力提供接口、必填字段及可用示例。" }, "ativos_e_redes": { "type": "object" }, "limites": { "type": "object" }, "como_comecar": { "type": "object" }, "regra_de_seguranca": { "type": "object" }, "atribuicao": { "type": "object" } } }, "AgentIdentity": { "type": "object", "description": "智能体永久身份。凭证可以替换，但推荐关系、交易量、奖励、mandate 及信誉均归属 agent_id。", "properties": { "agent_id": { "type": "string", "example": "agt_2319c9da313e84af3b" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "contact": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AgentLifecycle" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "settlement_address": { "type": [ "string", "null" ] }, "referred_by": { "type": [ "string", "null" ], "description": "注册后不可变，由数据库触发器保护。" }, "created_at": { "type": "string", "format": "date-time" } } }, "AgentLifecycle": { "type": "string", "enum": [ "registered", "sandbox_active", "validated", "production_active", "suspended" ], "description": "生产环境按规则自动激活，无需人工审批。风险控制来自 cash-in 付款人分级、单笔上限、Pix 收款人每日上限及密钥自身 mandate。自2026年9月10日起，不设 API 密钥每日总额度，也没有人工审批队列。" }, "AgentRegistration": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "description": { "type": "string" }, "contact": { "type": "string" }, "agent_card_url": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "referral_token": { "type": "string", "description": "由推荐方签名的推荐证明，是建立推荐关系的唯一方式。由于涉及奖励，拒绝客户端自行申报 referred_by。" } } }, "AgentKey": { "type": "object", "description": "凭证前缀：lun_test_* 为测试，lun_live_* 为生产。2026年8月29日前签发的旧 lun_ 密钥仍有效。身份验证依据密钥哈希，前缀仅便于人工识别。", "properties": { "api_key": { "type": "string", "example": "lun_live_a977c15a…", "description": "完整值仅显示一次，平台仅保存哈希。" }, "sandbox": { "type": "boolean" } } }, "Mandate": { "type": "object", "description": "密钥为自身设置的授权策略，只能收紧限额，不能扩大权限。智能体可自行降低其操作范围，生产激活前必须设置。", "properties": { "max_por_operacao_cents": { "type": "integer", "example": 30000 }, "max_diario_cents": { "type": "integer", "example": 200000 }, "contrapartes": { "type": "array", "items": { "type": "string" }, "description": "允许付款的 Pix 收款标识，空列表表示不另加此项限制。" } } }, "SettlementConfiguration": { "type": "object", "required": [ "settlement_address" ], "properties": { "settlement_address": { "type": "string", "example": "0x51e3…75e0", "description": "支持的结算网络钱包。" } } }, "ProductionActivation": { "type": "object", "description": "自动激活，activated_by 始终为 policy，不为 operator。", "properties": { "status": { "type": "string", "example": "production_active" }, "agent_id": { "type": "string" }, "environment": { "type": "string", "example": "production" }, "activated_at": { "type": "string", "format": "date-time" }, "activated_by": { "type": "string", "example": "policy" }, "api_key": { "type": "string", "description": "生产凭证 lun_live_*，仅显示一次。" }, "settlement": { "type": "object" }, "mandate": { "$ref": "#/components/schemas/Mandate" }, "capabilities": { "type": "array", "items": { "type": "string" } } } }, "ReferralAttestation": { "type": "object", "description": "签名 token（JWS HS256）用于证明推荐方，一次性且有有效期。未提供时，智能体作为根节点加入，不为推荐方产生奖励。", "properties": { "type": { "type": "string", "example": "mesh_referral" }, "referrer_agent_id": { "type": "string" }, "referral_token": { "type": "string" }, "capability": { "type": [ "string", "null" ] }, "nonce": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "one_time_use": { "type": "boolean", "example": true } } }, "AgentNetwork": { "type": "object", "description": "某智能体下方的推荐树。network_volume 统计整棵树，用于信誉；reward_eligible_volume 仅统计可计奖交易量。", "properties": { "agent_id": { "type": "string" }, "referred_by": { "type": [ "string", "null" ] }, "depth": { "type": "integer" }, "direct_children": { "type": "integer" }, "total_descendants": { "type": "integer" }, "own_volume_cents": { "type": "integer" }, "own_transactions": { "type": "integer" }, "network_volume_cents": { "type": "integer" }, "network_transactions": { "type": "integer" }, "reward_eligible_volume_cents": { "type": "integer" }, "lifetime_rewards_cents": { "type": "integer" }, "first_operation": { "type": [ "string", "null" ], "format": "date-time" }, "production_since": { "type": [ "string", "null" ], "format": "date-time" }, "children": { "type": "array", "items": { "type": "object" } } } }, "MeshEconomyPolicy": { "type": "object", "description": "公开网络经济规则：未结算，不计奖励。", "properties": { "model": { "type": "string", "example": "transaction_attribution" }, "direct_rate": { "type": "string", "example": "0.10%" }, "direct_rate_bps": { "type": "integer", "example": 10 }, "max_paid_levels": { "type": "integer", "example": 1 }, "recruitment_reward": { "type": "boolean", "example": false }, "requires_settled_transaction": { "type": "boolean", "example": true }, "revenue_share_cap": { "type": "string" } } }, "RewardEvent": { "type": "object", "description": "不可变账本记录。冲回以新的负数记录表示，不执行 UPDATE 或 DELETE。", "properties": { "transaction_id": { "type": "string" }, "transaction_kind": { "type": "string", "enum": [ "cashout", "cashin" ] }, "source_agent_id": { "type": "string", "description": "产生交易量的智能体。" }, "referral_level": { "type": "integer", "example": 1 }, "volume_cents": { "type": "integer" }, "rate_bps": { "type": "integer", "example": 10 }, "gross_reward_cents": { "type": "integer" }, "revenue_cents": { "type": "integer", "description": "Lunium 在该交易中的收入。" }, "revenue_cap_cents": { "type": "integer", "description": "奖励适用上限。" }, "final_reward_cents": { "type": "integer", "description": "冲回时为负数。" }, "reward_usdt": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "pending", "available", "paid", "reversed" ] }, "motivo": { "type": [ "string", "null" ] }, "criado_em": { "type": "string", "format": "date-time" } } }, "RewardBalance": { "type": "object", "description": "agent_id 的余额，不属于凭证本身。轮换密钥不会丢失余额。", "properties": { "agent_id": { "type": "string" }, "own_volume_cents": { "type": "integer" }, "direct_referral_volume_cents": { "type": "integer" }, "network_volume_cents": { "type": "integer" }, "pending_rewards_cents": { "type": "integer" }, "available_rewards_cents": { "type": "integer" }, "paid_rewards_cents": { "type": "integer" }, "lifetime_rewards_cents": { "type": "integer" }, "reward_events": { "type": "integer" }, "reversals": { "type": "integer" }, "policy": { "$ref": "#/components/schemas/MeshEconomyPolicy" }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/RewardEvent" } } } }, "ServiceRecommendation": { "type": "object", "description": "智能体间传递的推荐信息，仅包含域名、能力及可选推荐证明，不包含密钥、私密接口或数据模式。接收方仍须独立核实 Lunium。", "properties": { "type": { "type": "string", "example": "service_recommendation" }, "from_agent": { "type": "string" }, "domain": { "type": "string", "example": "https://luniumpay.com" }, "capability": { "type": "string", "example": "usdt_to_pix" }, "referral_token": { "type": "string" }, "verify_yourself": { "type": "string" } } }, "Cobranca": { "type": "object", "description": "收款单创建响应，含二维码。状态、列表及 webhook 请参阅 StatusCobranca。", "properties": { "cashin_id": { "type": "string", "description": "收款单标识，格式为 ci_…。" }, "status": { "type": "string", "description": "Pix 状态。paid 本身不证明入账 / 交付完成，须读取 settlement_status。", "enum": [ "pending", "delayed", "under_review", "paid", "expired", "refunded", "failed" ] }, "amount_cents": { "type": "integer", "description": "Pix 金额，以分计。" }, "destino": { "type": "string", "description": "cripto 表示链上交付，saldo 表示计入密钥 BRL 托管余额，可通过 POST /payouts 及 POST /saldo/sacar-cripto 使用。", "enum": [ "cripto", "saldo" ] }, "fonte": { "type": "string", "enum": [ "pix", "saldo" ], "description": "创建时的资金来源：Pix 或余额提现。" }, "customer_ref": { "type": [ "string", "null" ], "description": "您的最终客户引用，即余额子账户。", "maxLength": 80 }, "payout_address": { "type": [ "string", "null" ], "description": "接收加密资产的钱包，适用于 destino=cripto。" }, "payout_tag": { "type": [ "string", "null" ], "description": "共用收款地址等需要附加标识的网络，填写目标钱包 memo/tag，适用于 destino=cripto。" }, "chain": { "type": "string", "description": "交付网络，使用 GET /cashin/catalog 中的 ID。" }, "asset": { "type": "string", "description": "交付资产，如 usdt、usdc、btc 等。" }, "lunium_fee_bps": { "type": "integer", "description": "创建收款单时固定的比例费用，单位 bps。" }, "lunium_fee_fixed_cents": { "type": "integer", "description": "创建收款单时固定的费用，以分计。" }, "partner_fee_bps": { "type": "integer", "description": "创建收款单时保存的合作伙伴 sub fee。" }, "qr_copypaste": { "type": [ "string", "null" ], "description": "创建时返回的 Pix Copia e Cola，托管余额提现时为 null。" }, "qr_image_url": { "type": [ "string", "null" ], "description": "二维码 PNG 图片，仅在创建响应中提供。" }, "external_id": { "type": [ "string", "null" ], "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。", "maxLength": 64 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "该收款单的实际有效期，以此时间戳为准，也包括机器人延长的有效期。" }, "delay_until": { "type": [ "string", "null" ], "format": "date-time", "description": "服务商冻结的预计释放时间，如有。" }, "liberar_em": { "type": [ "string", "null" ], "format": "date-time", "description": "余额入账结束等待期的时间。即时可用时为 null，新密钥自2026年9月16日起默认采用即时释放，但仍须核对适用冻结规则。" }, "hold_hours": { "type": "integer", "description": "收款单本地冻结小时数，不等同于 held_hours 或余额的一般等待期。" }, "held_hours": { "type": "integer", "description": "向服务商请求的冻结时长。即使为零，也可能存在本地冻结 hold_hours/liberar_em。" }, "held": { "type": "boolean", "description": "held_hours > 0 时为 true，单独此字段不能反映本地冻结。" }, "sandbox": { "type": "boolean", "description": "模拟交易时为 true。" }, "simulation": { "type": "object", "additionalProperties": true }, "sandbox_payment": { "type": "object", "properties": { "method": { "const": "POST" }, "path": { "type": "string" } } }, "timeline": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "delivery_mode": { "type": "string", "enum": [ "full", "split" ], "description": "仅 chain=\"liquid\" 提供，说明 DePix 交付方式。其他网络无此字段。" }, "net_cents": { "type": "integer", "description": "仅 chain=\"liquid\" 且 delivery_mode=\"split\" 提供，表示扣费后收款人实际收到的 DePix，即 Lunium 链上发送金额。" }, "fee_total_cents": { "type": "integer", "description": "仅 chain=\"liquid\" 且 delivery_mode=\"split\" 提供，表示从总额扣除的固定及比例费用。net_cents + fee_total_cents == amount_cents。" } } }, "StatusCobranca": { "type": "object", "description": "收款单状态。GET 可能补充渠道、timeline 及 tempos_tipicos，列表与 webhook 使用基础对象。", "properties": { "cashin_id": { "type": "string", "description": "收款单标识，格式为 ci_…。" }, "status": { "type": "string", "description": "Pix 状态。paid 本身不证明入账 / 交付完成，须读取 settlement_status。", "enum": [ "pending", "delayed", "under_review", "paid", "expired", "refunded", "failed" ] }, "settlement_status": { "type": [ "string", "null" ], "description": "入账 / 交付状态：sent 表示完成；incerto 须对账。Pix 已付款与资产交付是不同状态。", "enum": [ "pending", "sending", "entregando", "sent", "incerto", "failed", null ] }, "amount_cents": { "type": "integer", "description": "Pix 金额，以分计。" }, "depix_received_cents": { "type": [ "integer", "null" ], "description": "从结算服务商收到、尚未扣除密钥充值费用的金额，不是托管净入账。" }, "usdt_amount": { "type": [ "string", "null" ], "description": "结算返回的旧版数量字段，须结合 asset 及路由专有字段理解。" }, "settlement_tx_hash": { "type": [ "string", "null" ], "description": "交付链上哈希，或交易所内部交付标识。" }, "settlement_tx_url": { "type": [ "string", "null" ], "description": "上述哈希的区块浏览器链接，如存在。" }, "payout_address": { "type": [ "string", "null" ], "description": "接收加密资产的钱包，适用于 destino=cripto。" }, "payout_tag": { "type": [ "string", "null" ], "description": "共用收款地址等需要附加标识的网络，填写目标钱包 memo/tag，适用于 destino=cripto。" }, "chain": { "type": "string", "description": "交付网络，使用 GET /cashin/catalog 中的 ID。" }, "asset": { "type": "string", "description": "交付资产，如 usdt、usdc、btc 等。" }, "payer_tax_number": { "type": "string", "description": "应支付二维码的付款人 CPF/CNPJ。不同证件付款将退款，refund_reason 为 PAYER_MISMATCH。" }, "external_id": { "type": [ "string", "null" ], "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。", "maxLength": 64 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "该收款单的实际有效期，以此时间戳为准，也包括机器人延长的有效期。" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "destino": { "type": "string", "description": "cripto 表示链上交付，saldo 表示计入密钥 BRL 托管余额，可通过 POST /payouts 及 POST /saldo/sacar-cripto 使用。", "enum": [ "cripto", "saldo" ] }, "held_hours": { "type": "integer", "description": "向服务商请求的冻结时长。即使为零，也可能存在本地冻结 hold_hours/liberar_em。" }, "held": { "type": "boolean", "description": "held_hours > 0 时为 true，单独此字段不能反映本地冻结。" }, "delay_until": { "type": [ "string", "null" ], "format": "date-time", "description": "服务商冻结的预计释放时间，如有。" }, "liberar_em": { "type": [ "string", "null" ], "format": "date-time", "description": "余额入账结束等待期的时间。即时可用时为 null，新密钥自2026年9月16日起默认采用即时释放，但仍须核对适用冻结规则。" }, "e2e": { "type": [ "string", "null" ], "description": "收到的 Pix EndToEndId，即巴西央行端到端标识。" }, "payer_name": { "type": [ "string", "null" ], "description": "用户填写或银行识别的付款人姓名。" }, "customer_ref": { "type": [ "string", "null" ], "description": "您的最终客户引用，即余额子账户。", "maxLength": 80 }, "refund_reason": { "type": [ "string", "null" ], "description": "status=refunded 时的退款原因，例如 PAYER_MISMATCH（付款证件不符）、TEST_AMOUNT（测试金额）或 PROVIDER_REJECTED。" }, "refund_reason_detail": { "type": [ "string", "null" ], "description": "便于人工阅读的退款原因。" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "trilho": { "type": "string", "description": "交易渠道：casa、corretora、saldo 或 liquid，不构成时效承诺。" }, "timeline": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tempos_tipicos": { "type": "object", "description": "按渠道统计的各阶段耗时中位数，单位秒，用于展示典型耗时，不是保证期限。", "additionalProperties": true }, "sandbox": { "type": "boolean", "description": "模拟交易时为 true。" }, "simulation": { "type": "object", "additionalProperties": true }, "delivery_mode": { "type": "string", "enum": [ "full", "split" ], "description": "仅 chain=\"liquid\" 提供，说明 DePix 交付方式。其他网络无此字段。" }, "net_cents": { "type": "integer", "description": "仅 chain=\"liquid\" 且 delivery_mode=\"split\" 提供，表示扣费后收款人实际收到的 DePix，即 Lunium 链上发送金额。" }, "fee_total_cents": { "type": "integer", "description": "仅 chain=\"liquid\" 且 delivery_mode=\"split\" 提供，表示从总额扣除的固定及比例费用。net_cents + fee_total_cents == amount_cents。" }, "settlement_proof": { "type": "string", "enum": [ "none", "broadcast", "confirmed", "reported", "simulated" ], "description": "独立于 Pix 付款的交付证据：none = 无已完成发送；broadcast = 已提供交易但尚无已记录确认；confirmed = 已记录确认凭证；reported = 已报告完成但无链上证明，包括托管入账 / 内部转账；simulated = 无真实资金的测试。没有确认记录不能证明失败，核验覆盖范围取决于网络及时间段。" }, "settlement_confirmed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "记录链上确认的时间，仅 settlement_proof=confirmed 时填写。" }, "settlement_block": { "type": "string", "nullable": true, "description": "已确认区块号，以字符串保存，避免精度损失。" } } }, "Payout": { "type": "object", "description": "从密钥托管余额扣款的 Pix 提现（Pix → Pix）。", "properties": { "payout_id": { "type": "string" }, "customer_ref": { "type": [ "string", "null" ], "maxLength": 80 }, "status": { "type": "string", "description": "processing、sent、failed 或 refunded，须通过流水核对余额，并兼容新增状态。" }, "amount_cents": { "type": "integer", "description": "收款人实际收到的金额。" }, "fee_cents": { "type": [ "integer", "null" ], "description": "amount_cents 之外的总费用：fee_service_total_cents + fee_provider_cents。已包含合作伙伴佣金，不要重复加上。" }, "fee_service_cents": { "type": [ "integer", "null" ], "description": "已保存的 Lunium 服务费，以分计，为会计组成项。客户界面及通知应使用 fee_service_total_cents。" }, "fee_provider_cents": { "type": [ "integer", "null" ], "description": "服务商费用：fee_cents 减去 fee_service_cents 及 fee_partner_cents。" }, "pix_key": { "type": "string" }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "phone", "email", "random" ] }, "tax_number": { "type": [ "string", "null" ], "description": "收款人证件经遮盖后的值，如有；请求中该字段为可选。" }, "external_id": { "type": [ "string", "null" ], "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。", "maxLength": 64 }, "error": { "type": [ "string", "null" ], "description": "failed/refunded 时的原因。" }, "e2e": { "type": [ "string", "null" ], "description": "已发送 Pix 的 EndToEndId。" }, "receiver_name": { "type": [ "string", "null" ], "description": "付款后取得的收款人姓名，如可用；未取得时为 null。" }, "receiver_tax_number": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "verify_url": { "type": [ "string", "null" ], "description": "公开 Pix 核验，GET /v1/verificar/{e2e}。" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "sandbox": { "type": "boolean", "description": "模拟交易时为 true。" }, "simulation": { "type": "object", "additionalProperties": true }, "fee_partner_cents": { "type": "integer", "nullable": true, "description": "本次提现从余额扣除的合作伙伴 sub fee，以分计，已包含在 fee_cents 中。" }, "fee_service_total_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "客户合并服务费，即交易保存的 Lunium 费用加合作伙伴佣金，保留原分位舍入及历史费率。旧记录中平台组成项未知时为 null。生产及测试环境的付款响应与 payout.* webhook data 均提供此字段。仅加一次 fee_provider_cents 即得 fee_cents，不再加 fee_partner_cents。" } } }, "ChaveMe": { "type": "object", "description": "您的密钥、当前限额及已启用能力。", "properties": { "key": { "type": "object", "properties": { "sandbox": { "type": "boolean" }, "key_id": { "type": "integer" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "创建密钥时填写的邮箱。测试密钥自2026年10月1日起须提供邮箱；旧版无邮箱密钥可为 null。" }, "cashin_enabled": { "type": "boolean" }, "cashout_enabled": { "type": "boolean" }, "payout_enabled": { "type": "boolean" }, "settlement_address": { "type": [ "string", "null" ], "description": "默认 Polygon 结算钱包，配置前为 null。" }, "chain": { "type": [ "string", "null" ] }, "fee_bps": { "type": "integer" }, "rate_limit_per_minute": { "type": "integer" }, "webhook_url": { "type": [ "string", "null" ], "description": "通过 PATCH /keys/me 配置前为 null；未配置接收端时，不会向您投递 cashin.paid、cashin.settled、cashin.delayed 等通知。" }, "webhook_configured": { "type": "boolean" }, "telegram_linked": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "partner_fee_bps": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "合作伙伴 sub fee，以 bps 表示，在 Lunium 的 fee_bps 之外另计。100 = 1%，由最终用户承担，不改变 Lunium 份额。0 表示不使用，通过 PATCH /keys/me 配置。" }, "partner_cashout_fee_bps": { "type": "integer", "description": "卖出交易的合作伙伴 sub fee，单位 bps，0 表示不使用。" }, "partner_saque_fee_bps": { "type": "integer", "description": "托管资金转出的合作伙伴 sub fee，单位 bps，0 表示不使用。" } } }, "limits": { "type": "object", "description": "当前密钥按单笔及付款人计算的限额与使用情况。每日限额为 null 仅表示没有该项上限，不代表不存在其他限制，仍可能适用 mandate 及个人限额。", "additionalProperties": true, "properties": { "cashin_min_por_rota": { "type": "object", "description": "各币种 / 网络的最低 BRL 金额，已考虑当前密钥费用。per_operation 中 cash-in 的 min_brl_cents 是账户最低金额，通常取决于固定费用；网络最低金额可能更高，实际取两者较大值。", "properties": { "nota": { "type": "string" }, "rotas": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "network": { "type": "string" }, "min_brl_cents": { "type": "integer" } } } } } } } }, "payout": { "type": "object", "description": "enabled、via、unlocks_at_settled_volume_cents、settled_volume_cents、remaining_cents。", "additionalProperties": true }, "monitor_url": { "type": "string", "description": "密钥的项目监控面板。" }, "telegram": { "type": "object", "additionalProperties": true }, "grupos_obrigatorios": { "type": "object", "description": "状态、合作伙伴及社区群组链接。", "additionalProperties": true }, "comissao": { "type": "object", "description": "Sub fee 累计佣金，即合作伙伴余额，详情见 GET /comissao。", "properties": { "partner_fee_bps": { "type": "integer" }, "max_partner_fee_bps": { "type": "integer" }, "disponivel_cents": { "type": [ "integer", "null" ] }, "creditado_cents": { "type": "integer" }, "estornado_cents": { "type": "integer" }, "sacado_cents": { "type": "integer" }, "operacoes": { "type": "integer" }, "ultimo_credito_em": { "type": [ "string", "null" ], "format": "date-time" }, "moeda": { "type": "string" }, "nota": { "type": "string" }, "partner_cashout_fee_bps": { "type": "integer" }, "partner_saque_fee_bps": { "type": "integer" } } } } }, "Catalogo": { "type": "object", "description": "Cash-out 卖出目录。", "properties": { "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "fast": { "type": "array", "description": "FAST 渠道的可用组合。充值 / Pix 时效取决于具体交易，不是固定 SLA。自2026年9月24日起包含平台 DEPIX/liquid 路由，该项目有独立 min、max、费用及时效。", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "network": { "type": "string" }, "min": { "type": "string", "description": "仅平台 DePix 路由提供，单笔最低 BRL 金额。" }, "max": { "type": "string", "description": "仅平台 DePix 路由提供，单笔最高 BRL 金额。" }, "precision": { "type": "integer" }, "fee_bps": { "type": "integer", "description": "此路由的 Lunium 费率，单位 bps。" }, "fee_fixed_cents": { "type": "integer", "description": "Lunium 固定费用，以分计。" }, "eta": { "type": "string" }, "nota": { "type": "string" } } } }, "dex": { "type": "object", "description": "DEX 长尾代币支持的网络及说明。", "additionalProperties": true }, "convert": { "type": "array", "description": "交易所渠道，每个资产列出支持网络。自2026年9月6日起包含 solana、tron，以及 XRP、XLM、ATOM、HBAR、KAVA、HIVE、STEEM、IOST 等共用地址网络；这些网络在接受报价后返回 deposit_tag。", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "networks": { "type": "array", "items": { "type": "string" } }, "min": { "type": "string", "description": "以本资产单位表示的最低金额，适用于该项目列出的网络。不要将 USDT/USDC 的 6 单位最低金额套用于 BTC、ETH 或其他资产，同时仍须满足交易最低 BRL 金额。" }, "max": { "type": "string", "description": "Convert 渠道以本资产单位表示的最高金额。实际上限可能因 BRL 限额、收款人当日剩余额度及 mandate 而降低。" }, "precision": { "type": "integer" }, "deposit_eta": { "type": "array", "description": "客户发送加密资产后的预估等待时间，按网络列出，适合在卖出界面展示。依据交易所要求的充值确认计算，不同于购买流程的提现时效。按预计由快到慢排序。", "items": { "type": "object", "properties": { "network": { "type": "string" }, "confirmations": { "type": "integer", "description": "交易所要求的确认数，例如 Base 为 1,000、Arbitrum 为 5,000、BSC 为 61。" }, "eta_seconds": { "type": "integer", "description": "预估秒数 = 确认数 × 网络出块时间，向上取整。" }, "eta": { "type": "string", "description": "相同时长的简短说明，例如“约 34 分钟”。" } }, "required": [ "network", "confirmations", "eta_seconds", "eta" ] } } } } } } }, "CatalogoCompra": { "type": "object", "description": "Cash-in 购买目录，即 Pix 收款后可交付的资产。", "properties": { "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "instant": { "type": "array", "description": "平台渠道路由，可能因配置为空，不保证始终存在或有固定时效。", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "network": { "type": "string" }, "eta": { "type": "string" }, "entregavel": { "type": "boolean" }, "min_brl_cents": { "type": "integer", "description": "当前路由可交付的最低 BRL 收款金额，已考虑密钥费用。与 POST /cashin/preview 的 min_brl_cents 及创建收款单的最低金额规则一致。尚未为该路由计算时可能缺失，此时应查询预览。自2026年9月24日起为 USDT 及 USDC 公布。" } } } }, "convert": { "type": "array", "description": "交易所渠道，每个资产 / 网络组合一行。", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "network": { "type": "string" }, "etaSeconds": { "type": "integer" }, "eta": { "type": "string" }, "fastest": { "type": "boolean" }, "withdrawFee": { "type": "string", "description": "交易所在该网络的提现费用，以资产单位表示，独立于 Lunium 及合作伙伴费用，已参与 minBuyAmount 计算。" }, "withdrawMin": { "type": "string", "description": "交易所在该网络的最低提现量，以资产单位表示，不是 cash-out 加密资产充值的最低金额。" }, "withdrawMax": { "type": "string", "description": "该网络公布的最高提现量，以资产单位表示，不能替代单笔 BRL、付款人、余额或 mandate 限制。字段缺失不代表无限额。" }, "minBuyAmount": { "type": "string", "description": "交易所路由须购买的最低资产数量，用于覆盖 withdrawMin + withdrawFee，不一定等于交付净额。使用当前密钥查询 POST /cashin/preview 的 min_brl_cents，费用及汇率会改变最低 BRL 金额。" }, "precision": { "type": "integer" }, "memoRequired": { "type": "boolean", "description": "共用地址网络，payout_tag 必填。" }, "entregavel": { "type": "boolean" }, "min_brl_cents": { "type": "integer", "description": "当前路由可交付的最低 BRL 收款金额，已考虑密钥费用。与 POST /cashin/preview 的 min_brl_cents 及创建收款单的最低金额规则一致。尚未为该路由计算时可能缺失，此时应查询预览。自2026年9月24日起为 USDT 及 USDC 公布。" } } } }, "dropped": { "type": "array", "description": "未纳入的组合及原因，例如 sem_par_usdt。", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "network": { "type": "string" }, "motivo": { "type": "string" } } } }, "totals": { "type": "object", "additionalProperties": true }, "stale": { "type": "boolean", "description": "目录来自备用缓存时为 true。" } } }, "Comissao": { "type": "object", "properties": { "disponivel_cents": { "type": "integer" }, "creditado_cents": { "type": "integer" }, "estornado_cents": { "type": "integer" }, "sacado_cents": { "type": "integer" }, "operacoes": { "type": "integer" }, "ultimo_credito_em": { "type": [ "string", "null" ], "format": "date-time" }, "moeda": { "type": "string" }, "sandbox": { "type": "boolean" }, "min_saque_cents": { "type": [ "integer", "null" ], "description": "按当前汇率折合 US$ 10 的 BRL 金额。null 表示当前无有效报价，提现会被拒绝。" }, "pode_sacar_agora": { "type": "boolean" }, "ultimo_saque_em": { "type": [ "string", "null" ], "format": "date-time" }, "proximo_saque_em": { "type": [ "string", "null" ], "format": "date-time" }, "politica": { "type": "object" } }, "required": [ "disponivel_cents", "creditado_cents", "sacado_cents", "operacoes", "moeda", "sandbox", "pode_sacar_agora", "politica" ] }, "ComissaoEvento": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "credito", "estorno", "saque", "saque_estorno" ] }, "valor_cents": { "type": "integer", "description": "带符号金额：入账 +、冲回 −、提现 −、提现退回 +。" }, "sentido": { "type": "string", "enum": [ "credito", "debito" ] }, "origem_id": { "type": "string", "description": "购买收款单或加密资产提现的 ci_…、Pix 提现的 po_…、卖出订单 UUID，或佣金提现 ID（kind 为 saque）。" }, "base_cents": { "type": "integer" }, "partner_fee_bps": { "type": "integer" }, "status": { "type": "string" }, "motivo": { "type": [ "string", "null" ], "description": "流水来源：空值表示购买，或为 'venda: cripto -> PIX'、'saida: saque por PIX'、'saida: saque em cripto'，也可能为冲回原因。原始取值按接口保留。" }, "criado_em": { "type": "string", "format": "date-time" } } }, "SaqueCripto": { "allOf": [ { "$ref": "#/components/schemas/Cobranca" }, { "type": "object", "properties": { "settlement_status": { "type": [ "string", "null" ], "description": "入账 / 交付状态：sent 表示完成；incerto 须对账。Pix 已付款与资产交付是不同状态。", "enum": [ "pending", "sending", "entregando", "sent", "incerto", "failed", null ] }, "settlement_tx_hash": { "type": [ "string", "null" ], "description": "交付链上哈希，或交易所内部交付标识。" }, "fee_cents": { "type": "integer", "description": "在 amount_cents 之外从余额另扣的平台提现费用。" }, "debited_cents": { "type": "integer", "description": "amount_cents 加平台提现费用。" } } } ], "properties": { "fonte": { "type": "string", "enum": [ "saldo" ] }, "settlement_status": { "type": "string" }, "fee_cents": { "type": "integer", "description": "从余额扣除的 Lunium 费用。" }, "partner_fee_cents": { "type": "integer", "description": "在 Lunium 费用之外，从余额另扣的合作伙伴 sub fee，自2026年9月24日起提供。" }, "debited_cents": { "type": "integer", "description": "amount_cents + fee_cents + partner_fee_cents。" } } }, "CarteiraUsdt": { "type": "object", "description": "项目 USDT 钱包状态与余额。", "properties": { "enabled": { "type": "boolean", "description": "钱包当前可操作。" }, "sandbox": { "type": "boolean", "description": "仅测试密钥模拟器提供，值为 true。" }, "funding_source": { "type": "string", "enum": [ "crypto_usdt" ] }, "currency": { "type": "string", "enum": [ "USDT" ] }, "pix_rules": { "type": "object", "properties": { "recipient_document_required": { "type": "boolean" } } }, "networks": { "type": "array", "description": "当前可充值网络、各网络支持的币种及预估入账时间。", "items": { "type": "object", "properties": { "network": { "type": "string", "example": "polygon" }, "name": { "type": "string", "example": "Polygon" }, "assets": { "type": "array", "items": { "type": "string", "enum": [ "USDT", "USDC" ] } }, "eta_minutes": { "type": [ "integer", "null" ] } } } }, "balance": { "type": "object", "properties": { "available": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "可用于 Pix 支付或加密货币提现的 USDT，6 位小数。" }, "reserved": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "正在进行的 Pix 支付和加密货币提现所预留的 USDT。" }, "confirming": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "已检测到、等待托管确认的充值。" } } }, "min_deposit": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "最低 USDT 充值金额。" }, "min_payment_brl": { "type": "string", "example": "25.00", "description": "使用 USDT 支付 Pix 的最低 BRL 金额。" }, "deposit_validity_hours": { "type": "number", "description": "充值请求有效期，以小时计，目前为 1。" }, "payments_enabled": { "type": "boolean" }, "withdrawals_enabled": { "type": "boolean", "description": "是否允许新提现；禁用新请求后，查询和跟踪仍继续。" }, "payment_methods": { "type": "object", "properties": { "pix_key": { "type": "boolean" }, "br_code": { "type": "boolean" } } } } }, "DepositoCarteira": { "type": "object", "description": "充值请求。实际到账的精确金额用于识别该笔充值，请在 expires_at 前，通过指定网络发送 amount_to_send。", "properties": { "deposit_id": { "type": "string", "example": "ud_3f9c0a1b2c3d4e5f6a7b" }, "status": { "type": "string", "enum": [ "waiting", "confirming", "available", "expired", "under_review", "reversed" ], "description": "waiting = 等待发送；confirming = 已检测到，确认中；available = 已计入余额；expired = 到期仍未充值；under_review = 核查中；reversed = 已撤销。" }, "amount_to_send": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "须发送的精确金额，末尾小数用于识别该笔充值。" }, "amount_received": { "type": [ "string", "null" ], "description": "实际收到并入账的金额。" }, "address": { "type": "string", "description": "所选网络的目标地址。测试环境为虚构地址 SANDBOX-NAO-ENVIE-FUNDOS，不得发送资金。" }, "network": { "type": "string" }, "network_name": { "type": "string" }, "asset": { "type": "string" }, "accepted_assets": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time", "description": "请求自创建起有效 1 小时，即 created_at + deposit_validity_hours，请在期限内发送。" }, "created_at": { "type": "string", "format": "date-time" }, "credited_at": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string", "enum": [ "request", "assigned_by_support" ] }, "instructions": { "type": "string", "description": "仅在创建响应中提供，供用户阅读的说明。" }, "sandbox": { "type": "boolean" } } }, "LancamentoCarteira": { "type": "object", "description": "流水记录。amount 始终为正数，由 type 表示方向。", "properties": { "entry_id": { "type": "string" }, "type": { "type": "string", "enum": [ "deposit", "reserve", "release", "debit", "reversal" ], "description": "deposit = 充值入账；reserve = Pix 或加密货币提现预留；debit = 操作完成；release = 预留款释放回可用余额；reversal = 充值撤销。" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "" }, "available_after": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "" }, "reserved_after": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "" }, "reference": { "type": "string", "description": "Pix 的 payment_id、加密货币提现的 withdrawal_id，或 deposit、adjustment。" }, "created_at": { "type": "string", "format": "date-time" }, "operation_type": { "type": "string", "enum": [ "deposit", "pix_payment", "crypto_withdrawal" ] } } }, "CotacaoPixCarteira": { "type": "object", "description": "使用 USDT 支付 Pix 的预览。仅为预估，确认时会重新报价，并最多额外预留 1%，未使用部分会释放。", "properties": { "payment_method": { "type": "string", "enum": [ "pix_key", "br_code" ] }, "brl_amount": { "type": "string", "example": "50.00" }, "usdt_order": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "用于支付 Pix 的 USDT 兑换金额。" }, "withdrawal_fee": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "发送成本。" }, "usdt_total": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "预估扣款总额。" }, "usdt_reserved": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "Pix 完成前的预留金额。" }, "quote_id": { "type": "string", "description": "仅使用 br_code 时提供，传入 POST /carteira-usdt/payments，确保支付的是同一完整支付码。" }, "merchant_name": { "type": [ "string", "null" ] }, "pix_key": { "type": [ "string", "null" ] }, "pix_key_type": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "note": { "type": "string" }, "sandbox": { "type": "boolean" }, "reserve_usd": { "type": [ "string", "null" ], "description": "R$ 1 运营预留款的 USDT 等值金额，报价时换算，已包含在总额中，不要重复加上。已有订单保留其原金额。", "example": "0.200000" }, "reserve_brl": { "type": [ "string", "null" ], "example": "1.00", "description": "新订单固定 R$ 1 运营预留款，已包含在总额中。旧订单保留原预留金额。" } } }, "PagamentoCarteira": { "type": "object", "description": "使用 USDT 余额支付的 Pix。", "properties": { "payment_id": { "type": "string", "example": "cu_8a7b6c5d4e3f2a1b0c9d" }, "external_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "reservado", "ordem_criada", "aceita", "sacando", "enviado", "revisao", "concluido", "falhou", "falhou_apos_envio" ], "description": "最终处理状态：concluido 表示 Pix 已付款；falhou 表示未执行、预留款已释放；falhou_apos_envio 表示发送后仍须核查，预留款不会自行释放。revisao 表示核查中，不等于失败，须继续跟踪。其他状态为处理中阶段。" }, "final": { "type": "boolean", "description": "状态不再继续变化时为 true。" }, "payment_method": { "type": "string", "enum": [ "pix_key", "br_code" ] }, "brl_amount": { "type": "string" }, "pix_key": { "type": [ "string", "null" ], "description": "已遮盖。" }, "usdt_reserved": { "type": "string", "pattern": "^-?\\d+\\.\\d{6}$", "description": "" }, "usdt_debited": { "type": [ "string", "null" ] }, "usdt_order": { "type": [ "string", "null" ] }, "withdrawal_fee": { "type": [ "string", "null" ] }, "cashout_id": { "type": [ "string", "null" ], "description": "支付该 Pix 的订单，详情见 GET /cash-outs/{cashout_id}。" }, "error": { "type": [ "string", "null" ] }, "pix_e2e": { "type": "string", "description": "仅 concluido 提供，Pix E2E 标识。" }, "recipient_name": { "type": "string", "description": "仅 concluido 提供，收款人姓名。" }, "recipient_document": { "type": [ "string", "null" ], "description": "仅 concluido 提供，按巴西央行方式部分遮盖的 CPF 或 CNPJ。" }, "receipt_url": { "type": [ "string", "null" ], "description": "仅 concluido 提供，官方凭证公开链接，测试环境为 null。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean" } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "当前密钥每分钟请求上限，即 rate_limit_per_minute。" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "当前时间窗口内剩余可请求次数。" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "请求配额完全恢复前的秒数。" }, "Retry-After": { "schema": { "type": "integer" }, "description": "仅 429 响应提供，表示重试前应等待的秒数。" } } }, "security": [ { "ApiKey": [] } ], "paths": { "/carteira-usdt/withdrawals/networks": { "get": { "tags": [ "USDT 钱包" ], "security": [ { "ApiKey": [] } ], "summary": "加密货币余额提现路径", "description": "仅使用当前返回的币种和网络组合；可充值不代表可提现。Polygon、BSC、Tron、Ethereum、Arbitrum、Optimism、Base、Avalanche 和 Solana 使用与充值相同的标识。Tron：USDT；Base：USDC。", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "USDT", "USDC" ] }, "network": { "type": "string", "enum": [ "polygon", "bsc", "tron", "eth", "arbitrum", "optimism", "base", "avalanche", "solana" ] }, "name": { "type": "string" }, "min_received": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "network_fee": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, "precision": { "type": "integer" } } } }, "funding_source": { "type": "string", "enum": [ "crypto_usdt" ] }, "fee_mode": { "type": "string", "enum": [ "deducted" ] } } } } } }, "400": { "description": "请求无效、网络不可用或金额低于最低限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "报价已过期、余额不足或 external_id 不一致。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "现有操作仍在跟踪中；请恢复同一请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt/withdrawals/quote": { "post": { "tags": [ "USDT 钱包" ], "security": [ { "ApiKey": [] } ], "summary": "不预留资金的提现预览", "description": "提供 USDT 总额（5–100000，最多两位小数）、币种、网络及外部地址。报价有效期为 120 秒，不预留资金。费用从总额中扣除；Polygon Gas 由 Lunium 支付。USDC 包含兑换及授权的最低净到账金额，允许相对估算值最高 0.5% 的波动。此 USDT 余额流程不收取额外服务费。BRL 余额提现费用不变。 测试密钥使用相同接口且不涉及真实资金：模拟费用 0.01；金额以 .01 结尾模拟核查，.02 模拟发送前失败，.05 模拟缓慢处理。测试哈希以 SANDBOX- 开头。列表仅返回最新 100 笔；仍可通过 ID 和 external_id 查询。", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CotacaoSaqueCriptoCarteira" } } } }, "400": { "description": "请求无效、网络不可用或金额低于最低限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "报价已过期、余额不足或 external_id 不一致。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "现有操作仍在跟踪中；请恢复同一请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "funding_source", "amount", "asset", "network", "address" ], "properties": { "funding_source": { "type": "string", "enum": [ "crypto_usdt" ] }, "amount": { "type": "string", "pattern": "^\\d{1,9}(?:\\.\\d{1,2})?$" }, "asset": { "type": "string", "enum": [ "USDT", "USDC" ] }, "network": { "type": "string", "enum": [ "polygon", "bsc", "tron", "eth", "arbitrum", "optimism", "base", "avalanche", "solana" ] }, "address": { "type": "string" } } } } } } } }, "/carteira-usdt/withdrawals": { "get": { "tags": [ "USDT 钱包" ], "security": [ { "ApiKey": [] } ], "summary": "列出加密货币提现", "description": "状态：reserved、funding、converting、processing、under_review、completed、failed。仅 completed/failed 为最终状态。结果不确定时继续预留余额。completed 要求发送已确认且存在 tx_hash；failed 仅凭未发送或链上回退证明解除预留。确认后无公共取消接口。签名 Webhook：wallet.withdrawal.completed / wallet.withdrawal.failed，data 与资源一致。即使 Webhook 延迟，也应通过 GET 查询。 测试密钥使用相同接口且不涉及真实资金：模拟费用 0.01；金额以 .01 结尾模拟核查，.02 模拟发送前失败，.05 模拟缓慢处理。测试哈希以 SANDBOX- 开头。列表仅返回最新 100 笔；仍可通过 ID 和 external_id 查询。", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SaqueCriptoCarteira" } } } } } } }, "400": { "description": "请求无效、网络不可用或金额低于最低限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "报价已过期、余额不足或 external_id 不一致。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "现有操作仍在跟踪中；请恢复同一请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } }, "post": { "tags": [ "USDT 钱包" ], "security": [ { "ApiKey": [] } ], "summary": "确认 USDT 余额提现", "description": "仅发送 funding_source、quote_id 和 external_id（8–64 个字符）。预留操作为原子操作，与 Pix 共用余额。201 表示创建；200 表示恢复。同一报价或活跃请求即使使用其他参考编号也不会生成重复提现。超时/5xx 后须保留请求体及 external_id，并查询 external/{external_id}。查询返回 404 不代表请求被拒绝：只能重试同一请求体，不得创建新参考编号。确认后不能更改网络或地址。 状态：reserved、funding、converting、processing、under_review、completed、failed。仅 completed/failed 为最终状态。结果不确定时继续预留余额。completed 要求发送已确认且存在 tx_hash；failed 仅凭未发送或链上回退证明解除预留。确认后无公共取消接口。签名 Webhook：wallet.withdrawal.completed / wallet.withdrawal.failed，data 与资源一致。即使 Webhook 延迟，也应通过 GET 查询。", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaqueCriptoCarteira" } } } }, "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaqueCriptoCarteira" } } } }, "400": { "description": "请求无效、网络不可用或金额低于最低限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "报价已过期、余额不足或 external_id 不一致。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "现有操作仍在跟踪中；请恢复同一请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "funding_source", "quote_id", "external_id" ], "properties": { "funding_source": { "type": "string", "enum": [ "crypto_usdt" ] }, "quote_id": { "type": "string", "pattern": "^uq_[a-f0-9]{24}$" }, "external_id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.:-]{7,63}$" } } } } } } } }, "/carteira-usdt/withdrawals/{withdrawal_id}": { "get": { "tags": [ "USDT 钱包" ], "security": [ { "ApiKey": [] } ], "summary": "查询加密货币提现", "description": "仅发送 funding_source、quote_id 和 external_id（8–64 个字符）。预留操作为原子操作，与 Pix 共用余额。201 表示创建；200 表示恢复。同一报价或活跃请求即使使用其他参考编号也不会生成重复提现。超时/5xx 后须保留请求体及 external_id，并查询 external/{external_id}。查询返回 404 不代表请求被拒绝：只能重试同一请求体，不得创建新参考编号。确认后不能更改网络或地址。 状态：reserved、funding、converting、processing、under_review、completed、failed。仅 completed/failed 为最终状态。结果不确定时继续预留余额。completed 要求发送已确认且存在 tx_hash；failed 仅凭未发送或链上回退证明解除预留。确认后无公共取消接口。签名 Webhook：wallet.withdrawal.completed / wallet.withdrawal.failed，data 与资源一致。即使 Webhook 延迟，也应通过 GET 查询。", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaqueCriptoCarteira" } } } }, "400": { "description": "请求无效、网络不可用或金额低于最低限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "报价已过期、余额不足或 external_id 不一致。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "现有操作仍在跟踪中；请恢复同一请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "parameters": [ { "name": "withdrawal_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/carteira-usdt/withdrawals/external/{external_id}": { "get": { "tags": [ "USDT 钱包" ], "security": [ { "ApiKey": [] } ], "summary": "使用原始参考编号恢复", "description": "仅发送 funding_source、quote_id 和 external_id（8–64 个字符）。预留操作为原子操作，与 Pix 共用余额。201 表示创建；200 表示恢复。同一报价或活跃请求即使使用其他参考编号也不会生成重复提现。超时/5xx 后须保留请求体及 external_id，并查询 external/{external_id}。查询返回 404 不代表请求被拒绝：只能重试同一请求体，不得创建新参考编号。确认后不能更改网络或地址。 状态：reserved、funding、converting、processing、under_review、completed、failed。仅 completed/failed 为最终状态。结果不确定时继续预留余额。completed 要求发送已确认且存在 tx_hash；failed 仅凭未发送或链上回退证明解除预留。确认后无公共取消接口。签名 Webhook：wallet.withdrawal.completed / wallet.withdrawal.failed，data 与资源一致。即使 Webhook 延迟，也应通过 GET 查询。", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaqueCriptoCarteira" } } } }, "400": { "description": "请求无效、网络不可用或金额低于最低限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "报价已过期、余额不足或 external_id 不一致。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "现有操作仍在跟踪中；请恢复同一请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "parameters": [ { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/leads": { "post": { "tags": [ "Contato" ], "operationId": "contactIntegrationTeam", "summary": "将商务或技术问题转交人工", "description": "公开接口，无需密钥，仅用于按量报价、合同、合作或文档未解决的场景。联系方式须由本人为本次联系提供，不应搜索、抓取或挪用其他用途的邮箱。无需人工联系即可开始测试：POST /keys/sandbox。", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "consentimento" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "nome": { "type": "string", "maxLength": 120 }, "empresa": { "type": "string", "maxLength": 120 }, "whatsapp": { "type": "string", "maxLength": 40 }, "mensagem": { "type": "string", "maxLength": 1000 }, "fluxo": { "type": "string", "enum": [ "cashin", "cashout", "cashin_cashout", "payout", "outro", "custody" ] }, "volume_mensal": { "type": "string", "maxLength": 60 }, "prazo": { "type": "string", "maxLength": 60 }, "estagio_produto": { "type": "string", "maxLength": 60 }, "como_encontrou": { "type": "string", "description": "用户自行申报的来源，与 UTM 分开，例如 chatgpt、google、indicacao。" }, "consentimento": { "type": "boolean", "const": true, "description": "确认用户提供联系方式，以接收对此次请求的回复。" }, "origem": { "type": "string", "description": "请求开始时所在页面或业务背景。" }, "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_content": { "type": "string" }, "utm_term": { "type": "string" }, "ref_agent": { "type": "string" }, "website": { "type": "string", "description": "反垃圾隐藏字段，正常客户端应省略或留空。" } } }, "examples": { "empresa_vinda_do_chatgpt": { "value": { "email": "integracao@empresa.com.br", "empresa": "Empresa Exemplo", "fluxo": "cashin_cashout", "volume_mensal": "R$ 250 mil a R$ 1 milhão", "prazo": "Neste mês", "como_encontrou": "chatgpt", "consentimento": true, "utm_source": "chatgpt", "utm_medium": "answer" } } } } } }, "responses": { "200": { "description": "在去重时间窗口内更新已有联系人。用户明确同意时，返回新的 lead_token，并使旧 token 失效。", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "lead_id": { "type": "integer", "format": "int64" }, "lead_token": { "type": "string", "pattern": "^ldt_[A-Za-z0-9_-]{43}$", "minLength": 47, "maxLength": 47, "description": "用户明确同意后返回的不透明归因 token，仅发送至 POST /keys、POST /keys/sandbox 或 lunium_start_sandbox_demo，绝不放入 URL 或日志。" }, "detail": { "type": "string" }, "integration_url": { "type": "string", "format": "uri", "description": "立即开始自助接入，人工联系为可选。" } } } } } }, "201": { "description": "联系请求已收到。用户明确同意时，可通过 lead_token 将此联系人关联至后续创建的密钥。", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "lead_id" ], "properties": { "ok": { "type": "boolean", "const": true }, "lead_id": { "type": "integer", "format": "int64" }, "lead_token": { "type": "string", "pattern": "^ldt_[A-Za-z0-9_-]{43}$", "minLength": 47, "maxLength": 47, "description": "用户明确同意后返回的不透明归因 token，仅发送至 POST /keys、POST /keys/sandbox 或 lunium_start_sandbox_demo，绝不放入 URL 或日志。" }, "detail": { "type": "string" }, "integration_url": { "type": "string", "format": "uri", "description": "立即开始自助接入，人工联系为可选。" } } } } } }, "400": { "description": "邮箱或请求体无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "同一地址尝试次数过多。", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "503": { "description": "无法保存联系请求，请重试或使用公开支持邮箱。" } }, "externalDocs": { "description": "获取测试密钥及联系接入团队的页面", "url": "https://luniumpay.com/integrar?utm_source=openapi&utm_medium=spec" } } }, "/v1/verificar/{e2e}": { "get": { "tags": [ "Verificação" ], "operationId": "verificarPagamento", "security": [], "summary": "公开核验 Pix 付款，无需密钥", "description": "用于独立核验声称已支付的 Pix，无需账户或密钥。不返回 Pix 标识、完整姓名或完整证件，在保护相关主体资料的同时证明付款。未查到时会明确说明可能由其他机构完成，因此这里不存在记录不代表付款从未发生。", "parameters": [ { "name": "e2e", "in": "path", "required": true, "schema": { "type": "string" }, "description": "巴西央行端到端标识：E + 32 个字符。", "example": "E37293930202607312006361894c4a82" } ], "responses": { "200": { "description": "该付款由 Lunium 结算。", "content": { "application/json": { "schema": { "type": "object", "properties": { "verificado": { "type": "boolean" }, "pago": { "type": "boolean" }, "e2e": { "type": "string", "description": "原样返回的巴西央行端到端标识，由字母 E 及凭证代码组成。任何第三方均可通过同一接口重新核验。" }, "valor_brl": { "type": "string" }, "pago_em": { "type": "string", "format": "date-time", "example": "2026-08-01T22:35:49-03:00", "description": "含明确时区偏移的 ISO 8601 时间，采用巴西利亚时间。不要默认 UTC 或设备本地时间，应使用返回的偏移。" }, "recebedor_iniciais": { "type": [ "string", "null" ] }, "instituicao": { "type": [ "string", "null" ] }, "liquidado_por": { "type": "string" }, "comprovante_url": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "未由 Lunium 结算，也可能由其他机构完成。" }, "400": { "description": "格式无效。" } }, "x-lunium-capability": [ "payment_verification" ], "x-lunium-intents": [ "verify_payment", "prove_settlement" ], "x-lunium-agent-safe": true } }, "/catalog": { "get": { "tags": [ "Catálogo" ], "operationId": "obterCatalogo", "summary": "当前可结算的资产、网络及限额", "description": "Cash-out 加密资产入金目录。使用当前返回的组合、最低 / 最高金额及时效预估，不固定保存网络列表。fast、convert、dex 为不同渠道，与 /cashin/catalog 交付目录的可用性不同。接受报价返回 deposit_tag 时，充值必须一并填写。stale=true 表示备用缓存。使用 lun_test_ 时，fast 中的 DEPIX/liquid 为模拟路由，可通过 asset=DEPIX&network=liquid 筛选。", "responses": { "200": { "description": "当前目录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalogo" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cash-outs": { "post": { "tags": [ "Cash-out" ], "operationId": "criarCotacao", "summary": "创建报价（第 1 / 3 步）", "description": "创建外部加密资产兑换 Pix 的报价，充值地址仅在 accept 后提供。选择 GET /catalog 的有效组合及三种请求方式之一：amount + pix_key、brl_amount + pix_key，或完整 br_code（不另传金额及收款人字段）。金额为十进制字符串。通过 GET /keys/me 查询密钥 / 单笔限额，并核对响应的实际收款人限额；mandate 可能进一步限制。br_code 须为兼容 USDT/USDC 路由，预览或创建均可能返回 503 br_code_indisponivel。测试环境不证明生产可用性；生产创建返回 200，测试可能返回 201。相同 external_id 仅用于原请求，冲突时查询 recovery_endpoint 指向的订单。DePix/Liquid 同样支持 amount 或 brl_amount；邮箱、手机号或随机 Pix 标识须提供收款人 CPF/CNPJ，即 payee_tax_number。refund_address 自 1.44.0 起可选；需要退款但缺少钱包时，订单进入 AWAITING_REFUND_ADDRESS，并发送 cashout.awaiting_refund_address，直至通过 POST /cash-outs/{cashout_id}/refund-address 提交客户 Liquid 钱包。测试 DePix 按 BRL 平价及密钥卖出费率模拟，accept 后自动模拟充值，约 14 秒完成。绝不向 SANDBOX:LIQUID:NAO_ENVIAR: 地址发送真实资产。指南：https://docs.luniumpay.com/zh/sandbox#depix-pix 。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "network" ], "properties": { "asset": { "type": "string", "examples": [ "USDT", "DEPIX" ], "description": "卖出的资产。必须使用 GET /catalog 中完全一致的 id，例如 \"usdt\"。须与 network 组合使用，且 (asset, network) 必须存在于目录。" }, "network": { "type": "string", "description": "GET /catalog 列出的加密资产入金网络，不同于 /cashin/catalog 的交付网络。", "examples": [ "polygon", "liquid" ] }, "amount": { "type": "string", "description": "加密资产数量，十进制字符串，例如 \"50\"，不要使用浮点数。不能同时传 brl_amount 或 br_code，此方式创建订单时须提供 pix_key。", "examples": [ "50" ] }, "brl_amount": { "type": "string", "description": "反向报价的目标 BRL 金额，最多两位小数的字符串，例如 \"250.00\"。不能同时传 amount 或 br_code，创建时须提供 pix_key。响应返回精确加密资产充值量及实际 BRL 金额，后者可能因舍入与目标略有差异。接受前展示返回金额，最低金额及限额以路由、密钥及收款人当前条件为准。", "examples": [ "250.00" ] }, "pix_key": { "type": "string", "description": "接收 BRL 的 Pix 标识。格式由 API 规范化为服务商要求，不符合时在创建充值前返回 400 pix_key_invalida。支持 CPF 11 位、CNPJ 14 位、+55 国际格式手机号（如 +5548996005588）、邮箱，或 UUID 随机标识（如 6602ede6-b1a9-4e63-9178-c6883fd0095e）。" }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "phone", "email", "random" ], "description": "可选，通常根据收款标识格式推断，如邮箱、CNPJ、UUID 或带 +55 的手机号。若为 11 位纯数字，无法区分 CPF 与手机号，则必须填写，否则返回 tipo_ambiguo，不会擅自猜测。" }, "token_address": { "type": "string", "description": "精确合约地址 / mint。/catalog/dex 代币可能有相同符号，因此必须明确地址。" }, "external_id": { "type": "string", "description": "每个业务意图的持久标识，最多 64 个字符。相同请求体重试复用原订单；更改网络、资产、token、目的地、Pix 类型、金额或退款钱包会产生 409 冲突。须先恢复原订单，再决定是否新建。旧订单若缺少可验证请求身份，可能须按 cashout_id/external_id 恢复。", "maxLength": 64 }, "refund_address": { "type": "string", "description": "客户确认并控制的退款钱包，须符合退款网络。不能根据充值链上来源自动推断。未提供钱包时，流程可能停留于 AWAITING_REFUND_ADDRESS；请查询返回的 refund_asset、refund_network 及 refund_amount。DePix 卖出自 1.44.0 起也为可选，此前必填；如提供，须为客户有效的 Liquid 地址（lq1…），测试环境同样要求格式有效。", "examples": [ "0x51e3d44172868acc60d68ca99591ce4230bc75e0" ] }, "br_code": { "type": "string", "description": "已启用时可提交带固定金额的 Pix Copia e Cola，支持兼容的 USDT/USDC 路由，替代 pix_key、amount 及 brl_amount。生产可能返回 503 br_code_indisponivel。报价 amount 已包含固定 R$ 1 运营预留款（reserve_brl，其 USDT 等值见 copia_e_cola_buffer_usd），用于确保按二维码精确金额付款；剩余部分由 Lunium 留作修正预留，不退还。客户粘贴或扫描了带金额的静态 / 动态二维码时，须发送完整 br_code，不能仅提取 pix_key + brl_amount，否则可能无法保留原收款单 txid 或精确金额，收款方可能无法匹配。", "examples": [ "00020126330014br.gov.bcb.pix0111498113948905204000053039865406…6304ABCD" ], "minLength": 40, "maxLength": 512 }, "sandbox_scenario": { "type": "string", "enum": [ "success", "delayed", "failed", "expired", "refunded", "settlement_uncertain", "provider_unavailable", "route_unavailable", "no_deposit" ], "description": "仅用于测试环境 DePix/Liquid，优先于金额小数触发条件。未明确指定场景时，.01 至 .08 触发仍有效。生产密钥返回 403 sandbox_only，场景见 GET /sandbox。" }, "payee_tax_number": { "type": "string", "description": "DePix/Liquid 收款人的 CPF（11 位）或 CNPJ（14 位）。email、phone 或 random 类型 Pix 标识必填；cpf/cnpj 类型直接使用标识本身的证件。生产不得使用虚构证件。" } }, "oneOf": [ { "required": [ "pix_key", "amount" ], "not": { "anyOf": [ { "required": [ "brl_amount" ] }, { "required": [ "br_code" ] } ] } }, { "required": [ "pix_key", "brl_amount" ], "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "br_code" ] } ] } }, { "required": [ "br_code" ], "not": { "anyOf": [ { "required": [ "amount" ] }, { "required": [ "brl_amount" ] }, { "required": [ "pix_key" ] }, { "required": [ "pix_key_type" ] } ] } } ] }, "examples": { "usdt": { "summary": "Polygon 上的 USDT", "value": { "asset": "USDT", "network": "polygon", "amount": "50", "pix_key": "12345678901", "pix_key_type": "cpf", "refund_address": "0x51e3d44172868acc60d68ca99591ce4230bc75e0", "external_id": "saque-4471" } }, "reverso": { "summary": "按目标 BRL 金额反向报价", "value": { "asset": "USDT", "network": "polygon", "brl_amount": "250.00", "pix_key": "vendas@loja.com.br", "external_id": "pedido-9921" } }, "cobranca": { "summary": "使用兼容目录路由的 USDT/USDC 支付二维码 / Copia e Cola", "value": { "asset": "USDC", "network": "polygon", "br_code": "00020126330014br.gov.bcb.pix0111498113948905204000053039865406…6304ABCD", "refund_address": "0x51e3d44172868acc60d68ca99591ce4230bc75e0", "external_id": "pedido-9922" } }, "depix_sandbox": { "summary": "模拟 DePix → Pix，仅限 lun_test_ 密钥，请替换退款钱包", "value": { "asset": "DEPIX", "network": "liquid", "amount": "100.00", "pix_key": "depix@example.invalid", "pix_key_type": "email", "payee_tax_number": "12345678901", "refund_address": "SUA_CARTEIRA_LIQUID_DE_DEVOLUCAO", "external_id": "sandbox-depix-pix-001", "sandbox_scenario": "success" } } } } } }, "responses": { "201": { "description": "报价已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashOut" } } } }, "200": { "description": "报价已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashOut" } } } }, "400": { "description": "请求无效或网络不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "该 external_id 已用于其他参数。" }, "422": { "description": "参数语义无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "sandbox_scenario 须使用测试密钥，未创建订单。" }, "503": { "description": "服务不可用。测试场景 provider_unavailable 不创建订单。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-lunium-capability": [ "usdt_to_pix", "usdc_to_pix", "crypto_to_pix" ], "x-lunium-intents": [ "sell_crypto", "receive_fiat", "offramp", "cash_out" ], "x-lunium-reward-eligible": true }, "get": { "tags": [ "Cash-out" ], "operationId": "listarCashOuts", "summary": "列出订单", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "external_id", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "幂等恢复：返回该 external_id 对应的交易，结果为 0 或 1 笔。标识在同一密钥及产品内唯一，区分大小写，并永久保留。" } ], "responses": { "200": { "description": "当前密钥的订单，最新记录在前。" }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cash-outs/{cashout_id}/accept": { "post": { "tags": [ "Cash-out" ], "operationId": "aceitarCotacao", "summary": "接受报价并取得地址（第 2 / 3 步）", "description": "锁定报价并返回 deposit_address。须发送精确报价数量；需要 memo/tag 时会在 deposit_tag 返回，缺少附加标识可能导致无法识别或找回充值。", "parameters": [ { "name": "cashout_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "充值地址。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashOut" } } } }, "404": { "description": "未找到订单。" }, "422": { "description": "报价已过期或已接受。" }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cash-outs/{cashout_id}": { "get": { "tags": [ "Cash-out" ], "operationId": "consultarCashOut", "summary": "跟踪订单（第 3 / 3 步）", "description": "优先使用 webhook。如需轮询，建议每 10–15 秒一次；每秒一次会独占密钥每分钟 60 次请求额度。COMPLETED 表示付款完成，pix_e2e、pix_paid_at 及凭证链接可能稍后提供。展示当前可用字段，并继续跟踪同一订单或 cashout.receipt_ready。暂时没有凭证不是新建付款的理由。", "parameters": [ { "name": "cashout_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "当前状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashOut" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cashin/charge": { "post": { "tags": [ "Cash-in" ], "operationId": "criarCobranca", "summary": "创建 Pix 收款单，用于 BRL 托管或加密资产交付", "description": "创建 Pix 收款单，用于 BRL 托管（destino=saldo，无需钱包）或直接交付加密资产（destino=cripto，默认）。填写实际付款人的证件，查询 GET /cashin/limits 及密钥条件。实际最低金额由限额、费用及服务商共同决定，创建时会重新校验。资金可能由服务商冻结（held_hours/delay_until），也可能在本地冻结（hold_hours/liberar_em）。Pix 为 paid 不代表交付 / 入账已完成，须跟踪 settlement_status 及流水。测试环境生成不可真实付款的二维码，通过 POST /sandbox/cashin/{cashin_id}/pay 确认，不产生银行交易。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents", "payer_tax_number" ], "properties": { "amount_cents": { "type": "integer", "description": "收款金额，以整数 BRL 分计，例如 15000 = R$ 150.00。创建前查询 GET /cashin/limits，获取付款人当前无需冻结及需要冻结的额度区间。", "examples": [ 25000 ] }, "chain": { "type": "string", "default": "polygon", "description": "交付路由的网络，将目录中的 network 值填入此 chain 字段。" }, "asset": { "type": "string", "default": "usdt", "description": "GET /cashin/catalog 中可交付路由的资产，不限于稳定币。" }, "payout_address": { "type": "string", "description": "destino=cripto 时为该收款单的钱包，省略时可能使用密钥的 settlement_address；destino=saldo 时应省略。地址必须符合所选网络。" }, "payer_tax_number": { "type": "string", "description": "付款人 CPF（11 位）或 CNPJ（14 位），仅数字。用于识别付款人，并计算 GET /cashin/limits 公布的反欺诈限额与冻结条件。" }, "external_id": { "type": "string", "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。", "maxLength": 64 }, "destino": { "type": "string", "enum": [ "cripto", "saldo" ], "default": "cripto", "description": "saldo 将扣费后的净额计入 BRL 托管余额，无需钱包；cripto（默认）交付至所填或已配置的钱包。费用及等待期见 GET /saldo，冻结条件见收款单创建响应及状态。" }, "customer_ref": { "type": "string", "maxLength": 80, "description": "可选余额子账户，即您的最终客户 ID。destino: \"saldo\" 时入账至该子账户；GET /saldo?customer_ref= 查询，POST /payouts 使用相同 customer_ref 支出。省略时使用密钥主账户。" }, "allow_hold": { "type": "boolean", "default": true, "description": "false 会拒绝需要按付款人分级规则冻结的收款单，不会移除密钥的其他冻结或限制。true 或省略时允许适用冻结。须同时读取 held_hours 及 hold_hours/liberar_em。" }, "payout_tag": { "type": "string", "maxLength": 120, "description": "目标 memo/tag。XRP、XLM、TON、ATOM、HBAR、ALGO、EOS、KAVA、LUNA 等共用地址网络须提供，以识别实际收款人。缺少时，创建收款单前返回 400 memo_obrigatorio。XRP 使用 destination tag，为 0 至 4294967295 的整数。支持 memo、tag、destination_tag 别名，目录以 memoRequired: true 标记。" }, "payer_name": { "type": "string", "description": "付款人姓名，如提供。" }, "sandbox_scenario": { "type": "string", "enum": [ "success", "delayed", "held", "expired", "refunded", "failed", "payer_mismatch", "settlement_failed", "settlement_uncertain", "route_unavailable", "provider_unavailable" ], "description": "仅用于测试密钥。GET /sandbox 提供各流程的场景矩阵，生产环境应省略。价格、付款及提现均为模拟结果。" }, "delivery_mode": { "type": "string", "enum": [ "full", "split" ], "default": "full", "description": "仅 chain=\"liquid\"（DePix）适用。full 直接向指定钱包交付全部 DePix，不从中扣除密钥费用。split 采用接收再转发：Lunium 接收后扣除密钥的固定及比例费用，再向 payout_address 发送净额，响应 net_cents 即收款人实际接收金额。split 必须提供 payout_address。省略此字段时，以密钥的实际默认配置为准。" } } } } } }, "responses": { "200": { "description": "收款单已创建，向客户展示 qr_copypaste 中的 Pix 支付码。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cobranca" } } } }, "403": { "description": "超过付款人限额（limite_do_pagador），或 Lunium 对此接入阻止该付款人（pagador_bloqueado，不创建收款单，不要使用同一 CPF/CNPJ 循环重试）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "400": { "description": "参数无效、金额超限，或当前密钥不可使用 cash-in。valor_abaixo_do_minimo：所选币种 / 网络有独立最低金额，响应中的 minimo_estimado_cents 表示预估起点，在任何资金操作前校验。memo_obrigatorio：网络要求 memo/tag，但未提供或格式无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "502": { "description": "provedor_indisponivel（acao: repetir）表示 Pix 结算服务商未能生成二维码，未创建收款单。请等待几分钟，以相同 external_id 重试原请求。此 HTTP 状态下有两类错误，处理不同：provedor_indisponivel（acao 为 repetir 或 esperar）通常为结算服务暂时不稳定；config_provedor（acao 为 falar_com_suporte）表示我方收款标识、凭证或服务商账户配置有误，单纯等待或重试不能解决。两种情况均未创建收款单。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "catalogo_indisponivel / cotacao_indisponivel：交易所当前无有效报价，可重试。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "external_id 与已有请求不一致。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-lunium-capability": [ "pix_to_usdt", "pix_to_usdc" ], "x-lunium-intents": [ "buy_crypto", "onramp", "fiat_to_crypto" ], "x-lunium-reward-eligible": true } }, "/keys": { "post": { "tags": [ "Conta" ], "operationId": "criarChave", "security": [], "summary": "自助创建密钥", "description": "完整密钥只显示一次，请在创建时保存，平台仅保存哈希。响应也提供跟踪群组，接口契约变更会在上线前于相应渠道公告。", "responses": { "201": { "description": "密钥已创建。", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "description": "明文密钥，仅本次响应提供，平台只保存哈希。" }, "email_sent": { "type": "boolean", "description": "成功将密钥副本发送至所填 email 时为 true；未填邮箱或发送失败时为 false。" }, "webhook_secret": { "type": "string", "description": "提供 webhook_url 时出现。" }, "key": { "type": "object", "description": "密钥公开视图：prefix、name、flags。" }, "limits": { "type": "object", "description": "当前有效限额。" }, "monitor_url": { "type": "string", "format": "uri", "description": "当前密钥交易流程的只读实时监控。" }, "lead_attribution": { "type": "object", "description": "提交已获同意的 lead_token 后，返回归因关联结果，绝不阻止密钥创建。", "required": [ "requested", "linked", "status" ], "properties": { "requested": { "type": "boolean", "description": "请求体中提供了 lead_token 时为 true。" }, "linked": { "type": "boolean", "description": "密钥已关联至获同意的联系请求时为 true。" }, "status": { "type": "string", "enum": [ "nao_solicitado", "vinculado", "token_invalido", "indisponivel" ], "description": "关联状态。" } } } } } } } }, "400": { "description": "字段无效：name 必填，webhook_url 须为公开 HTTPS 地址。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "已达到该 IP 的密钥创建限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80, "description": "企业或项目名称，将显示在控制台及通知中。" }, "email": { "type": "string", "format": "email", "description": "建议提供邮箱，新密钥除在响应中显示外，也会发送至此邮箱。" }, "settlement_address": { "type": "string", "description": "EVM（Polygon）结算钱包，可选，也可之后设置。" }, "webhook_url": { "type": "string", "format": "uri", "description": "用于接收事件的 HTTPS URL，可选。" }, "lead_token": { "type": "string", "pattern": "^ldt_[A-Za-z0-9_-]{43}$", "minLength": 47, "maxLength": 47, "description": "用户同意技术联系后，由 POST /leads 返回的 ldt_… 不透明 token，将此密钥关联至联系请求。仅放请求体，不放 URL。可选，缺失或无效不阻止创建。" } } } } } } } }, "/keys/me": { "get": { "tags": [ "Conta" ], "operationId": "consultarConta", "summary": "当前限额及当日使用量", "description": "限额须通过本接口读取，不应固定写入代码。Cash-out：单笔 R$ 6.00 至 R$ 250,000.00；Pix 收款人按 CPF/CNPJ 每日最高 R$ 100,000.00，非证件类型则按 Pix 收款标识计算，于巴西利亚时间午夜重置。实际上限取较小值，见 limits.max_brl_cents；单笔总上限见 limits.max_brl_cents_por_transacao。卖出没有 API 密钥每日总额度。Cash-in 与 Pix 对外付款自2026年9月10日起也无密钥每日总额度：limits.daily_limit_cents 为 null，limits.tier 为 \"Sem teto\"，limits.available_today_cents 与 limits.next_tier 为 null，limits.daily_limit_applies_to 为 []。收款单全局范围为 R$ 1.00 至 R$ 6,000.00，实际最低金额见 limits.per_operation.cashin.min_brl_cents，并适用 GET /cashin/limits 的付款人规则。密钥自身仍可通过 mandate.max_diario_cents 设置每日限制。", "responses": { "200": { "description": "您的密钥信息及限额。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChaveMe" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新密钥配置：名称、结算、webhook 及凭证轮换", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "settlement_address": { "type": [ "string", "null" ], "description": "Polygon 地址，格式为 0x…；null 表示清除。" }, "webhook_url": { "type": [ "string", "null" ], "description": "公开 HTTPS 地址，null 表示清除。如密钥尚无 webhook_secret，设置 URL 时会生成。" }, "rotate_webhook_secret": { "type": "boolean", "description": "true 表示轮换 webhook 签名密钥，新值仅在响应中显示一次。" }, "rotate_monitor_token": { "type": "boolean", "description": "true 表示轮换监控 token。自本次调用起，旧 URL 无法再查看数据，新 URL 返回于 monitor_url。" }, "partner_fee_bps": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "合作伙伴 sub fee，以 bps 表示，另加于 Lunium 费用，由最终用户承担。100 = 1%，最高 1000 = 10%。仅影响新建收款单，已有收款单保留创建时费率；0 表示关闭。" }, "partner_cashout_fee_bps": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "加密资产 → Pix 卖出的合作伙伴 sub fee，单位 bps，在 Lunium 费用之外另计。订单创建时固定，仅影响新订单，不适用于二维码 Copia e Cola 卖出。0 表示关闭。" }, "partner_saque_fee_bps": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "托管转出佣金，包括 POST /payouts 的 Pix 提现及 POST /saldo/sacar-cripto 的加密资产提现，单位 bps，在平台费用之外从余额另扣，提现完成后计入佣金。0 表示关闭。" } } } } } }, "responses": { "200": { "description": "密钥已更新，可能包含仅显示一次的 webhook_secret，以及新的 monitor_url。" }, "400": { "description": "字段无效或没有可更新的内容。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "updateMyKey" } }, "/ping": { "get": { "tags": [ "Conta" ], "operationId": "ping", "security": [], "summary": "API 健康状态", "responses": { "200": { "description": "pong" } } } }, "/keys/sandbox": { "post": { "summary": "一次调用获取测试密钥，无需已有 API 密钥", "description": "一次调用返回 lun_test_ 密钥，无需审批、已有 API 密钥或钱包。email 必填，须为测试人员邮箱。约一分钟后，LuniumPay 支持团队发送一次介绍邮件，包含平台介绍、三步接入、手册及 PDF、流程图与 VendaCripto（无需接入即可使用 Pix 买卖加密资产的应用）；每个邮箱仅一次，附退订链接。邮箱缺失或无效返回 400 email_obrigatorio（acao=corrigir，campo=email）。六类资金流程均通过常规接口使用虚拟资金模拟。GET /sandbox 返回流程、场景矩阵及控制；POST /sandbox/cashin/{cashin_id}/pay 确认不可真实付款的测试收款单。Cash-in、托管余额及对外付款持久保存，cash-out 保留 2 小时。签名 webhook 使用正常投递队列，带 sandbox:true。不调用金融服务商，目录及价格为模拟快照，非实时报价。详见 https://docs.luniumpay.com/zh/sandbox 。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 160, "description": "必填，测试人员邮箱，例如 you@company.com。LuniumPay 支持团队向该地址发送一封接入邮件，包含平台介绍、三步接入、手册及 PDF、流程图及 VendaCripto。每个地址仅发送一次，并附退订链接。" }, "name": { "type": "string", "description": "可选标签，便于之后识别密钥。" }, "webhook_url": { "type": "string", "format": "uri", "description": "可选 HTTPS webhook。" }, "lead_token": { "type": "string", "pattern": "^ldt_[A-Za-z0-9_-]{43}$", "description": "可选，为用户同意后 POST /leads 返回的不透明 token，用于将此测试密钥关联至联系人。归因无效或不可用不会阻止创建密钥。不要将 token 放入 URL 或日志。" } } } } } }, "responses": { "201": { "description": "测试密钥已创建", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "example": "lun_test_1df82296e3459819702c6a6087aab1c7" }, "sandbox": { "type": "boolean", "const": true }, "gatilhos": { "type": "object", "description": "上述确定性测试触发条件。" }, "diferencas_para_producao": { "type": "array", "items": { "type": "string" } }, "lead_link": { "type": "object", "properties": { "requested": { "type": "boolean" }, "linked": { "type": "boolean" }, "status": { "type": "string" } } } } } } } }, "400": { "description": "email_obrigatorio：邮箱缺失或无效。请提供测试人员邮箱，例如 {\"email\": \"you@company.com\"}。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "erro": "email_obrigatorio", "acao": "corrigir", "campo": "email", "detail": "Informe o e-mail de quem vai testar: {\"email\": \"voce@empresa.com\"}. É por ele que mandamos o manual, o fluxograma e o passo a passo da integração." } } } }, "429": { "description": "该 IP 今日创建密钥过多", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "createSandboxKey" } }, "/cashin/limits": { "get": { "summary": "查询该付款人当前可支付金额", "description": "按 CPF/CNPJ 查询参考限额、已用额度，以及无需冻结 / 须冻结的分级区间。创建时会重新校验交易及密钥条件，包括无等待期托管。max_amount_cents 不能替代费用、路由 / 服务商最低金额或合同限制。资金可能在服务商或本地冻结，须核对收款单的 held_hours、hold_hours 及 liberar_em。不要在客户端固定写入分级限额。", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "payer_tax", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^([0-9]{11}|[0-9]{14})$" }, "description": "CPF 为 11 位数字，CNPJ 为 14 位，仅接受数字。" } ], "responses": { "200": { "description": "当前分级限额状态", "content": { "application/json": { "schema": { "type": "object", "properties": { "payer_tax": { "type": "string", "description": "返回给您的值已遮盖，不提供完整资料。" }, "stage": { "enum": [ "first_transaction", "first_24h", "mature", "disabled", "desconhecido" ] }, "max_amount_cents": { "type": "integer", "description": "含适用冻结的证件参考最高额度。创建时仍会核对密钥、最低金额及可用性。" }, "used_cents": { "type": "integer" }, "available_cents": { "type": [ "integer", "null" ], "description": "当前阶段无需冻结即可接受的剩余额度，别名为 instant_available_cents。限额规则关闭时为 null（stage=disabled）。" }, "limit_cents": { "type": [ "integer", "null" ], "description": " 限额规则关闭时为 null（stage=disabled）。" }, "next_stage": { "type": [ "object", "null" ], "description": "限额何时提高，以及提高至多少。" }, "instant_available_cents": { "type": "integer", "description": "与 available_cents 相同，明确表示无需冻结即可接受的额度。" }, "held_qr": { "type": [ "object", "null" ], "description": "适用时提供需要冻结的额度条件。可能由服务商冻结，也可能是收款单本地冻结，须核对创建响应及状态。", "properties": { "stage": { "type": "string", "enum": [ "held_qr" ] }, "max_amount_cents": { "type": "integer" }, "used_cents": { "type": "integer", "description": "过去 24 小时已付款及处理中的金额。" }, "available_cents": { "type": "integer" }, "hold_hours": { "type": "integer" }, "explicacao": { "type": "string" } } } } } } } }, "400": { "description": "证件格式无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "getCashinLimits" } }, "/cashin/{cashin_id}/status": { "get": { "summary": "Pix 收款单状态", "description": "分别查询 Pix 付款及入账 / 交付状态。paid 本身不代表加密资产已交付或余额可用；settlement_status=sent 表示入账 / 交付完成，托管余额仍须核对可用及冻结金额。delayed 表示服务商冻结，paid 配合 liberar_em 可能表示本地冻结。不要因交付尚未完成就要求再次付款。优先使用 webhook，轮询须遵守密钥请求频率限制。", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "cashin_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "当前状态，附服务器记录的时间线。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusCobranca" } } } }, "404": { "description": "未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "getPixChargeStatus" } }, "/payouts": { "post": { "summary": "直接支付 Pix，不经过加密资产环节", "description": "发送 Pix，仅扣减通过 Pix 收到的主账户或 customer_ref 子账户可用 BRL 余额。先核对 GET /keys/me 的 payout.enabled，以及 GET /saldo 的 custodia_ativa、pix_rules 与费用。单笔 Pix 最高 R$ 6,000.00，仍受账户较低限额约束。收款人须有有效 CPF/CNPJ；若收款标识本身为 CPF/CNPJ，API 可从中提取。调用服务商前预留本金及费用；余额不足返回 402。请读取当前费用，并用交易的 fee_cents 对账。密钥限额及 mandate 仍然有效。使用稳定 external_id，超时后查询原订单。测试环境使用虚拟余额并按其 API 费用计算，不产生真实付款。USDT 钱包与 BRL 余额相互独立，接收外部 USDT 充值，不使用 /payouts；对应钱包付款流程使用 funding_source=crypto_usdt，不要求收款人证件，限额以报价及 API 条件为准，不适用 BRL 余额的 R$ 6,000 上限。测试密钥使用独立的钱包模拟器，不涉及真实资金。", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 1, "description": "Pix 金额，以整数 BRL 分计，5000 = R$ 50.00。最高 600000（R$ 6,000.00），仍受账户较低限额约束，费用在此金额之外另行扣除。", "maximum": 600000 }, "pix_key": { "type": "string", "description": "接收 BRL 的 Pix 收款标识：CPF、CNPJ、+55 手机号、邮箱或随机标识。11 位纯数字必须同时指定 pix_key_type（\"cpf\" 或 \"phone\"），否则返回 erro=tipo_ambiguo，不会猜测。" }, "pix_key_type": { "enum": [ "cpf", "cnpj", "phone", "email", "random" ], "description": "可选，通常根据收款标识格式推断，如邮箱、CNPJ、UUID 或带 +55 的手机号。若为 11 位纯数字，无法区分 CPF 与手机号，则必须填写，否则返回 tipo_ambiguo，不会擅自猜测。" }, "tax_number": { "type": "string", "description": "收款人的有效 CPF 或 CNPJ，须通过校验位检查。邮箱、手机号及随机收款标识必填；收款标识本身为有效 CPF/CNPJ 时可省略，API 直接提取，如另行提供则须一致。证件格式校验不证明该 Pix 标识的实际归属。" }, "beneficiary_name": { "type": "string", "maxLength": 120, "description": "可选，收款人完整姓名，作为最终用户姓名发送给 Pix 服务商。不是必填项，允许向第三方 Pix 收款标识付款。" }, "external_id": { "type": "string", "description": "最多 64 个字符的幂等标识。重试保持原金额、Pix 标识、类型、证件、customer_ref 及 funding_source。409 external_id_divergente 或 external_id_nao_verificavel 会返回 payout_id/recovery_endpoint，供查询原订单；不要为绕过冲突生成新 ID。", "maxLength": 64 }, "customer_ref": { "type": "string", "maxLength": 80, "description": "扣款子账户，适用于托管密钥。Pix 发送前先扣除本金、平台费用（saque_fee_bps）及服务商费用；服务商明确拒绝时冲回扣款。可用余额低于本金及费用时返回 402 saldo_insuficiente，费用字段见 GET /saldo 的 saque_fee_bps、saque_taxa_estimada_cents。使用与充值时相同的子账户引用，例如商户引用。" }, "sandbox_scenario": { "type": "string", "enum": [ "success", "delayed", "held", "expired", "refunded", "failed", "payer_mismatch", "settlement_failed", "settlement_uncertain", "route_unavailable", "provider_unavailable" ], "description": "仅用于测试密钥。GET /sandbox 提供各流程的场景矩阵，生产环境应省略。价格、付款及提现均为模拟结果。" }, "funding_source": { "type": "string", "enum": [ "pix_brl" ], "description": "可选，仅接受 pix_brl。此接口扣减通过 Pix 收到的 BRL 余额，绝不扣减 USDT 钱包。" } }, "required": [ "amount_cents", "pix_key" ] } } } }, "responses": { "403": { "description": "管理端停用或 custodia_desligada。生产密钥默认启用；若出现此响应，应停止并联系支持，不要持续重试。未发送 Pix。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "external_id_divergente 或 external_id_nao_verificavel：通过 payout_id/recovery_endpoint 查询原交易，不改变参数或为同一意图生成新 ID。em_processamento：查询正在处理的原订单，不新建付款。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Erro" }, { "type": "object", "properties": { "payout_id": { "type": "string", "description": "原 Pix 对外付款标识。" }, "recovery_endpoint": { "type": "string", "description": "原 Pix 对外付款的相对 API 路径。" } } } ] } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "423": { "description": "carencia_primeiro_deposito — 首次充值等待期，仅适用于约定了等待期的密钥；自2026年9月16日起，新密钥默认无此等待期。对应子账户须等待 libera_em 后才可提现，其他冻结规则仍可能适用。", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "string", "enum": [ "carencia_primeiro_deposito" ] }, "acao": { "type": "string", "enum": [ "esperar" ] }, "detail": { "type": "string" }, "libera_em": { "type": "string", "format": "date-time" } } } } } }, "503": { "description": "saque_indisponivel：资金渠道或服务商不可用，本次尝试不新增预留或扣款。idempotencia_indisponivel：无法核对原订单，不创建新订单，但原订单可能已存在。请等待并查询同一 external_id，不要生成新 ID。" }, "200": { "description": "Pix 对外付款已创建，或幂等返回原交易。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "已拒绝或失败，请读取返回的 erro、acao 及 detail（如有）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "402": { "description": "已拒绝或失败，请读取返回的 erro、acao 及 detail（如有）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "500": { "description": "已拒绝或失败，请读取返回的 erro、acao 及 detail（如有）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "createPixPayout" }, "get": { "summary": "列出当前密钥的 Pix 对外付款", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "processing", "sent", "failed", "refunded" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "external_id", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "幂等恢复：返回该 external_id 对应的交易，结果为 0 或 1 笔。标识在同一密钥及产品内唯一，区分大小写，并永久保留。" } ], "responses": { "200": { "description": "列表，最新记录在前。空列表返回 200，不返回 403。", "content": { "application/json": { "schema": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } } } } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "当前密钥尚未启用 Pix 对外付款。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "listPixPayouts" } }, "/payouts/{payout_id}": { "get": { "summary": "Pix 对外付款状态", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "提现状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "404": { "description": "未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "getPixPayout" } }, "/webhooks/deliveries": { "get": { "summary": "查询当前密钥的 webhook 投递历史", "description": "诊断已投递、失败及其原因，不返回原事件请求体。重发原始请求体须使用 retry 接口。", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "failed" ] } }, { "name": "event", "in": "query", "schema": { "type": "string", "enum": [ "cashin.paid", "cashin.delayed", "cashin.held", "cashin.settled", "cashin.settlement_failed", "cashin.expired", "cashin.refunded", "cashin.failed", "cashout.awaiting_deposit", "cashout.deposit_detected", "cashout.confirming", "cashout.processing", "cashout.under_review", "cashout.awaiting_refund_address", "cashout.refunding", "cashout.completed", "cashout.receipt_ready", "cashout.refunded", "cashout.expired", "cashout.failed", "payout.sent", "payout.failed", "payout.refunded", "webhook.test", "saldo.liberado", "saldo.congelado", "saldo.transferido", "wallet.deposit_credited", "wallet.payment_completed", "wallet.payment_failed" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "投递记录，最新在前。", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/EntregaWebhook" } }, "failed_count": { "type": "integer", "description": "本次响应中，已耗尽尝试次数的记录数。" } } } } } }, "400": { "description": "筛选条件无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "listWebhookDeliveries" } }, "/webhooks/deliveries/{event_id}/retry": { "post": { "summary": "重发事件", "description": "在本次调用中尝试投递并返回结果；再次失败时，重新入队，并获得新的 12 次尝试机会。已收到 2xx 确认的事件不允许重发。", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "本次投递成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "delivered": { "type": "boolean", "const": true }, "status_code": { "type": "integer" }, "ms": { "type": "integer" }, "delivery_id": { "type": "string" } } } } } }, "202": { "description": "本次未送达，已重新入队。" }, "404": { "description": "当前密钥下未找到记录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "已送达，重发将造成重复", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "retryWebhookDelivery" } }, "/webhooks/test": { "post": { "summary": "立即发送测试事件", "description": "通过与生产相同的 HTTP 投递机制，向 webhook_url 发送 webhook.test，并返回接收端状态码及延迟。不移动资金，也不进入持久投递队列。首张真实收款单前可先测试，每分钟最多 6 次。", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "您的接收端返回了 2xx。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "event_id": { "type": "string" }, "delivery_id": { "type": "string" }, "url": { "type": "string" }, "status_code": { "type": "integer" }, "ms": { "type": "integer" } } } } } }, "400": { "description": "尚未配置 webhook_url", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "每分钟测试次数超过 6 次", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "502": { "description": "您的接收端未返回 2xx，请求响应说明了具体情况。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "testWebhook" } }, "/cashin/charges": { "get": { "summary": "列出 / 恢复当前密钥的 cash-in 收款单", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "external_id", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "幂等恢复：返回该 external_id 对应的交易，结果为 0 或 1 笔。标识在同一密钥及产品内唯一，区分大小写，并永久保留。" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "列表，最新记录在前。", "content": { "application/json": { "schema": { "type": "object", "properties": { "charges": { "type": "array", "items": { "$ref": "#/components/schemas/Cobranca" } } } } } } }, "401": { "description": "缺少 X-API-Key 或密钥无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "列表查询须提供 X-API-Key，不是公开接口。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "listPixCharges" } }, "/cashin/preview": { "post": { "summary": "Cash-in 预估，不创建交易", "description": "2026年10月15日政策：余额充值 R$ 1.00，无比例费用及佣金；直接购买 3.3% + R$ 1.00；余额兑换加密资产 3.3%，不再收固定费用；余额 Pix 提现 1.5%。购买及转出另计合作伙伴佣金。参考汇率为 Binance 卖一价，不加溢价；网络及处理成本在预览中列明。destino=saldo 时预览返回 BRL，net_cents=amount_cents-100，不执行兑换或创建收款单，也不是加密资产提现的扣款预览。", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "minimum": 1, "description": "BRL 金额，以整数分计。实际最低金额取决于密钥、费用及路由。查询 GET /keys/me 及返回的 min_brl_cents/limits，不要固定使用示例最低金额。" }, "asset": { "type": "string", "default": "usdt", "description": "GET /cashin/catalog 中可交付路由的资产，不限于稳定币。" }, "chain": { "type": "string", "default": "polygon", "description": "交付路由的网络，将目录中的 network 值填入此 chain 字段。" }, "delivery_mode": { "type": "string", "enum": [ "full", "split" ], "default": "full", "description": "仅 chain=\"liquid\"（DePix）适用。full 直接向指定钱包交付全部 DePix，不从中扣除密钥费用。split 采用接收再转发：Lunium 接收后扣除密钥的固定及比例费用，再向 payout_address 发送净额，响应 net_cents 即收款人实际接收金额。split 必须提供 payout_address。省略此字段时，以密钥的实际默认配置为准。" }, "destino": { "type": "string", "enum": [ "cripto", "saldo" ], "default": "cripto" } } } } } }, "responses": { "200": { "description": "已应用当前密钥费用的报价。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "asset": { "type": "string", "description": "交付资产，原样返回请求值，如 usdt、usdc、depix、btc。" }, "amount_cents": { "type": "integer", "description": "收款单金额，以分计，原样返回请求值。" }, "admin_fee_bps": { "type": "integer" }, "admin_fee_fixed_cents": { "type": "integer" }, "fee_total_cents": { "type": "integer", "description": "从总额扣除的全部费用：固定费用 + Lunium 比例费用 + 合作伙伴 sub fee。恒等式为 fee_total_cents + net_cents == amount_cents，各方份额见 lunium_fee_cents 与 partner_fee_cents。" }, "net_cents": { "type": "integer", "description": "用于为最终用户兑换加密资产的净额，已扣除适用合作伙伴 sub fee。" }, "brl_per_usdt": { "type": "string", "description": "供阅读的舍入汇率，实际交付使用完整精度汇率。" }, "usdt_amount": { "type": "string", "description": "旧版数量字段。平台渠道（DePix 及由 Lunium 自有钱包交付）表示交付数量；经兑换的路由（BTC、ETH、其他币种，及部分网络上的稳定币）表示用于购买的 USDT，不是客户收到的数量。展示钱包接收数量时，始终使用 asset_amount。" }, "chain": { "type": "string", "description": "交付网络，原样返回并规范化请求值，例如 sol → solana、trc20 → tron。" }, "asset_amount": { "type": "string", "description": "客户钱包预计收到的加密资产数量，已扣密钥费用、合作伙伴 sub fee，以及兑换路由的购买成本和网络提现费用 withdraw_fee。用于展示“您将收到”，测试环境使用相同字段。此值为预估，交付时按付款时的汇率重新计算。" }, "withdraw_fee": { "type": "string", "description": "网络提现费用，以资产单位表示，已从 asset_amount 扣除。按每次发送固定收取，与金额无关，因此小额交易影响更大，例如 Bitcoin 网络上的 BTC。平台自有渠道为 \"0\"。换算 BRL 使用 withdraw_fee × brl_per_asset。" }, "withdraw_min": { "type": "string", "description": "网络可发送的最低资产数量，适用于兑换路由。最低 BRL 金额已在 min_brl_cents 计算。" }, "brl_per_asset": { "type": [ "number", "null" ], "description": "本次预览每单位资产对应的 BRL，即净额 ÷ 购买数量，可用于将 withdraw_fee 及 asset_amount 换算为 BRL。仅供参考，无有效计算时为 null。" }, "min_brl_cents": { "type": "integer", "description": "该路由在当前密钥费用条件下可交付的最低金额，以分计。" }, "eta": { "type": "string", "description": "兑换路由的典型交付时间，不是合同最长时限。" }, "amount": { "type": "string", "description": "asset_amount 的旧名称，仅兑换路由提供，优先使用 asset_amount。", "deprecated": true }, "network_min": { "type": "string", "description": "withdraw_min 的旧名称，优先使用 withdraw_min。", "deprecated": true }, "partner_fee_bps": { "type": "integer", "description": "本次报价适用的合作伙伴 sub fee，单位 bps，0 表示不使用。" }, "lunium_fee_cents": { "type": "integer", "description": "Lunium 份额，含固定及比例部分。未设 sub fee 时等于 fee_total_cents。" }, "partner_fee_cents": { "type": "integer", "description": "合作伙伴 sub fee 份额，加密资产交付后记入佣金。通过同一次向下取整结果的差额计算，合作伙伴佣金不改变 Lunium 份额。" }, "sandbox": { "const": false }, "delivery_mode": { "type": "string", "enum": [ "full", "split" ], "description": "仅 chain=\"liquid\" 提供，说明 DePix 交付方式。其他网络无此字段。" }, "destino": { "type": "string", "enum": [ "cripto", "saldo" ] } }, "description": "2026年10月15日政策：余额充值 R$ 1.00，无比例费用及佣金；直接购买 3.3% + R$ 1.00；余额兑换加密资产 3.3%，不再收固定费用；余额 Pix 提现 1.5%。购买及转出另计合作伙伴佣金。参考汇率为 Binance 卖一价，不加溢价；网络及处理成本在预览中列明。destino=saldo 时预览返回 BRL，net_cents=amount_cents-100，不执行兑换或创建收款单，也不是加密资产提现的扣款预览。" }, { "type": "object", "description": "隔离的测试环境，使用含路由提现费用的模拟报价，不调用服务商。fee_bps 及 fee_fixed_cents 为模拟费率，不代表生产报价。", "required": [ "sandbox", "synthetic", "amount_cents", "min_brl_cents", "fee_bps", "fee_fixed_cents", "partner_fee_bps", "asset", "chain", "usdt_amount", "asset_amount", "withdraw_fee", "withdraw_min", "brl_per_usdt", "brl_per_asset" ], "properties": { "sandbox": { "const": true }, "synthetic": { "const": true }, "amount_cents": { "type": "integer" }, "min_brl_cents": { "type": "integer" }, "fee_bps": { "type": "integer" }, "fee_fixed_cents": { "type": "integer" }, "partner_fee_bps": { "type": "integer" }, "asset": { "type": "string" }, "chain": { "type": "string" }, "usdt_amount": { "type": "string" }, "asset_amount": { "type": "string" }, "withdraw_fee": { "type": "string" }, "withdraw_min": { "type": "string" }, "brl_per_usdt": { "type": "number" }, "brl_per_asset": { "type": "number" } } } ] } } } }, "400": { "description": "金额超过密钥限额或参数无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } }, "operationId": "previewPixCharge" } }, "/pix/keys/lookup": { "get": { "operationId": "consultarTitularChavePix", "summary": "在核验服务可用时查询 Pix 收款人", "description": "辅助收款人查询。停用时返回 HTTP 200，且 verified=false、available=false、verification_status=not_performed、source=disabled，收款人资料为 null，不影响付款功能。可用时返回从 DICT 获取的资料，受缓存及限流约束。测试环境返回虚构资料，source=sandbox。不能仅凭 HTTP 200 判定已核验收款人；已知类型时，应明确发送 type。", "tags": [ "Pix" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Pix 收款标识：CPF、CNPJ、邮箱、带或不带 +55 的手机号，或随机标识。", "examples": { "email": { "value": "vendas@loja.com.br" }, "telefone": { "value": "+5511987654321" } } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cpf", "cnpj", "phone", "email", "random" ] }, "description": "可选，省略时按格式推断。" } ], "responses": { "200": { "description": "已找到收款人。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TitularPix" } } } }, "400": { "description": "收款标识格式无效（pix_key_invalida）或缺失（pix_key_obrigatoria）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "DICT 中不存在该收款标识（chave_nao_encontrada）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "账户每分钟最多查询 5 次（limite_consultas），请读取 Retry-After。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "DICT 服务商不可用（provedor_indisponivel，可重试），或查询已停用（consulta_indisponivel，应等待）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/saldo": { "get": { "tags": [ "Conta" ], "summary": "BRL 托管余额：可用、冻结及后续资金释放", "description": "主账户或 customer_ref 子账户的 BRL 余额，返回可用、冻结金额、后续释放及实际托管条件。费用及等待期因密钥而异。收款单本地冻结、服务商冻结及余额等待期是不同规则。仅 disponivel_cents 可用于提现；GET /saldo/consolidado 汇总主账户及客户子账户。测试环境返回持久保存的虚拟余额，支持模拟充值、提现与转账。", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "customer_ref", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "子账户，即您系统中的最终客户 ID。省略时查询密钥主账户余额。" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "disponivel_cents", "bloqueado_cents", "total_cents" ], "properties": { "customer_ref": { "type": [ "string", "null" ], "maxLength": 80 }, "disponivel_cents": { "type": "integer" }, "bloqueado_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "movimentos": { "type": "integer" }, "proximas_liberacoes": { "type": "array", "description": "所查询主账户或 customer_ref 子账户的后续资金释放记录，最多 200 项，1.44.1 之前最多 20 项。不要假定更低上限。", "items": { "type": "object", "properties": { "disponivel_em": { "type": "string", "format": "date-time" }, "valor_cents": { "type": "integer" } } } }, "custodia_ativa": { "type": "boolean", "description": "false 表示当前密钥不能托管 BRL，destino=\"saldo\" 会被拒绝。" }, "carencia_horas": { "type": "integer", "description": "该密钥配置的等待期，即时入账时为零。收款单冻结及其他冻结入账仍独立适用。" }, "deposito_fee_bps": { "type": "integer", "description": "新余额充值始终为 0。" }, "saque_taxa_estimada_cents": { "type": "integer", "description": "服务商固定费用或预估最低费用。比例计费须应用 saque_taxa_provedor_formula，此值不是所有提现的完整总价。" }, "saque_fee_bps": { "type": "integer", "description": "BRL 余额通过 Pix 提现的 Lunium 费率，标准 150 bps，另计合作伙伴佣金，处理费用单独列明。" }, "saque_cripto_fee_bps": { "type": "integer", "description": "加密资产扣款附加费为 0，Lunium 费用仅在兑换时计一次。" }, "primeiro_deposito_em": { "type": [ "string", "null" ], "format": "date-time", "description": "该子账户首次充值入账时间，null 表示从未充值。" }, "carencia_ate": { "type": [ "string", "null" ], "format": "date-time", "description": "正在适用的首次充值等待期结束时间，否则为 null。还须读取 bloqueado_cents 及 proximas_liberacoes。" }, "retencao_acima_cents": { "type": "integer", "description": "托管首笔合格付款的规则阈值，不表示超过此金额的每笔充值均冻结，仍取决于付款人分级及密钥条件。" }, "deposito_fee_fixed_cents": { "type": "integer", "description": "新余额充值每笔固定 100 分，即 R$ 1.00。" }, "saque_taxa_provedor_formula": { "type": [ "string", "null" ], "description": "当前公式：固定费用（piso_cents），或带最低费用的比例计费。不要假定某个服务商始终可用。" }, "saque_taxa_provedor_tipo": { "type": "string", "enum": [ "fixo", "percentual" ], "description": "Pix 对外付款服务商当前计费类型。" }, "saque_taxa_provedor_piso_cents": { "type": "integer", "description": "固定费用或比例计费的最低费用，以分计。" }, "sandbox": { "type": "boolean", "description": "精简测试响应中为 true。" }, "saque_partner_fee_bps": { "type": "integer", "description": "Pix 及加密资产转出的合作伙伴 sub fee，在 Lunium 费用之外另计。" }, "saque_fee_total_bps": { "type": "integer", "minimum": 0, "description": "客户展示用合并服务费率，平台费率 + 合作伙伴附加费率，单位 bps，250 = 2.5%。与固定费用一起展示，不单列合作伙伴佣金。金额使用实际报价 / 已保存值，内部组成项分别按分舍入。生产及测试环境均适用。" }, "saque_cripto_conversao_fee_bps": { "type": "integer", "description": "余额兑换加密资产的 Lunium 比例费用，基于无溢价 Binance 报价，标准 330 bps。" }, "saque_cripto_conversao_fee_fixed_cents": { "type": "integer", "description": "为零，入金固定成本已在充值时收取。" }, "deposito_partner_fee_bps": { "type": "integer", "description": "为零，余额充值不产生合作伙伴佣金。" } } } } } }, "401": { "description": "缺少密钥或密钥无效" } }, "operationId": "getBalance" } }, "/saldo/extrato": { "get": { "tags": [ "Conta" ], "summary": "余额流水：会计记录或按交易分组", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "customer_ref", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "visao", "in": "query", "schema": { "type": "string", "enum": [ "lancamentos", "operacoes" ], "default": "lancamentos" }, "description": "operacoes 将相关费用合并在对应交易内。省略时保留默认会计流水契约，项目特殊展示配置另行适用。" }, { "name": "before", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "description": "使用同一视图及 customer_ref 返回的 proxima_pagina。游标为十进制 bigint 字符串，不转换为 Number。分组视图以最早账本 ID 为锚点。" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "movimentos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "valor_cents": { "type": "integer", "description": "对 BRL 余额产生的带符号总影响，以分计。负数为扣款，正数为入账。分组视图已计入费用。" }, "sentido": { "type": "string", "enum": [ "credito", "debito" ] }, "tipo": { "type": "string", "enum": [ "cashin", "payout", "cashout", "estorno", "ajuste", "transfer_in", "transfer_out" ] }, "origem_tipo": { "type": [ "string", "null" ] }, "origem_id": { "type": [ "string", "null" ] }, "disponivel_em": { "type": "string", "format": "date-time" }, "disponivel": { "type": "boolean" }, "descricao": { "type": [ "string", "null" ] }, "criado_em": { "type": "string", "format": "date-time" }, "customer_ref": { "type": [ "string", "null" ] }, "valor_operacao_cents": { "type": "integer", "description": "分组视图的带符号本金。无法关联本金的独立费用调整为零。" }, "taxas_cents": { "type": "integer", "minimum": 0, "description": "分组视图已包含费用流水的绝对值总和，不是额外扣款。" }, "taxas": { "type": "array", "items": { "type": "object", "required": [ "tipo", "descricao", "valor_cents", "efeito_saldo_cents" ], "properties": { "tipo": { "type": "string", "enum": [ "servico" ] }, "descricao": { "type": "string" }, "valor_cents": { "type": "integer", "minimum": 0 }, "efeito_saldo_cents": { "type": "integer" } } }, "description": "客户费用明细中的 servico 已包含合作伙伴费用。当前合并展示将适用 Pix 费用及服务费计入交易总费用，不向客户单列合作伙伴佣金。" }, "status": { "type": [ "string", "null" ] }, "status_label": { "type": [ "string", "null" ], "description": "查询时已保存的状态。原始标签为葡萄牙语，产品界面可按已知状态 / 类型进行本地化，不修改账本原值。" }, "settlement_status": { "type": [ "string", "null" ] }, "movimentos_ids": { "type": "array", "items": { "type": "string" }, "description": "分组视图中的原始账本 ID，用于对账，不代表额外动态记录。" }, "atualizado_em": { "type": [ "string", "null" ], "format": "date-time" } } } }, "proxima_pagina": { "type": [ "string", "null" ] }, "visao": { "type": "string", "const": "operacoes", "description": "仅分组视图提供。" }, "has_more": { "type": "boolean", "description": "分组视图是否还有下一页，最后一页游标为 null。" } } }, "examples": { "groupedOperation": { "summary": "visao=operacoes：Pix R$ 2.00 + 合并费用 R$ 1.05 = 扣款 R$ 3.05", "value": { "visao": "operacoes", "movimentos": [ { "id": "123", "tipo": "payout", "origem_tipo": "payout", "origem_id": "po_example", "customer_ref": "customer-42", "valor_cents": -305, "sentido": "debito", "valor_operacao_cents": -200, "taxas_cents": 105, "taxas": [ { "tipo": "servico", "descricao": "Taxa", "valor_cents": 105, "efeito_saldo_cents": -105 } ], "status": "sent", "status_label": "Concluído", "settlement_status": null, "descricao": "Saque por Pix", "movimentos_ids": [ "123", "124", "125", "126" ], "criado_em": "2026-10-09T21:36:00Z", "atualizado_em": "2026-10-09T21:38:00Z", "disponivel_em": "2026-10-09T21:36:00Z", "disponivel": true } ], "proxima_pagina": null, "has_more": false } } } } } }, "401": { "description": "缺少密钥或密钥无效" }, "400": { "description": "分组视图的 limit 或 before 游标格式错误。" } }, "operationId": "getBalanceStatement", "description": "最终用户动态应使用 visao=operacoes：每笔交易一个带符号总额，内部仅一个费用项（tipo=servico，descricao=Taxa），包含 Pix 固定费用及全部费用组成。退款另列。先分组再分页，通知按 origem_id 及 tipo 去重，不按费用会计项去重。不得将支出 / 费用显示为收入，也不得重复扣费。已配置合并展示的项目默认使用此视图；visao=movimentos 明确选择供后端对账使用的会计视图。其他项目仍默认逐笔会计流水，测试环境行为相同。内部费用归属及组成字段不应直接转发至客户通知。详见 https://docs.luniumpay.com/zh/manual#extrato-por-operacao 。" } }, "/saldo/sacar-cripto": { "post": { "tags": [ "Conta" ], "summary": "将 BRL 余额兑换并提取至自托管加密资产钱包", "description": "将可用 BRL 余额兑换为加密资产。选择 GET /cashin/catalog 中 entregavel=true 的路由，每次提现填写钱包及必要 memo，无需固定钱包。不支持 Liquid/DePix。交付前扣减 amount_cents 及平台提现费用；兑换及路由成本影响最终数量。通过 GET /cashin/{cashin_id}/status 跟踪 cashin_id。external_id 命名空间与收款单共用，没有公开的提现预览接口。", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents", "payout_address", "tax_number" ], "properties": { "amount_cents": { "type": "integer", "minimum": 100, "description": "BRL 金额，以整数分计。实际最低金额取决于密钥、费用及路由。查询 GET /keys/me 及返回的 min_brl_cents/limits，不要固定使用示例最低金额。" }, "chain": { "type": "string", "default": "polygon", "description": "网络，支持别名：sol、trc20、erc20、bep20、arbitrum、base 等。" }, "asset": { "type": "string", "default": "usdt", "description": "小写资产代码，如 usdt、usdc、btc、eth、sol，须存在于 GET /cashin/catalog。" }, "payout_address": { "type": "string", "description": "目标钱包，按所选网络校验。" }, "tax_number": { "type": "string", "description": "余额所属客户的 CPF（11 位）或 CNPJ（14 位）。" }, "customer_ref": { "type": "string", "maxLength": 80, "description": "扣款子账户，省略时使用密钥主账户。" }, "external_id": { "type": "string", "maxLength": 64, "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。" }, "payout_tag": { "type": "string", "maxLength": 120, "description": "目标 memo/tag。XRP、XLM、TON、ATOM、HBAR、ALGO、EOS、KAVA、LUNA 等共用地址网络必填，用于识别实际收款人。缺失时，创建收款单前返回 400 memo_obrigatorio。XRP destination tag 须为 0 至 4294967295 的整数。支持 memo、tag、destination_tag 别名，目录以 memoRequired: true 标记。" }, "max_debited_cents": { "type": "integer", "minimum": 0, "description": "可选 BRL 扣款上限，包含本金及平台费用。超出时返回 409 taxa_alterada，不锁定汇率或代币数量。" }, "sandbox_scenario": { "type": "string", "enum": [ "success", "delayed", "held", "expired", "refunded", "failed", "payer_mismatch", "settlement_failed", "settlement_uncertain", "route_unavailable", "provider_unavailable" ], "description": "仅用于测试密钥。GET /sandbox 提供各流程的场景矩阵，生产环境应省略。价格、付款及提现均为模拟结果。" } } } } } }, "responses": { "200": { "description": "已扣款并进入交付队列。返回与 POST /cashin/charge 相同的状态视图：cashin_id、status=paid（余额本身即付款来源）、chain、asset、payout_address、amount_cents、settlement_status、settlement_tx_hash；另有 fee_cents（平台扣除费用）、debited_cents（本金 + 费用）、fonte: \"saldo\"、destino: \"cripto\" 及 customer_ref。通过 GET /cashin/{cashin_id}/status 跟踪 settlement_status，直至 sent。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaqueCripto" } } } }, "400": { "description": "rede_indisponivel | asset_invalido | payout_address_invalido | documento_invalido | valor_abaixo_do_minimo；memo_obrigatorio 表示网络要求 memo/tag，但未提供或无效。" }, "402": { "description": "saldo_insuficiente — 可用余额 < 本金 + 费用，请求响应提供 saldo 及 fee_cents。" }, "409": { "description": "external_id_divergente" }, "423": { "description": "carencia_primeiro_deposito — 约定了首次充值等待期的密钥适用，libera_em 表示释放时间。" }, "503": { "description": "entrega_indisponivel — 当前无可交付库存 / 路由，未扣款。" } }, "operationId": "withdrawBalanceToCrypto" } }, "/mesh": { "get": { "tags": [ "Mesh · Discovery" ], "operationId": "meshDiscovery", "summary": "智能体接入前须知", "description": "一次 GET 返回平台介绍、可结算流程、资产与网络、全部接口、获取密钥及生产接入方式、限额与数据模式，无需凭证。", "security": [], "x-lunium-agent-safe": true, "x-lunium-environment": "any", "responses": { "200": { "description": "发现文档。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshDiscovery" } } } } } } }, "/mesh/economy": { "get": { "tags": [ "Mesh · Economy" ], "operationId": "meshEconomy", "summary": "网络经济的公开规则", "description": "仅对直接推荐的第一级智能体，按实际已结算交易量的 0.10% 计奖励。注册、推荐动作、报价及测试环境本身均不产生奖励。", "security": [], "x-lunium-agent-safe": true, "responses": { "200": { "description": "当前规则。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshEconomyPolicy" } } } } } } }, "/mesh/agents": { "post": { "tags": [ "Mesh · Identity" ], "operationId": "meshRegisterAgent", "summary": "注册智能体并获取测试环境凭证", "description": "一次调用完成注册及凭证签发。提供 referral_token 可验证推荐关系；未提供时作为根节点加入。", "security": [], "x-lunium-agent-safe": true, "x-lunium-environment": "sandbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistration" } } } }, "responses": { "201": { "description": "智能体已创建，提供凭证及下一步操作。", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/AgentIdentity" }, "api_key": { "type": "string" }, "sandbox": { "type": "boolean" }, "lineage": { "type": "object" }, "proximo_passo": { "type": "object" } } } } } }, "400": { "description": "请求无效或 referral_token 被拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } } }, "get": { "tags": [ "Mesh · Network" ], "operationId": "meshListAgents", "summary": "发现网络成员", "security": [], "x-lunium-agent-safe": true, "description": "公开目录，绝不返回密钥、密钥哈希或 token。", "responses": { "200": { "description": "智能体列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentIdentity" } } } } } } } } } }, "/mesh/referrals": { "post": { "tags": [ "Mesh · Network" ], "operationId": "meshIssueReferral", "summary": "签发推荐证明（attestation）", "description": "须提供推荐方智能体的 X-API-Key，返回带签名、一次性且有有效期的 token。这是建立推荐关系及相应 0.10% 奖励关系的唯一方式。", "x-lunium-agent-safe": true, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "type": "string" }, "expires_in_minutes": { "type": "integer", "default": 60, "maximum": 10080 } } } } } }, "responses": { "201": { "description": "推荐证明已签发。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralAttestation" } } } }, "401": { "description": "缺少密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "404": { "description": "密钥未关联至智能体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } } } }, "/mesh/agents/{agent_id}": { "get": { "tags": [ "Mesh · Identity" ], "operationId": "meshGetAgent", "summary": "智能体状态、mandate 授权、指标及推荐关系", "security": [], "x-lunium-agent-safe": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "responses": { "200": { "description": "智能体资料。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIdentity" } } } }, "404": { "description": "不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } } } }, "/mesh/agents/{agent_id}/validate": { "post": { "tags": [ "Mesh · Identity" ], "operationId": "meshValidateAgent", "summary": "提交测试环境使用证明", "description": "仅创建测试密钥不够，须在测试环境创建并接受至少一笔订单。此步骤用于确认真实资金接入前，已有错误处理及状态跟踪流程。", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "x-lunium-agent-safe": true, "responses": { "200": { "description": "已完成。", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "缺少密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "403": { "description": "密钥不属于此智能体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "409": { "description": "缺少前置条件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } } } }, "/mesh/agents/{agent_id}/settlement": { "post": { "tags": [ "Mesh · Policy" ], "operationId": "meshSetSettlement", "summary": "设置资金目的地", "description": "支持的结算网络地址。", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "x-lunium-agent-safe": true, "responses": { "200": { "description": "已完成。", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "缺少密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "403": { "description": "密钥不属于此智能体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "409": { "description": "缺少前置条件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementConfiguration" } } } } } }, "/mesh/agents/{agent_id}/mandate": { "post": { "tags": [ "Mesh · Policy" ], "operationId": "meshSetMandate", "summary": "设置自身限额策略", "description": "仅收紧密钥限额，不能扩大权限。进入生产前必须设置。", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "x-lunium-agent-safe": true, "responses": { "200": { "description": "已完成。", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "缺少密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "403": { "description": "密钥不属于此智能体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "409": { "description": "缺少前置条件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } } } }, "/mesh/agents/{agent_id}/production-request": { "post": { "tags": [ "Mesh · Identity" ], "operationId": "meshActivateProduction", "summary": "自动激活生产环境，无需人工审批", "description": "自动检查：测试环境使用证明、支持网络的结算地址、符合规则的 mandate，以及有效凭证。通过后，在同一响应激活生产；缺少条件则返回 422，并提供 missing 及 next_actions，供智能体修正后重试。", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "x-lunium-agent-safe": true, "responses": { "200": { "description": "已完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionActivation" } } } }, "401": { "description": "缺少密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "403": { "description": "密钥不属于此智能体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "409": { "description": "缺少前置条件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } }, "422": { "description": "条件不完整，响应可供程序解析。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } }, "x-lunium-settlement-required": true } }, "/mesh/agents/{agent_id}/network": { "get": { "tags": [ "Mesh · Network" ], "operationId": "meshAgentNetwork", "summary": "推荐关系、层级树及网络交易量", "security": [], "x-lunium-agent-safe": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "description": "递归查询推荐树。network_volume 统计整棵树，reward_eligible_volume 仅统计第一级可计奖交易量。", "responses": { "200": { "description": "网络资料。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentNetwork" } } } }, "404": { "description": "不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } } } }, "/mesh/agents/{agent_id}/rewards": { "get": { "tags": [ "Mesh · Economy" ], "operationId": "meshAgentRewards", "summary": "奖励余额及账本流水", "security": [], "x-lunium-agent-safe": true, "x-lunium-reward-eligible": true, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "agt_2319c9da313e84af3b" } ], "responses": { "200": { "description": "余额与账本。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardBalance" } } } }, "404": { "description": "不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroAutocorrigivel" } } } } } } }, "/saldo/consolidado": { "get": { "summary": "密钥汇总：主账户 + 客户子账户，总托管金额", "description": "汇总密钥的全部托管资金。casa 为无 customer_ref 的主账户流水，包括合作伙伴份额、调整及自身提现；clientes 为有 customer_ref 的客户子账户总额。total_custodiado_cents = 主账户 + 客户子账户，用于合作伙伴财务对账。", "security": [ { "ApiKey": [] } ], "tags": [ "Conta" ], "responses": { "200": { "description": "汇总结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "casa": { "type": "object", "properties": { "disponivel_cents": { "type": "integer" }, "bloqueado_cents": { "type": "integer" }, "total_cents": { "type": "integer" } } }, "clientes": { "type": "object", "properties": { "qtd": { "type": "integer" }, "disponivel_cents": { "type": "integer" }, "bloqueado_cents": { "type": "integer" }, "total_cents": { "type": "integer" } } }, "total_custodiado_cents": { "type": "integer" }, "movimentos": { "type": "integer" }, "ultimo_movimento_em": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "/saldo/clientes": { "get": { "summary": "分页列出有余额的客户子账户", "description": "列出当前密钥各 customer_ref 的可用、冻结及总余额，按 customer_ref 排序；使用 cursor=next_cursor 分页。com_saldo=1 隐藏零余额子账户。", "security": [ { "ApiKey": [] } ], "tags": [ "Conta" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "上一页的 next_cursor，即某个 customer_ref。" }, { "name": "com_saldo", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "1 表示仅列出非零余额子账户。" } ], "responses": { "200": { "description": "子账户分页列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientes": { "type": "array", "items": { "type": "object", "properties": { "customer_ref": { "type": "string", "maxLength": 80 }, "disponivel_cents": { "type": "integer" }, "bloqueado_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "movimentos": { "type": "integer" }, "primeiro_movimento_em": { "type": "string", "format": "date-time" }, "ultimo_movimento_em": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/keys/painel-link": { "post": { "summary": "通过邮件获取监控链接，无需 API 密钥", "description": "完整 API 密钥仅显示一次，监控面板不依赖该密钥登录。填写密钥登记邮箱，只读监控链接（dashboard token）会发送至该邮箱。响应始终为统一格式，不透露邮箱是否存在。每小时每个邮箱最多发送 3 次，每个 IP 最多 10 次。", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "请求已接受，统一格式响应。" }, "400": { "description": "邮箱无效。" }, "429": { "description": "已达到每小时限额。" } } } }, "/saldo/transferir": { "post": { "summary": "子账户与主账户之间内部转账，不生成 Pix", "description": "在客户子账户（customer_ref）与主账户（\"casa\"，即密钥自身）之间，或两个客户之间转移可用余额，不经过 Pix。常用于客户向主账户支付费用，或主账户向客户发放奖励 / 退款。冻结资金（24 小时冻结或 MED）不可转移。首次充值等待期内的来源子账户不可转账，返回 423，仅约定了等待期的密钥适用。通过 external_id 保证幂等，并发送 saldo.transferido。", "security": [ { "ApiKey": [] } ], "tags": [ "Conta" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_customer_ref", "to_customer_ref", "amount_cents" ], "properties": { "from_customer_ref": { "type": "string", "description": "来源 customer_ref 或 \"casa\"。" }, "to_customer_ref": { "type": "string", "description": "目标 customer_ref 或 \"casa\"。" }, "amount_cents": { "type": "integer", "minimum": 1 }, "descricao": { "type": "string", "maxLength": 140, "description": "同时显示在转出与转入两侧流水中。" }, "external_id": { "type": "string", "maxLength": 64, "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。" } } } } } }, "responses": { "201": { "description": "已转账。", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer_id": { "type": "string" }, "from_customer_ref": { "type": [ "string", "null" ] }, "to_customer_ref": { "type": [ "string", "null" ] }, "amount_cents": { "type": "integer" }, "descricao": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "movimentos": { "type": "object" }, "saldos": { "type": "object", "description": "转账后两侧余额。" } } } } } }, "200": { "description": "幂等重放，idempotente: true。" }, "400": { "description": "valor_invalido · origem_igual_destino · custodia_desligada。" }, "409": { "description": "saldo_insuficiente（提供 disponivel_cents/bloqueado_cents）· external_id_divergente。" }, "423": { "description": "来源子账户处于 carencia_primeiro_deposito 等待期。" } } } }, "/cash-outs/preview": { "post": { "tags": [ "Cash-out" ], "operationId": "previaCotacao", "security": [ { "ApiKeyAuth": [] } ], "summary": "报价预览（不创建订单）", "description": "按 amount、brl_amount 或 br_code 预估兑换，不创建订单，无需 pix_key，不预留余额、限额或地址。三个字段须且仅传一个。创建 / 接受报价还会校验收款人限额及 mandate 等额外条件。生产 br_code 可用性在预览及创建时均校验，预览成功不保证订单获接受。也支持 DEPIX/liquid，按平台费率计算，返回 fee_bps、fee_fixed_cents、fee_total_cents、net_cents、min_amount_cents、max_amount_cents。测试环境亦支持相同卖出公式及 BRL 平价，预览无需钱包或收款人。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "network" ], "properties": { "asset": { "type": "string", "examples": [ "USDT", "DEPIX" ], "description": "卖出的资产。必须使用 GET /catalog 中完全一致的 id，例如 \"usdt\"。须与 network 组合使用，且 (asset, network) 必须存在于目录。" }, "network": { "type": "string", "description": "GET /catalog 列出的加密资产入金网络，不同于 /cashin/catalog 的交付网络。", "examples": [ "polygon", "liquid" ] }, "amount": { "type": "string", "description": "加密资产数量，十进制字符串，例如 \"50\"，不要使用浮点数。不能同时传 brl_amount 或 br_code，此方式创建订单时须提供 pix_key。", "examples": [ "50" ] }, "brl_amount": { "type": "string", "description": "反向报价的目标 BRL 金额，最多两位小数的字符串，例如 \"250.00\"。不能同时传 amount 或 br_code，创建时须提供 pix_key。响应返回精确加密资产充值量及实际 BRL 金额，后者可能因舍入与目标略有差异。接受前展示返回金额，最低金额及限额以路由、密钥及收款人当前条件为准。", "examples": [ "250.00" ] }, "token_address": { "type": "string", "description": "精确合约地址 / mint。/catalog/dex 代币可能有相同符号，因此必须明确地址。" }, "br_code": { "type": "string", "description": "带金额的 Pix 收款码。预览解码后返回 amount、brl_amount（二维码金额）、merchant_name 及遮盖后的收款标识，不创建订单。使用 br_code 时不传 amount 或 brl_amount，遵循 POST /cash-outs 的相同规则，仅支持兼容目录路由的 USDT/USDC。amount 已包含 R$ 1.00 Copia e Cola 预留款（reserve_brl，其 USDT 等值见 copia_e_cola_buffer_usd）。客户粘贴或扫描了带金额的静态 / 动态二维码时，须发送完整 br_code，不仅提取 pix_key + brl_amount，才能保留精确金额及收款单 txid；按收款标识付款可能相差几分，导致收款方无法匹配。" }, "sandbox_scenario": { "type": "string", "enum": [ "success", "delayed", "failed", "expired", "refunded", "settlement_uncertain", "provider_unavailable", "route_unavailable", "no_deposit" ], "description": "仅用于测试环境 DePix/Liquid，优先于金额小数触发条件。未明确指定场景时，.01 至 .08 触发仍有效。生产密钥返回 403 sandbox_only，场景见 GET /sandbox。" } } } } } }, "responses": { "200": { "description": "预览已计算，未创建订单。", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "boolean", "const": true }, "asset": { "type": "string" }, "network": { "type": "string" }, "path": { "type": "string", "enum": [ "FAST", "DEX", "CONVERT", "simulated" ], "description": "该笔卖出将使用的渠道。" }, "amount": { "type": "string", "description": "须发送的加密资产数量，十进制字符串。" }, "brl_amount": { "type": "string", "description": "Pix 的 BRL 金额。" }, "expires_at": { "type": "string", "format": "date-time", "description": "该报价预计适用的有效期限。" }, "merchant_name": { "type": [ "string", "null" ], "description": "仅 br_code 提供，收款码中的收款人名称。" }, "copia_e_cola_buffer_usd": { "type": [ "string", "null" ], "description": "R$ 1 运营预留款的 USDT 等值金额，报价时换算，已包含在总额中，不要重复加上。已有订单保留其原金额。", "example": "0.200000" }, "pix_key": { "type": [ "string", "null" ], "description": "仅 br_code 提供，经遮盖的收款人标识。" }, "pix_key_type": { "type": [ "string", "null" ] }, "partner_fee_bps": { "type": "integer", "description": "本次报价计入的合作伙伴 sub fee，单位 bps。" }, "fee_bps": { "type": "integer", "description": "DePix 卖出费率，单位 bps。" }, "fee_fixed_cents": { "type": "integer", "description": "DePix 卖出固定费用，以分计。" }, "fee_total_cents": { "type": "integer", "description": "总费用，以分计，在 DePix 报价及模拟订单中提供。" }, "net_cents": { "type": "integer", "description": "Pix 净额，以分计，在 DePix 报价及模拟订单中提供。" }, "pix_key_reserve_usd": { "type": [ "string", "null" ], "description": "R$ 1 运营预留款的 USDT 等值金额，报价时换算，已包含在总额中，不要重复加上。已有订单保留其原金额。", "example": "0.200000" }, "reserve_brl": { "type": [ "string", "null" ], "example": "1.00", "description": "新订单固定 R$ 1 运营预留款，已包含在总额中。旧订单保留原预留金额。" } }, "required": [ "preview", "asset", "network", "amount", "brl_amount" ] } } } }, "400": { "description": "请求无效或网络不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "422": { "description": "参数语义无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "sandbox_scenario 须使用测试密钥，未创建订单。" }, "503": { "description": "服务不可用。测试场景 provider_unavailable 不创建订单。" } } } }, "/cashin/catalog": { "get": { "tags": [ "Cash-in" ], "operationId": "catalogoCompra", "security": [ { "ApiKeyAuth": [] } ], "summary": "Cash-in 目录：Pix 收款后可交付的资产", "description": "加密资产交付目录，用于直接 cash-in 及托管余额提现。仅提供 instant/convert 中 entregavel=true 的项目；instant 可能为空。读取各路由的 memoRequired、withdrawFee、withdrawMin 及时效预估。最低 BRL 金额取决于 POST /cashin/preview 的汇率。托管提现须排除 Liquid/DePix。stale=true 表示缓存目录。", "responses": { "200": { "description": "购买目录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogoCompra" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/catalog/dex": { "get": { "tags": [ "Cash-out" ], "operationId": "catalogoDex", "security": [ { "ApiKeyAuth": [] } ], "summary": "可通过 DEX 交易的长尾代币", "description": "列出指定 DEX 网络上 relay 白名单代币。将此处 address 用作 POST /cash-outs 的 token_address；符号可能重复，合约地址用于准确识别。不支持结算的网络返回 400。", "parameters": [ { "name": "chain", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "polygon" ] }, "description": "DEX 网络，目前仅 polygon。" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "按代币符号或地址片段筛选。" } ], "responses": { "200": { "description": "白名单中的代币。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "代币符号并不唯一，请使用 address。" }, "address": { "type": "string", "description": "合约地址，即报价中的 token_address。" }, "decimals": { "type": "integer" } }, "required": [ "symbol", "address", "decimals" ] } } } } }, "400": { "description": "错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/cashin/events": { "get": { "tags": [ "Cash-in" ], "operationId": "eventosDaChave", "security": [ { "ApiKeyAuth": [] } ], "summary": "当前密钥的运行事件流", "description": "当前密钥近期事件，最新在前，包含收款单、卖出、提现及 webhook 投递，与私密监控使用相同事件流。可用于运行界面，但不替代持久历史。接受 X-API-Key 或该密钥的监控 token。", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 60, "maximum": 200 }, "description": "返回事件数，默认为 60。" } ], "responses": { "200": { "description": "近期事件。", "content": { "application/json": { "schema": { "type": "object", "properties": { "projeto": { "type": "string", "description": "密钥名称。" }, "agora": { "type": "string", "format": "date-time", "description": "服务器时间，用于避免界面时钟依赖客户端设备。" }, "eventos": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "fluxo": { "type": "string", "description": "cashin · cashout · payout · webhook" }, "provedor": { "type": "string" }, "ref": { "type": "string", "description": "交易标识。" }, "valor": { "type": "string" }, "estado": { "type": "string" }, "detalhe": { "type": [ "string", "null" ] }, "tx": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/comissao": { "get": { "tags": [ "Comissão (sub fee)" ], "summary": "Sub fee 余额，即合作伙伴佣金", "security": [ { "ApiKey": [] } ], "description": "Sub fee 累计佣金。符合计佣条件的交易须完成结算 / 交付后才入账，Pix 已付款本身不代表佣金可用。新余额充值不产生佣金；购买及转出按对应佣金类别和交易保存费率核算。购买计费基数为收到金额减去平台固定费用。min_saque_cents 为按当前汇率折合 US$ 10 的最低 BRL 提现金额。", "responses": { "200": { "description": "余额、规则及最低提现金额", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comissao" } } } }, "401": { "description": "缺少密钥", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/comissao/extrato": { "get": { "tags": [ "Comissão (sub fee)" ], "summary": "佣金流水", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "before", "in": "query", "schema": { "type": "string" }, "description": "上一页最后一项的 ID" } ], "responses": { "200": { "description": "流水，最新记录在前", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "$ref": "#/components/schemas/ComissaoEvento" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "缺少密钥", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/comissao/sacar": { "post": { "tags": [ "Comissão (sub fee)" ], "summary": "以加密资产形式提取佣金", "security": [ { "ApiKey": [] } ], "description": "手动将佣金提取为加密资产，可选择 GET /cashin/catalog 当前可交付的币种与网络。不再收取 sub fee 或 Lunium 管理费，因为佣金已由用户在原交易承担；仍须考虑兑换及路由成本。最低金额按当前汇率折合 US$ 10，见 GET /comissao 的 min_saque_cents。每滚动 24 小时一次。交付与 cash-in 相同，通过 GET /cashin/{cashin_id}/status 跟踪 saque.cashin_id，或接收 cashin.settled。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents", "payout_address" ], "properties": { "amount_cents": { "type": "integer", "minimum": 1, "description": "待兑换的 BRL 金额，以分计，须 ≥ min_saque_cents。" }, "asset": { "type": "string", "default": "usdt", "description": "usdt、usdc（Polygon），或 GET /cashin/catalog 中的资产。" }, "chain": { "type": "string", "default": "polygon" }, "payout_address": { "type": "string", "description": "您在所选网络的钱包。" }, "payout_tag": { "type": "string", "description": "需要时提供该网络的 memo/tag。" }, "external_id": { "type": "string", "maxLength": 64, "description": "最多 64 个字符的幂等标识。重试保持相同标识及全部参数。差异比较规则因接口而异，不要利用重放修改原交易。409 external_id_divergente 表示检测到冲突。" } } } } } }, "responses": { "200": { "description": "提现已创建，正在交付", "content": { "application/json": { "schema": { "type": "object", "properties": { "saque": { "$ref": "#/components/schemas/Cobranca" }, "comissao": { "$ref": "#/components/schemas/Comissao" } } } } } }, "400": { "description": "valor_invalido | valor_abaixo_do_minimo（提供 min_saque_cents）| rede_indisponivel | asset_invalido | payout_address_invalido | sandbox_sem_saque", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "402": { "description": "saldo_insuficiente — 可用佣金低于请求金额", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "external_id_divergente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "429": { "description": "saque_comissao_diario — 提供 proximo_saque_em", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "provedor_indisponivel — 无有效报价，无法核对最低金额", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/mesh/graph": { "get": { "tags": [ "Mesh · Discovery" ], "operationId": "meshGraph", "summary": "Mesh 智能体关系图", "description": "查看公开网络成员及推荐关系，汇总网络总量，不包含机密资料，无需凭证。", "security": [], "x-lunium-agent-safe": true, "x-lunium-environment": "any", "responses": { "200": { "description": "网络统计与公开智能体资料。", "content": { "application/json": { "schema": { "type": "object", "required": [ "stats", "agents" ], "properties": { "stats": { "type": "object", "additionalProperties": true }, "agents": { "type": "array", "items": { "type": "object", "required": [ "agent_id", "name", "status", "capabilities" ], "properties": { "agent_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "referred_by": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } }, "/sandbox": { "get": { "tags": [ "Sandbox" ], "summary": "查询测试环境功能", "description": "支持的流程、各流程场景、二维码含义、限额及模拟控制接口。包含 DePix/Liquid → Pix 的 cashout_depix 及 scenarios_by_flow.cashout_depix。", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "模拟结果，sandbox=true，不移动真实资金。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "缺少密钥或密钥无效。" }, "403": { "description": "须使用测试密钥。" }, "404": { "description": "当前密钥下未找到交易。" }, "409": { "description": "状态冲突或幂等参数不一致。" }, "503": { "description": "模拟器不可用，绝不会回退至真实服务商执行。" } } } }, "/sandbox/cashin/{cashin_id}/pay": { "post": { "tags": [ "Sandbox" ], "summary": "模拟测试 Pix 收款单的付款", "description": "仅所属测试密钥可确认，重复请求不会重复入账。此接口不能确认生产付款。", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "模拟结果，sandbox=true，不移动真实资金。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "缺少密钥或密钥无效。" }, "403": { "description": "须使用测试密钥。" }, "404": { "description": "当前密钥下未找到交易。" }, "409": { "description": "状态冲突或幂等参数不一致。" }, "503": { "description": "模拟器不可用，绝不会回退至真实服务商执行。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payer_tax_number": { "type": "string", "description": "可选模拟付款人证件，资料不符时模拟退款。" } }, "required": [] } } } }, "parameters": [ { "name": "cashin_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sandbox/operations/{operation_id}/resolve": { "post": { "tags": [ "Sandbox" ], "summary": "核实测试环境中结果不确定的交易", "description": "仅可核实已经处于不确定状态的测试交易，相同结果可安全重放。DePix 卖出的 operation_id 为通过 settlement_uncertain 创建、处于 PROCESSING 的 sbx_… cashout_id。sent 使其完成；failed 进入 REFUNDING，并约 4 秒后达到 REFUNDED。", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "模拟结果，sandbox=true，不移动真实资金。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "outcome 缺失或不是 sent / failed 时，返回 outcome_invalido，acao 为 corrigir，sandbox=true。自 1.44.1 起，校验发生在查找交易前，不改变模拟器。此前缺少 outcome 的请求可能返回 200 却未核实任何操作。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "erro": "outcome_invalido", "acao": "corrigir", "detail": "Informe outcome: sent ou failed.", "sandbox": true } } } }, "401": { "description": "缺少密钥或密钥无效。" }, "403": { "description": "须使用测试密钥。" }, "404": { "description": "当前密钥下未找到交易。" }, "409": { "description": "状态冲突或幂等参数不一致。" }, "503": { "description": "模拟器不可用，绝不会回退至真实服务商执行。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "sent", "failed" ] } }, "required": [ "outcome" ] } } } }, "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/sandbox/events": { "get": { "tags": [ "Sandbox" ], "summary": "查看测试环境生成的事件", "description": "即使未配置 webhook，也会返回已生成事件。实际回调尝试请查询 /webhooks/deliveries。", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "模拟结果，sandbox=true，不移动真实资金。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "缺少密钥或密钥无效。" }, "403": { "description": "须使用测试密钥。" }, "404": { "description": "当前密钥下未找到交易。" }, "409": { "description": "状态冲突或幂等参数不一致。" }, "503": { "description": "模拟器不可用，绝不会回退至真实服务商执行。" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ] } }, "/sandbox/reset": { "post": { "tags": [ "Sandbox" ], "summary": "重置当前密钥的模拟数据", "description": "仅清除所属密钥的模拟状态，之前入队的 webhook 投递历史仍保留。生产密钥会被拒绝。", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "模拟结果，sandbox=true，不移动真实资金。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "缺少密钥或密钥无效。" }, "403": { "description": "须使用测试密钥。" }, "404": { "description": "当前密钥下未找到交易。" }, "409": { "description": "状态冲突或幂等参数不一致。" }, "503": { "description": "模拟器不可用，绝不会回退至真实服务商执行。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "boolean", "const": true } }, "required": [ "confirm" ] } } } } } }, "/sandbox/qr/{cashin_id}.svg": { "get": { "tags": [ "Sandbox" ], "summary": "不可用于真实付款的测试二维码图片", "description": "编码内容为 `SANDBOX:NAO_PAGAVEL:`，不是银行 Pix 支付码，不包含付款操作或客户资料。", "security": [], "parameters": [ { "name": "cashin_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ci_sbx_[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "模拟 SVG 二维码。", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } }, "/cash-outs/{cashout_id}/refund-address": { "post": { "tags": [ "Cash-out" ], "operationId": "informarCarteiraDevolucao", "summary": "为待退款订单提交客户确认的钱包", "description": "订单处于 AWAITING_REFUND_ADDRESS 时使用，refund_address_required: true，并有 cashout.awaiting_refund_address 事件。表示卖出须退款，但尚无钱包。提交您客户在退款网络的钱包，核对订单 refund_network 及 refund_asset。Lunium 绝不自动退至链上充值来源 deposit_from，已登记钱包不可替换。DePix（asset DEPIX、network liquid）自 1.44.0 起适用，须提供客户 Liquid 地址 lq1…。相同地址重复提交返回 200 及原订单；其他地址返回 409 refund_address_imutavel；Lunium 自身地址，包括本订单 / 其他订单充值地址或平台钱包，返回 400 refund_address_invalida。DePix 全部由 Lunium 持有或已确认服务商返还时，进入 REFUNDING，发送 cashout.refunding，按 refund_amount 自动退款；最终 REFUNDED，提供 refund_tx_hash 及 cashout.refunded。若仍待服务商返还确认，则进入 MANUAL_REVIEW 并发送 cashout.under_review，确认后才退款，最高为实际返还金额。仅在卖出失败时要求钱包；不处于 AWAITING_REFUND_ADDRESS 且无钱包的订单返回 409 devolucao_indisponivel。", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "cashout_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refund_address" ], "properties": { "refund_address": { "type": "string", "description": "客户确认的退款地址，须符合订单返回的退款网络。绝不能从 deposit_from 自动推断。DePix 卖出须提供客户 Liquid 地址（lq1…）。" } } } } } }, "responses": { "200": { "description": "订单已更新，请跟踪至 REFUNDED 并取得 refund_tx_hash。DePix 卖出的 state 为 REFUNDING（资金已由 Lunium 持有），或 MANUAL_REVIEW（资金仍在服务商处，等待返还）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashOut" } } } }, "400": { "description": "地址缺失、不符合网络或属于 Lunium 自身，返回 refund_address_invalida；加密资产卖出在退款处理时拒绝地址，也可能使用其他错误码，并在 detail 说明原因。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "X-API-Key 缺失、未知或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "404": { "description": "订单不存在，或属于其他密钥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "状态不兼容或已登记钱包。DePix：已有不同钱包时返回 refund_address_imutavel（acao: parar）；当前未等待钱包时返回 devolucao_indisponivel（acao: esperar），仅在卖出失败后才要求。其他加密资产卖出原因见 detail。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt": { "get": { "tags": [ "Carteira USDT" ], "summary": "USDT 钱包余额与状态", "description": "可用、已预留及确认中的余额，当前支持的网络与最低金额。请从此接口开始。", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarteiraUsdt" } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt/deposits": { "post": { "tags": [ "Carteira USDT" ], "summary": "创建 USDT/USDC 充值请求", "description": "创建要求精确金额、有效期 1 小时的充值请求，见 expires_at。向用户展示 amount_to_send、network_name 及 address。系统自动入账，通过 GET /carteira-usdt/deposits 或 wallet.deposit_credited 跟踪。USDC 按 1:1 计入余额。", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "example": "100", "description": "USDT 金额最多 6 位小数，最低金额见 min_deposit。" }, "network": { "type": "string", "default": "polygon", "description": "须选择 GET /carteira-usdt 返回的 networks[].network 之一。" } } }, "example": { "amount": "100", "network": "tron" } } } }, "responses": { "201": { "description": "请求已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositoCarteira" } } } }, "400": { "description": "valor_invalido、valor_abaixo_do_minimo（提供 min_usdt）、rede_indisponivel。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "muitos_pedidos_abertos。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } }, "get": { "tags": [ "Carteira USDT" ], "summary": "列出充值请求", "description": "最近 100 笔充值请求及其入账情况。", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DepositoCarteira" } } } } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt/statement": { "get": { "tags": [ "Carteira USDT" ], "summary": "钱包流水", "description": "最近 200 笔账本记录，包含每笔之后的余额。", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LancamentoCarteira" } } } } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt/quote": { "post": { "tags": [ "Carteira USDT" ], "summary": "预估使用 USDT 支付 Pix 的成本", "description": "仅预览，不执行交易：查询支付该 Pix 所需的 USDT。Pix 最低金额见 min_payment_brl。", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brl_amount": { "type": "string", "example": "50.00", "description": "收款人实际收到的 BRL 金额。选择 brl_amount + pix_key，或完整 br_code，二者不可同时使用。" }, "br_code": { "type": "string", "description": "Pix Copia e Cola 支付码，以 000201 开头。金额及收款人由支付码确定，不要另传 brl_amount。" }, "funding_source": { "type": "string", "enum": [ "crypto_usdt" ], "description": "可选，仅接受 crypto_usdt。" } } }, "example": { "brl_amount": "50.00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CotacaoPixCarteira" } } } }, "400": { "description": "valor_invalido、valor_abaixo_do_minimo（提供 min_brl）、br_code_invalido、campos_conflitantes、cotacao_recusada、funding_source_invalido。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt/payments": { "post": { "tags": [ "Carteira USDT" ], "summary": "使用 USDT 余额支付 Pix", "description": "预留 USDT、支付 Pix，并按实际成本扣款，未使用预留会释放。异步响应初始为 reservado，通过 GET /carteira-usdt/payments/{payment_id} 或 wallet.payment_completed / wallet.payment_failed 跟踪。使用 external_id 安全重试，相同 external_id 及资料返回同一付款，HTTP 200。", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brl_amount": { "type": "string", "example": "50.00", "description": "收款人实际收到的 BRL 金额。选择 brl_amount + pix_key，或完整 br_code，二者不可同时使用。" }, "br_code": { "type": "string", "description": "Pix Copia e Cola 支付码，以 000201 开头。金额及收款人由支付码确定，不要另传 brl_amount。" }, "funding_source": { "type": "string", "enum": [ "crypto_usdt" ], "description": "可选，仅接受 crypto_usdt。" }, "pix_key": { "type": "string", "description": "Pix 收款标识，使用 brl_amount 时必填。" }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "description": "当收款标识为 11 位数字、可能是 CPF 或手机号时，建议明确填写类型。" }, "quote_id": { "type": "string", "description": "使用 br_code 时，可选传入预览报价的 quote_id。" }, "external_id": { "type": "string", "maxLength": 64, "description": "您的幂等标识。" } } }, "example": { "brl_amount": "50.00", "pix_key": "cliente@exemplo.com", "pix_key_type": "email", "external_id": "pedido-123" } } } }, "responses": { "201": { "description": "付款已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagamentoCarteira" } } } }, "200": { "description": "相同 external_id 的重复请求，返回已存在的付款。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagamentoCarteira" } } } }, "400": { "description": "valor_invalido、valor_abaixo_do_minimo、pix_key_obrigatoria、br_code_invalido、campos_conflitantes、cotacao_recusada。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "409": { "description": "saldo_insuficiente、external_id_divergente、cotacao_divergente。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } }, "get": { "tags": [ "Carteira USDT" ], "summary": "列出付款", "description": "最近 100 笔付款。已完成记录提供 E2E、收款人姓名、部分遮盖的 CPF 及凭证链接。", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PagamentoCarteira" } } } } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }, "/carteira-usdt/payments/{payment_id}": { "get": { "tags": [ "Carteira USDT" ], "summary": "跟踪付款", "description": "查询使用 USDT 支付 Pix 的当前状态。完成后提供 E2E、收款人姓名、部分遮盖的 CPF 及 receipt_url。", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagamentoCarteira" } } } }, "404": { "description": "nao_encontrado。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "401": { "description": "密钥缺失或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "403": { "description": "carteira_nao_liberada：当前项目尚未启用钱包。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "503": { "description": "carteira_indisponivel / pagamentos_indisponiveis：稍后重试，acao: esperar。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } } }, "externalDocs": { "description": "各币种及网络的最低与最高金额", "url": "https://docs.luniumpay.com/minimos" }, "webhooks": { "evento": { "post": { "summary": "Lunium 发送至您接收端的事件", "description": "通过 POST /keys 或 PATCH /keys/me 配置公开 HTTPS webhook_url。快速返回 2xx，后续异步处理；非 2xx 将按指数退避重试，最多 12 次、约 7 小时。始终验签。重试耗尽的记录仍可在 GET /webhooks/deliveries 查看，并通过 retry 恢复。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoWebhook" } } } }, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "已弃用，计划于2026年11月9日停用，2026年8月8日起创建的密钥不再提供。请验证 v2：X-Lunium-Signature，对 \"timestamp.原始请求体\" 计算 HMAC，并拒绝超过 5 分钟的投递。停用前，已有接入仍会收到此旧 v1 签名，即原始请求体的 HMAC。", "deprecated": true }, { "name": "X-Lunium-Signature", "in": "header", "schema": { "type": "string", "pattern": "^t=\\d+,v1=[0-9a-f]{64}$" }, "description": "v2 签名格式：`t=,v1=.<原始请求体>\")>`。应优先采用，因为时间戳参与 HMAC，可拒绝过期投递，防止捕获事件在之后被重放。建议容许时间窗口为 5 分钟。" }, { "name": "X-Lunium-Event", "in": "header", "schema": { "type": "string" }, "description": "事件名称，可在解析请求体前用于路由。" }, { "name": "X-Lunium-Event-Id", "in": "header", "schema": { "type": "string" }, "description": "与请求体中的 event_id 相同。" }, { "name": "X-Lunium-Delivery-Id", "in": "header", "schema": { "type": "string" }, "description": "本次投递尝试的标识，每次重试都会变化，联系支持时可提供。" }, { "name": "X-Lunium-Attempt", "in": "header", "schema": { "type": "integer", "minimum": 1 }, "description": "尝试次数，大于 1 表示可能已经收到过此事件。" }, { "name": "X-Lunium-Timestamp", "in": "header", "schema": { "type": "integer" }, "description": "发送时的 Unix 时间，与 v2 的 t 相同。" } ], "responses": { "200": { "description": "已接收，任何 2xx 均结束该次事件投递流程。" }, "default": { "description": "Nao-2xx agenda nova tentativa." } } } } } }