Zenn
👛

【Shopify.dev和訳】Apps/Payments/Capturing an authorized payment

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

この記事について

この記事は、Apps/Payments/Capturing an authorized paymentの記事を和訳したものです。

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

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

Capturing an authorized payment

キャプチャーとは、マーチャントが承認された支払いのために資金を獲得するプロセスのことです。

キャプチャーは、2 部構成のペイメントフローの第 2 部であり、認証されたペイメントがファイナライズされた後に発生します。

ファイナライズされた支払いは、kindがauthorizationに設定されます。

マーチャントが承認されたトランザクションの資金をキャプチャしたい場合、Shopify はペイメントアプリにキャプチャリクエストを送信し、アプリはそれを解決または拒否することができます。

  1. マーチャントは、承認された支払いをキャプチャするためにクリックします。
  2. Shopify は決済アプリにバックエンドリクエストを送信し、キャプチャリクエストを指定します。
  3. アプリは 201 と空のレスポンスボディで応答します。
  4. アプリはCaptureSessionResolveまたはCaptureSessionRejectのいずれかの変異を使用してキャプチャを確定します。
  5. Shopify はステータスを更新します。

要件 | Requirements

スコープ | Scopes

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

フローの開始 | Initiate the flow

キャプチャーは、Shopify によって開始された支払いのkindプロパティの値がauthorizationである場合にのみ実行できます。

オーソリゼーションでは、資金を保留し、Shopify のキャプチャーリクエストに対してCaptureSessionResolveまたはCaptureSessionRejectのいずれかのメッセージを返信し、資金のキャプチャーを受け入れるか拒否するかを決定します。

キャプチャーフローは、Shopify からプロバイダのキャプチャーセッション URLへの HTTP リクエストで始まります。

リクエストボディー | Request Body

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

リクエストヘッダー | Request headers

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

リクエストの属性 | Request attributes

Attribute Description Type
id required キャプチャーの試みのためのユニークな識別子。idempotency key として使用されます。与えられた ID を持つリクエストは、以前に受信した同じ ID を持つリクエストと同一であると仮定します。 String
gid required Shopify と通信する際にキャプチャを識別します (GraphQL の変異などで)。 String
mayment_id required キャプチャーされる承認済みの支払いの ID です。 String
amount required キャプチャされる金額です。ロケールに関係なく、値は常に小数点をセパレータとして使用して送信されます。 String
currency required 3 文字の ISO 通貨コードです。 String
merchant_locale required マーチャントが使用する言語を表す IETF BCP 47 言語タグ。 String
proposed_at required キャプチャ要求が提案された時刻を表すタイムスタンプ。 String(ISO-8601)

承認された支払いの補足 | Capture an authorized payment

キャプチャーリクエストの処理に成功した後は、CaptureSessionResolveミューテーションを使って解決することができます。

POST https://{shop_domain}/payments_apps/api/2021-07/graphql.json
Mutation
mutation captureSessionResolve($id: ID!) {
  captureSessionResolve(id: $id) {
    captureSession {
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}

id引数は、キャプチャのgidに対応しています。

Variables
{
  "id": "gid://shopify/CaptureSession/WVXNNTgPLXRNqHxF7_hvpNzE"
}
JSON Response
Response
{
  "data": {
    "captureSessionResolve": {
      "captureSession": {
        "id": "gid://shopify/CaptureSession/WVXNNTgPLXRNqHxF7_hvpNzE"
      },
      "userErrors": []
    }
  },
  ...
    }
  }
}

キャプチャの拒否 | Reject a capture

キャプチャーリクエストを処理したくない場合は、拒否する必要があります。

認証の有効期限が切れている場合や、リクエストが詐欺的であったり高リスクであると疑われる場合には、キャプチャーを拒否したいと思うかもしれません。

キャプチャーを拒否するのは、最終的で回復不可能なエラーの場合だけにしてください。それ以外の場合は、キャプチャーの解決を再度試みる必要があります。

キャプチャーを拒否するには、RefundSessionRejectミューテーションを使用します。

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

mutation captureSessionReject($id: ID!, $reason: CaptureSessionRejectionReasonInput!) {
  captureSessionReject(id: $id, reason: $reason) {
    captureSession {
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}
Variables
{
  "id": "gid://shopify/CaptureSession/GbPYHMeBk3VALoEU8l095cbh",
  "reason": {
    "code": "PROCESSING_ERROR"
  }
}

拒否の一部として、キャプチャが拒否された理由をCaptureSessionRejectionReasonInputに含める必要があります。

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

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

JSON Response
Response
{
  "data": {
    "captureSessionReject": {
      "captureSession": {
        "id": "gid://shopify/CaptureSession/GbPYHMeBk3VALoEU8l095cbh"
      },
      "userErrors": []
    }
  },
...
    }
  }
}

再試行ポリシー | Retry policy

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

追加情報 | Additional information

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

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