Stripe統合の追加

Stripeはインターネットビジネス向けのオンライン決済処理プラットフォームです。Stripeを統合することで、アプリケーションが取引、サブスクリプション、財務データを安全に処理できるようになります。

設定手順

統合リストからStripeを選択すると、設定モーダルが表示されます。接続を確立するには、Stripeダッシュボードから以下の認証情報を提供する必要があります：

1. シークレットキー (Secret Key)

• 入力: Stripeのプライベートシークレットキー（通常sk_で始まります）をSecret Keyフィールドに入力してください。このキーにより、バックエンドが安全なリクエストを認証できるようになります。

2. 公開可能キー (Publishable Key)

• 入力: Stripeのパブリック公開可能キー（通常pk_で始まります）をPublishable Keyフィールドに入力してください。このキーはフロントエンドの実装に使用されます。

3. 環境

• 入力: ドロップダウンメニューから適切な環境コンテキストを選択してください（例：開発/サンドボックスモードの場合はTest、本番処理の場合はProduction）。

接続の完了

キーと環境が設定されたら：

1. ステータスバーを確認してください（現在はNot Connectedと表示されています）。
2. 右下の黒いAddボタンをクリックして認証情報を保存し、決済統合を有効にしてください。

Stripe統合APIリファレンス

---

設定管理

configureStripe

プロジェクトと環境用の新しいStripe設定を作成します。

Mutation:

mutation ConfigureStripe (
  $input: ConfigureStripeInput!
) {
  configureStripe (
    input: $input
  ) {
    id
    publishableKey
    webhookUrl
  }
}

Input:

input ConfigureStripeInput {
  secretKey: String!          # Stripe secret key (sk_test_... or sk_live_...)
  publishableKey: String!    # Stripe publishable key (pk_test_... or pk_live_...)
  environment: StripeEnvironment!  # TEST or LIVE
  webhookSecret: String      # Webhook signing secret (optional)
}

Response:

type ConfigureStripePayload {
  id: ID!                    # Configuration ID
  publishableKey: String!    # Publishable key
  webhookUrl: String!        # Generated webhook URL
}

Example:

{
  "input": {
    "secretKey": "sk_test_...",
    "publishableKey": "pk_test_...",
    "environment": "TEST",
    "webhookSecret": "whsec_..."
  }
}

注意:

• シークレットキーは保存前にAES-256-GCMで暗号化されます
• プロジェクト/環境の組み合わせごとに1つの設定のみ
• 設定が既に存在する場合はエラーを返します

---

updateStripeConfig

既存のStripe設定を更新します。

Mutation:

mutation UpdateStripeConfig (
  $input: UpdateStripeConfigInput!
) {
  updateStripeConfig (
    input: $input
  ) {
    id
    publishableKey
    webhookUrl
  }
}

Input:

input UpdateStripeConfigInput {
  secretKey: String          # Optional
  publishableKey: String     # Optional
  environment: StripeEnvironment  # Optional
  webhookSecret: String      # Optional
}

Response:

type UpdateStripeConfigPayload {
  id: ID!
  publishableKey: String!
  webhookUrl: String!
}

注意:

• すべてのフィールドはオプションです
• 提供されたフィールドのみが更新されます
• シークレットキーが提供された場合は暗号化されます

---

顧客管理 (Customer Management)

stripe_customer

IDで単一の顧客を取得します。

Query:

query stripe_customer{
  stripe_customer(
    id: "cus_Ts..."
  )
  {
    id
    name
    email
    phone
    description
    metadata
    object
    createdAt
  }
}

---

stripe_customers

ページネーションとオプションのフィルタリングを使って顧客をリストします。

Query:

query stripe_customers (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_customers (
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        name
        email
        phone
        description
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• customerId: 顧客IDでフィルタリング（オプション）

---

stripe_createCustomer

新しい顧客を作成します。

Mutation:

mutation stripe_createCustomer {
  stripe_createCustomer (
    input: {
      name: "Customer",
      email: "example@archie.com",
      phone: "+573001230001",
      description: "Description Example"
      metadata: {
        data1: "Example data1",
        data2: "Example data2"
      }
    }
  )
  {
    id
    name
    email
    phone
    description
    metadata
    object
    createdAt
  }
}

---

stripe_updateCustomer

既存の顧客を更新します。

Mutation:

mutation stripe_updateCustomer {
  stripe_updateCustomer(
    id: "cus_Ts...",
    input: {
      name: "Customer",
      email: "example@archie.com",
      phone: "+573001230001",
      description:"Description Example",
      metadata: {
        data1: "Example data1 updated",
        data2: "Example data2 updated"
      }
    }
  )
  {
    id
    name
    email
    phone
    description
    metadata
    object
    createdAt
  }
}

注意:

• すべてのフィールドはオプションです
• 提供されたフィールドのみが更新されます

---

stripe_deleteCustomer

顧客を削除します。

Mutation:

mutation stripe_deleteCustomer {
  stripe_deleteCustomer (
    id: "cus_Ts...")
}

Response:

• 成功時にtrueを返します
• 顧客が見つからない場合はエラーを返します

---

支払いインテント (Payment Intents)

stripe_paymentIntent

IDで単一の支払いインテントを取得します。

Query:

query stripe_paymentIntent {
  stripe_paymentIntent (
    id: "pi_3Su..."
  )
  {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

---

stripe_paymentIntents

ページネーションとオプションのフィルタリングを使って支払いインテントをリストします。

Query:

query stripe_paymentIntents (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_paymentIntents (
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        customerId
        paymentMethodId
        currency
        amount
        status
        metadata
        object
        clientSecret
        createdAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• customerId: 顧客IDでフィルタリング（オプション）

---

stripe_createPaymentIntent

新しい支払いインテントを作成します。

Mutation:

mutation stripe_createPaymentIntent {
  stripe_createPaymentIntent (
    input: {
      amount: 12.35,
      currency: "usd",
      customerId: "cus_Ts...",
      paymentMethodId: "pm_1Su...",
      automaticPaymentMethods: true
    }
  )
  {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

注意:

• フロントエンドでの確認用にclientSecretが返されます
• Stripe.jsとの統合にはautomaticPaymentMethods: trueを使用してください

---

stripe_updatePaymentIntent

確認前に支払いインテントを更新します。

Mutation:

mutation stripe_updatePaymentIntent{
  stripe_updatePaymentIntent(
    id: "pi_3S...",
    input: {
      amount: 36.92,
      currency: "usd",
      paymentMethodId: "pm_1Su..."
      metadata:{
        data1: "Example data1"
      }
    }
  ) {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

注意:

• 確認前にのみ更新可能です
• すべてのフィールドはオプションです

---

stripe_confirmPaymentIntent

支払いインテントを確認（確定）します。

Mutation:

mutation stripe_confirmPaymentIntent{
  stripe_confirmPaymentIntent(
    id: "pi_3Su..."
    input: {
      paymentMethodId: "pm_1Su...",
      returnUrl: "http://localhost:3000/successful-payment"
    }
  ) {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

注意:

• 支払いを完了するために必要です
• 3Dセキュア認証が必要な場合があります
• 更新されたステータス（succeeded, requires_actionなど）を返します

---

stripe_cancelPaymentIntent

支払いインテントをキャンセルします。

Mutation:

mutation stripe_cancelPaymentIntent {
  stripe_cancelPaymentIntent(
    id: "pi_3Su..."
  ) {
    id
    customerId
    paymentMethodId
    currency
    amount
    status
    metadata
    object
    clientSecret
    createdAt
  }
}

注意:

• 成功していない、またはまだキャンセルされていない支払いインテントのみキャンセルできます
• ステータスは”canceled”に変更されます

---

サブスクリプション

stripe_subscription

IDで単一のサブスクリプションを取得します。

Query:

query stripe_subscription {
  stripe_subscription(id: "sub_1Su...") {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

---

stripe_subscriptions

ページネーションとオプションのフィルタリングを使ってサブスクリプションをリストします。

Query:

query stripe_subscriptions (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_subscriptions (
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        customerId
        status
        currentPeriodStart
        currentPeriodEnd
        createdAt
        cancelAtPeriodEnd
        metadata
        object
        items {
          data {
            id
            priceId
            quantity
          }
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• customerId: 顧客IDでフィルタリング（オプション）
• status: ステータスでフィルタリング（オプション）

---

stripe_createSubscription

新しいサブスクリプションを作成します。

Mutation:

mutation stripe_createSubscription {
  stripe_createSubscription (
    input: {
      customerId: "cus_TsQ...",
      items: {
        priceId: "price_1Su...",
        quantity: 1
      },
      metadata: {
        data1: "Example data1"
      },
      trialPeriodDays: 0
    }
  ) {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

注意:

• 支払い方法を必要とするサブスクリプションの場合、paymentBehaviorは”default_incomplete”となる可能性があります
• トライアル期間は日数で指定されます
• 最新の請求書と支払いインテントは自動的に展開されます

---

stripe_updateSubscription

既存のサブスクリプションを更新します。

Mutation:

mutation stripe_updateSubscription {
  stripe_updateSubscription(
    id: "sub_1Sv..."
    input: {
      cancelAtPeriodEnd: false
      metadata: {
        data2: "Example data2"
      }
    }
  ) {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

---

stripe_cancelSubscription

サブスクリプションをキャンセルします。

Mutation:

mutation stripe_cancelSubscription {
  stripe_cancelSubscription (
    cancelAtPeriodEnd: true,
    id: "sub_1Sv..."
  ) {
    id
    customerId
    status
    currentPeriodStart
    currentPeriodEnd
    createdAt
    cancelAtPeriodEnd
    metadata
    object
    items {
      data {
        id
        priceId
        quantity
      }
    }
  }
}

Parameters:

• id: サブスクリプションID（必須）
• cancelAtPeriodEnd: trueの場合、期間終了時にキャンセルします。falseの場合、即座にキャンセルします（デフォルト: false）

注意:

• 即時キャンセル: サブスクリプションは今すぐ終了します
• 期間終了時のキャンセル: サブスクリプションは現在の期間が終了するまで継続します

---

商品と価格

stripe_products

ページネーションを使って商品をリストします。

Query:

query stripe_products (
  $first: Int,
  $after: String
) {
  stripe_products (
    first: $first,
    after: $after
  ) {
    edges {
      node {
        id
        name
        description
        active
        metadata
        object
        createdAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

---

stripe_createProduct

新しい商品を作成します。

Mutation:

mutation stripe_createProduct {
  stripe_createProduct (
    input: {
      name: "Product 01",
      description: "Description product 01",
      metadata: {
        data1: "Example data1"
      }
    }
  ) {
    id
    name
    description
    active
    metadata
    object
    createdAt
  }
}

---

stripe_prices

ページネーションとオプションのフィルタリングを使って価格をリストします。

Query:

query stripe_prices (
  $first: Int,
  $after: String,
  $productId: String
) {
  stripe_prices (
    first: $first,
    after: $after,
    productId: $productId
  ) {
    edges {
      node {
        id
        productId
        active
        currency
        unitAmount
        object
        metadata
        createdAt
        recurring {
          interval
          intervalCount
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• productId: 商品IDでフィルタリング（オプション）

---

stripe_createPrice

新しい価格を作成します。

Mutation:

mutation stripe_createPrice {
  stripe_createPrice (
    input: {
      productId: "prod_Tst...",
      unitAmount: 25.85,
      currency: "usd",
      recurring: {
        interval: "month",
        intervalCount: 1
      },
      metadata: {
        data1: "Example data1"
      }
    }
  ) {
    id
    productId
    currency
    unitAmount
    active
    object
    createdAt
    metadata
    recurring {
      interval
      intervalCount
    }
  }
}

注意:

• 1回限りの価格の場合はrecurringを省略してください
• intervalは次のいずれかである必要があります: “day”, “week”, “month”, “year”

---

請求書 (Invoices)

stripe_invoice

IDで単一の請求書を取得します。

Query:

query stripe_invoice {
  stripe_invoice (
    id: "in_1Su..."
  ) {
    id
    customerId
    subscriptionId
    currency
    amountPaid
    amountDue
    status
    object
    metadata
    createdAt
    lineItems {
      data {
        id
        description
        currency
        amount
        quantity
      }
    }
  }
}

注意:

• サブスクリプションIDは、利用可能な場合にAPI展開を介して入力されます

---

stripe_invoices

ページネーションとオプションのフィルタリングを使って請求書をリストします。

Query:

query stripe_invoices (
  $first: Int,
  $after: String,
  $customerId: String,
  $status: String
) {
  stripe_invoices (
    first: $first,
    after: $after,
    customerId: $customerId,
    status: $status
  ) {
    edges {
      node {
        id
        customerId
        subscriptionId
        currency
        amountPaid
        amountDue
        status
        object
        metadata
        createdAt
        lineItems {
          data {
            id
            description
            currency
            amount
            quantity
          }
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• customerId: 顧客IDでフィルタリング（オプション）
• status: ステータスでフィルタリング（オプション）

---

stripe_payInvoice

プログラムで請求書を支払います。

Mutation:

mutation stripe_payInvoice {
  stripe_payInvoice (
    id: "in_1Sv..."
  ) {
    id
    customerId
    subscriptionId
    currency
    amountPaid
    amountDue
    status
    object
    metadata
    createdAt
    lineItems {
      data {
        id
        description
        currency
        amount
        quantity
      }
    }
  }
}

注意:

• 顧客のデフォルトの支払い方法を使用して請求書の支払いを試みます
• 支払いに失敗した場合はエラーを返します
• 成功時に請求書ステータスを”paid”に更新します

---

返金 (Refunds)

stripe_refunds

ページネーションとオプションのフィルタリングを使って返金をリストします。

Query:

query  stripe_refunds (
  $first: Int,
  $after: String,
  $paymentIntentId: String
)  {
  stripe_refunds (
    first: $first,
    after: $after,
    paymentIntentId: $paymentIntentId
  ) {
    edges {
      node {
        id
        paymentIntentId
        reason
        status
        currency
        amount
        metadata
        object
        createdAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• paymentIntentId: 支払いインテントIDでフィルタリング（オプション）

---

stripe_createRefund

支払いインテントに対する返金を作成します。

Mutation:

mutation stripe_createRefund {
  stripe_createRefund (
    input: {
      paymentIntentId: "pi_3Sv...",
      amount: 200,
      reason: "requested_by_customer"
    }
  ) {
    id
    reason
    paymentIntentId
    status
    currency
    amount
    object
    metadata
    createdAt
  }
}

注意:

• 全額返金の場合はamountを省略してください
• reasonは次のいずれかです: “duplicate”, “fraudulent”, “requested_by_customer”
• 返金ステータスは”pending”で始まり、“succeeded”または”failed”に更新されます

---

支払い方法 (Payment Methods)

stripe_paymentMethods

ページネーションとオプションのフィルタリングを使って支払い方法をリストします。

Query:

query stripe_paymentMethods (
  $first: Int,
  $after: String,
  $customerId: String
) {
  stripe_paymentMethods(
    first: $first,
    after: $after,
    customerId: $customerId
  ) {
    edges {
      node {
        id
        customerId
        type
        object
        metadata
        createdAt
        card {
          brand
          expMonth
          expYear
          last4
        }
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル
• customerId: 顧客IDでフィルタリング（オプション）

注意:

• 安全なカード情報（下4桁、ブランド、有効期限）のみが返されます
• 完全なカード番号が公開されることはありません

---

stripe_attachPaymentMethod

顧客に支払い方法を紐付けます。

Mutation:

mutation stripe_attachPaymentMethod {
  stripe_attachPaymentMethod (
    id: "pm_1Sv...",
    input: {
      customerId: "cus_Ts4..."
    }
  ) {
    id
    customerId
    type
    card {
      brand
      expMonth
      expYear
      last4
    }
    metadata
    object
    createdAt
  }
}

注意:

• 支払い方法は最初に作成する必要があります（通常はStripe.js経由）
• 紐付けられた支払い方法は、サブスクリプションや支払いに使用できます

---

stripe_detachPaymentMethod

顧客から支払い方法を切り離します。

Mutation:

mutation stripe_detachPaymentMethod {
  stripe_detachPaymentMethod (
    id: "pm_1Sv..."
  ) {
    id
    customerId
    type
    card {
      brand
      expYear
      expMonth
      last4
    }
    metadata
    object
    createdAt
  }
}

注意:

• 切り離された支払い方法は、支払いには使用できなくなります
• customerIdがnullに設定された支払い方法を返します

---

Webhookイベント

stripe_webhookEvents

サービスによって受信されたWebhookイベントをリストします。

Query:

query ListWebhookEvents (
  $first: Int,
  $after: String
) {
  stripe_webhookEvents (
    first: $first,
    after: $after
  ) {
    edges {
      node {
        id
        type
        data
        processed
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      endCursor
    }
  }
}

Response:

type StripeWebhookEvent {
  id: ID!
  type: String!              # Event type (e.g., "payment_intent.succeeded")
  data: String!              # JSON string of event data
  processed: Boolean!        # Whether event has been processed
  createdAt: Time!
}

Parameters:

• first: 返すアイテム数（デフォルト: 10）
• after: ページネーション用カーソル

注意:

• イベントはWebhookエンドポイントを介して自動的に受信されます
• イベントは署名検証後に保存されます
• dataフィールドには、JSON文字列として完全なイベントペイロードが含まれます

---

ページネーション

すべてのリストクエリは、Relay接続パターンを使用したカーソルベースのページネーションをサポートしています。

PageInfo

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

使用例

query ListCustomers (
  $first: Int,
  $after: String
) {
  stripe_customers (
    first: $first,
    after: $after
  ) {
    edges {
      node {
        id
        email
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

ページネーションフロー:

1. 初回リクエスト: first: 10, after: null
2. レスポンスのpageInfo.endCursorを次のリクエストのafterとして使用
3. hasNextPageを確認して、次のページが存在するかどうかを判断

デフォルト値:

• first: 提供されていない場合はデフォルトで10
• after: 提供されていない場合は最初から開始

---

エラー処理

すべての操作は、ユーザーフレンドリーなメッセージを含むGraphQLエラーを返します。エラーはStripe APIエラーからマッピングされ、明確なフィードバックを提供します。

一般的なエラーシナリオ

設定エラー:

• 400: 無効なStripeキー形式
• 404: プロジェクトまたは設定が見つからない
• 400: 設定が既に存在する

顧客エラー:

• 404: 顧客が見つからない
• 400: 無効な顧客データ

支払いインテントエラー:

• 404: 支払いインテントが見つからない
• 400: 無効な金額または通貨
• 402: 支払い失敗（カード拒否、残高不足など）

サブスクリプションエラー:

• 404: サブスクリプションが見つからない
• 400: 無効なサブスクリプションパラメータ
• 400: キャンセルされたサブスクリプションを更新できません

Stripeエラーコード: 一般的なStripeエラーコードは、ユーザーフレンドリーなメッセージにマッピングされます：

• card_declined: “カードが拒否されました”
• insufficient_funds: “残高不足です”
• invalid_number: “無効なカード番号です”
• expired_card: “カードの有効期限が切れています”
• incorrect_cvc: “CVCコードが正しくありません”

エラーレスポンス形式

{
  "errors": [
    {
      "message": "Customer not found",
      "extensions": {
        "code": "NOT_FOUND",
        "stripeErrorCode": "resource_missing"
      }
    }
  ],
  "data": null
}

---

データ型

StripeEnvironment

enum StripeEnvironment {
  TEST  # Test mode
  LIVE  # Live/production mode
}

Scalar Map

Mapスカラー型はキーと値のマップを表します：

• キーは文字列
• 値は文字列、数値、ブール値、またはネストされたマップにすることができます
• メタデータフィールドに使用されます

例:

{
  "metadata": {
    "order_id": "12345",
    "user_id": "67890",
    "premium": true
  }
}

Scalar Time

Timeスカラー型は、ISO 8601形式のタイムスタンプを表します。

例: "2025-11-16T00:28:48.081Z"