使用 Stripe 元數據檢索訂閱信息

在本主題中，您將學習如何使用 Stripe API 檢索與 Stripe 自定義元數據關聯的訂閱信息。

概覽

Brightcove 正在向 Stripe 訂閱添加自定義元數據，這將允許您在創建訂閱時識別查看者使用的設備類型。您可以查詢 Stripe API 以搜索與自定義元數據關聯的訂閱。您還可以添加 webhooks 來監聽 Stripe 事件。

本主題將向您展示如何執行以下操作：

  • 使用 Stripe API 在任何訂閱/購買中搜索特定元數據以返回列表
  • 創建一個 webhook 來監聽 Stripe 事件

先決條件

要使用本主題中所示的 Stripe API，您需要具備以下條件：

  • 條紋帳戶
  • 郵差或其他 API 平台

    您可以使用您選擇的 API 平台與 Stripe API 交互，但對於這些示例，我們將使用 Postman。

了解條紋 API

基本網址

Stripe API 的基本 URL 是：

https://api.stripe.com

驗證

請求通過您的 API 密鑰在Authorization標頭：

Authorization: Bearer {api_key}

API集合

Stripe API 集合託管在Stripe 的 Postman 公共工作區 .這允許您從公共工作區分叉到您的工作區。

如果你不想從公共工作區派生集合，你可以從條紋郵遞員 GitHub 存儲庫。

創建郵遞員環境

您可以使用您選擇的 API 平台與 Stripe API 交互，但對於這些示例，我們將使用 Postman。

  1. 登錄或創建帳戶郵差 .
  2. 在郵遞員條紋公共工作區，或在 Postman 中創建一個新環境。我們將創建一個新環境。

  3. 在您的工作區中，單擊新的 .

    創建新的

  4. 在對話框中，選擇環境 .

    選擇環境

  5. 將您的密鑰添加為環境變量，然後單擊節省 .

    創建密鑰變量
  6. 點擊添加選項卡圖標打開新標籤頁。

  7. 在請求對話框中，執行以下操作：

    • 選擇授權
    • 為了類型， 選擇不記名令牌
    • 對於令牌，輸入{{secret_key}}

    如果您的環境設置正確，當您將鼠標懸停在secret_key多變的。

    鼠標懸停在關鍵變量上
  8. 按一下「儲存」。
  9. 在對話框中，執行以下操作：
    • 添加一個請求名稱
    • 選擇或創建新系列
    • 請點擊保存
    保存請求

  10. 您現在可以創建一個GET向 Stripe API 請求。

    環境創建

使用元數據搜索訂閱

在本節中，您將使用 Stripe API 搜索具有自定義元數據的訂閱。

自訂中繼資料

名字 價格
device_type 值：
  • androidtv
  • firetv
  • lgtv
  • nettv
  • operatv
  • panasonic
  • samsung

步驟

  1. 返回到您在上一節中創建的 Postman 環境。

  2. 為了GET請求，將以下內容粘貼到請求 URL 中。使用您選擇的設備類型值。

    https://api.stripe.com/v1/subscriptions/search?query=metadata["device_type"]:"samsung"

    獲取三星訂閱
  3. 按一下「傳送」。

  4. 如果您收到以下錯誤GET要求，

    條紋 API 版本錯誤

    確保您使用的是當前版本的 Stripe API。您可以通過添加以下標頭來執行此操作：

    • KEY是“條紋版”
    • VALUE是“2020-08-27”（或最新版本）
    條紋版本標題

響應

API 響應應包含帶有元數據的訂閱Samsung:yes .

請注意，響應包含以下內容：

"metadata": {
    "Samsung": "yes"
},

API 回應

您的回應看起來應該類似於這樣：

{
  "object": "search_result",
  "data": [
      {
          "id": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
          "object": "subscription",
          "application": null,
          "application_fee_percent": null,
          "automatic_tax": {
              "enabled": false
          },
          "billing_cycle_anchor": 1653581061,
          "billing_thresholds": null,
          "cancel_at": null,
          "cancel_at_period_end": false,
          "canceled_at": null,
          "collection_method": "charge_automatically",
          "created": 1653581061,
          "current_period_end": 1656259461,
          "current_period_start": 1653581061,
          "customer": "cus_LlFcWXPXftQibf",
          "days_until_due": null,
          "default_payment_method": null,
          "default_source": null,
          "default_tax_rates": [],
          "description": null,
          "discount": null,
          "ended_at": null,
          "items": {
              "object": "list",
              "data": [
                  {
                      "id": "si_LlFgWbs9lqlwOF",
                      "object": "subscription_item",
                      "billing_thresholds": null,
                      "created": 1653581062,
                      "metadata": {},
                      "plan": {
                          "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
                          "object": "plan",
                          "active": true,
                          "aggregate_usage": null,
                          "amount": 100,
                          "amount_decimal": "100",
                          "billing_scheme": "per_unit",
                          "created": 1653580781,
                          "currency": "eur",
                          "interval": "month",
                          "interval_count": 1,
                          "livemode": false,
                          "metadata": {},
                          "nickname": null,
                          "product": "prod_LlFbyvOQ6dpLXF",
                          "tiers_mode": null,
                          "transform_usage": null,
                          "trial_period_days": null,
                          "usage_type": "licensed"
                      },
                      "price": {
                          "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
                          "object": "price",
                          "active": true,
                          "billing_scheme": "per_unit",
                          "created": 1653580781,
                          "currency": "eur",
                          "livemode": false,
                          "lookup_key": null,
                          "metadata": {},
                          "nickname": null,
                          "product": "prod_LlFbyvOQ6dpLXF",
                          "recurring": {
                              "aggregate_usage": null,
                              "interval": "month",
                              "interval_count": 1,
                              "trial_period_days": null,
                              "usage_type": "licensed"
                          },
                          "tax_behavior": "unspecified",
                          "tiers_mode": null,
                          "transform_quantity": null,
                          "type": "recurring",
                          "unit_amount": 100,
                          "unit_amount_decimal": "100"
                      },
                      "quantity": 1,
                      "subscription": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
                      "tax_rates": []
                  }
              ],
              "has_more": false,
              "total_count": 1,
              "url": "/v1/subscription_items?subscription=sub_1L3jAgFzWFPFNFjqFpyUF8XY"
          },
          "latest_invoice": "in_1L3jAgFzWFPFNFjq8YFoU6R3",
          "livemode": false,
          "metadata": {
              "Samsung": "yes"
          },
          "next_pending_invoice_item_invoice": null,
          "pause_collection": null,
          "payment_settings": {
              "payment_method_options": null,
              "payment_method_types": null,
              "save_default_payment_method": "off"
          },
          "pending_invoice_item_interval": null,
          "pending_setup_intent": null,
          "pending_update": null,
          "plan": {
              "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
              "object": "plan",
              "active": true,
              "aggregate_usage": null,
              "amount": 100,
              "amount_decimal": "100",
              "billing_scheme": "per_unit",
              "created": 1653580781,
              "currency": "eur",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {},
              "nickname": null,
              "product": "prod_LlFbyvOQ6dpLXF",
              "tiers_mode": null,
              "transform_usage": null,
              "trial_period_days": null,
              "usage_type": "licensed"
          },
          "quantity": 1,
          "schedule": null,
          "start_date": 1653581061,
          "status": "active",
          "test_clock": null,
          "transfer_data": null,
          "trial_end": null,
          "trial_start": null
      }
  ],
  "has_more": false,
  "next_page": null,
  "url": "/v1/subscriptions/search"

使用 Stripe 網絡鉤子

您的 Brightcove Beacon 應用程序可以偵聽您的 Stripe 帳戶上的事件，您可以使用網絡鉤子讓 Stripe 能夠將實時通知推送到您的應用程序，或者您可以使用網絡鉤子作為端點。

有關詳細信息，請參閱條紋使用傳入的 webhook參考。

請注意，每個響應都包含以下內容：

"metadata": {
    "Samsung": "yes"
},

活動

以下是您可以監聽的一些事件：

customer.subscription.created

Stripe webhook 可以監聽customer.subscription.created事件。

API 回應

您的回應看起來應該類似於這樣：

{
  "object": {
    "id": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
    "object": "subscription",
    "application": null,
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false
    },
    "billing": "charge_automatically",
    "billing_cycle_anchor": 1653581061,
    "billing_thresholds": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "collection_method": "charge_automatically",
    "created": 1653581061,
    "current_period_end": 1656259461,
    "current_period_start": 1653581061,
    "customer": "cus_LlFcWXPXftQibf",
    "days_until_due": null,
    "default_payment_method": null,
    "default_source": null,
    "default_tax_rates": [
    ],
    "description": null,
    "discount": null,
    "ended_at": null,
    "invoice_customer_balance_settings": {
      "consume_applied_balance_on_void": true
    },
    "items": {
      "object": "list",
      "data": [
        {
          "id": "si_LlFgWbs9lqlwOF",
          "object": "subscription_item",
          "billing_thresholds": null,
          "created": 1653581062,
          "metadata": {
          },
          "plan": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "plan",
            "active": true,
            "aggregate_usage": null,
            "amount": 100,
            "amount_decimal": "100",
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "interval": "month",
            "interval_count": 1,
            "livemode": false,
            "metadata": {
            },
            "name": "Beacon Metadata",
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "statement_descriptor": null,
            "tiers": null,
            "tiers_mode": null,
            "transform_usage": null,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "price": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "price",
            "active": true,
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "livemode": false,
            "lookup_key": null,
            "metadata": {
            },
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "recurring": {
              "aggregate_usage": null,
              "interval": "month",
              "interval_count": 1,
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "tax_behavior": "unspecified",
            "tiers_mode": null,
            "transform_quantity": null,
            "type": "recurring",
            "unit_amount": 100,
            "unit_amount_decimal": "100"
          },
          "quantity": 1,
          "subscription": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
          "tax_rates": [
          ]
        }
      ],
      "has_more": false,
      "total_count": 1,
      "url": "/v1/subscription_items?subscription=sub_1L3jAgFzWFPFNFjqFpyUF8XY"
    },
    "latest_invoice": "in_1L3jAgFzWFPFNFjq8YFoU6R3",
    "livemode": false,
    "metadata": {
      "Samsung": "yes"
    },
    "next_pending_invoice_item_invoice": null,
    "pause_collection": null,
    "payment_settings": {
      "payment_method_options": null,
      "payment_method_types": null,
      "save_default_payment_method": "off"
    },
    "pending_invoice_item_interval": null,
    "pending_setup_intent": null,
    "pending_update": null,
    "plan": {
      "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
      "object": "plan",
      "active": true,
      "aggregate_usage": null,
      "amount": 100,
      "amount_decimal": "100",
      "billing_scheme": "per_unit",
      "created": 1653580781,
      "currency": "eur",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Beacon Metadata",
      "nickname": null,
      "product": "prod_LlFbyvOQ6dpLXF",
      "statement_descriptor": null,
      "tiers": null,
      "tiers_mode": null,
      "transform_usage": null,
      "trial_period_days": null,
      "usage_type": "licensed"
    },
    "quantity": 1,
    "schedule": null,
    "start": 1653581061,
    "start_date": 1653581061,
    "status": "active",
    "tax_percent": null,
    "test_clock": null,
    "transfer_data": null,
    "trial_end": null,
    "trial_start": null
  },
  "previous_attributes": {
    "metadata": {
      "Samsung": null
    }
  }
}

客戶.訂閱.更新

Stripe webhook 可以監聽customer.subscription.updated事件。

API 回應

您的回應看起來應該類似於這樣：

{
  "object": {
    "id": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
    "object": "subscription",
    "application": null,
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false
    },
    "billing": "charge_automatically",
    "billing_cycle_anchor": 1653581061,
    "billing_thresholds": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "collection_method": "charge_automatically",
    "created": 1653581061,
    "current_period_end": 1656259461,
    "current_period_start": 1653581061,
    "customer": "cus_LlFcWXPXftQibf",
    "days_until_due": null,
    "default_payment_method": null,
    "default_source": null,
    "default_tax_rates": [
    ],
    "description": null,
    "discount": null,
    "ended_at": null,
    "invoice_customer_balance_settings": {
      "consume_applied_balance_on_void": true
    },
    "items": {
      "object": "list",
      "data": [
        {
          "id": "si_LlFgWbs9lqlwOF",
          "object": "subscription_item",
          "billing_thresholds": null,
          "created": 1653581062,
          "metadata": {
          },
          "plan": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "plan",
            "active": true,
            "aggregate_usage": null,
            "amount": 100,
            "amount_decimal": "100",
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "interval": "month",
            "interval_count": 1,
            "livemode": false,
            "metadata": {
            },
            "name": "Beacon Metadata",
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "statement_descriptor": null,
            "tiers": null,
            "tiers_mode": null,
            "transform_usage": null,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "price": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "price",
            "active": true,
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "livemode": false,
            "lookup_key": null,
            "metadata": {
            },
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "recurring": {
              "aggregate_usage": null,
              "interval": "month",
              "interval_count": 1,
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "tax_behavior": "unspecified",
            "tiers_mode": null,
            "transform_quantity": null,
            "type": "recurring",
            "unit_amount": 100,
            "unit_amount_decimal": "100"
          },
          "quantity": 1,
          "subscription": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
          "tax_rates": [
          ]
        }
      ],
      "has_more": false,
      "total_count": 1,
      "url": "/v1/subscription_items?subscription=sub_1L3jAgFzWFPFNFjqFpyUF8XY"
    },
    "latest_invoice": "in_1L3jAgFzWFPFNFjq8YFoU6R3",
    "livemode": false,
    "metadata": {
      "Samsung": "yes"
    },
    "next_pending_invoice_item_invoice": null,
    "pause_collection": null,
    "payment_settings": {
      "payment_method_options": null,
      "payment_method_types": null,
      "save_default_payment_method": "off"
    },
    "pending_invoice_item_interval": null,
    "pending_setup_intent": null,
    "pending_update": null,
    "plan": {
      "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
      "object": "plan",
      "active": true,
      "aggregate_usage": null,
      "amount": 100,
      "amount_decimal": "100",
      "billing_scheme": "per_unit",
      "created": 1653580781,
      "currency": "eur",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Beacon Metadata",
      "nickname": null,
      "product": "prod_LlFbyvOQ6dpLXF",
      "statement_descriptor": null,
      "tiers": null,
      "tiers_mode": null,
      "transform_usage": null,
      "trial_period_days": null,
      "usage_type": "licensed"
    },
    "quantity": 1,
    "schedule": null,
    "start": 1653581061,
    "start_date": 1653581061,
    "status": "active",
    "tax_percent": null,
    "test_clock": null,
    "transfer_data": null,
    "trial_end": null,
    "trial_start": null
  },
  "previous_attributes": {
    "metadata": {
      "Samsung": null
    }
  }
}

限制

使用 Stripe API 時有一些限制：

  • 引用 Stripe - “不要在需要嚴格一致性的寫後讀流程中使用搜索。在正常操作條件下，不到一分鐘即可搜索到數據。有時，新數據或更新數據的傳播在中斷期間可能會延遲一個小時。搜索功能不適用於印度的商家。”
'