Facturer des frais SaaS à vos comptes connectésVersion bêta publique

Configurez votre compte Stripe en tant que plateforme Connect en suivant le processus d’inscription dans votre Dashboard.

Le Guide d’intégration Connect explique les options de configuration de la plateforme.

Si vous disposez d’une plateforme existante, cette intégration ne prend pas en charge vos comptes connectés qui utilisent Accounts v1. Si vous souhaitez les inclure, vous devez les recréer en suivant le processus expliqué ici, puis supprimer leurs anciens comptes.

Pour chaque compte connecté, utilisez l’API Accounts v2 pour créer un objet Account avec les configurations customer et merchant.

• La configuration customer permet au Account de payer des frais d’abonnement à votre plateforme à l’aide d’un moyen de paiement que vous associez au Account.
• La configuration merchant fait de Account un compte connecté qui peut accepter les paiements par carte de ses propres clients. Lorsque vous attribuez la configuration merchant, vous définissez également d’autres aspects du compte connecté. En voici quelques exemples :
  • Pour obtenir la possibilité d’accepter les paiements par carte, définissez configuration.merchant.capabilities.card_payments.requested sur true.
  • Spécifiez l’accès à un Dashboard Stripe en définissant dashboard. Dans l’exemple suivant, nous définissons dashboard sur full, ce qui signifie que l’objet Account a accès à l’intégralité du Dashboard Stripe.
  • Spécifiez la responsabilité de la collecte des frais sur le Account en définissant defaults.responsibilities.fees_collector sur stripe ou application.
  • Spécifiez la responsabilité des soldes négatifs sur le Account en définissant defaults.responsibilities.losses_collector sur stripe ou application.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "dashboard": "full",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        }
    },
    "defaults": {
        "currency": "usd",
        "responsibilities": {
            "fees_collector": "stripe",
            "losses_collector": "stripe"
        },
        "locales": [
            "en-US"
        ]
    },
    "include": [
        "configuration.customer",
        "configuration.merchant",
        "identity",
        "requirements"
    ]
  }'

La réponse inclut l’ID, que vous utilisez pour référencer le Account tout au long de votre intégration.

{
  "id": "acct_xxxxxxxxxxxxxxxx",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "ip_address": null,
        "location": null,
        "location-source": "identity_address"
      },
      "billing": {
        ...
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        }
      },
      "shipping": ...,
      "test_clock": ...
    },
    "merchant": {
      "bacs_debit_payments": null,
      "branding": {
        ...
      },
      "capabilities": {
        ...
        "card_payments": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        },
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          }
        },
        ...
      },
      "card_payments": {
        "decline_on": {
          "avs_failure": false,
          "cvc_failure": false
        }
      },
      "mcc": null,
      ...
      "statement_descriptor": {
        ...
      },
      "support": {
        "address": {
          ...
        },
        ...
      }
    },
    "recipient": null
  },
  "contact_email": "furever_contact@example.com",
  "created": "2025-03-04T02:23:20.000Z",
  "dashboard": "full",
  "identity": {
    "attestations": {
      ...
    },
    "terms_of_service": {
      "account": null
    },
    "business_details": {
      ...
      "registered_name": "Furever",
      ...
    },
    "country": "US",
    "entity_type": "company",
    "individual": null
  },
  "defaults": null,
  "display_name": "Furever",
  "metadata": {},
  "requirements": {
    "collector": "stripe",
    "entries": [
      {
        "awaiting_action_from": "user",
        "description": "representative.surname",
        "errors": [],
        "impact": {
          "restricts_capabilities": [
            {
              "capability": "card_payments",
              "configuration": "merchant",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.payouts",
              "configuration": "merchant",
              "deadline": {
                "status": "past_due"
              }
            }
          ]
        },
        "minimum_deadline": {
          "status": "past_due"
        },
        "reference": null,
        "requested_reasons": [
          {
            "code": "routine_onboarding"
          }
        ]
      }
    ],
    "summary": {
      "minimum_deadline": {
        "status": "past_due",
        "time": null
      }
    }
  }
}

Responsabilités liées au compte

Les responsabilités définissent certains comportements des comptes connectés, notamment la manière dont ils paient les frais Stripe et à qui incombe la responsabilité des soldes négatifs. Vous les définissez lorsque vous ajoutez la configuration merchant à vos comptes connectés.

Pour permettre à vos Accounts d’encaisser des paiements en tant que comptes connectés, définissez les responsibilities suivantes :

Les responsabilités sont soumises aux restrictions suivantes :

• Si vous définissez losses_collector sur application, vous devez également définir fees_collector sur application.
• Si vous utilisez des paiements indirects avec un compte, nous vous recommandons de définir à la fois losses_collector et fees_collector sur application.

Pour plus d’informations sur les configurations prises en charge, consultez les recommandations d’intégration.

Types de paiements

La version bêta ne prend en charge que les paiements directs et indirects pour les comptes connectés. Vous ne pouvez pas utiliser de paiements et de transferts distincts.

Pour utiliser les paiements indirects, vous devez définir le paramètre on_behalf_of pour faire du compte connecté le marchand de règlement. Vous devez également ajouter la configuration recipient à vos comptes connectés et demander la fonctionnalité stripe_transfers pour ceux-ci.

Pour autoriser le transfert de fonds du solde Stripe de votre plateforme vers le solde Stripe du compte connecté, ajoutez la configuration recipient et demandez la fonctionnalité stripe_balance.stripe_transfers. Les paiements indirects nécessitent cette fonctionnalité.

La requête stripe_balance.stripe_transfers demande également automatiquement la fonctionnalité stripe_balance.payouts de la configuration recipient, qui permet au compte connecté d’effectuer un virement vers son compte bancaire externe.

La configuration merchant demande automatiquement sa propre fonctionnalité stripe_balance.payouts, qui est identique à la fonctionnalité stripe_balance.payouts de la configuration recipient. Si le compte n’a pas besoin d’autres fonctionnalités recipient, vous n’avez pas besoin d’ajouter la configuration recipient.

Pour ajouter la configuration recipient et demander la fonctionnalité stripe_balance.stripe_transfers, mettez à jour l’objet Account et définissez le paramètre configuration.recipient.capabilities.stripe_balance.stripe_transfers.requested sur true.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "include": [
        "identity",
        "requirements"
    ],
    "configuration": {
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    }
  }'

Pour que vos comptes connectés puissent accepter des paiements sur votre plateforme, vous devez les inscrire. Vous pouvez diriger vos comptes vers l’inscription hébergée par Stripe, proposer un flux portant le logo de votre marque à l’aide d’un composant intégré Connect ou coder votre propre flux d’inscription personnalisé. L’inscription hébergée par Stripe est l’option la plus simple. L’utilisation d’un composant intégré permet une certaine personnalisation tout en gérant automatiquement la plupart des processus. Un flux d’inscription personnalisé donne à votre plateforme un contrôle total, mais nécessite plus de ressources pour la mise en œuvre et les mises à jour régulières.

Le processus de création d’un compte externe dépend de l’accès au Dashboard dont bénéficient vos comptes connectés :

• Si le dashboard d’un Account est défini sur full ou express, le propriétaire du compte ajoute son compte externe depuis son Dashboard.
• Si le dashboard d’un Account est défini sur none, vous pouvez créer son compte externe à l’aide de l’endpoint /v1/external_accounts.

curl https://api.stripe.com/v1/external_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "external_account[account_number]"=000123456789 \
  -d "external_account[routing_number]"=110000000 \
  -d "external_account[country]"=US \
  -d "external_account[currency]"=USD \
  -d "external_account[object]"=bank_account

Pour configurer les paiements de vos comptes connectés, suivez les instructions des sections Paiements directs ou Paiements indirects. Pour utiliser les paiements indirects, vous devez définir le paramètre on_behalf_of.

Vous pouvez configurer les paramètres de virement de vos comptes connectés, y compris la fréquence, le libellé de relevé bancaire et les jours de délai, à l’aide de votre Dashboard ou de l’API.

curl https://api.stripe.com/v1/balance_settings \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d debit_negative_balances=true \
  -d "payouts[schedule][interval]"=weekly \
  -d "payouts[schedule][weekly_anchor]"=monday

Les exigences applicables aux comptes peuvent évoluer, souvent en raison de changements mis en œuvre par les régulateurs financiers, les réseaux de cartes ou d’autres institutions financières. Pour configurer des notifications webhook de modification des exigences, créez une destination d’événements qui écoute les événements de mise à jour Account v2.

1. Dans votre Dashboard Stripe, ouvrez le menu des développeurs en cliquant sur Développeurs au bas du menu de navigation, puis sélectionnez Webhooks.
2. Cliquez sur + Ajouter une destination.
3. Dans la section Événements de, sélectionnez Comptes connectés.
4. Sélectionnez Afficher les options avancées. Dans la section Style de charge utile, sélectionnez Léger.
5. Dans le champ Events, tapez « v2 » pour rechercher les types d’événements v2. Sélectionnez les types v2.account[requirements].updated et v2.account[configuration.configuration_type].capability_status_updated pour chaque type de configuration utilisé par vos comptes connectés.

Poursuivez la configuration de votre destination d’événements en suivant les instructions du générateur d’endpoint de webhook interactif.

Configurez votre application pour qu’elle réponde aux événements de mise à jour en collectant des informations à jour.

Configurer un écouteur local pendant le développement

Vous pouvez envoyer des événements à votre serveur local à des fins de développement en installant la CLI Stripe et en configurant un écouteur local.

1. Connectez-vous au Dashboard Stripe.
2. Dans l’interface de ligne de commande Stripe, saisissez la commande stripe login. Elle vous redirige vers votre navigateur pour confirmer et authentifier votre compte.
3. Revenez à l’interface de ligne de commande et exécutez la commande suivante. Elle permet d’écouter tous les événements v2 disponibles sur votre plateforme et vos comptes connectés, et de les transmettre à http://localhost:4242.

stripe listen --thin-events 'v2.core.account[requirements].updated,v2.core.account[configuration.recipient].capability_status_updated,v2.core.account[configuration.merchant].capability_status_updated,v2.core.account[configuration.customer].capability_status_updated' --forward-thin-to http://localhost:4242

Le prélèvement des frais récurrents auprès de vos comptes connectés avec Stripe Billing implique les étapes suivantes :

1. Créez un ou plusieurs produits pour représenter vos frais récurrents.
2. Créez des abonnements à vos produits tarifaires avec vos comptes en tant que clients.
3. (Facultatif) Pour prélever les frais d’abonnement directement sur les soldes Stripe des comptes connectés et éviter ainsi les frais de transaction associés à d’autres moyens de paiement tels que les cartes, configurez-le comme moyen de paiement.

Créer un produit avec un tarif récurrent

Créez un produit et un tarif représentant vos frais d’abonnement. Vous pouvez utiliser l’API ou le Dashboard.

curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Connected account subscription fee" \
  -d "default_price_data[unit_amount]"=1000 \
  -d "default_price_data[currency]"=usd \
  -d "default_price_data[recurring][interval]"=month \
  -d "expand[]"=default_price

Créer des abonnements pour débiter vos comptes connectés

Vous pouvez prélever les frais d’abonnement SaaS directement depuis le solde Stripe d’un compte connecté. Le compte connecté doit répondre aux exigences suivantes :

• Il doit disposer à la fois des configurations merchant et customer.
• La fonctionnalité card_payments de sa configurationmerchant doit être active.
• Son solde disponible doit disposer de fonds suffisants pour effectuer le paiement complet.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d customer_account=acct_xxxxxxxxxxxxxx \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance

{
  "id": "seti_123",
  "object": "setup_intent",
  "customer": "cus_xxxxxxxxxxxxxx",
  "customer_account": "acct_xxxxxxxxxxxxxx",
  "payment_method": "pm_xxxxxxxxxxxxxx",
  "status": "succeeded"
}

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d customer_account=acct_xxxxxxxxxxxxxx \
  -d default_payment_method=pm_xxxxxxxxxxxxxx \
  -d "items[0][price]"=price_xxxxxxxxxxxxxx \
  -d "items[0][quantity]"=1 \
  -d "payment_settings[payment_method_types][0]"=stripe_balance

Lorsque vous encaissez un paiement à partir du solde Stripe d’un compte connecté, le solde disponible du compte doit disposer de fonds suffisants pour effectuer le paiement complet. Dans le cas contraire, le paiement échoue. Si vous prévoyez d’encaisser des paiements directement à partir du solde Stripe de vos comptes connectés, nous vous recommandons de configurer votre intégration pour gérer les échecs de paiement liés au solde.

Éviter les échecs de paiement à partir du solde

Étant donné que les paiements provenant du solde Stripe d’un compte connecté dépendent de ses fonds disponibles, vous pouvez éviter les échecs de paiement en prenant des mesures pour optimiser les soldes de vos comptes connectés.

Personnaliser la fréquence de virement des comptes connectés

Coordonnez vos fréquences de virement avec vos cycles de facturation d’abonnement. Par exemple, si vous facturez vos frais d’abonnement le premier jour du mois et que vous programmez des virements hebdomadaires le lundi, davantage de virements seront effectués les mois avec davantage de lundis. Ces mois afficheront des soldes disponibles plus faibles que ceux avec moins de virements, ce qui augmentera la probabilité d’échecs de paiement.

Pour éviter les échecs de paiement liés aux virements, vous pouvez également passer aux virements manuels avant le paiement d’un abonnement. Avant chaque paiement d’abonnement, si les fonds disponibles d’un compte connecté sont suffisants, passez aux virements manuels afin que le paiement de l’abonnement soit réglé avant que le virement automatique n’effectue la compensation du compte. Une fois l’abonnement payé, réactivez les virements automatiques.

Définir un solde minimum sur les comptes connectés

Vous pouvez empêcher les virements automatiques de faire baisser le solde disponible d’un compte connecté en dessous d’un certain montant en définissant un solde minimum pour ce compte.

1. Recherchez le compte dans votre Dashboard.
2. Dans le menu déroulant du compte (), sélectionnez Afficher le Dashboard comme….
3. Cliquez sur l’icône d’engrenage et sélectionnez Paramètres.
4. Sous Paramètres du compte, cliquez sur Entreprise.
5. Sélectionnez l’onglet Comptes de virement externes et fréquence des virements.
6. Activez l’option Conserver un montant minimum dans votre solde de paiements et saisissez un montant.

Vous devez définir manuellement le solde minimum pour chaque compte connecté.

Gérer les échecs de paiement à partir du solde

Configurez des webhooks et des destinations d’événement pour recevoir des notifications sur les paiements d’abonnement. Identifiez les échecs de paiement en écoutant l’événement invoice.payment_failed. En cas d’échec d’un paiement :

• L’état du PaymentIntent passe à requires_action.
• L’abonnement reste à l’état incomplete pour la facture en cours.
• L’abonnement continue de générer des factures, qui restent à l’état draft.

Si un paiement effectué à partir d’un solde Stripe échoue en raison de fonds insuffisants, vous pouvez réessayer en suivant ces étapes :

1. Définissez la fréquence des virements du compte connecté sur manual.
2. Écoutez le prochain paiement qui sera effectué sur le compte connecté, puis vérifiez le solde disponible du compte.
3. Si le solde disponible est supérieur ou égal aux frais d’abonnement, définissez le moyen de paiement de la facture impayée sur stripe_balance et réessayez. Sinon, continuez à écouter les paiements jusqu’à ce que le solde disponible soit suffisant pour payer la facture.
4. Si le paiement réussit, rétablissez la fréquence de virement normale du compte connecté.

Instead of retrying a failed payment from a Stripe balance, you can try using a different payment method by specifying it directly on the invoice. You can also implement a flow that allows connected accounts to update their own subscription payment methods.