# Créez une intégration avec un formulaire intégré

Le guide suivant montre comment utiliser le formulaire intégré avec *Checkout Sessions* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription).

Vous pouvez également créer et prévisualiser votre formulaire Checkout intégré via [Checkout studio](https://docs.stripe.com/payments/checkout-studio.md), qui fournit une page centralisée du Dashboard pour configurer et surveiller vos intégrations Checkout.

## Configurer Stripe [Côté serveur]

Tout d’abord, [créez un compte Stripe](https://dashboard.stripe.com/register) ou [connectez-vous](https://dashboard.stripe.com/login).

Coding agents: [install the Stripe CLI](https://docs.stripe.com/cli/install) using the installation script for your operating system. Open a new terminal and run `stripe sandbox create --help` to provision an anonymous Stripe sandbox with working API keys. It doesn’t require account registration.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

## Activer les moyens de paiement

Par défaut, Stripe utilise vos [paramètres de moyens de paiement](https://dashboard.stripe.com/settings/payment_methods)pour déterminer quels moyens de paiement sont activés dans le formulaire intégré. Vous pouvez également configurer des moyens de paiement spécifiques dans votre Checkout Session à l’aide de l’attribut [payment_method_types](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_types).

## Créer une session Checkout [Côté serveur]

Créez une session Checkout sur votre serveur pour contrôler le tunnel de paiement. La session Checkout définit vos éléments de poste, vos options de livraison et d’autres paramètres pour le paiement.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=form \
  -d return_url={{RETURN_URL}} \
  -d integration_identifier=embedded_web_0001
```

Définissez `ui_mode` sur `form` pour intégrer le formulaire intégré. L’objet `CheckoutSession` renvoyé comprend une clé secrète du client, que celui-ci utilise pour afficher en toute sécurité l’interface de paiement.

L’API Checkout Sessions prend en charge un paramètre `integration_identifier` facultatif que vous pouvez définir lors de la création d’une session. Utilisez-le pour attribuer un nom reconnaissable à cette intégration de formulaire et mesurer sa conversion indépendamment des autres intégrations Checkout que vous utilisez.

Vous pouvez également configurer les options suivantes dans la [CheckoutSession](https://docs.stripe.com/api/checkout/sessions/create.md)&nbsp;:

- [automatic_tax](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_tax)&nbsp;: activer le calcul automatique des taxes
- [automatic_tax[address_collection_precision]](https://docs.stripe.com/payments/checkout/taxes.md?ui=checkout-form)&nbsp;: Contrôler la collecte de l’adresse de facturation dans les formulaires intégrés pour le calcul de la taxe lorsque la taxe automatique est activée
- [billing_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection): collecter les adresses de facturation
- [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email)&nbsp;: préremplir l’adresse e-mail du client
- [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer)&nbsp;: préremplir les données client d’un objet `Customer` existant
- [name_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-name_collection)&nbsp;: collectez le nom de l’entreprise, le nom de l’entrepreneur individuel ou les deux
- [shipping_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection)&nbsp;: collecter les adresses de livraison
- [shipping_options](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options): fournir des options de tarifs de livraison
- [submit_type](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type)&nbsp;: indiquer le type de transaction en cours
- [phone_number_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-phone_number_collection)&nbsp;: collecter le numéro de téléphone de vos clients
- [tax_id_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-tax_id_collection)&nbsp;: collecter les numéros fiscaux
- [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-allow_promotion_codes)&nbsp;: autoriser les codes promotionnels utilisables par la clientèle

> #### Paramètres CheckoutSession non pris en charge
> 
> Le formulaire intégré ne prend pas en charge `consent_collection`.

## Configurer Stripe&nbsp;Elements [Côté client]

#### React

Le formulaire intégré est disponible en tant que fonctionnalité de Stripe.js. Installez [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) et le [chargeur Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) depuis le registre public npm.

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

Créer `clientSecret` sous forme de `Promise<string> | string` contenant la clé secrète du client renvoyée par votre serveur. Encapsulez votre application avec le composant [CheckoutFormProvider](https://docs.stripe.com/js/react_stripe_js/checkout_form/checkout_form_provider) en transmettant `clientSecret` et l’instance `stripe`.

```jsx
import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutForm />
    </CheckoutFormProvider>
  );
};

export default App;
```

#### HTML + JS

Le formulaire intégré est disponible automatiquement en tant que fonctionnalité de Stripe.js. Intégrez le script Stripe.js à votre page de paiement en l’ajoutant à l’en-tête de votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com pour rester conforme aux normes PCI. N’incluez pas le script dans un lot et n’en hébergez pas de copie.

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/endive/stripe.js"></script>
</head>
```

Créez une instance de Stripe sur votre page de paiement&nbsp;:

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

Récupérez la clé secrète du client depuis votre serveur et initialisez le SDK Checkout Form&nbsp;:

```javascript
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.client_secret);
```

Créer l’instance du SDK du formulaire Checkout&nbsp;:

```javascript
const checkout = stripe.initCheckoutFormSdk({
  clientSecret
});
```

## Créer et monter [Côté client]

Le formulaire intégré contient un iframe, qui, via une connexion HTTPS, envoie de manière sécurisée les informations de paiement à Stripe.

#### React

Le composant `CheckoutForm` est déjà rendu dans `CheckoutFormProvider` à l’étape précédente. Aucun montage supplémentaire n’est requis pour React.

#### HTML + JS

Le formulaire intégré doit avoir un emplacement dédié dans votre page de paiement. Créez un nœud DOM (conteneur) vide avec un ID unique dans votre formulaire de paiement.

```html
<div id="checkout-form">
  <!-- embedded form will be inserted here -->
</div>
```

Une fois l’instance du SDK Checkout Form prête, créez le formulaire intégré et montez-le sur le nœud DOM conteneur&nbsp;:

```javascript
const form = checkout.createForm();
form.mount('#checkout-form');
```

Vous pouvez définir la [mise en page](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-layout) pour afficher le formulaire intégré en version mono-étape ou multi-étapes.

## Renseigner automatiquement l’e-mail du client

Vous pouvez préremplir l’adresse e-mail du client avec l’une des deux approches, selon que vous souhaitez que l’e-mail soit modifiable ou non.

### Définir l’adresse e-mail sur la Checkout Session (non modifiable)

Transmettez [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) lors de la création de la Checkout Session sur votre serveur. L’e-mail s’affiche dans le formulaire intégré, mais le client ne peut pas le modifier. Vous pouvez également transmettre un ID [Customer](https://docs.stripe.com/api/customers.md) au champ [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) pour préremplir l’e-mail sauvegardé sur le Customer.

### Définir une adresse e-mail par défaut sur le client (modifiable)

Transmettez `defaultValues.email` lors de l’initialisation du SDK pour préremplir une adresse e-mail modifiable. Le client peut modifier cette valeur dans le formulaire intégré.

#### React

```jsx
<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret,
    defaultValues: {
      email: 'customer@example.com',
    },
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>
```

#### HTML + JS

```javascript
const checkout = stripe.initCheckoutFormSdk({
  clientSecret,
  defaultValues: {
    email: 'customer@example.com',
  },
});
```

## Finalisation du paiement [Côté client]

La session Checkout que vous avez créée sur le serveur détermine automatiquement les postes, le montant total et les moyens de paiement disponibles. Le formulaire intégré utilise ces informations pour afficher l’interface adaptée.

#### React

### Traiter la confirmation des paiements

Gérer l’événement confirm lorsque votre client finalise son paiement&nbsp;:

```jsx
import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm, useCheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const CheckoutPage = () => {
  const checkoutState = useCheckoutForm();

  if (checkoutState.type === 'error') {
    return <div>Error: {checkoutState.error.message}</div>;
  }

  const onConfirm = (event) => {
    if (checkoutState.type === 'success') {
       checkoutState.checkout.confirm({formConfirmEvent: event});
    }
  };

  return <CheckoutForm onConfirm={onConfirm} />;
};

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutPage />
    </CheckoutFormProvider>
  );
};

export default App;
```

### Gérer les erreurs

Le formulaire intégré affiche automatiquement les messages d’erreur localisés destinés au client lors de la confirmation du client. Si un problème empêche la poursuite de la méthode de confirmation, cette dernière peut générer une exception. Capturez et gérez ces exceptions.

```jsx
const onConfirm = async (event) => {
  if (checkoutState.type === 'success') {
    try {
      await checkoutState.checkout.confirm({formConfirmEvent: event});
    } catch (error) {
      console.error('Payment confirmation error:', error);
    }
  }
};
```

#### HTML + JS

### Traiter la confirmation des paiements

Écoutez l’événement de confirmation lorsque votre client finalise son paiement&nbsp;:

```javascript
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  form.on('confirm', (event) => {
    loadActionsResult.actions.confirm({formConfirmEvent: event});
  });
}
```

Le formulaire intégré affiche automatiquement les messages d’erreur localisés destinés au client lors de la confirmation du client. Si un problème immédiat empêche la poursuite de la méthode de confirmation, cette dernière peut générer une exception. Capturez et gérez ces exceptions.

```javascript
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  form.on('confirm', async (event) => {
    try {
      await loadActionsResult.actions.confirm({formConfirmEvent: event});
    } catch (error) {
      console.error('Payment confirmation error:', error);
    }
  });
}
```

> #### Personnaliser le comportement de redirection
> 
> Par défaut, après un paiement réussi, le formulaire intégré redirige votre client vers l’URL `return_url` que vous indiquez lors de la création de la session Checkout. Pour éviter les redirections avec les moyens de paiement qui n’en nécessitent pas, comme les cartes bancaires, définissez [redirect](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) sur `'if_required'` lorsque vous appelez [confirm](https://docs.stripe.com/js/custom_checkout/confirm). Pour en savoir plus, consultez la page [Personnaliser le comportement de redirection](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=checkout-form).

## Gérer les événements post-paiement [Côté serveur]

La Checkout Session définit votre poste, vos options de livraison, ainsi que d’autre paramètres de paiement. Une fois qu’un client confirme le paiement de son côté, gérez le résultat du côté du serveur plutôt que de vous fier à l’état côté client.

- **Webhooks** (Recommandé)&nbsp;: écoutez l’événement [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed), que Stripe envoie lorsque le paiement aboutit. Cette approche garantit que vous en êtes informé même si le client ferme son navigateur avant la redirection.
- **Page de retour**&nbsp;: [récupérez la Checkout Session](https://docs.stripe.com/api/checkout/sessions/retrieve.md) à l’aide de son ID pour vérifier l’état du paiement et afficher le résultat approprié à votre client sur la page que vous avez définie comme `return_url`.

Découvrez comment [traiter les commandes](https://docs.stripe.com/checkout/fulfillment.md?ui=checkout-form) après la réception d’un paiement.

## Tester l’intégration

Avant de vous mettre en production, [testez](https://docs.stripe.com/testing.md) chaque intégration de moyen de paiement. Cliquez sur **Payer** pour finaliser le paiement, ce qui vous redirigera vers la page de retour spécifiée.

Si vous voyez la page de retour, et que le paiement apparaît dans la liste des paiements réussis dans le Dashboard, votre intégration fonctionne.

#### Cartes bancaires

Utilisez les [numéros de cartes bancaire de test](https://docs.stripe.com/testing.md#cards) fournis par Stripe pour tester les paiements par carte. Par exemple&nbsp;:

| Scenario | Card Number |
| --- | --- |
| Payment succeeds | 4242424242424242 |
| Payment requires 3DS authentication | 4000002500003155 |
| Payment is declined | 4000000000009995 |

#### Boutons de paiement en un clic

Suivez ces étapes pour tester les boutons de paiement en un clic&nbsp;:

1. Ajoutez un moyen de paiement à votre navigateur. Par exemple, vous pouvez ajouter une carte à votre compte Google&nbsp;Pay ou à votre Apple Wallet.
2. Fournissez votre application via HTTPS. Cette exigence s’applique à la fois en développement et en production Vous pouvez utiliser un service comme [ngrok](https://ngrok.com/)
3. [Enregistrez votre domaine](https://dashboard.stripe.com/settings/payment_method_domains) en modes *environnement de test* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) et production.
4. Suivez les instructions du [guide pour le composant Element Express Checkout](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=embedded-components#test-integration).

## Personnaliser la mise en page et l’apparence

Vous pouvez personnaliser le formulaire intégré en définissant ses options ou en utilisant l’API Appearance.

### Mise en page

Utilisez l’option [layout](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-layout) pour contrôler la façon dont le formulaire intégré présente les étapes de paiement.

- **Expanded**&nbsp;: utilisez cette disposition pour un paiement en une seule étape. Elle est idéale pour les formulaires de paiement traditionnels situés directement sur la page web.
- **Compact** (Private preview)&nbsp;: utilisez cette disposition pour un paiement en plusieurs étapes. Elle est idéale pour les interfaces utilisateur plus compactes telles que les modales, les fenêtres pop-up et les interfaces de chat.

Lorsque vous laissez `layout` non défini, Stripe applique la disposition qui offre la meilleure conversion.

### Demandez l’accès à la disposition compacte

Le format compact affiche le formulaire intégré sous forme de tunnel de paiement en plusieurs étapes. Il est disponible sur demande en version bêta privée. Saisissez votre adresse e-mail ci-dessous pour en demander l’accès.

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

#### React

```jsx
const checkoutFormOptions = {
  layout: 'expanded',
};

<CheckoutForm
  options={checkoutFormOptions}
  onConfirm={onConfirm}
/>
```

#### HTML + JS

```javascript
const form = checkout.createForm({
  layout: 'expanded',
});

form.mount('#checkout-form');
```

### Options du formulaire intégré

Vous pouvez configurer l’apparence de chaque bouton de moyen de paiement express et transmettre les contacts enregistrés à l’aide des options.

#### React

```jsx
const checkoutFormOptions = {
  expressCheckout: {
    buttonTheme: {
      applePay: 'white-outline'
    },
    paymentMethods: {
      applePay: 'always'
    }
  }
};

<CheckoutForm
  options={checkoutFormOptions}
  onConfirm={onConfirm}
/>
```

#### HTML + JS

```javascript
const form = checkout.createForm({
  expressCheckout: {
    buttonTheme: {
      applePay: 'white-outline'
    },
    paymentMethods: {
      applePay: 'always'
    }
  }
});

form.mount('#checkout-form');
```

Le formulaire intégré prend en charge les options suivantes&nbsp;:

|  |
| `expressCheckout.buttonTheme` | Spécifiez un thème par bouton de paiement en un clic. Voir [buttonTheme](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-expressCheckout-buttonTheme). |
| `expressCheckout.paymentMethods` | Définissez quels boutons de paiement en un clic apparaissent. Voir [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-expressCheckout-paymentMethods). |
| `contacts` | Un tableau d’objets représentant des adresses enregistrées, chacun contenant les propriétés `name`, `address` et `phone`. Voir [contacts](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-contacts). |

### API Appearance

Vous pouvez utiliser l’[API Appearance](https://docs.stripe.com/elements/appearance-api.md) pour contrôler le style du formulaire intégré en appliquant un thème ou en mettant à jour des détails spécifiques. Cependant, l’option `rules` n’est pas prise en charge par le formulaire intégré.

Par exemple, choisissez le thème «&nbsp;flat&nbsp;» et remplacez la couleur principale du texte.

#### React

```jsx
const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret, // Dans une intégration fonctionnelle, votre back-end transmet ce hachage contenant des détails tels que le montant d'un paiement. Consultez l'échantillon complet pour en savoir plus.
    appearance
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>
```

#### HTML + JS

```javascript
const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

const checkout = stripe.initCheckoutFormSdk({
  clientSecret, // Dans une intégration fonctionnelle, votre back-end transmet ce hachage contenant des détails tels que le montant d'un paiement. Consultez l'échantillon complet pour en savoir plus.
  appearance
});
```

## Divulguer Stripe à vos clients

Stripe recueille des informations sur les interactions des clients avec Elements afin de vous fournir des services, de prévenir la fraude et d’améliorer ses services. Cela inclut l’utilisation de cookies et d’adresses IP pour identifier les Elements qu’un client a vus au cours d’une même session Checkout. Vous êtes responsable de la divulgation et de l’obtention de tous les droits et consentements nécessaires pour que Stripe puisse utiliser les données à cette fin. Pour en savoir plus, visitez notre [Centre de confidentialité](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe).

## See also

- [Enregistrer le moyen de paiement d’un client lorsqu’il l’utilise pour un paiement](https://docs.stripe.com/payments/save-during-payment.md?payment-ui=embedded-components)