跳到主要内容

创建退款

开放待确认。 查看适用范围。

对象与完整字段 · 认证、金额与错误 · 接入指南

POST /v1/refunds

针对一个付款项创建退款,返回状态为 requires_action 的 Refund。商户打开 next_action.url,通过钱包签名完成退款操作。创建成功不表示退款成功。

Attributes​

属性位置类型必填说明
Idempotency-Keyheaderstring是本次操作的唯一键;重试沿用原值
attempt_idbodystring是从付款明细中选择的付款标识,须属于当前商户且已有最终确认的到账
amountbodystring是正十进制退款金额,以原付款的稳定币为单位,不得超过所选付款项的 amount_refundable,且须满足原资产精度及转账金额范围
payment_methodbodyobject是本次退款方式
payment_method.typebodystring是erc20_transfer,表示 ERC-20 代币转账
descriptionbodystring否退款说明
metadatabodyobject否商户自定义的字符串键值对,限制见 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"
}

业务错误码