Stripe UI拡張機能入門: StripeのAPIをアプリ内から呼び出す方法

この記事は、Stripe Apps を25日間紹介し続ける Advent Calendar 2022 8日目の記事です。

「Stripe Dashboardを拡張する」ためのアプリを作るには、Stripeのデータを取得・更新・削除する必要があります。

今回は、Stripe AppsのReactアプリ内で、Stripe Node.js SDKを利用したStripe API呼び出しを行う方法を紹介します。

Stripe Appsアプリは、アプリ内でStripe APIを呼び出せる

StripeアプリでStripeのAPIを呼び出す方法

今回は、アプリ内からStripe APIを利用して決済履歴を取得するサンプルを構築します。

Stripe CLIでアプリにAPI呼び出しの権限を設定する

まずはじめに、アプリがどのAPI操作を利用するかの「権限設定」を行います。

アプリケーションのディレクトリ内にて、Stripe CLIでstripe apps grant permissionを実行しましょう。

Step1: 権限を設定したいリソースを選択する

どのリソースへのアクセスかを選択する画面が表示されます。

$ stripe apps grant permission 
Use the arrow keys to navigate: ↓ ↑ → ← 
? Select a resource to grant access to: 
  ▸ Account link
    Apply Pay Domain
    Application Fee
    Balance
↓   Balance transaction source

矢印キーの下を押してスクロールして、Payment intentを選択しましょう。

▸ Payment intent

Step2: 権限の種類を選択する

「読み込みだけ」か「書き込み（作成・更新・削除）もするか」を聞かれます。

? Select access type: 
  ▸ read
    write

今回は読み込みだけなので、readを選びます。

Step3: アクセスを要求する理由を入力する

続いて次のメッセージが表示されます。

✗ Enter a purpose for the grant: █

これは、「そのリソースへのアクセス権限を要求する理由」を入力するエリアです。

アプリの設定画面やマーケットプレイスにて、ユーザーが「このアプリはStripeアカウントのどんなリソースに、どういう目的でアクセスしてくるか」を確認できるようになります。

Lists the payment intent data to analyze the business.など、シンプルな説明文を入れましょう。

あとから変更できますので、ローカルで試す範囲であれば、dummyやTBDなどで一旦進めることも可能です。

ただし公開時には修正する必要がありますので、TODOリストに「stripe-app.jsonのpermissions.purposeを更新する」のようにタスクを入れておくことをお勧めします。

セットアップが終わると、stripe-app.jsonのpermissionsに入力したデータが反映されます。

{
  "id": "com.example.first-stripe-app",
  "version": "0.0.1",
  "name": "First Stripe App",
  "icon": "",
-  "permissions": [],
+  "permissions": [
+    {
+      "permission": "payment_intent_read",
+      "purpose": "tbd"
+    }
+  ],
...

stripe apps startを実行中の場合、アプリの再読み込みが必要

stripe apps startを実行したままstripe apps grantコマンドを実行した場合、stripe apps startを実行中のターミナルに以下のメッセージが表示されます。

[14:48:51] compiled successfully
[12:17:16] WARNING stripe-app.json
To reflect recent changes from stripe-app.json, click "Continue" on https://dashboard.stripe.com/apps/enable-preview?cliaccount=acct_123456abcde
[12:17:16] compiled successfully

変更した権限設定でアプリを実行するには、このURLにアクセスしてプレビューを再度有効化する必要があります。

@stripe/ui-extension-sdkで、Stripe Node.js SDKのクライアントをセットアップする

権限の設定が終わりましたので、Stripe APIを呼び出すためのSDKを準備します。

stripe apps createで作成したアプリには、デフォルトでNode.js SDKが追加されています。

  "dependencies": {
    "@stripe/ui-extension-sdk": "^8.5.0",
    "stripe": "^11.1.0"
  }

Stripe SDKのクライアントは次のコードでセットアップできます。

import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client'
import Stripe from 'stripe'

// Initiate communication with the stripe client.
const stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient(),
  apiVersion: '2022-11-15',
})

apiVersionがSDKのバージョンによって変わることがあります。
TypeScriptで型エラーが発生した場合は、エラー文または型定義が指示するバージョンに変更しましょう。

APIキーを環境変数などで設定する必要はありません。

アプリが実行されるサンドボックス側で自動的に設定されます。

useEffectとuseStateを利用して、API呼び出しとレスポンスの取得を行う

クライアントの準備ができましたので、Reactのコンテキストに従ってAPIを呼び出しましょう。

const PaymentIntentsViewer: FC = () => {
  const [paymentIntents, setPaymentIntents] = useState<Stripe.PaymentIntent[]>([])
  useEffect(() => {
    stripe.paymentIntents.list()
      .then(response => {
        setPaymentIntents(response.data)
      })
      .catch(error => {
        console.log(error)
      })
  }, [])
  return (
    <Box>
      {JSON.stringify(paymentIntents, null, 2)}
    </Box>
  )
}

作成したPaymentIntentsViewerコンポーネントを、src/views/App.tsxで読み込ませます。

const App = ({ userContext, environment }: ExtensionContextValue) => {
  return (
    <ContextView
      title="Hello world"
      brandColor="#F6F8FA" // replace this with your brand color
      brandIcon={BrandIcon} // replace this with your brand icon
      externalLink={{
        label: "View docs",
        href: "https://stripe.com/docs/stripe-apps"
      }}
    >
+      <PaymentIntentsViewer />    
    </ContextView>
  );
};

アプリを再読み込みすると、アカウントのPayment IntentデータがJSONで出力されます。

List系コンポーネントで、取得したデータを表示する

データの取得ができましたので、見た目を整えましょう。

今回は、Listコンポーネントを活用します。

PaymentIntentsViewerを次のように書き換えましょう。

-import { Box } from "@stripe/ui-extension-sdk/ui";
+import { List, ListItem } from "@stripe/ui-extension-sdk/ui";

// 中略

  return (
+    <List>
-    <Box>  
+      {paymentIntents.map(intent => {
+        const value = `${intent.amount.toLocaleString()} ${intent.currency.toLocaleUpperCase()}`
+        const createdAt = new Date(intent.created * 1000).toLocaleString('ja-JP')
+        return (
+          <ListItem
+            key={intent.id}
+            title={intent.id}
+            secondaryTitle={createdAt}
+            value={value}
+          />
+        )
+      })}
-      {JSON.stringify(paymentIntents, null, 2)}
-    </Box>
+    </List>
  )

保存してアプリを再読み込みすると、JSONデータがリスト形式の表示に変わります。

[Advanced] 表示中のページのID情報などを取得する方法

「現在表示中の顧客・サブスクリプションデータを取得したい」など、顧客やサブスクリプションなどのIDが必要なケースも存在します。

この場合は、コンポーネントから渡されるenvironmentプロパティを利用しましょう。

environment.objectContextの中身を見てみます。

const App = ({ environment }: ExtensionContextValue) => {
+  console.log(environment.objectContext)

顧客の詳細ページでは、次のようなデータが取得できます。

{
  "id": "cus_MuOQ7rso8N3wF6",
  "object": "customer"
}

environment.objectContext.objectでIDの種類を見ることができます。

そしてenvironment.objectContext.idでIDを取得し、Stripe APIの引数に渡すことができます。

次のサンプルコードでは、「顧客IDが取得できた場合に、その顧客に関連するPayment Intentを取得する」処理を行います。

const App = ({ environment }: ExtensionContextValue) => {
  useEffect(() => {
    if (!environment.objectContext) return
    if (environment.objectContext.object !== 'customer') return
    const customerId = environment.objectContext.id
    stripe.paymentIntents.list({
      customer: customerId
    })
      .then(response => {
        console.log(response.data)
      })
      .catch(error => {
        console.log(error)
      })
  }, [environment.objectContext])
...

ドキュメント

Stripe Appsひとりアドベントカレンダー 2022

今年ベータリリースされたばかりのStripe Appsは、まだ日本語の情報が多くありません。

そこでQiita Advent Calendar 2022にて、毎日Stripe Appsについての情報を投稿します。

ノーコードで利用する方法や、開発するためのTipsなども紹介予定ですので、ぜひ購読をお願いします。