处理全额与部分退款
付款明细与退款的开放状态待确认。确认目标环境和账户支持查询付款明细、创建、查询及取消退款后,再启用本流程。参阅接口可用性。
退款针对一项实际付款,而不是直接退回订单应收金额。先查询 Checkout 的付款明细,取得 attempt_id,再创建 Refund。平台固定原付款网络、稳定币和退款接收地址;商户不能改为其他收款人。退款采用直接 ERC-20 转账,不经过 IPP 隐私支付流程,商户另付 Gas,付款人收到完整的 amount。
准备服务端参数
开始前确认测试环境已开放本流程需要的付款明细及退款操作。将 Key、Checkout ID、Refund ID 和示例 attempt_id 替换为实际值;幂等键示例须替换为自己持久化的新操作键。Key 只保留在服务端,钱包页面由商户自己的服务端提供必要信息。
export API_BASE='https://connect-dev.invisipay.fi'
export API_KEY='inv_test_REPLACE_WITH_YOUR_SERVER_KEY'
export CHECKOUT_ID='checkout_REPLACE_WITH_YOUR_CHECKOUT_ID'
export REFUND_ID='re_REPLACE_WITH_CREATED_REFUND_ID'
export REFUND_CREATE_KEY='550e8400-e29b-41d4-a716-446655440000'
export REFUND_CANCEL_KEY='ec3a7e90-673e-41a1-94d0-6724fba6a339'
1. 选择付款项及可退金额
curl --fail-with-body --silent --show-error --get \
"$API_BASE/v1/checkouts/$CHECKOUT_ID/payments" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode 'page_size=20'
示例付款项见下;这不是完整分页响应:
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "20",
"amount_refunded": "2.5",
"amount_refundable": "17.5",
"currency": "usdc",
"chain": 56
}
只有达到 finalized 的到账才计入 amount_received,Checkout 已 succeeded 不一定代表可退。amount_refundable 已扣除成功退款和进行中退款的占用。本例还可退 17.5 USDC:退 2.5 是部分退款,退 17.5 是退清当前剩余可退金额;不要按原始 20 再退款。
同一付款项后来重复到账会增加该项累计金额,可在一笔 Refund 中退回;不同 attempt_id 必须分别创建。同一 Payment Intent 最多一笔 requires_action 或 processing 的 Refund,即使选择其他 attempt_id 也受此限制。Refund 的 payment_intent 标识原收款;进行中退款数量限制覆盖该收款下的所有付款项。
金额使用币种单位的正十进制字符串,通用上限为 8 位小数,还必须精确满足原资产精度和转账范围。例如精度为 6 时不能提交第 7 位非零小数;服务不会自动舍入。不要用浮点数计算退款金额。
2. 创建并保存 Refund
本例使用付款项占位 ID,部分退回 2.5 USDC。平台根据 attempt_id 确定 payment_intent、currency、网络和接收地址,不要额外传入这些字段:
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/refunds" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $REFUND_CREATE_KEY" \
--data '{"attempt_id":"8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21","amount":"2.5","payment_method":{"type":"erc20_transfer"},"description":"Price adjustment","metadata":{"return_id":"RETURN_001"}}'
成功 HTTP 200 返回完整 Refund,初始 status=requires_action。保存其 id、attempt_id、payment_intent、金额和本地售后单关联。HTTP 成功只表示创建目标;还未完成资金转账。
创建金额及付款项不可修改。如需调整,先成功取消原 Refund,再按剩余额度创建新目标。网络超时或崩溃时,用原 Idempotency-Key 和完全相同参数重试;有效重放返回首次结果,不代表当前最新状态。24 小时后先确认原结果,再决定是否创建新操作。
3. 打开钱包签名并核对结果
在 requires_action 时打开返回的 next_action.url,让商户通过平台页面用钱包签名。不要自行拼接签名 URL,也没有额外的确认退款 API。打开页面、签名或关闭页面都不是退款成功证明。
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/refunds/$REFUND_ID" \
-H "Authorization: Bearer $API_KEY"
| status | 下一步 |
|---|---|
| requires_action | 等待商户签名;若此前已发送交易,先核对原执行,避免重复 |
| processing | 平台核实未确定的链上结果;不重新转账,不能取消 |
| succeeded | 退款转账已 finalized;更新售后单,不能再次执行 |
| canceled | 已释放占用,不能执行该 Refund |
已确定的执行失败通过 last_execution_error 报告,例如 transaction_reverted 或 transaction_replaced。只有平台确认旧执行失败且无其他未知执行,状态回到 requires_action 时,才在同一 Refund 上重试签名。失败期间额度继续占用。钱包未提交前的拒签、余额或 Gas 不足及未知广播结果,不应当作已确定链上失败。
4. 取消或对账
仅 requires_action 可申请取消,以操作结果为准;processing 和 succeeded 拒绝取消。取消请求使用独立幂等键和 {},成功后才释放金额:
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/refunds/$REFUND_ID/cancel" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $REFUND_CANCEL_KEY" \
--data '{}'
取消结果未知时复用原取消键查询/重试,不能立即创建替代退款。按事件 ID 去重处理 refund.* 通知,并认证查询当前 Refund,防止乱序通知覆盖最新状态。退款不改写原 Payment Intent 主状态,订单退款情况单独记录。
退款额度不足返回 refund_amount_exceeded;没有 finalized 到账返回 payment_not_finalized;同一 Payment Intent 已有进行中目标返回 refund_in_progress。它们是请求错误,不写入 last_execution_error。完整字段、查询筛选、通知和错误见付款明细与退款 API。