# Guide d'intégration pour Stripe Apps intégrées

Utilisez les composants intégrés de Stripe Apps pour permettre à vos clients de gérer les données de paiement dans des applications tierces.

Les clients préfèrent que leurs données de paiement soient facilement accessibles dans les outils qu’ils utilisent déjà pour leurs workflows métier. Les composants intégrés pour les applications permettent à vos clients d’utiliser des applications tierces dans Stripe.

Avec les composants intégrés pour les applications, vous pouvez ajouter des intégrations créées pour Stripe à votre plateforme, et ainsi permettre à vos clients d’utiliser leurs applications tierces préférées sans quitter Stripe. Utilisez des composants d’interface utilisateur préconçus qui synchronisent les données directement avec des applications telles que QuickBooks et Xero.

## Intégration avec les composants intégrés Connect

[Configurez Connect.js](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions) pour permettre l’ajout d’une fonctionnalité de tableau de bord pour comptes connectés à votre site Web.

Les applications intégrées Stripe Apps utilisent des composants en version bêta privée qui nécessitent l’utilisation de versions bêta des SDK Stripe. En savoir plus sur les [composants en version bêta privée](https://docs.stripe.com/connect/supported-embedded-components.md#preview-components).

## Sélectionner l'application à intégrer

Stripe prend en charge les intégrations d’applications suivantes.

| Intégration des applications | ID de l’application |
| --- | --- |
| [QuickBooks Sync par Acodei](https://docs.stripe.com/stripe-apps/embedded-apps/accounting-integrations.md#quickbooks-sync-by-acodei) | com.example.acodeistripeapp |
| [Xero sync par Xero](https://docs.stripe.com/stripe-apps/embedded-apps/accounting-integrations.md#xero) | com.xero.stripeapp |
| [Mailchimp](https://docs.stripe.com/stripe-apps/embedded-apps/marketing-integrations.md#mailchimp) | mailchimp |

## Configurer l'installation de l'application

Affichez le composant d’installation intégré pour l’application voulue. L’installation de l’application autorise l’application tierce à accéder aux données Stripe de vos utilisateurs, créant ainsi une connexion entre votre plateforme, Stripe et l’application tierce. Le composant a deux états possibles : `uninstalled` et `installed`. Écoutez les déclencheurs d’événements d’installation pour créer votre flux d’expérience utilisateur personnalisé ou modifier votre propre backend.

Lors de la [création d’une session de compte](https://docs.stripe.com/api/account_sessions/create.md), activez l’installation et l’affichage de l’application en spécifiant `app_install` et `app_viewport` dans le paramètre `components`. Vous devez activer l’application que vous souhaitez afficher en spécifiant le paramètre `features` sous `allowed_apps`.

```curl
curl https://api.stripe.com/v1/account_sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-08-26.preview; embedded_connect_beta=v2;" \
  -d account={{CONNECTED_ACCOUNT_ID}} \
  -d "components[app_install][enabled]=true" \
  -d "components[app_install][features][allowed_apps][]=APP_ID" \
  -d "components[app_viewport][enabled]=true" \
  -d "components[app_viewport][features][allowed_apps][]=APP_ID"
```

Après avoir créé la session du compte et [initialisé ConnectJS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), vous pouvez afficher le composant d’installation de l’application dans le frontend&nbsp;:

#### JavaScript

```js
const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
container.appendChild(appInstall);
```

Ce composant intégré prend en charge les paramètres suivants&nbsp;:

#### HTML + JS

| Méthode | Type | Description |
| --- | --- | --- |
| `setApp` | `string` | Définit l’ID de l’application que votre compte connecté peut installer. Consultez la liste des [applications disponibles](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). |

#### React

| Propriété React | Type | Description |
| --- | --- | --- |
| `app` | `string` | L’ID de l’application que votre compte connecté peut installer. Consultez la liste des [applications disponibles](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). |

Vous pouvez configurer un comportement personnalisé en fonction de l’état actuel ou mis à jour d’une installation.

#### HTML et JavaScript

```html
<div id="app-install-container"></div>
```

```js
// Do something when install state fetched on render
const handleAppInstallFetched = (response) => {
  console.log(`Install state fetched for app  ${response.appId} to ${response.state}`);
};

// Do something when install state changes
const handleAppInstallChanged = (response) => {
  console.log(`Install state changed for app  ${response.appId} to ${response.state}`);
};


const container = document.getElementById('app-install-container');
const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
appInstall.setOnAppInstallStateFetched(handleAppInstallFetched);
appInstall.setOnAppInstallStateChanged(handleAppInstallChanged);
container.appendChild(appInstall);
```

#### HTML + JS

| Méthode | Description | Variables |
| --- | --- | --- |
| `setOnAppInstallStateFetched` | Permet aux utilisateurs de spécifier un comportement personnalisé dans une fonction de rappel lors de la récupération de l’installation. | - `response.appId`&nbsp;: L’application installée
- `response.state`&nbsp;: L’état de l’installation `INSTALLED | UNINSTALLED` |
| `setOnAppInstallStateChanged` | Permet aux utilisateurs de spécifier un comportement personnalisé dans une fonction de rappel lorsque l’état de l’installation a changé. | - `response.appId`&nbsp;: L’application installée
- `response.state`&nbsp;: L’état de l’installation `INSTALLED | UNINSTALLED` |

#### React

| Propriété React | Description | Variables |
| --- | --- | --- |
| `onAppInstallStateFetched` | Permet aux utilisateurs de spécifier un comportement personnalisé dans une fonction de rappel lors de la récupération de l’installation. | - `response.appId`&nbsp;: L’application installée
- `response.state`&nbsp;: L’état de l’installation `INSTALLED | UNINSTALLED` |
| `onAppInstallStateChanged` | Permet aux utilisateurs de spécifier un comportement personnalisé dans une fonction de rappel lorsque l’état de l’installation a changé. | - `response.appId`&nbsp;: L’application installée
- `response.state`&nbsp;: L’état de l’installation `INSTALLED | UNINSTALLED` |

## Configurer les paramètres de l'application

Affichez le composant intégré App viewport pour l’application que vous avez sélectionnée afin d’activer les fonctionnalités de base de l’application, y compris la connexion au compte du logiciel de l’application avec OAuth, l’inscription des utilisateurs, les paramètres et la configuration du service et des états de synchronisation des transactions. Transmettez `user_id` (entreprise représentée sur votre plateforme) en tant qu’attribut HTML facultatif que les applications tierces peuvent utiliser pour créer une URL dynamique qui redirige vers le tableau de bord de votre utilisateur après OAuth.

#### JavaScript

```js
const appViewport = stripeConnectInstance.create('app-viewport');
appViewport.setApp('{{APP_ID}}');
appViewport.setAppData({userId: '{{PLATFORM_USER_ID}}'});
container.appendChild(appViewport);
```

Ce composant intégré prend en charge les paramètres suivants&nbsp;:

#### HTML + JS

| Méthode | Type | Description |
| --- | --- | --- |
| `setApp` | `string` | Définit l’ID de l’application que votre compte connecté peut afficher. Découvrez les applications disponibles dans le [guide d’intégration des Stripe Apps intégrées](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). |
| `setAppData` | `Record<String, String>` | Définit les données relatives à votre plateforme consommées par l’application. |

#### React

| Propriété React | Type | Description |
| --- | --- | --- |
| `app` | `string` | L’ID de l’application que votre compte connecté peut afficher. Consultez les [applications disponibles](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select). |
| `appData` | `Record<String, String>` | Données relatives à votre plateforme consommées par l’application. |

## Personnalisation pour les paiements indirects de type «&nbsp;on behalf of&nbsp;» (OBO)

Pour vous assurer que l’application que vous avez sélectionnée traite correctement les données de transaction, vous devez mettre à jour le paiement indirect sur le compte connecté à l’aide du schéma de données normalisé. Votre plateforme doit impérativement envoyer au moins un objet [Customer](https://docs.stripe.com/api/customers/object.md) (spécifiquement l’ID client) à chaque événement de paiement.

Cette exigence est importante, car l’événement `charge.updated` peut être envoyé plusieurs fois pour une même transaction. Cependant, l’application tierce ne lit et ne traite que les événements qui incluent un ID client. Incluez toujours l’ID du client dans la charge utile pour confirmer que l’application traite la transaction correspondante. Trois scénarios vous obligent à mettre à jour votre paiement indirect&nbsp;:

- Paiement ponctuel effectué
- Paiement récurrent effectué
- Paiement remboursé

#### Comptabilité

| Nom du champ ou de la clé | Format (les règles standard en matière de CSV s’appliquent) | Description | Obligatoire |
| --- | --- | --- | --- |
| [charges.customer](https://docs.stripe.com/api/charges/object.md#charge_object-customer) | Chaîne (ID) | ID client Stripe (appartenant au compte connecté) associé à un objet `Charge` de destination. Si ce champ n’est pas renseigné, les transactions ne sont pas synchronisées avec les applications (comme Xero et QBO). | Obligatoire |
| [customer.name](https://docs.stripe.com/api/customers/object.md#customer_object-name) | Chaîne | Nom complet du client |  |
| [customer.email](https://docs.stripe.com/api/customers/object.md#customer_object-email) | Chaîne | Adresse e-mail du client |  |
| [customer.address.<>](https://docs.stripe.com/api/customers/object.md#customer_object-address) | Chaîne (plusieurs champs) | Adresse physique du client (peut être utilisée pour la facturation et la livraison) |  |
| `charges.metadata.[refund_amount]` | Chaîne (entier exprimé en centimes) | Reflète [charges.amount_refunded](https://docs.stripe.com/api/charges/object.md#charge_object-amount_refunded) dans les sous-unités de la devise de base (‘350’ = 3,50&nbsp;USD) | Requis par Quickbooks Online Sync by Acodei |
| `charges.metadata.[refund_reason]` | chaîne | Motif du remboursement |  |
| `charges.metadata.[currency_converted]` | `true` | `false` | `null` | À définir sur `true` si la devise a été convertie, par exemple si la devise de présentation diffère de la devise de règlement. | Requis par Quickbooks Online Sync by Acodei si vous utilisez les métadonnées fees_names |
| `customer.metadata.[platform_customer_ID]` | Chaîne | ID du client, tel qu’il est enregistré dans le système de la plateforme* |  |
| `charges.metadata.[platform_product_ID]` | Chaîne, CSV produits multiples | ID des produits tels qu’ils sont enregistrés dans le système de la plateforme |  |
| `charges.metadata.[platform_product_name]` | Chaîne, CSV produits multiples | Nom du produit tel qu’il est enregistré dans le système de la plateforme |  |
| `charges.metadata.[platform_product_quantity]` | Chaîne, CSV produits multiples | Quantité de chaque produit correspondant au tableau d’ID et de nom |  |
| `charges.metadata.[platform_product_value]` | Entier, CSV produits multiples | La valeur de chaque produit (tarif ou coût) correspondant à l’ID et au nom du produit. Sous-unités de la devise de base (‘350’ = 3,50&nbsp;USD) |  |
| `charges.metadata.[platform_product_tag]` | Chaîne, CSV produits multiples | Libellé ou catégorie de produit correspondant au tableau d’ID et de nom |  |
| `charges.metadata.[platform_order_ID]` | Chaîne | ID de la commande, tel qu’il est enregistré dans le système de la plateforme |  |
| `charges.metadata.[platform_charge_ID]` | Chaîne | ID de la transaction ou du paiement, tel qu’il est enregistré dans le système de la plateforme et visible pour l’entreprise |  |
| `charges.metadata.[fees_names]` | Chaîne, CSV frais multiples | Nom des frais de toute nature que l’utilisateur paie (dépenses) dans le cadre de la transaction et qui ne sont pas pris en compte dans le paiement (par exemple, frais de traitement du crédit, commission de plateforme) *Si ce champ est renseigné, le champ charges.application\_fee est ignoré.* |  |
| `charges.metadata.[fees_values]` | Entier, CSV frais multiples | Valeurs des frais de toute nature que l’utilisateur paie (dépenses) dans le cadre de la transaction et qui ne sont pas pris en compte dans le paiement (par exemple, frais de traitement du crédit, commission de plateforme) Sous-unités de la devise de base (‘350’ = 350&nbsp;USD) |  |
| `charges.metadata.[revenues_names]` | Chaîne, CSV revenus multiples | Frais (revenus) perçus par l’entreprise dans le cadre de cette transaction (paiement) et qui ne sont pas pris en compte dans le paiement (par exemple, frais de commodité ou pourboires) |  |
| `charges.metadata.[revenues_values]` | Entier, CSV revenus multiples | Valeurs des frais (revenus) perçus par l’entreprise dans le cadre de cette transaction (paiement). Sous-unités de la devise de base (‘350’ = 3,50&nbsp;USD) |  |
| `charges.metadata.[total_tax]` | Nombre entier | Total des taxes associées à cette transaction (paiement). Sous-unités de la devise de base (‘350’ = 3,50&nbsp;USD) |  |
| `charges.metadata.[tax_names]` | Chaîne, CSV taxes multiples | Noms des types de taxes appliqués à une transaction permettant d’utiliser plusieurs types de taxes à l’aide d’un tableau (par exemple, ‘TPS’ ou ‘vente’) |  |
| `charges.metadata.[tax_rates]` | Flottant, CSV taxes multiples | Taux de taxe appliqués à une transaction correspondant aux types de taxes spécifiés, sous forme de pourcentage (par exemple, ‘3’ ou ‘1,5’ correspond à une TPS de 3&nbsp;% et une taxe de vente de 1,5&nbsp;%) |  |
| `charges.metadata.[tax_values]` | chaîne, CSV taxes multiples | Valeurs fiscales appliquées à une transaction correspondant aux types de taxes spécifiés. Sous-unités de la devise de base (‘350’ = 3,50&nbsp;USD) |  |

QuickBooks Sync by Acodei exige nécessite également de mettre à jour les paiements avec montants des remboursement écrits dans les métadonnées.$$$

#### Marketing

| Nom du champ ou de la clé | Format (les règles standard en matière de CSV s’appliquent) | Description | Obligatoire |
| --- | --- | --- | --- |
| [charges.customer](https://docs.stripe.com/api/charges/object.md#charge_object-customer) | Chaîne (ID) | ID client Stripe (appartenant au compte connecté) associé à un objet `Charge` de destination. Si ce champ n’est pas renseigné, les transactions ne sont pas synchronisées avec les applications (comme Xero et QBO). | Obligatoire |
| [customer.name](https://docs.stripe.com/api/customers/object.md#customer_object-name) | Chaîne | Nom complet du client |  |
| [customer.email](https://docs.stripe.com/api/customers/object.md#customer_object-email) | Chaîne | Adresse e-mail du client |  |
| [customer.address.<>](https://docs.stripe.com/api/customers/object.md#customer_object-address) | Chaîne (plusieurs champs) | Adresse physique du client (peut être utilisée pour la facturation et la livraison) |  |
| `charges.metadata.[refund_amount]` | Chaîne (entier exprimé en centimes) | Reflète [charges.amount_refunded](https://docs.stripe.com/api/charges/object.md#charge_object-amount_refunded) |  |
| `charges.metadata.[refund_reason]` | chaîne | Motif du remboursement |  |
| `customer.metadata.[platform_customer_ID]` | Chaîne | ID du client, tel qu’il est enregistré dans le système de la plateforme* |  |
| `charges.metadata.[platform_product_ID]` | Chaîne, CSV produits multiples | ID des produits tels qu’ils sont enregistrés dans le système de la plateforme |  |
| `charges.metadata.[platform_product_name]` | Chaîne, CSV produits multiples | Nom du produit tel qu’il est enregistré dans le système de la plateforme |  |
| `charges.metadata.[platform_product_quantity]` | Chaîne, CSV produits multiples | Quantité de chaque produit correspondant au tableau d’ID et de nom |  |
| `charges.metadata.[platform_product_value]` | Chaîne, CSV produits multiples | Valeur du produit (tarif et coût) correspondant à l’ID et au nom du produit |  |
| `charges.metadata.[total_tax]` | chaîne | Total des taxes associées à cette transaction (paiement) |  |

L’extrait de code suivant permet d’accéder au paiement indirect ciblé et montre comment mettre à jour par schéma.

1. Identifiez le paiement indirect à partir de la transaction

#### TypeScript

```ts
const paymentOnPlatform = await StripeClient.paymentIntents.retrieve(
  "pi_3N6JL7LirQdaQn8E1Lpn7Dui",
);

const latestCharge = await StripeClient.charges.retrieve(
  paymentOnPlatform.latest_charge as string,
);

const transfer = await StripeClient.transfers.retrieve(
  latestCharge.transfer as string,
);


const payment = await StripeClient.charges.retrieve(
  transfer.destination_payment as string,
    undefined,
    {
        stripeAccount: transfer.destination as string,
      },
  );

```

1. Créez un client, puis modifiez le paiement avec l’ID client et les métadonnées correspondantes. Le client doit appartenir au compte connecté et non à la plateforme pour que les données soient transmises et que les applications se synchronisent.

#### javascript

```jsx
const customer = await StripeClient.customers.create(
      {
        email: `jenny.rosen@example.com`,
        name: "Jenny Rosen",
        address: {
          city: "Brothers",
          state: "Oregon",
          country: "USA",
          line1: "27 Fredrick Ave",
          postal_code: "97712"
        },
       	 metadata: {
 	   platform_customer_ID: "K-123456"
	 },
      },
      {
        stripeAccount: accountId,
      },
    );
    const payment = await StripeClient.charges.update(
      id,
      {
        customer: customer.id,
        metadata: {
          product_name: "Creative writing course for PMs",
          platform_product_ID: "P-123456",
          platform_order_ID: "O-123456"
        },
      },
      {
        stripeAccount: accountId,
      },
    );



```

## Paiements directs

Les intégrations intégrées accèdent à toutes les données de paiement, de client et de produit stockées dans Stripe. Vous pouvez transmettre à l’application des données facultatives spécifiques à la plateforme en utilisant le schéma de métadonnées ci-dessous.

| Nom du champ ou de la clé | Format (les règles standard en matière de CSV s’appliquent) | Description |
| --- | --- | --- |
| `customer.metadata.[platform_customer_ID]` | chaîne | ID du client, tel qu’il est enregistré dans le système de la plateforme |
| `payment.metadata.[platform_product_ID]` | chaîne, CSV produits multiples | Les ID de produits liés à cette transaction (s’ils sont différents de l’ID de produit Stripe), tels qu’ils sont enregistrés dans le système de la plateforme. |
| `payment.metadata.[platform_product_name]` | chaîne, CSV produits multiples | Les noms de produits ou servies liés à cette transaction (s’ils sont différents du nom de produit Stripe), tels qu’ils sont enregistrés dans le système de la plateforme. |
| `payment.metadata.[platform_product_value]` | chaîne, CSV produits multiples | La valeur de chaque produit (tarif ou coût) correspondant au tableau des ID et des noms (si elle est différente de la valeur du produit Stripe) |
| `payment.metadata.[platform_order_ID]` | chaîne | L’ID de commande lié à cette transaction (paiement), tel qu’il est enregistré dans le système de la plateforme. |
| `payment.metadata.[platform_charge_ID]` | chaîne | ID de paiement ou de transaction, tel qu’enregistré sur la plateforme et tel que le voit l’utilisateur (s’il est différent de l’ID de paiement Stripe) |

### Vous souhaitez accéder à la version bêta des composants intégrés pour les applications&nbsp;?

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/stripe-apps/embedded-apps" \
  -d '{"email": "EMAIL", "preview": "stripe_apps_for_platforms_preview"}'
```