返金

Refund (返金)APIAPI を使用すると、成功した支払い（Payment FlowAPI）の全額または一部を顧客に返金でき、以下のような処理が自動的に行われます

支払い方法を通じた返金処理の実行
Payment Transaction (決済トランザクション)API の自動生成（返金の記録）
Webhook イベント refund.created の送信

返金の作成

返金を作成するには、返金対象の Payment Flow ID を指定して Refund API を呼び出します。

全額返金

amount パラメーターを省略すると、Payment Flow の全額が返金されます。

curl https://api.pay.jp/v2/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_flow": "pfw_xxxxx"}'

部分返金

amount パラメーターで返金額を指定することで、部分返金が可能です。

curl https://api.pay.jp/v2/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_flow": "pfw_xxxxx",
    "amount": 1000
  }'

部分返金の制限

複数回に分けて部分返金を行う場合、返金額の合計が元の決済額を超えることはできません。既に全額返金済みの場合、追加の返金はエラーになります。

返金理由の記録

reason パラメーターを使用して返金の理由を記録できます。返金理由を記録することで、返金パターンの分析や顧客対応の履歴、不正検知などに利用します。

curl https://api.pay.jp/v2/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_flow": "pfw_xxxxx",
    "reason": "requested_by_customer"
  }'

返金理由

返金理由は以下のいずれかを指定できます。

値	説明
`duplicate`	重複した支払い
`fraudulent`	不正な支払い
`requested_by_customer`	顧客からの要求

返金ステータスの監視

返金処理は非同期で行われる場合があるため、ステータスを適切に監視することが重要です。

返金ステータス

ステータス	説明
`succeeded`	返金が成功しました
`pending`	返金処理中です
`requires_action`	追加のアクションが必要です
`failed`	返金が失敗しました
`canceled`	返金がキャンセルされました

Webhook による監視

返金が作成されると、refund.created イベントが Webhook で通知されます。このイベントを受け取って、返金ステータスを確認できます。

# Webhookで受信するイベントの例
{
  "type": "refund.created",
  "data": {
    "id": "re_xxxxx",
    "status": "succeeded",
    "amount": 1000,
    "payment_flow": "pfw_xxxxx"
  }
}

詳細はイベントと Webhookを参照してください。

ステータスの確認

返金の ID を使用していつでもステータスを確認できます。

curl https://api.pay.jp/v2/refunds/re_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

支払い方法による違い

返金処理は支払い方法によって挙動が異なります。

カード決済

カード決済の返金は、ほとんどの場合即座に完了し、ステータスは succeeded になります。返金の結果は Webhook イベント（refund.created）で確認してください。

返金は支払い作成から180日以内に作成する必要があります。

PayPay 決済

PayPay 決済の返金は非同期処理のため、返金作成時のレスポンスでは pending ステータスが返されます。最終的な結果は Webhook イベント（refund.created）で確認してください。

返金は支払い確定から365日後の23:59:59までに作成する必要があります。

制約事項とエラーハンドリング

返金の制約事項

返金を作成する際は、以下の制約があります。

返金対象の Payment Flow は succeeded ステータスである必要があります
返金額の合計は元の決済額 amount_received を超えることはできません
既に全額返金済みの場合、追加の返金はエラーになります

冪等性

返金APIは冪等性に対応しています。Idempotency-Key ヘッダーを使用することで、ネットワークエラー時の重複返金を防ぐことができます。

curl https://api.pay.jp/v2/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique_key_12345" \
  -d '{"payment_flow": "pfw_xxxxx"}'

詳細は冪等リクエストを参照してください。

返金