> ## Documentation Index > Fetch the complete documentation index at: https://docs.cbpayapp.com/llms.txt > Use this file to discover all available pages before exploring further. # 退款一笔卡片收款 > 将资金退还给持卡人，并冲销你余额中的入账。仅支持状态为 `credited` 的卡片收款 （其他通道返回 `refund_not_supported`）—— 且仅当其余额实际可用时：结算仍待处理的 已确认收款（`settlement_pending: true`，余额在 `settle_at` 到账）将以 `422 settlement_pending` 被拒。按毛额扣款：原收款的手续费与汇率点差 不可退还。`idempotency_key` 为必填；重放会返回同一笔退款并带 `idempotency_hit`， 绝不会向处理方发送第二次退款。调用方为会话时需要 OTP（API key 豁免）。 ## OpenAPI ````yaml /openapi.zh.yaml post /v1/payins/{payinID}/refunds openapi: 3.1.0 info: title: CBPay API version: '2.62' description: > CBPay 是一个多币种支付平台:覆盖拉美的法币付款(payout)与收款(payin)、内部转账、链上充值与提现,以及 KYC 筛查。每个账户持有四个相互独立的虚拟余额——USDT(运营货币)、USDC、BTC 和 GOLD(纯金克数)——可通过兑换(swap)按需转换。 payout 和服务费可从四个余额中的任意一个支付(用 `PUT /v1/settlement` 设置默认值,或在单笔 payout 中用 `settlement_asset` 覆盖);payin 可自动兑换为你选择的资产(`default_payin_asset`)。 所有金额均为十进制字符串,遵循各货币的精度(USDT/USDC/GOLD 为 6 位小数,BTC 为 8 位)。错误始终返回 `{"error": "", "message": ""}`。 servers: - url: https://api.qbank.cl/platform description: Live（生产环境，真实资金） - url: https://cryptobank.qbank.cl/platform description: Test（沙盒，模拟资金 — pk_test_ 密钥） security: - bearerAuth: [] tags: - name: 凭证 description: >- 每笔操作的品牌化 PDF 凭证,附带公开的签名 QR 真伪校验、每个响应/webhook 中的 receipt_url,以及最终状态时的自动邮件发送。 - name: 身份认证 description: 注册与登录账户成员。会话有效期 24 小时。 - name: 账户 description: 调用账户的档案、成员与 API key。 - name: 余额 description: 余额、流水历史与外汇汇率。 - name: 付款(Payouts) description: 从你选择的结算余额扣款的法币派发(默认 USDT)。 - name: 收款(Payins) description: 法币充值(二维码、转账、专属账户、pull 收款、卡片、checkout 链接)自动入账——默认入账 USDT,也可自动兑换为你选择的结算资产。 - name: 收银台(Checkout) description: >- 通用收银台链接(`POST /v1/payins`,`method: "checkout"`)与公开支付页端点——多国法币、每个链接专属临时钱包的加密货币支付,以及 CBPay 直接支付,按你选择的资产结算。 - name: 已保存卡片(Stored cards) description: 在 3-D Secure 支付中经付款人明确同意保存的卡片(COF)。可列出、吊销并按需扣款(MIT),无需再次索要卡片信息。 - name: 订阅(Subscriptions) description: 由平台调度器管理的已保存卡片周期性扣款——按日、周、月或年,支持暂停/恢复/取消与自动催收。 - name: 转账 description: CBPay 账户之间的免费内部转账(个人或企业,任意组合)。 - name: 联系人 description: 按账户维护的收款人通讯录(CBPay、银行与加密货币目的地),支持手机号匹配与每次发送时自动保存。 - name: 兑换(Swaps) description: 按账户报价即时兑换账户的 USDT、USDC、BTC 与 GOLD 余额。 - name: 加密货币 description: 链上充值与提现(TRON、Ethereum 和 Bitcoin)。 - name: 隔离钱包 description: 拥有自身余额的链上钱包(企业不限数量;个人每个网络+资产组合 1 个)——创建、导入、发送、导出私钥与自动转发。余额存在于链上,从不进入账本。 - name: 签名证明 description: 使用钱包进行加密消息签名(EIP-191 ETH/EVM、TIP-191 TRON)——创建、列出、查询和吊销具有公开验证功能的签名证明。 - name: 钱包链接 description: 通过签名 nonce 挑战将外部钱包(custody=client)链接到你的账户——创建挑战、验证签名、列出和吊销链接。 - name: QR Crypto POS description: >- 面向拥有实体 POS 终端的处理商（企业账户）的定额加密货币二维码收款：已验证商户、每笔收款专属地址 + 二维码、支付早期检测、按商户对账，以及经加密货币提现通道的退款。 - name: KYC / KYB description: 身份验证:个人 KYC、企业 KYB——你自己的入驻验证,以及企业账户的第三方验证。 - name: AML 筛查 description: 针对个人与企业的独立 AML 筛查(制裁、PEP 与负面媒体名单),含重新筛查、持续监控与可下载的 PDF 报告。 - name: 钱包筛查 description: 区块链地址的 AML 风险评估(制裁、非法资金暴露),按次收费;另附提现与充值的免费自动防护。 - name: Qscore description: >- API 优先的信用局。签发完整的信用报告，评分为 1-999（A-E 等级，无数据时为 SC），查询主体的最新评分，并管理 ARCO 争议。智利先行，设计上与国家无关。每份签发的报告都带有公开验证码。 - name: 分析 - name: Webhooks description: 接收签名事件通知的订阅。 - name: 状态 description: 服务可用性。 - name: 银行服务 description: 真实银行账户:通过国际银行通道接收、持有与发送资金。 - name: 卡片 description: 以 Just-In-Time 方式从你选择的余额(USDT、USDC、BTC 或 GOLD)消费的虚拟卡与实体卡,支持按卡设置消费限额。 - name: 安全(OTP) description: >- 通过 SMS/WhatsApp/email 发送的一次性验证码,保护敏感操作;并提供自助 2FA 偏好设置。仅适用于用户会话——API key 豁免。 - name: 通行密钥 description: >- 通过 WebAuthn 使用设备生物识别(Face ID、Touch ID、Windows Hello、安全密钥)的无密码登录、带备份码的验证器应用(TOTP),以及会话/设备管理。 - name: 社交登录 description: >- 通过令牌交换以 Google、Apple、Microsoft 和 Facebook 实现无密码注册与登录。前端获取提供方凭证;API 验证后签发 CBPay 会话。 - name: 实时事件 description: >- Server-Sent Events 流，实时推送账户内（管理员则为整个组织）发生的所有事件，支持通过 `Last-Event-ID` 重放、可选的初始快照，以及 90 天可查询历史。 paths: /v1/payins/{payinID}/refunds: parameters: - name: payinID in: path required: true schema: type: string format: uuid post: tags: - Payins summary: 退款一笔卡片收款 description: >- 将资金退还给持卡人，并冲销你余额中的入账。仅支持状态为 `credited` 的卡片收款 （其他通道返回 `refund_not_supported`）—— 且仅当其余额实际可用时：结算仍待处理的 已确认收款（`settlement_pending: true`，余额在 `settle_at` 到账）将以 `422 settlement_pending` 被拒。按毛额扣款：原收款的手续费与汇率点差 不可退还。`idempotency_key` 为必填；重放会返回同一笔退款并带 `idempotency_hit`， 绝不会向处理方发送第二次退款。调用方为会话时需要 OTP（API key 豁免）。 operationId: createPayinRefund parameters: - name: X-OTP-Token in: header required: false schema: type: string description: 一次性 OTP 令牌（见 OTP 指南）。仅适用于会话调用方。 requestBody: required: true content: application/json: schema: type: object required: - idempotency_key properties: amount: type: string description: 以原始本地货币计价的金额。省略则退还剩余可退金额的全部。 kind: type: string enum: - refund - void description: '`refund`（默认）退还已清算的交易；`void` 撤销尚未清算的交易。' reason: type: string idempotency_key: type: string example: amount: '150.00' kind: refund reason: customer request idempotency_key: refund-order-8842 responses: '200': description: 相同幂等键的重放 —— 返回同一笔退款，并带 `idempotency_hit`。 content: application/json: schema: $ref: '#/components/schemas/PayinRefund' example: refund_id: 6f1a2b3c-4d5e-4f6a-8b9c-0d1e2f3a4b5c payin_id: d0135ed5-8e9c-4f8b-a522-8ec100470426 account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d kind: refund status: completed currency: USD local_amount: '150.00' usdt_debited: '150.000000' requested_by: account idempotency_key: refund-order-8842 reason: customer request idempotency_hit: true receipt_url: >- https://api.qbank.cl/platform/v1/payin-refunds/6f1a2b3c-4d5e-4f6a-8b9c-0d1e2f3a4b5c/receipt created_at: '2026-07-25T13:10:00Z' updated_at: '2026-07-25T13:10:03Z' '201': description: 退款已创建并获处理方批准，余额已扣款。 content: application/json: schema: $ref: '#/components/schemas/PayinRefund' example: refund_id: 6f1a2b3c-4d5e-4f6a-8b9c-0d1e2f3a4b5c payin_id: d0135ed5-8e9c-4f8b-a522-8ec100470426 account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d kind: refund status: completed currency: USD local_amount: '150.00' usdt_debited: '150.000000' requested_by: account idempotency_key: refund-order-8842 reason: customer request receipt_url: >- https://api.qbank.cl/platform/v1/payin-refunds/6f1a2b3c-4d5e-4f6a-8b9c-0d1e2f3a4b5c/receipt created_at: '2026-07-25T13:10:00Z' updated_at: '2026-07-25T13:10:03Z' '202': description: >- 结果不确定的下发：处理方可能已经退款。退款保持 `pending`，你的余额继续被冻结， 由对账流程解决。我们绝不自行重试 —— 使用相同的 `idempotency_key` 重试， 会拿回同一笔退款。 content: application/json: schema: $ref: '#/components/schemas/PayinRefund' example: refund_id: 6f1a2b3c-4d5e-4f6a-8b9c-0d1e2f3a4b5c payin_id: d0135ed5-8e9c-4f8b-a522-8ec100470426 account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d kind: refund status: pending currency: USD local_amount: '150.00' usdt_debited: '150.000000' requested_by: account idempotency_key: refund-order-8842 reconciliation_required: true receipt_url: >- https://api.qbank.cl/platform/v1/payin-refunds/6f1a2b3c-4d5e-4f6a-8b9c-0d1e2f3a4b5c/receipt created_at: '2026-07-25T13:10:00Z' updated_at: '2026-07-25T13:10:00Z' '400': description: '`idempotency_key_required` 或 `invalid_amount` / `invalid_payload`。' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: idempotency_key_required message: idempotency_key is required '401': $ref: '#/components/responses/Unauthorized' '402': description: '`insufficient_funds` —— 请先充值余额，再用相同的 `idempotency_key` 重试。' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_funds message: >- the account balance is not enough to fund this refund; top up and retry with the same idempotency_key '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: '`idempotency_conflict` —— 另一笔使用该键的退款正在进行中。' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: idempotency_conflict message: another refund with this key is in flight '422': description: >- `payin_not_refundable`、`refund_not_supported`、`refund_exceeds_payin`、 `settlement_pending`（收款已确认，但其余额仍排期在未来的 `settle_at` —— 请等待到期，或先请机构管理员释放结算）， 或处理方拒绝的退款（响应体即该退款，`status: failed` 并带 `failure_reason`； 扣款已全额冲回）。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: refund_exceeds_payin message: >- the requested amount exceeds what is left to refund on this payin components: schemas: PayinRefund: type: object properties: refund_id: type: string format: uuid payin_id: type: string format: uuid account_id: type: string format: uuid kind: type: string enum: - refund - void - chargeback description: '`chargeback` 由发卡机构强制发起 —— 会自动记账，并可能使余额变为负数。' status: type: string enum: - pending - completed - failed currency: type: string description: 原始收款的货币。 local_amount: type: string usdt_debited: type: string description: 从 USDT 余额中扣除的金额。原收款的手续费与汇率点差不予退还。 requested_by: type: string enum: - account - admin - issuer reason: type: string failure_reason: type: string description: 当 `status` 为 `failed` 时出现 —— 扣款已全额冲回。 idempotency_key: type: string idempotency_hit: type: boolean reconciliation_required: type: boolean description: 退款处于 `pending` 期间出现 —— 结果由对账流程解决，绝不会重新下发。 balance_after: type: string description: 出现在 `payin_refunded` webhook 中 —— 该笔变动后的 USDT 余额（拒付时可能为负）。 receipt_url: type: string created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object properties: error: type: string description: 机器可读的错误代码(snake_case)。 example: insufficient_funds message: type: string description: 人类可读的说明。 responses: Unauthorized: description: 凭证缺失或无效(`unauthorized`)。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: invalid or missing credentials Forbidden: description: 此端点不允许该凭证级别(`forbidden`)。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: forbidden message: credentials required NotFound: description: 资源未找到(`not_found`)。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found message: resource not found securitySchemes: bearerAuth: type: http scheme: bearer description: | 会话 JWT(来自注册/登录)或 API key(`pk_...`)。 也接受 `X-API-Key: ` 作为替代请求头。 ````