退款

了解如何通过 Tokenz 退款 API 处理已完成付款的退款。

退款 API 允许您为已完成的订单向客户退还资金。您可以发起退款、跟踪退款状态并管理退款生命周期。

金额格式： API 中所有货币值（如 amount 字段）均以各货币的最小单位表示。请参阅支持的货币了解每种货币的确切编码。

概述

退款系统提供退款管理功能：

退款创建：为已完成的订单发起指定原因的退款
状态跟踪：通过 pending 或 failed 状态监控退款进度
审计追踪：跟踪谁发起了退款以及何时发起
测试模式：完整的测试环境支持用于开发和测试

退款生命周期

退款经历定义的生命周期：

退款发起：商户或 API 为已完成的订单发起退款
处理中：退款异步处理（状态保持为 pending）
失败：如果出现问题，退款可能失败（状态变为 failed）

退款状态值

退款可以有以下状态：

pending：退款已发起并正在处理中
failed：退款尝试失败

流程图

创建退款

要发起退款，请向退款端点发送包含订单 ID 和退款原因的 POST 请求：

bash

curl --request POST \
  --url https://api.tokenz.one/v2/refunds \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "orderId": "order_1p4LPTRKB5Z",
    "reason": "customer_cancellation",
    "detail": "Customer requested cancellation"
  }'

必需参数

orderId：要退款的订单 ID（必须是已完成的订单）
reason：退款原因。有效值：
- customer_cancellation：客户取消了订单
- duplicate_payment：付款重复
- other：其他原因（需要 detail 字段）
detail：可选的详细说明（当 reason 为 other 时必需）

响应

成功创建退款返回退款对象：

json

{
  "refund": {
    "id": "refund_1p4LS47fB1h",
    "object": "refund",
    "orderId": "order_1p4LPTRKB5Z",
    "amount": {
      "amount": 10000,
      "currency": "JPY"
    },
    "consumerAmount": {
      "amount": 10000,
      "currency": "JPY"
    },
    "status": "pending",
    "reason": "customer_cancellation",
    "initiatedBy": "apikey",
    "test": false,
    "createdAt": "2024-10-07T10:30:00Z",
    "updatedAt": "2024-10-07T10:30:00Z"
  }
}

获取退款

获取特定退款的当前状态和详细信息：

bash

curl --request GET \
  --url https://api.tokenz.one/v2/refunds/refund_1p4LS47fB1h \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

响应字段

id：退款的唯一标识符
orderId：退款订单的 ID
amount：以最小货币单位表示的退款金额
consumerAmount：以消费者货币表示的退款金额（可选）
status：当前退款状态（pending、failed）
reason：提供的退款原因
initiatedBy：谁发起了退款（merchantUser、apikey、admin）
test：这是否为测试退款
createdAt：创建退款的时间戳
updatedAt：最后状态更新的时间戳

列出退款

使用可选过滤器列出所有退款：

bash

curl --request GET \
  --url 'https://api.tokenz.one/v2/refunds?orderId=order_1p4LPTRKB5Z&limit=10' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

查询参数

orderId：按订单 ID 过滤退款
status：按退款状态过滤（pending、failed）
limit：返回的最大退款数（1-100，默认：10）
createdAfter：过滤在此时间戳之后创建的退款（ISO 8601）
createdBefore：过滤在此时间戳之前创建的退款（ISO 8601）

响应

json

{
  "refunds": {
    "items": [
      {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "status": "pending",
        "reason": "customer_cancellation",
        "initiatedBy": "apikey",
        "test": false,
        "createdAt": "2024-10-07T10:30:00Z",
        "updatedAt": "2024-10-07T10:30:00Z"
      }
    ],
    "hasMore": false
  }
}

退款 Webhook

配置 webhook 以接收有关退款事件的通知：

`refund.created`

退款创建时触发：

json

{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "object": "refund.created",
  "createdAt": "2024-10-07T10:30:00Z",
  "test": false,
  "eventData": {
    "type": "refund",
    "version": "v2",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "status": "pending",
        "reason": "customer_cancellation",
        "initiatedBy": "apikey",
        "test": false,
        "createdAt": "2024-10-07T10:30:00Z",
        "updatedAt": "2024-10-07T10:30:00Z"
      }
    }
  }
}

`refund.failed`

退款失败时触发：

json

{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "object": "refund.failed",
  "createdAt": "2024-10-07T10:40:00Z",
  "test": false,
  "eventData": {
    "type": "refund",
    "version": "v2",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "status": "failed",
        "reason": "customer_cancellation",
        "initiatedBy": "apikey",
        "test": false,
        "createdAt": "2024-10-07T10:30:00Z",
        "updatedAt": "2024-10-07T10:40:00Z"
      }
    }
  }
}

错误处理

退款 API 返回标准 HTTP 状态代码和详细的错误消息：

常见错误

400 Bad Request：无效的请求参数或格式错误的请求
401 Unauthorized：无效或缺少 API 密钥
403 Forbidden：执行退款的权限不足
404 Not Found：未找到订单或退款
422 Unprocessable Entity：业务逻辑错误

错误响应格式

json

{
  "status": 422,
  "code": "refund.amount-exceeds-available",
  "message": "Refund amount exceeds available refund amount for this order"
}

测试退款

使用测试模式开发和测试您的退款集成：

使用测试 API 密钥（以 test_ 为前缀）
使用测试结账会话创建测试订单
测试退款的 ID 中将有 _t 后缀（例如 refund_1p4LS47fB1h_t）
测试 webhook 发送到您配置的测试 webhook 端点

API 参考

端点

POST /v2/refunds - 创建新退款
GET /v2/refunds/{refundId} - 获取特定退款
GET /v2/refunds - 使用可选过滤器列出退款

认证

所有端点都需要通过 Bearer 令牌进行认证：

Code

Authorization: Bearer secret_test_YOUR_KEY_HERE