返金

Tokenz返金APIを使用して、完了した決済の返金処理を行う方法を学びます。

返金APIを使用すると、完了した注文に対して顧客へ資金を返却できます。返金の開始、返金ステータスの追跡、返金ライフサイクルの管理が可能です。

金額フォーマット： すべての金額値（amount フィールドなど）は各通貨の最小単位で表現されます。通貨ごとの正確なエンコーディングについては、サポートされている通貨を参照してください。

概要

返金システムは返金管理機能を提供します：

返金作成：指定した理由で完了した注文の返金を開始
ステータス追跡：pendingまたはfailedステータスを通じて返金の進捗を監視
監査証跡：返金を開始したユーザーと時刻を追跡
テストモード：開発とテストのための完全なテスト環境サポート

返金ライフサイクル

返金は定義されたライフサイクルを経て進行します：

返金開始：マーチャントまたはAPIが完了した注文の返金を開始
処理中：返金は非同期で処理されます（ステータスはpendingのまま）
失敗：問題がある場合、返金が失敗する可能性があります（ステータスがfailedに変更）

返金ステータス値

返金には以下のステータスがあります：

pending：返金が開始され、処理中です
failed：返金の試行が失敗しました

図

返金の作成

返金を開始するには、注文IDと返金理由を含むPOSTリクエストを返金エンドポイントに送信します：

bash

curl --request POST \
  --url https://api.tokenz.one/v1/refunds \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "orderId": "order_1p4LPTRKB5Z",
    "reason": "customer_cancellation",
    "detail": "顧客からのキャンセルリクエスト"
  }'

必須パラメータ

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"
    },
    "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/v1/refunds/refund_1p4LS47fB1h \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

レスポンスフィールド

id：返金の一意識別子
orderId：返金された注文のID
amount：最小通貨単位での返金額
status：現在の返金ステータス（pending、failed）
reason：返金に提供された理由
initiatedBy：返金を開始したユーザー（merchantUser、apikey、admin）
test：これがテスト返金かどうか
createdAt：返金が作成されたタイムスタンプ
updatedAt：最後のステータス更新のタイムスタンプ

返金のリスト取得

オプションのフィルタリングですべての返金をリスト表示します：

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/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"
        },
        "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": "v1",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "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": "v1",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "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 /v1/refunds - 新しい返金を作成
GET /v1/refunds/{refundId} - 特定の返金を取得
GET /v1/refunds - オプションのフィルタで返金をリスト表示

認証

すべてのエンドポイントは、Bearerトークンによる認証が必要です：

Code

Authorization: Bearer secret_test_YOUR_KEY_HERE