付款明细与退款
接入前请查看接口开放状态,并在目标环境确认账户权限。
| 操作 | 方法与路径 | 开放状态 |
|---|---|---|
| 创建退款 | POST /v1/refunds | 开放待确认 |
| 查询退款 | GET /v1/refunds/{id} | 开放待确认 |
| 列出退款 | GET /v1/refunds | 开放待确认 |
| 取消退款 | POST /v1/refunds/{id}/cancel | 开放待确认 |
本节提供接入约定,商户访问尚待确认。启用前请查看接口开放状态,完成目标环境的开通确认。
Refund 的 payment_intent 标识原付款记录,由平台根据付款项确定,不是 Checkout ID。针对同一 Payment Intent 的进行中退款限制覆盖其所有付款项;创建退款仍使用付款项的 attempt_id,无需由商户转换标识。
商户通过付款明细获取 attempt_id,选择需要退款的付款项,再创建 Refund。例如退货退款、退差价或退回重复付款。每笔 Refund 固定关联一个付款项,创建后不可更换;接收人、网络和稳定币由平台根据该付款项确定。
创建退款后,商户需要通过平台页面使用钱包签名。退款不改变原 Payment Intent 的主状态。
金额、时间和 metadata 格式遵循商户 API 通用约定。
付款明细
商户查询收款下的付款明细,选择一项后,使用其 attempt_id 创建退款。同一付款项重复到账时,更新该项的累计金额;不同付款项分别展示。收款结束后,历史付款及后续到账仍可查询。
Attributes
| 属性 | 类型 | 说明 |
|---|---|---|
attempt_id | string | 付款标识,创建退款时使用 |
amount_received | string | 已最终确认的累计到账金额 |
amount_refunded | string | 已成功退款金额 |
amount_refundable | string | 当前可退款金额,已扣除成功退款及进行中退款占用的金额 |
currency | string | 付款稳定币:usdc、usdt |
chain | integer | 付款网络的标准编号(EIP-155 chain ID) |
金额以 currency 为单位,允许为 "0",其余格式沿用通用约定。尚未最终确认的到账不计入 amount_received 或可退款金额。
对象示例
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "20",
"amount_refunded": "2.5",
"amount_refundable": "17.5",
"currency": "usdc",
"chain": 56
}
查询付款明细
GET /v1/checkouts/{id}/payments
返回当前商户指定收款下已检测到付款的明细,按付款明细创建时间倒序排列,创建时间相同时按 attempt_id 倒序排列。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
id | path | string | 是 | 收款的唯一标识 |
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 next_page_token;第一页不传 |
收款不存在或无权访问时返回 404。本接口无需 Idempotency-Key,无请求体,分页沿用通用约定。返回金额反映当前付款和退款情况,可能随新到账或退款进度变化。
请求示例
GET /v1/checkouts/checkout_example/payments?page_size=20
Authorization: Bearer inv_test_...
返回示例
200 OK,data 中的每一项均为完整的付款明细。next_page_token 为空字符串表示没有下一页。
{
"data": [
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "20",
"amount_refunded": "2.5",
"amount_refundable": "17.5",
"currency": "usdc",
"chain": 56
}
],
"next_page_token": ""
}
尚未检测到付款时返回 {"data":[],"next_page_token":""}。
退款准入与金额
只有达到最终确认高度(finalized)的到账金额可以退款;收款状态为 succeeded 不一定满足此条件。存在尚未最终确认的付款时,仍可退回同一付款项中已最终确认的可退款金额。
每个付款项支持部分退款和多次退款。可退款金额为该项已最终确认的累计到账金额,扣除已退款金额及进行中退款占用的金额,以付款明细中的 amount_refundable 为准。
同一付款项重复到账时,累计金额随之增加,可以在同一 Refund 中退回该项的多笔到账。不同付款项须分别退款,不能合并为一笔 Refund。一个 Payment Intent 的累计退款金额可以超过其应收金额,但每个付款项的已退款与占用金额之和不得超过该项已最终确认的到账金额。
同一 Payment Intent 最多一笔处于 requires_action 或 processing 的退款;前一笔成功或取消后,才允许创建下一笔,并继续受剩余额度限制。
等待商户操作和处理中的退款持续占用额度。执行失败后在原 Refund 上重试,不释放额度;取消成功后释放额度,退款成功后计入已退款金额。
退款金额须能按原稳定币的精度精确表示,并满足该资产的转账金额范围,不自动舍入。不满足要求时,返回 400 参数错误,拒绝创建退款。
退款金额创建后不可修改。如需调整,须先取消原退款,取消成功后重新创建。
未完成的退款可以申请取消,是否允许取消以操作结果为准。退款执行结果尚未确定时不能取消;超时或关闭页面不会自动取消退款或释放额度。
Attributes
| 属性 | 类型 | 说明 |
|---|---|---|
id | string | 退款的唯一标识 |
attempt_id | string | 本次退款关联的付款标识,通过付款明细获取,创建后不可修改 |
payment_intent | string | 原收款的唯一标识 |
amount | string | 退款金额,以 currency 为单位,遵循通用金额格式;表示付款人实际收到的金额,创建后不可修改 |
currency | string | 退款币种:usdc、usdt |
status | string | 退款状态,见下表 |
payment_method | object | 本次退款方式及固定的退款目标,创建后不可修改 |
next_action | object / null | 商户需要完成的下一步操作;无需操作时为 null |
last_execution_error | object / null | 最近一次已确定的退款执行失败,包含 code 和 message;无失败记录或退款成功后为 null |
description | string / null | 商户填写的退款说明 |
metadata | object | 商户自定义的字符串键值对;无内容时为 {}。最多 50 对,键最长 40 个字符,值最长 500 个字符 |
created_at | string | 创建时间,使用 UTC RFC 3339 格式 |
updated_at | string | 最后更新时间,使用 UTC RFC 3339 格式 |
Gas 由商户另行承担,不从 amount 中扣除。
status
| 值 | 含义 |
|---|---|
requires_action | 等待商户通过钱包执行退款,包括上次执行已确定失败后等待重试 |
processing | 存在结果尚未确定的退款执行,正在核实链上结果 |
succeeded | 退款转账已达到最终确认高度(finalized) |
canceled | 退款已取消,不再执行,已释放占用额度 |
Refund 表达退款目标,单次执行失败不表示退款目标结束。只有已确定上次执行失败,且没有其他结果未知的执行时,才从 processing 回到 requires_action,由商户在同一 Refund 上重新签名执行。
商户拒绝签名或关闭签名页面,退款保持 requires_action。广播结果未知、交易暂未查到或最终确认前发生回滚时,继续保持 processing,不能仅据此重新发起转账。关闭签名页面不撤销已经签名的交易,商户应先核对原执行结果,避免重复退款。
succeeded、canceled 为终态,不能重新执行退款。
payment_method
| 属性 | 类型 | 说明 |
|---|---|---|
type | string | 当前仅支持 erc20_transfer,表示直接通过 ERC-20 代币转账退款,不经过 IPP 隐私支付流程 |
erc20_transfer | object | ERC-20 转账信息 |
erc20_transfer.chain | integer | attempt_id 对应付款的网络标准编号(EIP-155 chain ID) |
erc20_transfer.recipient_address | string | attempt_id 对应的原付款人的退款接收地址,由平台确定,不可修改 |
商户选择退款方式 type=erc20_transfer,网络、稳定币资产和接收地址由平台根据 attempt_id 确定,商户不能指定其他目标。无法可靠确定退款接收地址时,拒绝创建退款。
next_action
| 属性 | 类型 | 说明 |
|---|---|---|
type | string | redirect,表示打开平台页面完成操作 |
url | string | 商户完成钱包签名操作的平台页面地址 |
requires_action 状态下返回此对象;其他状态为 null。打开页面或完成签名不表示退款成功,退款结果以 status 为准。
last_execution_error
记录最近一次已确定的退款执行失败,不表示 Refund 已结束。新的执行失败覆盖旧值,重新执行或取消时保留,退款成功后清空。
| 属性 | 类型 | 说明 |
|---|---|---|
code | string | 稳定的失败码,使用小写 snake_case |
message | string | 英文失败说明,程序不应依赖具体措辞 |
code | 含义 |
|---|---|
transaction_reverted | 已最终确认退款交易执行回退,未完成转账 |
transaction_replaced | 已最终确认原交易被替代,且替代交易未完成该退款 |
参数错误等请求失败通过 HTTP error 返回,不写入此字段。商户拒绝签名,或余额、Gas 不足导致钱包尚未提交交易时,不记录执行失败。结果未知也不写入此字段;是否允许重试,以 status 为准。
对象示例
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "requires_action",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": {
"type": "redirect",
"url": "https://connect.invisipay.fi/refunds/re_example"
},
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:00:00Z"
}
创建退款
POST /v1/refunds
针对一个付款项创建退款,返回状态为 requires_action 的 Refund。商户打开 next_action.url,通过钱包签名完成退款操作。创建成功不表示退款成功。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
attempt_id | body | string | 是 | 从付款明细中选择的付款标识,须属于当前商户且已有最终确认的到账 |
amount | body | string | 是 | 正十进制退款金额,以原付款的稳定币为单位,不得超过所选付款项的 amount_refundable,且须满足原资产精度及转账金额范围 |
payment_method | body | object | 是 | 本次退款方式 |
payment_method.type | body | string | 是 | erc20_transfer,表示 ERC-20 代币转账 |
description | body | string | 否 | 退款说明 |
metadata | body | object | 否 | 商户自定义的字符串键值对,限制见 Refund 属性定义 |
payment_intent、currency、网络和接收地址由平台根据 attempt_id 确定,无需填写。同一 Payment Intent 已有进行中的退款时,拒绝创建另一笔;原请求的重试仍按通用幂等规则返回同一笔退款的首次操作结果。
请求与认证、金额格式及错误响应沿用商户 API 通用约定。
请求示例
POST /v1/refunds
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount": "2.5",
"payment_method": {
"type": "erc20_transfer"
},
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
}
}
返回示例
200 OK,返回完整的 Refund 对象。通过 next_action.url 打开钱包签名页面,无需再调用确认退款接口。
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "requires_action",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": {
"type": "redirect",
"url": "https://connect.invisipay.fi/refunds/re_example"
},
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:00:00Z"
}
查询退款
GET /v1/refunds/{id}
查询一笔退款的当前状态、签名入口及最近执行错误,可用于恢复签名页面展示或核对退款结果。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
id | path | string | 是 | 退款的唯一标识 |
仅允许查询当前商户的退款。退款不存在或无权访问时,统一返回 404,错误响应沿用通用约定。本接口无需 Idempotency-Key,无请求体。
请求示例
GET /v1/refunds/re_example
Authorization: Bearer inv_test_...
返回示例
200 OK,返回完整的 Refund 对象。以下示例表示退款已成功,商户无需再进行钱包操作。
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "succeeded",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": null,
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:05:00Z"
}
列出退款
GET /v1/refunds
查询当前商户的退款列表,按创建时间倒序排列,创建时间相同时按 ID 倒序排列。未提供筛选条件时返回所有状态的退款;同时提供多个筛选条件时,结果须同时满足这些条件。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
payment_intent | query | string | 否 | 按原收款的唯一标识筛选 |
attempt_id | query | string | 否 | 按付款标识筛选 |
status | query | string | 否 | 按退款状态筛选:requires_action、processing、succeeded、canceled |
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 next_page_token;第一页不传 |
翻页时保持筛选条件不变,分页规则见通用约定。本接口无需 Idempotency-Key,无请求体。
请求示例
GET /v1/refunds?payment_intent=pi_example&status=succeeded&page_size=20
Authorization: Bearer inv_test_...
返回示例
200 OK,data 中的每一项均为完整的 Refund 对象。next_page_token 为空字符串表示没有下一页。
{
"data": [
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "succeeded",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": null,
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:05:00Z"
}
],
"next_page_token": ""
}
没有匹配记录时返回 {"data":[],"next_page_token":""}。
取消退款
POST /v1/refunds/{id}/cancel
申请取消一笔退款。仅 requires_action 状态可申请,是否允许取消以操作结果为准;processing、succeeded 状态拒绝取消。已取消的退款再次取消,返回当前对象。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
id | path | string | 是 | 退款的唯一标识 |
请求体为 {}。仅允许操作当前商户的退款,退款不存在或无权访问时统一返回 404。错误响应及幂等行为沿用商户 API 通用约定。
取消成功后释放占用额度,商户才可创建替代退款。请求超时或无法确定取消结果时,沿用原幂等键重试;有效幂等重试返回首次操作结果。
请求示例
POST /v1/refunds/re_cancel_example/cancel
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: ec3a7e90-673e-41a1-94d0-6724fba6a339
{}
返回示例
200 OK,返回状态为 canceled 的完整 Refund 对象,next_action 为 null。取消保留最近执行错误,不产生新的执行错误。
{
"id": "re_cancel_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "canceled",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": null,
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:01:00Z"
}
退款 Webhook 事件
平台通过已配置的通知端点发送退款状态通知,沿用轻量事件格式。事件的 related_object.type 为 refund,related_object.id 为退款标识;完整退款信息通过查询退款获取。
事件类型
type | 触发条件 |
|---|---|
refund.requires_action | 退款创建成功,或执行失败后重新进入 requires_action,等待商户操作 |
refund.processing | 退款进入 processing,正在核实退款结果 |
refund.succeeded | 退款进入 succeeded,达到最终确认要求 |
refund.canceled | 退款进入 canceled,取消成功 |
同一状态重复核实不产生新事件;重新进入该状态时产生新的事件。执行失败详情通过查询退款的 last_execution_error 获取。
事件示例
{
"id": "evt_refund_example",
"type": "refund.succeeded",
"related_object": {
"id": "re_example",
"type": "refund"
},
"created_at": "2026-10-27T08:05:00Z"
}
通知可能重复或乱序到达。商户应按事件 id 去重,并查询退款确认当前状态,避免用较早的通知覆盖较新的状态。同一事件重复投递时,事件标识和内容保持不变。
接收方式、签名验证和投递重试分别沿用接收事件、签名验证和投递与重试规则。
错误码
以下错误适用于退款接口,响应结构和通用错误见错误响应。
error.code | HTTP 状态码 | 含义 | 适用接口 |
|---|---|---|---|
checkout_not_found | 404 | 会话不存在或无权访问 | 查询付款明细 |
refund_not_found | 404 | 退款不存在或无权访问 | 查询、取消 |
payment_attempt_not_found | 404 | 付款标识不存在或无权访问 | 创建 |
payment_not_finalized | 400 | 所选付款项尚无已最终确认的到账 | 创建 |
refund_amount_exceeded | 400 | 金额超过所选付款项的剩余可退款金额,包括额度已用完 | 创建 |
refund_in_progress | 409 | 同一 Payment Intent 已有进行中的退款 | 创建 |
refund_method_unsupported | 400 | 不支持该退款方式 | 创建 |
refund_not_cancelable | 400 | 当前退款不允许取消 | 取消 |
以上错误表示请求未被接受,不写入 last_execution_error;该字段仅记录退款执行过程中的失败。参数格式、认证、限流及幂等错误沿用通用约定。
原请求的有效幂等重试不因已有进行中退款而返回 refund_in_progress。已取消的退款再次取消仍返回当前对象,不返回 refund_not_cancelable。