👛

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

2021/09/30に公開

Shopify

apps

tech

この記事について

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

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

Shopify アプリのご紹介

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

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

承認された支払いの無効化

無効は、マーチャントが承認された支払いのために資金を無効にするプロセスを説明します。ボイドは、2 つの部分からなる支払いフローの 2 番目の部分であり、承認された支払いが完了した後に発生します。確定した支払いは、authorizationに設定されたkindを有しています。マーチャントが承認されたトランザクションの注文をキャンセルしたい場合、Shopify は支払いアプリに無効なリクエストを送信し、アプリはそれを解決または拒否できます。

void processing steps

マーチャントは、承認された支払いを無効にするように要求します。
Shopify は、無効なリクエストを指定して、バックエンドリクエストをペイメントアプリに送信します。
アプリは 201 と空のレスポンスボディでレスポンスします。
アプリは、voidSessionResolveまたはvoidSessionRejectミューテーションのいずれかを使用して void リクエストを確定します。
Shopify は支払いステータスを更新します。

要件

支払いアプリの作成を開始を完了しました。
一般的なトランザクション要件を理解しました。
ペイメントアプリの要件を満たしています。

スコープ

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

フローを開始します

無効化は、Shopify によって開始された支払いにauthorizationの値を持つkindプロパティがある場合にのみ実行できます。承認があれば、資金を保留にしてから、VoidSessionResolveまたはVoidSessionRejectミューテーションを使用して Shopify の無効リクエストに応答し、資金の無効化を受け入れるか拒否します。

ボイドフローは、Shopify からアプリ拡張機能の構成中に提供されたプロバイダーの URL に送信される HTTP リクエストで始まります。

リクエストボディ

{
  "id": "2sl4WR9jF82W0vQVg8fjux9S",
  "gid": "gid://shopify/VoidSession/2sl4WR9jF82W0vQVg8fjux9S",
  "payment_id": "e6dXWOq7-_NSjXFeCjQ9jsGZ",
  "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`)	void attempt の一意の識別子。べき等キーとして使用されます。特定の ID を持つ要求は、同じ ID を持つ以前に受信した要求と同一であると見なすことができます。	`String`
`gid` (`required`)	Shopify と通信するときのボイドを識別します（たとえば、GraphQL ミューテーションで）。	`String`
`payment_id` (`required`)	無効にする承認済み支払いの ID。	`String`
`merchant_locale` (`required`)	void attempt の一意の識別子。べき等キーとして使用されます。特定の ID を持つ要求は、同じ ID を持つ以前に受信した要求と同一であると見なすことができます。	`String`
`proposed_at` (`required`)	void リクエストがいつ提案されたかを表すタイムスタンプ。	`String (ISO-8601)`

レスポンス

void セッションの作成を成功させるには、Shopify が HTTP201 応答を受信する必要があります。

リクエストが失敗した場合は、数回再試行されます。それでもリクエストが失敗する場合、マーチャントは Shopify admin で void を手動で再試行する必要があります。

void リクエストを解決する

void リクエストを正常に処理した後、voidSessionResolveミューテーションを使用してリクエストを解決できます。

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

mutation voidSessionResolve($id: ID!) {
  voidSessionResolve(id: $id) {
    userErrors {
      code
      field
      message
    }
    voidSession {
      id
    }
  }
}

idの引数は void のgidに対応します。

変数：

{
  "id": "gid://shopify/VoidSession/7hxHr74cAErmFXlP5pJcl19H"
}

レスポンスを表示する

JSON レスポンス：

{
  "data": {
    "voidSessionResolve": {
      "userErrors": [],
      "voidSession": {
        "id": "gid://shopify/VoidSession/7hxHr74cAErmFXlP5pJcl19H"
      }
    }
  },
...
    }
  }
}

void リクエストを拒否する

void リクエストを処理できない場合は、拒否する必要があります。最終的な回復不能なエラーの場合にのみ、無効を拒否する必要があります。それ以外の場合は、ボイドの解決を再試行できます。

voidSessionRejectミューテーションを使用して、void を拒否できます。

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

mutation voidSessionReject($id: ID!, $reason: VoidSessionRejectionReasonInput!) {
  voidSessionReject(id: $id, reason: $reason) {
    userErrors {
      code
      field
      message
    }
    voidSession {
      id
    }
  }
}

変数：

{
  "id": "gid://shopify/VoidSession/2cEbFAEC_CgvbgDXM7pEUyda",
  "reason": {
    "code": "PROCESSING_ERROR"
  }
}

拒否の一部に、VoidSessionRejectionReasonInputの void が拒否された理由を含める必要があります。

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

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

レスポンスを表示する

JSON レスポンス：

{
  "data": {
    "voidSessionReject": {
      "userErrors": [],
      "voidSession": {
        "id": "gid://shopify/VoidSession/2cEbFAEC_CgvbgDXM7pEUyda"
      }
    }
  },
  ...
    }
  }
}

リトライポリシー

Shopify サービスが中断した場合（または 5xx ステータスコードが返されている場合）、リクエストを再試行する必要があります。リトライポリシーセクションのガイドラインに従うことをお勧めします。

追加情報

Shopify アプリのご紹介

Discussion

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