Zenn
👛

【Shopify.dev和訳】Apps/Payments/Processing a refund

2021/09/30に公開
Shopify
#
apps
tech

この記事について

この記事は、Apps/Payments/Processing a refundの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

払い戻しの処理

払い戻しを処理するために、Shopify はあなたのアプリに HTTP コールを行い、あなたのアプリは GraphQL ミューテーションで返信することで払い戻しを完了します。このやりとりを以下の図に示します。

  1. マーチャントが返金を要求します。
  2. Shopify はバックエンドリクエストをペイメントアプリに送信し、返金を指定する。
  3. アプリは 201 と空のレスポンスボディで応答します。
  4. アプリは RefundSessionResolve または RefundSessionReject のいずれかの変異を使用して返金を確定します。
  5. Shopify は返金ステータスを更新します。

必要条件

スコープ

GraphQL ミューテーションを使用するには、アプリがペイメントアプリのアクセススコープを認識している必要があります。

返金フローの開始

返金フローは、Shopify からプロバイダの返金セッション URL（アプリ拡張機能の設定時に提供されたもの）に送られる HTTP リクエストから始まります。

リクエストボディ

{
  "id": "2sl4WR9jF82W0vQVg8fjux9S",
  "gid": "gid://shopify\/RefundSession/2sl4WR9jF82W0vQVg8fjux9S",
  "payment_id": "e6dXWOq7-_NSjXFeCjQ9jsGZ"
  "amount": "123.00",
  "currency": "CAD",
  "merchant_locale": "en",
  "proposed_at": "2020-07-13T00:00:00Z",
}

リクエストヘッダー

Shopify-Shop-Domain: my-test-shop.myshopify.com
Shopify-Request-Id: 94169f7e-ac8d-4ef4-9fd2-90f0791daddf

リクエストの属性

属性 説明 タイプ
id required 返金を試みた際の一意の識別子。idempotency キーとして使用されます。指定された ID のリクエストは、以前に受信した同じ ID のリクエストと同一であるとみなすことができます。 String
gid required Shopify と通信する際に返金を識別します（GraphQL mutations など）。 String
payment_id required 返金対象となる元の支払いの ID。キャプチャーされた支払いの場合、この ID はキャプチャー ID ではなく元のオーソリ ID に対応します。 String
amount required 返金される金額です。ロケールによらず、金額は常に小数点をセパレータとして使用して送信されます。 String
currency required 3 文字の ISO 通貨コードです。 String
merchant_locale required IETF BCP 47 の言語タグで、マーチャントが使用している言語を表します。 String
proposed_at required 返金要求が提案された時刻を表すタイムスタンプです。 String (ISO-8601)

レスポンス

Shopify は返金セッションの作成が成功するために、HTTP 201 応答を受け取らなければなりません。

リクエストが失敗した場合は、何度か再試行されます。リクエストが失敗した場合、マーチャントは Shopify の管理画面で手動で返金を再試行する必要があります。

返金の解決

返金リクエストが正常に処理された後、RefundSessionResolve 変異を使用してそれを解決することができます。

POST https://{shop_domain}/payments_apps/api/2021-07/graphql.json

mutation RefundSessionResolve($id: ID!) {
  refundSessionResolve(id: $id) {
    refundSession {
      id
      status {
        code
      }
    }
    userErrors {
      field
      message
    }
  }
}

引数 id は、払い戻しの gid に対応します。

変数

{
  "id": "gid://shopify/RefundSession/PJUG6iB0xU7czy1ZN3xEwn4o"
}
Open/Hide response

JSON response:

{
  "data": {
    "refundSessionResolve": {
      "refundSession": {
        "id": "gid://shopify/RefundSession/vZnLIUzgV08M2AWqJnAv_Uc0",
        "status": {
          "code": "RESOLVED"
        }
      },
      "userErrors": []
    }
  }
}

払い戻しを拒否する

返金の処理ができない場合は、返金を拒否する必要があります。返金を拒否するのは、最終的に回復不可能なエラーが発生した場合のみにしてください。それ以外の場合は、払い戻しの処理を再度試みることができます。

払い戻しを拒否するには、RefundSessionReject 変異を使用します。

POST https://{shop_domain}/payments_apps/api/2021-07/graphql.json

mutation RefundSessionReject($id: ID!, $reason: RefundSessionRejectionReasonInput!) {
  refundSessionReject(id: $id, reason: $reason) {
    refundSession {
      id
      status {
        code
        reason {
          ... on RefundSessionStatusReason {
            code
            merchantMessage
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

変数

{
  "id": "gid://shopify/RefundSession/PJUG6iB0xU7czy1ZN3xEwn4o",
  "reason": {
    "code": "PROCESSING_ERROR",
    "merchantMessage": "too much sun, time for a break"
  }
}

拒否の一部として、返金が拒否された理由を RefundSessionRejectionReasonInput として含める必要があります。

RefundSessionRejectionReasonInput.codeは、標準化されたエラーコードの列挙体であるRefundSessionStatusReasonRejectionCodeです。

RefundSessionRejectionReasonInput.merchantMessage引数は、返金が拒否された理由を説明する、マーチャントに提示されるローカライズされたエラーメッセージです。

Open/Hide response

JSON 形式のレスポンスです。

{
  "data": {
    "refundSessionReject": {
      "refundSession": {
        "id": "gid://shopify/RefundSession/8rK86HoqXnLiW-8shNCWZhTH",
        "status": {
          "code": "REJECTED",
          "reason": {
            "code": "PROCESSING_ERROR",
            "merchantMessage": "too much sun, time for a break"
          }
        }
      },
      "userErrors": []
    }
  }
}

再試行ポリシー

Shopify のサービスに障害が発生した場合（または、5xx ステータスコードが返された場合）、リクエストは再試行されなければなりません。リトライポリシーのセクションにあるガイドラインに従うことをお勧めします。

その他の情報

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます