Récupération des informations d'abonnement avec les métadonnées Stripe

Dans cette rubrique, vous apprendrez à récupérer les informations d'abonnement associées aux métadonnées personnalisées Stripe à l'aide de l'API Stripe.

Aperçu

Brightcove ajoute des métadonnées personnalisées aux abonnements Stripe qui vous permettront d'identifier le type d'appareil du spectateur utilisé lors de la création de l'abonnement. Vous pouvez interroger l'API Stripe pour rechercher les abonnements associés aux métadonnées personnalisées. Vous pouvez également ajouter des webhooks pour écouter les événements Stripe.

Cette rubrique explique comment effectuer les opérations suivantes :

  • Utilisez l'API Stripe pour rechercher des métadonnées spécifiques dans n'importe quel abonnement/achat et obtenir une liste
  • Créer un webhook pour écouter les événements Stripe

Conditions préalables

Pour utiliser l'API Stripe comme indiqué dans cette rubrique, vous aurez besoin des éléments suivants :

  • Compte Stripe
  • Postman ou une autre plate-forme API

    Vous pouvez utiliser la plateforme API de votre choix pour interagir avec l'API Stripe, mais pour ces exemples, nous utiliserons Postman.

Comprendre l'API Stripe

URL de base

L'URL de base de l'API Stripe est la suivante :

https://api.stripe.com

Authentification

Les demandes sont authentifiées à l'aide de votre clé d'API dans l' Authorization en-tête :

Authorization: Bearer {api_key}

Collection API

La collection Stripe API est hébergée dans l' espace de travail public Postman de Stripe. Cela vous permet de passer de l'espace de travail public au vôtre.

Si vous ne souhaitez pas dédoubler la collection depuis l'espace de travail public, vous pouvez l'importer depuis le postier à rayures Référentiel GitHub.

Création d'un environnement Postman

Vous pouvez utiliser la plateforme API de votre choix pour interagir avec l'API Stripe, mais pour ces exemples, nous utiliserons Postman.

  1. Connectez-vous ou créez un compte avec Postman.
  2. Soit vous utilisez le modèle d'environnement dans l' espace de travail public de Postman Stripe, soit vous créez un nouvel environnement dans Postman. Nous allons créer un nouvel environnement.

  3. Dans votre espace de travail, cliquez sur Nouveau.

    créer un nouveau

  4. Dans la boîte de dialogue, sélectionnez Environnement.

    sélectionner l'environnement

  5. Ajoutez votre clé secrète en tant que variable d'environnement et cliquez sur Enregistrer.

    créer une clé secrète variable
  6. Cliquez sur Ajouter une icône d'onglet pour ouvrir un nouvel onglet.

  7. Dans la boîte de dialogue de demande, procédez comme suit :

    • Sélectionner l' autorisation
    • Pour Type, sélectionnez Token porteur
    • Pour Token, entrez {{secret_key}}

    Si votre environnement est correctement configuré, vous devriez voir la valeur de votre clé secrète lorsque vous passez la souris sur la secret_key variable.

    variable "mouse over key" (passage de la souris sur une touche)
  8. Cliquez sur Save.
  9. Dans la boîte de dialogue, procédez comme suit :
    • Ajouter un nom de demande
    • Choisir ou créer une nouvelle collection
    • Cliquez sur Enregistrer
    demande de sauvegarde

  10. Vous êtes maintenant prêt à créer une GET demande à l'API Stripe.

    Environnement créé

Recherche d'abonnements avec métadonnées

Dans cette section, vous utiliserez l'API Stripe pour rechercher des abonnements ayant des métadonnées personnalisées.

Métadonnées personnalisées

Prénom Montant
device_type Valeurs :
  • androidtv
  • firetv
  • lgtv
  • nettv
  • operatv
  • panasonic
  • samsung

Étapes

  1. Retournez dans l'environnement Postman que vous avez créé dans la section précédente.

  2. Pour la GET demande, collez ce qui suit dans l'URL de la demande. Utilisez la valeur du type d'appareil de votre choix.

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

    Obtenir des abonnements Samsung
  3. Cliquez sur Envoyer.

  4. Si le message d'erreur suivant s'affiche avec votre GET demande,

    Erreur de version de l'API Stripe

    assurez-vous que vous utilisez la version actuelle de l'API Stripe. Vous pouvez le faire en ajoutant l'en-tête suivant :

    • KEY est une « version Stripe »
    • VALUE est « 2020-08-27" (ou la dernière version)
    En-tête de version Stripe

Réponse

La réponse de l'API doit contenir des abonnements avec des métadonnées pour Samsung:yes.

Notez que la réponse contient les informations suivantes :

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

Réponse de l'API

Votre réponse devrait ressembler à ceci :

{
  "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"

Utiliser les webhooks de Stripe

Votre application Brightcove Beacon peut écouter les événements de votre compte Stripe, et vous pouvez utiliser les webhooks pour permettre à Stripe d'envoyer des notifications en temps réel à votre application, ou vous pouvez utiliser un webhook comme point de terminaison.

Pour plus de détails, voir la Stripe Utiliser les webhooks entrants référence.

Notez que chaque réponse contient les informations suivantes :

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

Evénements

Voici quelques événements que vous pouvez écouter :

client.abonnement.créé

Un webhook Stripe peut écouter l' customer.subscription.created événement.

Réponse de l'API

Votre réponse devrait ressembler à ceci :

{
  "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
    }
  }
}

client.abonnement.mis.à.jour

Un webhook Stripe peut écouter l' customer.subscription.updated événement.

Réponse de l'API

Votre réponse devrait ressembler à ceci :

{
  "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
    }
  }
}

Contraintes

L'utilisation de l'API Stripe présente certaines limites :

  • Pour citer Stripe, « N'utilisez pas la recherche dans les flux de lecture après écriture où une cohérence stricte est nécessaire. Dans des conditions normales d'utilisation, les données sont consultables en moins d'une minute. Il arrive que la propagation de données nouvelles ou mises à jour accuse un retard pouvant aller jusqu'à une heure pendant les pannes. La fonctionnalité de recherche n'est pas disponible pour les commerçants en Inde"
'