# Configurer de futurs paiements par carte
Utilisez la confirmation manuelle côté serveur ou présentez les moyens de paiement séparément.
# Une page hébergée par Stripe
> This is a Une page hébergée par Stripe for when platform is web and payment-ui is stripe-hosted. View the full page at https://docs.stripe.com/payments/save-and-reuse-cards-only?platform=web&payment-ui=stripe-hosted.
> Nous vous recommandons de suivre les instructions de notre guide [Configurer des paiements futurs](https://docs.stripe.com/payments/checkout/save-and-reuse.md). N’utilisez ce guide que si vous devez utiliser la confirmation manuelle côté serveur ou si votre intégration nécessite la présentation de moyens de paiement séparément. Si vous avez déjà intégré Elements, consultez le [Guide de migration du Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
Pour collecter les informations de paiement du client que vous pourrez réutiliser ultérieurement, utilisez le mode configuration de Checkout. Le mode configuration utilise l’[API Setup Intents](https://docs.stripe.com/api/setup_intents.md) pour créer des [moyens de paiement](https://docs.stripe.com/api/payment_methods.md).
Consultez notre [exemple fonctionnel complet sur GitHub](https://github.com/stripe-samples/checkout-remember-me-with-twilio-verify).
## Configurer Stripe [Côté serveur]
Tout d’abord, il vous faut un compte Stripe. [S’inscrire](https://dashboard.stripe.com/register).
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'
```
## Créer une session Checkout [Côté client] [Côté serveur]
Ajoutez à votre site Web un bouton de paiement qui appelle un endpoint côté serveur afin de créer une session Checkout.
```html
Checkout
```
Pour créer une Session en mode configuration, utilisez le paramètre `mode` avec la valeur `setup` lors de la création de la Session. Vous pouvez éventuellement spécifier le paramètre [client](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) pour associer automatiquement le moyen de paiement créé à un client existant. Checkout utilise par défaut les [moyens de paiement dynamiques](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md), ce qui nécessite de transmettre le paramètre [devise](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-currency) lorsque vous utilisez le mode `setup`.
Associez la variable de modèle `{CHECKOUT_SESSION_ID}` à l’URL `success_url` pour accéder à l’ID de session une fois que votre client termine sa session Checkout. Après avoir créé la session Checkout, redirigez votre client vers l’[URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) renvoyée dans la réponse.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d mode=setup \
-d currency=usd \
-d "customer={{CUSTOMER_ID}}" \
--data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
```
### Moyens de paiement
Par défaut, Stripe active les cartes bancaires et autres moyens de paiement courants. Vous avez la possibilité d’activer ou de désactiver des moyens de paiement directement depuis le [Dashboard Stripe](https://dashboard.stripe.com/settings/payment_methods). Dans Checkout, Stripe évalue la devise et les restrictions éventuelles, puis présente dynamiquement au client les moyens de paiement pris en charge.
Pour visualiser l’affichage des moyens de paiement pour les clients, saisissez un ID de transaction ou définissez le montant et la devise d’une commande dans le Dashboard.
Vous pouvez activer Apple Pay et Google Pay dans vos [paramètres des moyens de paiement](https://dashboard.stripe.com/settings/payment_methods). Par défaut, Apple Pay est activé et Google Pay est désactivé. Cependant, dans certains cas, Stripe les filtre même lorsqu’ils sont activés. Nous filtrons Google Pay si vous [activez les taxes automatiques](https://docs.stripe.com/tax/checkout.md) sans collecter d’adresse de livraison.
Aucune modification de l’intégration n’est requise pour activer Apple Pay ou Google Pay dans les pages hébergées par Stripe de Checkout. Stripe gère ces paiements de la même manière que les autres paiements par carte bancaire.
## Récupérer la session Checkout [Côté serveur]
Une fois que votre client a terminé sa session Checkout, vous devez récupérer l’objet session. Il y a deux façons de procéder :
- **De manière asynchrone** : en traitant les *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) `checkout.session.completed`, qui contiennent un objet session. En savoir plus sur la [configuration des webhooks](https://docs.stripe.com/webhooks.md).
- **De manière synchrone** : obtenez l’ID de session à partir de l’URL `success_url` lorsqu’un utilisateur est redirigé vers votre site. Utilisez l’ID de session pour [récupérer](https://docs.stripe.com/api/checkout/sessions/retrieve.md) l’objet de session.
```curl
curl https://api.stripe.com/v1/checkout/sessions/cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k \
-u "<>:"
```
Le choix entre ces deux méthodes dépend de votre tolérance aux abandons de paiement. En effet, il peut arriver que vos clients n’arrivent pas à l’URL `success_url` après la réussite d’un paiement. Ils peuvent par exemple fermer l’onglet de leur navigateur avant d’être correctement redirigés. Si votre intégration traite les webhooks, elle ne sera pas exposée à ce type d’abandon de paiement.
Après avoir récupéré l’objet session, obtenez la valeur de la clé `setup_intent`, qui correspond à l’ID du SetupIntent créé lors de la session Checkout. Un [SetupIntent](https://docs.stripe.com/payments/setup-intents.md) est un objet permettant de configurer les coordonnées de compte bancaire de votre client en vue de paiements futurs.
Exemple de charge utile `checkout.session.completed` :
```json
{
"id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
"object": "event",
"api_version": "2019-03-14",
"created": 1561420781,
"data": {
"object": {
"id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
"object": "checkout.session",
"billing_address_collection": null,
"client_reference_id": null,
"customer": "",
"customer_email": null,
"display_items": [],
"mode": "setup","setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM",
"submit_type": null,
"subscription": null,
"success_url": "https://example.com/success"
}
},
"livemode": false,
"pending_webhooks": 1,
"request": {
"id": null,
"idempotency_key": null
},
"type": "checkout.session.completed"
}
```
Prenez note de l’ID du `setup_intent` pour la prochaine étape.
## Récupérer le SetupIntent [Côté serveur]
À l’aide de l’ID de `setup_intent`, [récupérez](https://docs.stripe.com/api/setup_intents/retrieve.md) l’objet SetupIntent. L’objet renvoyé contient un ID de `payment_method` que vous pouvez associer à un client à l’étape suivante.
```curl
curl https://api.stripe.com/v1/setup_intents/seti_1EzVO3HssDVaQm2PJjXHmLlM \
-u "<>:"
```
> Si vous récupérez ces informations de manière synchrone auprès de l’API Stripe (et non en traitant des webhooks), vous pouvez combiner cette étape-ci à l’étape précédente en [développant](https://docs.stripe.com/api/expanding_objects.md) l’objet SetupIntent dans votre requête au endpoint /v1/checkout/session. De cette manière, vous n’avez pas besoin d’effectuer deux requêtes réseau différentes pour accéder à l’ID du PaymentMethod qui vient d’être créé.
## Débiter ultérieurement le moyen de paiement enregistré [Côté serveur]
Si vous n’avez pas renseigné de client existant à la création de la session Checkout, utilisez l’ID de PaymentMethod pour [associer](https://docs.stripe.com/api/payment_methods/attach.md) l’objet *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) à un *client* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Une fois cette opération effectuée, vous pouvez effectuer un *paiement hors session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) à l’aide d’un [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method) :
- Définissez [customer](https://docs.stripe.com/api.md#create_payment_intent-customer) sur l’ID du client et [payment_method](https://docs.stripe.com/api.md#create_payment_intent-payment_method) sur l’ID du PaymentMethod.
- Définissez l’attribut [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) sur `true` pour indiquer que le client ne se trouve pas dans votre tunnel de paiement lors d’une tentative de paiement, et qu’il ne peut donc pas répondre à une demande d’authentification effectuée par un partenaire, comme un émetteur de cartes, une banque ou un autre établissement de paiement. Si un partenaire demande une authentification dans le tunnel de paiement, Stripe demande une exemption en s’appuyant sur les informations utilisée par le client *pendant une session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) précédente. Si les conditions d’exemption ne sont pas remplies, le PaymentIntent peut renvoyer une erreur.
- Définissez la propriété [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) du PaymentIntent sur la valeur `true`, ce qui aura pour effet de générer immédiatement une confirmation lorsque vous créez le PaymentIntent.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-d amount=1099 \
-d currency=usd \
-d "customer={{CUSTOMER_ID}}" \
-d "payment_method={{PAYMENTMETHOD_ID}}" \
-d off_session=true \
-d confirm=true
```
Lorsqu’une tentative de paiement échoue, la requête échoue également avec un code d’état HTTP 402. L’état du PaymentIntent est *requires\_payment\_method* (This status appears as "requires_source" in API versions before 2019-02-11). Vous devez inviter votre client à revenir dans votre application (par e-mail ou par une notification dans l’application par exemple) et orientez votre client vers une nouvelle session Checkout pour sélectionner un autre moyen de paiement.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-d "customer={{CUSTOMER_ID}}" \
-d "line_items[0][price_data][currency]=usd" \
-d "line_items[0][price_data][product_data][name]=T-shirt" \
-d "line_items[0][price_data][unit_amount]=1099" \
-d "line_items[0][quantity]=1" \
-d mode=payment \
--data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
```
# Intégration avancée
> This is a Intégration avancée for when platform is web and payment-ui is direct-api. View the full page at https://docs.stripe.com/payments/save-and-reuse-cards-only?platform=web&payment-ui=direct-api.
> Nous vous recommandons de suivre le guide consacré à la [configuration de paiements futurs](https://docs.stripe.com/payments/save-and-reuse.md), mais seulement si vous devez exécuter une confirmation manuelle côté serveur, ou si votre intégration vous oblige à présenter les moyens de paiement dans une étape distincte. Si vous avez déjà intégré Elements, consultez le [guide de migration du composant Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
L’[API Setup Intents](https://docs.stripe.com/api/setup_intents.md) vous permet d’enregistrer la carte d’un client sans paiement initial. Cette fonction est utile si vous souhaitez configurer des paiements dès l’inscription de vos clients afin de les débiter plus tard, lorsqu’ils sont hors ligne.
Utilisez cette intégration pour configurer des paiements récurrents ou pour créer des paiements ponctuels dont le montant doit être déterminé ultérieurement, généralement après réception du service par votre client.
## Configurer Stripe [Côté serveur]
Utilisez nos bibliothèques officielles pour accéder à l’API Stripe à partir de 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'
```
## Créer un objet Customer avant la configuration [Côté serveur]
Pour configurer une carte bancaire en vue de paiements futurs, vous devez l’associer à un *client* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Lorsque votre client ouvre un compte chez vous, créez un objet Customer, qui permet de réutiliser des moyens de paiement et d’assurer le suivi de plusieurs paiements.
> #### Utiliser l’API Accounts v2 pour représenter des clients
>
> Si votre intégration utilise des [Accounts configurés par le client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), remplacez les références `Customer` et événement dans les exemples de code par les références équivalentes de l’API Accounts v2. Pour plus d’informations, consultez la page [Représenter des clients avec des objets Account](https://docs.stripe.com/connect/use-accounts-as-customers.md).
```curl
curl https://api.stripe.com/v1/customers \
-u "<>:" \
-d "name=Jenny Rosen" \
--data-urlencode "email=jennyrosen@example.com"
```
Lorsque la création aboutit, l’objet [Customer](https://docs.stripe.com/api/customers/object.md) est renvoyé. Vous pouvez l’examiner pour identifier l’`id` du client et stocker cette valeur dans votre base de données pour la récupérer ultérieurement.
Vous pouvez trouver ces clients sur la page [Clients](https://dashboard.stripe.com/customers) du Dashboard.
## Créer un SetupIntent [Côté serveur]
Un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) est un objet qui représente votre intention de configurer la carte d’un client pour encaisser de futurs paiements.
L’objet `SetupIntent` contient la [clé secrète du client](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret), une clé unique que vous devez transmettre à Stripe.js côté client afin de collecter les informations de carte. La clé secrète du client vous permet d’effectuer certaines actions côté client, comme confirmer la configuration et modifier des moyens de paiement, tout en masquant les informations sensibles, notamment le paramètre `customer`. Vous pouvez utiliser la clé secrète du client pour valider et authentifier des informations de carte à l’aide des réseaux de cartes de crédit. La clé secrète du client est confidentielle : ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne la dévoilez à personne d’autre que votre client.
Si votre application fait appel au rendu côté serveur, utilisez votre framework de modèle pour intégrer la clé secrète du client dans la page à l’aide d’un [attribut de données](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) ou d’un élément HTML masqué.
#### curl
```bash
curl https://api.stripe.com/v1/setup_intents \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}"
```
Si vous prévoyez d’utiliser la carte pour des paiements futurs uniquement lorsque votre client est présent dans le tunnel de paiement, configurez le paramètre [utilisation](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-usage) sur la valeur *on\_session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) afin d’optimiser votre taux d’autorisation.
## Collecter les informations de carte bancaire [Côté client]
L’*API Setup Intents* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method) est entièrement intégrée à [Stripe.js](https://docs.stripe.com/payments/elements.md), ce qui vous permet d’utiliser la bibliothèque d’interface utilisateur Elements pour collecter de manière sécurisée les informations de carte côté client.
> Lorsque vous enregistrez des informations de carte bancaire pour effectuer ultérieurement des *paiements hors session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information), [demandez au client l’autorisation d’enregistrer sa carte](https://docs.stripe.com/strong-customer-authentication.md#sca-enforcement). Ceci est particulièrement important en Europe, car cette région applique une réglementation particulière sur la réutilisation des cartes. Pour cela, incluez dans votre tunnel de paiement un texte expliquant à l’utilisateur comment vous comptez utiliser sa carte.
#### HTML + JS
Pour commencer à utiliser Elements, incluez le script suivant dans votre page de paiement. Chargez toujours Stripe.js directement à partir de js.stripe.com pour maintenir votre conformité PCI. Vous ne devez pas inclure le script dans une offre ni en héberger de copie.
```html
```
Pour tirer au mieux parti de la [fonctionnalité avancée de lutte contre la fraude](https://docs.stripe.com/radar.md) de Stripe, ajoutez ce script à chaque page de votre site, et pas uniquement à celle dédiée au paiement. Ajouter le script à chaque page [permet à Stripe de détecter tout comportement suspect](https://docs.stripe.com/disputes/prevention/advanced-fraud-detection.md) susceptible d’indiquer une fraude lorsque les utilisateurs consultent votre site Web.
### Ajouter Elements à votre page
Créez ensuite une instance de l’[objet Stripe](https://docs.stripe.com/js.md#stripe-function) en indiquant comme premier paramètre votre [clé API](https://docs.stripe.com/keys.md) publiable. Puis, créez une instance de [l’objet Elements](https://docs.stripe.com/js.md#stripe-elements) et utilisez-la pour intégrer un Element `card` au DOM.
Le composant Element `card` simplifie le formulaire de paiement et réduit le nombre de champs requis en insérant un champ de saisie flexible unique, qui recueille toutes les informations de carte et de facturation nécessaires, de manière sécurisée. Vous pouvez également combiner les composants Elements `cardNumber`, `cardExpiry` et `cardCvc` pour créer un formulaire de carte bancaire flexible et multi-saisie.
Consultez les [exemples de formulaires de paiement](https://stripe.com/payments/elements/examples) créés avec Elements sur GitHub.
> Recueillez toujours un numéro de code postal afin d’améliorer vos taux d’acceptation des cartes bancaires et de réduire la fraude.
>
> Le [composant Card Element à une seule ligne](https://docs.stripe.com/js/element/other_element?type=card) recueille automatiquement le code postal du client et l’envoie à Stripe. Si vous créez votre formulaire de paiement avec des Elements fractionnés ([Numéro de carte](https://docs.stripe.com/js/element/other_element?type=cardNumber), [Expiration](https://docs.stripe.com/js/element/other_element?type=cardExpiry), [CVC](https://docs.stripe.com/js/element/other_element?type=cardCvc), ajoutez un champ de saisie distinct pour le code postal du client.
```javascript
const stripe = Stripe('<>');
const elements = stripe.elements();
const cardElement = elements.create('card');
cardElement.mount('#card-element');
```
Un composant Element contient une balise iframe qui envoie de manière sécurisée les informations de paiement à Stripe par une connexion HTTPS. Pour que votre intégration fonctionne, l’adresse de votre page de règlement doit aussi commencer par https:// au lieu de http://.
Vous pouvez tester votre intégration sans utiliser le protocole HTTPS. [Activez-le](https://docs.stripe.com/security/guide.md#tls) au moment d’accepter des paiements en mode production.
### Confirmer le SetupIntent
Pour terminer la configuration, récupérez la clé secrète du client depuis le SetupIntent créé au cours de l’étape précédente et utilisez [stripe.confirmCardSetup](https://docs.stripe.com/js/setup_intents/confirm_card_setup) ainsi que le composant Card Element. Une fois la configuration terminée, la valeur de la propriété `status` du SetupIntent renvoyée est `succeeded`.
```javascript
const cardholderName = document.getElementById('cardholder-name');
const setupForm = document.getElementById('setup-form');
const clientSecret = setupForm.dataset.secret;
setupForm.addEventListener('submit', async (ev) => {
ev.preventDefault();
const {setupIntent, error} = await stripe.confirmCardSetup(
clientSecret,
{
payment_method: {
card: cardElement,
billing_details: {
name: cardholderName.value,
},
},
}
);
if (error) {
// Display error.message in your UI.
} else {
if (setupIntent.status === 'succeeded') {
// The setup has succeeded. Display a success message. Send
// setupIntent.payment_method to your server to save the card to a Customer
}
}
});
```
#### React
#### npm
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) à partir du registre public npm.
```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```
#### umd
Nous fournissons également une version UMD pour les sites qui n’utilisent pas npm ni de modules.
Incluez le script Stripe.js, qui exporte une fonction `Stripe` globale, ainsi que la version UMD de React Stripe.js, qui exporte un objet `ReactStripe` global. Chargez toujours le script Stripe.js directement à partir de **js.stripe.com** pour maintenir votre conformité PCI. Vous ne devez pas inclure le script dans un lot ni en héberger de copie.
```html
```
> La [démo de CodeSandbox](https://codesandbox.io/s/react-stripe-official-q1loc?fontsize=14&hidenavigation=1&theme=dark) vous permet de tester React Stripe.js sans créer de projet.
### Ajoutez Stripe.js et Elements à votre page
Pour utiliser les composants Element, enveloppez votre composant de page de paiement dans un [fournisseur Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Appelez `loadStripe` avec votre clé publiable et transmettez l’élément `Promise` renvoyé au fournisseur `Elements`.
```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';
import CardSetupForm from './CardSetupForm';
// Make sure to call `loadStripe` outside of a component's render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>');
function App() {
return (
);
};
ReactDOM.render(, document.getElementById('root'));
```
### Ajouter et configurer un composant CardElement
Utilisez des composants Element individuels, tels que `CardElement`, pour créer votre formulaire.
#### JSX
```jsx
/**
* Use the CSS tab above to style your Element's container.
*/
import React from 'react';
import {CardElement} from '@stripe/react-stripe-js';
import './Styles.css'
const CARD_ELEMENT_OPTIONS = {
style: {
base: {
color: "#32325d",
fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
fontSmoothing: "antialiased",
fontSize: "16px",
"::placeholder": {
color: "#aab7c4",
},
},
invalid: {
color: "#fa755a",
iconColor: "#fa755a",
},
},
};
function CardSection() {
return (
);
};
export default CardSection;
```
Les composants Element sont entièrement personnalisables. Vous pouvez [personnaliser les composants Element](https://docs.stripe.com/js/elements_object/create_element?type=card#elements_create-options) pour qu’ils s’intègrent visuellement à votre site afin de fournir un paiement uniforme à vos clients. Il est également possible de personnaliser différents états de saisie, par exemple lorsque le composant Element est sélectionné.
Le composant Element `CardElement` simplifie le formulaire et réduit le nombre de champs requis en insérant un champ de saisie flexible et unique qui collecte tous les détails de carte et de facturation nécessaires de manière sécurisée. Vous pouvez également combiner des composants `CardNumberElement`, `CardExpiryElement`, et `CardCvcElement` pour un formulaire flexible et multi-saisie de carte bancaire.
> Recueillez toujours un numéro de code postal afin d’améliorer vos taux d’acceptation des cartes bancaires et de réduire la fraude.
>
> Le [composant Card Element à une seule ligne](https://docs.stripe.com/js/element/other_element?type=card) recueille automatiquement le code postal du client et l’envoie à Stripe. Si vous créez votre formulaire de paiement avec des Elements fractionnés ([Numéro de carte](https://docs.stripe.com/js/element/other_element?type=cardNumber), [Expiration](https://docs.stripe.com/js/element/other_element?type=cardExpiry), [CVC](https://docs.stripe.com/js/element/other_element?type=cardCvc), ajoutez un champ de saisie distinct pour le code postal du client.
### Confirmer le SetupIntent
Pour terminer la configuration, récupérez la clé secrète du client depuis le SetupIntent créé au cours de l’[étape 3](https://docs.stripe.com/payments/save-and-reuse-cards-only.md#web-create-setup-intent) et utilisez [stripe.confirmCardSetup](https://docs.stripe.com/js/setup_intents/confirm_card_setup) ainsi que le composant Card Element. Une fois la configuration terminée, la valeur de la propriété `status` du SetupIntent renvoyée est `succeeded`.
Pour appeler `stripe.confirmCardSetup` depuis votre composant de formulaire de paiement, utilisez les hooks [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) et [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook). Si vous préférez les composants de classe traditionnels aux hooks, vous pouvez utiliser un [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer).
#### Hooks
```jsx
import React from 'react';
import {useStripe, useElements, CardElement} from '@stripe/react-stripe-js';
import CardSection from './CardSection';
export default function CardSetupForm() {
const stripe = useStripe();
const elements = useElements();
const handleSubmit = async (event) => {
// We don't want to let default form submission happen here,
// which would refresh the page.
event.preventDefault();
if (!stripe || !elements) {
// Stripe.js hasn't yet loaded.
// Make sure to disable form submission until Stripe.js has loaded.
return;
}
const result = await stripe.confirmCardSetup('{{CLIENT_SECRET}}', {
payment_method: {
card: elements.getElement(CardElement),
billing_details: {
name: 'Jenny Rosen',
},
}
});
if (result.error) {
// Display result.error.message in your UI.
} else {
// The setup has succeeded. Display a success message and send
// result.setupIntent.payment_method to your server to save the
// card to a Customer
}
};
return (
);
}
```
#### Composants de classe
```jsx
import React from 'react';
import {ElementsConsumer, CardElement} from '@stripe/react-stripe-js';
import CardSection from './CardSection';
class CardSetupForm extends React.Component {
handleSubmit = async (event) => {
// We don't want to let default form submission happen here,
// which would refresh the page.
event.preventDefault();
const {stripe, elements} = this.props;
if (!stripe || !elements) {
// Stripe.js hasn't yet loaded.
// Make sure to disable form submission until Stripe.js has loaded.
return;
}
const result = await stripe.confirmCardSetup('{{CLIENT_SECRET}}', {
payment_method: {
card: elements.getElement(CardElement),
billing_details: {
name: 'Jenny Rosen',
},
}
});
if (result.error) {
// Display result.error.message in your UI.
} else {
// The setup has succeeded. Display a success message and send
// result.setupIntent.payment_method to your server to save the
// card to a Customer
}
};
render() {
return (
);
}
}
export default function InjectedCardSetupForm() {
return (
{({stripe, elements}) => (
)}
);
}
```
> L’exécution de `stripe.confirmCardSetup` peut prendre plusieurs secondes. Pendant ce temps, désactivez le renvoi de votre formulaire et affichez un indicateur d’attente. Si vous recevez une erreur, montrez-la au client, réactivez le formulaire et masquez l’indicateur d’attente. Si le client doit effectuer des étapes supplémentaires pour finaliser le paiement, comme une authentification, Stripe.js le guide tout au long du processus.
La fonction SetupIntent vérifie que les informations de carte utilisées par votre client sont valides sur le réseau. Cependant, la vérification automatique n’est pas toujours effectuée. Pour plus d’informations à ce sujet, consultez la rubrique [Vérifier si une carte est valide sans la débiter](https://support.stripe.com/questions/check-if-a-card-is-valid-without-a-charge). De plus, ne conservez pas les SetupIntents à longue durée de vie et non traitées, car elles pourraient ne plus être valides lorsque vous appelez [stripe.confirmCardSetup](https://docs.stripe.com/js.md#stripe-confirm-card-setup).
Vous disposez désormais d’un flux permettant de recueillir les informations de carte et de gérer les éventuelles demandes d’authentification. Utilisez la carte de test `4000 0025 0000 3155`, ainsi qu’un CVC, un code postal et une date d’expiration postérieure à la date du jour pour tester le processus d’authentification.
Lors de l’enregistrement de cartes bancaires à débiter ultérieurement, il est important d’obtenir l’autorisation du client en amont. Ajoutez dans votre tunnel de paiement une mention précisant les conditions de paiement. Par exemple :
> J’autorise [nom de votre entreprise] à demander à l’émetteur de ma carte d’effectuer des paiements sur le compte bancaire de ma carte conformément au contrat qui nous lie.
Lorsque le SetupIntent aboutit, l’ID du *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) qui en résulte (dans `result.setupIntent.payment_method`) sera enregistré pour le *client* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) indiqué.
## Débiter ultérieurement la carte enregistrée [Côté serveur]
Lorsque vous êtes prêt à débiter votre client hors session, utilisez les identifiants Customer et PaymentMethod pour créer un PaymentIntent. Pour trouver une carte à débiter, [listez](https://docs.stripe.com/api/payment_methods/list.md) les PaymentMethods associés à votre Customer.
#### Accounts v2
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer_account={{CUSTOMERACCOUNT_ID}}" \
-d type=card
```
#### Customers v1
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer={{CUSTOMER_ID}}" \
-d type=card
```
Lorsque vous avez les identifiants Client et PaymentMethod, créez un PaymentIntent avec le montant et la devise du paiement. Réglez quelques autres paramètres pour effectuer un paiement hors session :
- Définissez [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) sur `true` pour indiquer que le client n’est pas dans votre tunnel de paiement lors de cette tentative de paiement. Dans ce cas, le PaymentIntent renvoie une erreur si une authentification est requise.
- Assignez la valeur `true` à la propriété [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) du PaymentIntent, ce qui aura pour effet de générer immédiatement une confirmation lors de la création du PaymentIntent.
- Renseignez l’ID du PaymentMethod dans [payment_method](https://docs.stripe.com/api.md#create_payment_intent-payment_method) et l’ID du client dans [customer](https://docs.stripe.com/api.md#create_payment_intent-customer).
#### curl
```bash
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-d amount=1099 \
-d currency=usd \-d customer="{{CUSTOMER_ID}}" \
-d payment_method="{{PAYMENT_METHOD_ID}}" \
-d off_session=true \
-d confirm=true
```
Lorsqu’une tentative de paiement échoue, la requête échoue également avec un code d’état HTTP 402. L’état de l’objet PaymentIntent est alors *requires\_payment\_method* (This status appears as "requires_source" in API versions before 2019-02-11). Vous devez inviter votre client à revenir dans votre application (par e-mail ou via une notification dans l’application par exemple) afin de terminer le paiement. Vérifiez le code d’[erreur](https://docs.stripe.com/api/errors/handling.md) généré par la bibliothèque d’API de Stripe ou le code [last_payment_error.decline_code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-decline_code) de l’objet PaymentIntent pour déterminer le motif du refus du paiement par l’émetteur de la carte.
Si le paiement a échoué en raison d’un code de refus de paiement [authentication_required](https://docs.stripe.com/declines/codes.md), utilisez la clé secrète du client et le [moyen de paiement](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-payment_method) de l’objet Paymentintent refusé avec la méthode confirmCardPayment pour permettre au client d’authentifier le paiement.
```javascript
// Pass the failed PaymentIntent to your client from your server
stripe.confirmCardPayment(intent.client_secret, {
payment_method: intent.last_payment_error.payment_method.id
}).then(function(result) {
if (result.error) {
// Show error to your customer
console.log(result.error.message);
} else {
if (result.paymentIntent.status === 'succeeded') {
// The payment is complete!
}
}
});
```
> `stripe.confirmCardPayment` peut prendre plusieurs secondes pour se terminer. Pendant ce temps, empêchez toute nouvelle soumission de votre formulaire et affichez un indicateur d’attente comme un spinner. Si vous recevez une erreur, affichez-la au client, réactivez le formulaire et masquez l’indicateur d’attente. Si le client doit effectuer des étapes supplémentaires pour finaliser le paiement, comme une authentification, Stripe.js le guide tout au long de ce processus.
Si le paiement a échoué pour d’autres raisons, par exemple parce que le solde de la carte est insuffisant, dirigez votre client vers une page de paiement sur laquelle il pourra saisir les informations d’une nouvelle carte. Vous pouvez ensuite réutiliser l’objet PaymentIntent existant pour réessayer le paiement avec les informations de la nouvelle carte.
## Tester l'intégration
À ce stade, vous devriez avoir une intégration qui :
1. Collecte les informations de carte bancaire sans débiter le client avec un SetupIntent
1. Débite la carte hors session et dispose d’un flux de récupération permettant de gérer les refus de paiement et les demandes d’authentification
Pour vérifier que votre intégration est prête, vous avez à votre disposition plusieurs cartes de test. Vous pouvez les utiliser en mode test avec n’importe quel CVC, code postal et date d’expiration non échue.
| Numéro | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | Transaction réussie et paiement effectué immédiatement. |
| 4000002500003155 | Authentification requise pour l’achat initial, mais la transaction réussit pour les paiements suivants (y compris ceux effectués hors session) dès l’instant que la carte bancaire est configurée avec `setup_future_usage`. |
| 4000002760003184 | Exige l’authentification pour l’achat initial, et la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `authentication_required`. |
| 4000008260003178 | Exige l’authentification pour l’achat initial, mais la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `insufficient_funds`. |
| 4000000000009995 | Échoue toujours (y compris pour l’achat initial) avec un code de refus de paiement `insufficient_funds`. |
Voir la liste complète des [cartes de test](https://docs.stripe.com/testing.md).
# iOS
> This is a iOS for when platform is ios. View the full page at https://docs.stripe.com/payments/save-and-reuse-cards-only?platform=ios.
> Nous vous recommandons de suivre les instructions de notre guide [Configurer des paiements futurs](https://docs.stripe.com/payments/mobile/set-up-future-payments.md). N’utilisez ce guide que si vous devez utiliser la confirmation manuelle côté serveur ou si votre intégration nécessite la présentation de moyens de paiement séparément. Si vous avez déjà intégré Elements, consultez le [Guide de migration du Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
L’[API Setup Intents](https://docs.stripe.com/api/setup_intents.md) vous permet d’enregistrer la carte d’un client sans paiement initial. Cette fonction est utile si vous souhaitez configurer des paiements dès l’inscription de vos clients afin de les débiter plus tard, lorsqu’ils sont hors ligne.
Utilisez cette intégration pour configurer des paiements récurrents ou pour créer des paiements ponctuels dont le montant doit être déterminé ultérieurement, généralement après réception du service par votre client.
> Les étapes de ce guide sont entièrement mises en œuvre sur GitHub. Clonez le [référentiel](https://github.com/stripe-samples/mobile-saving-card-without-payment) et suivez les [instructions](https://github.com/stripe-samples/mobile-saving-card-without-payment#how-to-run) pour exécuter l’application de démonstration.
## Configurer Stripe
Pour commencer, vous devez [créer un compte](https://dashboard.stripe.com/register) Stripe.
### Côté serveur
Pour cette intégration, votre serveur doit disposer de endpoints qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :
#### 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'
```
### Côté client
Le [SDK iOS de Stripe](https://github.com/stripe/stripe-ios) est disponible en open source et [fait l’objet d’une documentation complète](https://stripe.dev/stripe-ios/index.html). Il est également compatible avec les applications prenant en charge iOS 13 et les versions ultérieures.
#### Swift Package Manager
Pour installer le SDK, veuillez suivre les étapes ci-dessous :
1. Dans Xcode, sélectionnez **File** > **Add Package Dependencies…** puis saisissez `https://github.com/stripe/stripe-ios-spm` en tant qu’URL du référentiel.
1. Sélectionnez le dernier numéro de version, visible sur notre [page des versions](https://github.com/stripe/stripe-ios/releases).
1. Ajoutez le produit **StripePaymentsUI** à la [cible de votre application](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).
#### CocoaPods
1. Si vous ne l’avez pas encore fait, installez la version la plus récente de [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Si vous n’avez pas de fichier [Podfile](https://guides.cocoapods.org/syntax/podfile.html), exécutez la commande suivante pour en créer un :
```bash
pod init
```
1. Ajoutez cette ligne à votre `Podfile` :
```podfile
pod 'StripePaymentsUI'
```
1. Exécutez la commande suivante :
```bash
pod install
```
1. À partir de maintenant, n’oubliez pas d’utiliser le fichier .xcworkspace au lieu du fichier .xcodeproj pour ouvrir votre projet dans Xcode.
1. Pour mettre à jour ultérieurement le SDK vers la version la plus récente, il vous suffit d’exécuter :
```bash
pod update StripePaymentsUI
```
#### Carthage
1. Si vous ne l’avez pas encore fait, installez la version la plus récente de [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Ajoutez cette ligne à votre `Cartfile` :
```cartfile
github "stripe/stripe-ios"
```
1. Suivez les [instructions d’installation de Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Veillez à intégrer tous les cadres requis listés [ici](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking).
1. Pour mettre à jour ultérieurement le SDK vers la version la plus récente, exécutez la commande suivante :
```bash
carthage update stripe-ios --platform ios
```
#### Cadre manuel
1. Accédez à notre [page des versions GitHub](https://github.com/stripe/stripe-ios/releases/latest), puis téléchargez et décompressez **Stripe.xcframework.zip**.
1. Faites glisser **StripePaymentsUI.xcframework** vers la section **Embedded Binaries (Fichiers binaires incorporés)** des paramètres **General (Général)** de votre projet Xcode. Veillez à sélectionner **Copy items if needed (Copier les éléments si nécessaire)**.
1. Répétez l’étape 2 pour tous les cadres requis listés [ici](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking).
1. À l’avenir, pour mettre à jour vers la version la plus récente de notre SDK, répétez les étapes 1 à 3.
> Pour obtenir de plus amples informations sur la version la plus récente du SDK et ses versions antérieures, consultez la page des [versions](https://github.com/stripe/stripe-ios/releases) sur GitHub. Pour recevoir une notification lors de la publication d’une nouvelle version, [surveillez les versions](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) à partir du référentiel.
Configurez le SDK avec votre [clé publiable](https://dashboard.stripe.com/test/apikeys) Stripe au démarrage de votre application. Cela lui permet d’envoyer des requêtes à l’API Stripe.
#### Swift
```swift
import UIKitimportStripePaymentsUI
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<>"
// do any other necessary launch configuration
return true
}
}
```
> Utilisez vos [clés de test](https://docs.stripe.com/keys.md#obtain-api-keys) lors de vos activités de test et de développement et vos clés du [mode production](https://docs.stripe.com/keys.md#test-live-modes) pour la publication de votre application.
## Créer un objet Customer avant la configuration [Côté serveur]
Pour configurer une carte bancaire en vue de paiements futurs, vous devez l’associer à un *client* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Lorsque votre client ouvre un compte chez vous, créez un objet Customer, qui permet de réutiliser des moyens de paiement et d’assurer le suivi de plusieurs paiements.
> #### Utiliser l’API Accounts v2 pour représenter des clients
>
> Si votre intégration utilise des [Accounts configurés par le client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), remplacez les références `Customer` et événement dans les exemples de code par les références équivalentes de l’API Accounts v2. Pour plus d’informations, consultez la page [Représenter des clients avec des objets Account](https://docs.stripe.com/connect/use-accounts-as-customers.md).
```curl
curl https://api.stripe.com/v1/customers \
-u "<>:" \
-d "name=Jenny Rosen" \
--data-urlencode "email=jennyrosen@example.com"
```
Lorsque la création aboutit, l’objet [Customer](https://docs.stripe.com/api/customers/object.md) est renvoyé. Vous pouvez l’examiner pour identifier l’`id` du client et stocker cette valeur dans votre base de données pour la récupérer ultérieurement.
Vous pouvez trouver ces clients sur la page [Clients](https://dashboard.stripe.com/customers) du Dashboard.
## Créer un SetupIntent [Côté serveur]
Un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) est un objet qui représente votre intention de configurer un moyen de paiement pour encaisser de futurs paiements.
Cet objet contient la [clé secrète du client](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret), une clé unique que vous devez transmettre à votre application. Cette clé vous permet de réaliser diverses actions sur le client, comme confirmer la configuration et mettre à jour les informations du moyen de paiement, tout en masquant des données sensibles comme l’attribut `customer`. Vous pouvez également utiliser la clé secrète du client pour valider et authentifier les informations de carte par l’intermédiaire des réseaux de cartes de crédit. La clé secrète du client est une information sensible : ne la consignez pas, ne l’intégrez pas dans une URL et ne l’exposez à personne d’autre qu’au client.
### Côté serveur
Sur votre serveur, créez un endpoint qui crée lui-même un SetupIntent et renvoie la clé secrète du client à votre application.
#### curl
```bash
curl https://api.stripe.com/v1/setup_intents/ \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}"
```
Si vous prévoyez d’utiliser la carte pour des paiements futurs uniquement lorsque votre client est présent dans le tunnel de paiement, configurez le paramètre [utilisation](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-usage) sur la valeur *on\_session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) afin d’optimiser votre taux d’autorisation.
### Côté client
Côté client, demandez un SetupIntent auprès de votre serveur.
#### Swift
```swift
import StripePaymentsUI
class CheckoutViewController: UIViewController {
var setupIntentClientSecret: String?
func startCheckout() {
// Request a SetupIntent from your server and store its client secret
// Click View full sample to see a complete implementation
}
}
```
## Collecter les informations de carte bancaire [Côté client]
Lorsque le client envoie le formulaire de paiement, collectez ses informations de carte bancaire à l’aide de [STPPaymentCardTextField](https://stripe.dev/stripe-ios/stripe-payments-ui/Classes/STPPaymentCardTextField.html), un composant d’interface utilisateur prêt à l’emploi fourni par le SDK et qui recueille le numéro de carte, la date d’expiration, le CVC et le code postal.
> Lorsque vous enregistrez des informations de carte bancaire pour effectuer ultérieurement des paiements hors session, [demandez au client l’autorisation d’enregistrer sa carte](https://docs.stripe.com/strong-customer-authentication.md#sca-enforcement). Ceci est particulièrement important en Europe, car cette région applique une réglementation particulière sur la réutilisation des cartes. Pour cela, incluez dans votre tunnel de paiement un texte expliquant à l’utilisateur comment vous comptez utiliser sa carte.
Transmettez les informations collectées dans de nouvelles instances [STPPaymentMethodCardParams](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentMethodCardParams.html) et [STPPaymentMethodBillingDetails](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentMethodBillingDetails.html) afin de créer une instance `STPSetupIntentConfirmParams`.
#### Swift
```swift
class CheckoutViewController: UIViewController {
lazy var cardTextField: STPPaymentCardTextField = {
let cardTextField = STPPaymentCardTextField()
return cardTextField
}()
func pay() {
// Collect card details
let paymentMethodParams = cardTextField.paymentMethodParams
// Create SetupIntent confirm parameters with the above
let setupIntentParams = STPSetupIntentConfirmParams(clientSecret: setupIntentClientSecret)
setupIntentParams.paymentMethodParams = paymentMethodParams
// ...continued in next step
}
}
```
Pour terminer la configuration, transmettez l’objet `STPSetupIntentConfirmParams` à la méthode [confirmSetupIntent](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentHandler.html#/c:objc\(cs\)STPPaymentHandler\(im\)confirmSetupIntent:withAuthenticationContext:completion:) sur `STPPaymentHandler` [sharedManager](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentHandler.html#/c:objc\(cs\)STPPaymentHandler\(cm\)sharedHandler).
Si le client doit effectuer des actions supplémentaires, comme une authentification, pour finaliser le paiement, `STPPaymentHandler` lui présente des contrôleurs d’affichage à l’aide du [STPAuthenticationContext](https://stripe.dev/stripe-ios/stripe-payments/Protocols/STPAuthenticationContext.html) transmis et le guide tout au long du processus. Pour en savoir plus, consultez notre documentation relative à la [prise en charge de l’authentification 3D Secure sur iOS](https://docs.stripe.com/payments/3d-secure.md?platform=ios).
#### Swift
```swift
class CheckoutViewController: UIViewController {
// ...
func pay() {
// ...
// Complete the setup
let paymentHandler = STPPaymentHandler.shared()
paymentHandler.confirmSetupIntent(withParams: setupIntentParams, authenticationContext: self) { status, setupIntent, error in
switch (status) {
case .failed:
// Setup failed
break
case .canceled:
// Setup canceled
break
case .succeeded:
// Setup succeeded
break
@unknown default:
fatalError()
break
}
}
}
}
extension CheckoutViewController: STPAuthenticationContext {
func authenticationPresentingViewController() -> UIViewController {
return self
}
}
```
La fonction SetupIntent vérifie que les informations de carte utilisées par votre client sont valides sur le réseau. Cependant, la vérification automatique n’est pas toujours effectuée. Pour plus d’informations à ce sujet, consultez la rubrique [Vérifier si une carte est valide sans la débiter](https://support.stripe.com/questions/check-if-a-card-is-valid-without-a-charge). De plus, ne conservez pas les SetupIntents à longue durée de vie et non traitées, car elles pourraient ne plus être valides lorsque vous appelez `confirmSetupIntent`.
Vous disposez désormais d’un flux permettant de recueillir les informations de carte et de gérer les éventuelles demandes d’authentification. Utilisez la carte de test `4000 0025 0000 3155`, ainsi qu’un CVC, un code postal et une date d’expiration postérieure à la date du jour pour tester le processus d’authentification.
Lorsque le SetupIntent réussit, l’ID PaymentMethod généré (dans `setupIntent.paymentMethodID`) est enregistré dans l’objet Customer fourni.
## Débiter ultérieurement la carte enregistrée [Côté serveur]
Lorsque vous êtes prêt à débiter votre client hors session, utilisez les identifiants Customer et PaymentMethod pour créer un PaymentIntent. Pour trouver une carte à débiter, [listez](https://docs.stripe.com/api/payment_methods/list.md) les PaymentMethods associés à votre Customer.
#### Accounts v2
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer_account={{CUSTOMERACCOUNT_ID}}" \
-d type=card
```
#### Customers v1
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer={{CUSTOMER_ID}}" \
-d type=card
```
Lorsque vous avez les identifiants Client et PaymentMethod, créez un PaymentIntent avec le montant et la devise du paiement. Réglez quelques autres paramètres pour effectuer un paiement hors session :
- Définissez [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) sur `true` pour indiquer que le client n’est pas dans votre tunnel de paiement lors de cette tentative de paiement. Dans ce cas, le PaymentIntent renvoie une erreur si une authentification est requise.
- Assignez la valeur `true` à la propriété [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) du PaymentIntent, ce qui aura pour effet de générer immédiatement une confirmation lors de la création du PaymentIntent.
- Renseignez l’ID du PaymentMethod dans [payment_method](https://docs.stripe.com/api.md#create_payment_intent-payment_method) et l’ID du client dans [customer](https://docs.stripe.com/api.md#create_payment_intent-customer).
#### curl
```bash
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-d amount=1099 \
-d currency=usd \-d customer="{{CUSTOMER_ID}}" \
-d payment_method="{{PAYMENT_METHOD_ID}}" \
-d off_session=true \
-d confirm=true
```
Inspectez la [propriété d’état](https://docs.stripe.com/payments/paymentintents/lifecycle.md) du PaymentIntent pour confirmer que le paiement a été effectué avec succès. Si la tentative de paiement a réussi, l’état du PaymentIntent est `succeeded` et que le ** (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) est terminé.
### Démarrer un flux de récupération
Si le PaymentIntent a un autre état, le paiement n’a pas abouti et la requête échoue. Informez votre client qu’il doit revenir dans votre application (par exemple par e-mail, SMS ou notification push) pour finaliser le paiement. Nous vous recommandons de mettre en place un flux de récupération dans votre application qui explique pourquoi le paiement a initialement échoué et permet à votre client de réessayer.
Dans votre flux de récupération, récupérez l’objet PaymentIntent via sa *clé secrète du client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)). Vérifiez la valeur [lastPaymentError](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentIntent.html#/c:@M@StripePayments@objc\(cs\)STPPaymentIntent\(py\)lastPaymentError) du PaymentIntent pour découvrir pourquoi la tentative de paiement a échoué. Pour les erreurs de carte, vous pouvez montrer à l’utilisateur le dernier [message](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-message) d’erreur du paiement. Sinon, vous pouvez afficher un message d’échec générique.
#### Swift
```swift
func startRecoveryFlow(clientSecret: String) {
// Retrieve the PaymentIntent
STPAPIClient.shared.retrievePaymentIntent(withClientSecret: clientSecret) { (paymentIntent, error) in
guard error == nil, let lastPaymentError = paymentIntent?.lastPaymentError else {
// Handle error (for example, allow your customer to retry)
return
}
var failureReason = "Payment failed, try again." // Default to a generic error message
if lastPaymentError.type == .card {
failureReason = lastPaymentError.message
}
// Display the failure reason to your customer
// ...
}
}
```
### Permettre au client de réessayer
Votre flux de récupération doit permettre au client de [mettre à jour](https://docs.stripe.com/api/payment_methods/update.md) ou [supprimer](https://docs.stripe.com/api/payment_methods/detach.md) sa carte enregistrée et de réessayer le paiement. Suivez les mêmes étapes que pour l’acceptation du paiement d’origine, à une différence près : *confirmez* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) l’objet PaymentIntent d’origine qui a échoué en réutilisant sa [clé secrète de client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) plutôt que d’en créer une nouvelle.
Si le paiement échoue parce qu’il nécessite une authentification, réessayez avec l’objet *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) existant plutôt que d’en créer un nouveau.
#### Swift
```swift
func startRecoveryFlow(clientSecret: String) {
// ...continued from previous step
// Reuse the existing PaymentIntent's client secret
let paymentIntentParams = STPPaymentIntentParams(clientSecret: clientSecret)
if paymentIntent.lastPaymentError.code == STPPaymentIntentLastPaymentErrorCodeAuthenticationFailure {
// Payment failed because authentication is required, reuse the PaymentMethod
paymentIntentParams.paymentMethodId = paymentIntent.lastPaymentError.paymentMethod.stripeId
} else {
// Collect a new PaymentMethod from the customer...
}
// Submit the payment...
}
```
## Tester l'intégration
À ce stade, vous devriez avoir une intégration qui :
1. Collecte les informations de carte bancaire sans débiter le client avec un SetupIntent
1. Débite la carte hors session et dispose d’un flux de récupération permettant de gérer les refus de paiement et les demandes d’authentification
Pour vérifier que votre intégration est prête, vous avez à votre disposition plusieurs cartes de test. Vous pouvez les utiliser en mode test avec n’importe quel CVC, code postal et date d’expiration non échue.
| Numéro | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | Transaction réussie et paiement effectué immédiatement. |
| 4000002500003155 | Authentification requise pour l’achat initial, mais la transaction réussit pour les paiements suivants (y compris ceux effectués hors session) dès l’instant que la carte bancaire est configurée avec `setup_future_usage`. |
| 4000002760003184 | Exige l’authentification pour l’achat initial, et la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `authentication_required`. |
| 4000008260003178 | Exige l’authentification pour l’achat initial, mais la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `insufficient_funds`. |
| 4000000000009995 | Échoue toujours (y compris pour l’achat initial) avec un code de refus de paiement `insufficient_funds`. |
Voir la liste complète des [cartes de test](https://docs.stripe.com/testing.md).
# Android
> This is a Android for when platform is android. View the full page at https://docs.stripe.com/payments/save-and-reuse-cards-only?platform=android.
> Nous vous recommandons de suivre les instructions de notre guide [Configurer des paiements futurs](https://docs.stripe.com/payments/mobile/set-up-future-payments.md). N’utilisez ce guide que si vous devez utiliser la confirmation manuelle côté serveur ou si votre intégration nécessite la présentation de moyens de paiement séparément. Si vous avez déjà intégré Elements, consultez le [Guide de migration du Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
L’[API Setup Intents](https://docs.stripe.com/api/setup_intents.md) vous permet d’enregistrer la carte d’un client sans paiement initial. Cette fonction est utile si vous souhaitez configurer des paiements dès l’inscription de vos clients afin de les débiter plus tard, lorsqu’ils sont hors ligne.
Utilisez cette intégration pour configurer des paiements récurrents ou pour créer des paiements ponctuels dont le montant doit être déterminé ultérieurement, généralement après réception du service par votre client.
> Les étapes de ce guide sont entièrement mises en œuvre sur GitHub. Clonez le [référentiel](https://github.com/stripe-samples/mobile-saving-card-without-payment) et suivez les [instructions](https://github.com/stripe-samples/mobile-saving-card-without-payment#how-to-run) pour exécuter l’application de démonstration.
## Configurer Stripe
Pour commencer, vous devez [créer un compte](https://dashboard.stripe.com/register) Stripe.
### Côté serveur
Pour cette intégration, votre serveur doit disposer de endpoints qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :
#### 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'
```
### Côté client
Le [SDK Stripe Android](https://github.com/stripe/stripe-android) est disponible en open source et [fait l’objet d’une documentation complète](https://stripe.dev/stripe-android/).
Pour installer le SDK, ajoutez `stripe-android` au bloc `dependencies` de votre fichier [app/build.gradle](https://developer.android.com/studio/build/dependencies) :
#### Kotlin
```kotlin
plugins {
id("com.android.application")
}
android { ... }
dependencies {
// ...
// Stripe Android SDK
implementation("com.stripe:stripe-android:23.3.0")
// Include the financial connections SDK to support US bank account as a payment method
implementation("com.stripe:financial-connections:23.3.0")
}
```
> Pour obtenir de plus amples informations sur la version la plus récente du SDK et ses versions antérieures, consultez la page des [versions](https://github.com/stripe/stripe-android/releases) sur GitHub. Pour savoir quand une nouvelle version est disponible, [surveillez les versions du référentiel](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).
Configurez le SDK avec votre [clé publique](https://dashboard.stripe.com/apikeys) Stripe de façon à ce qu’il puisse envoyer des requêtes à l’API Stripe, par exemple à la sous-classe `Application` :
#### Kotlin
```kotlin
import com.stripe.android.PaymentConfiguration
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
PaymentConfiguration.init(
applicationContext,
"<>"
)
}
}
```
> Utilisez vos [clés de test](https://docs.stripe.com/keys.md#obtain-api-keys) lors de vos activités de test et de développement et vos clés du [mode production](https://docs.stripe.com/keys.md#test-live-modes) pour la publication de votre application.
## Créer un objet Customer avant la configuration [Côté serveur]
Pour configurer une carte bancaire en vue de paiements futurs, vous devez l’associer à un *client* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Lorsque votre client ouvre un compte chez vous, créez un objet Customer, qui permet de réutiliser des moyens de paiement et d’assurer le suivi de plusieurs paiements.
> #### Utiliser l’API Accounts v2 pour représenter des clients
>
> Si votre intégration utilise des [Accounts configurés par le client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), remplacez les références `Customer` et événement dans les exemples de code par les références équivalentes de l’API Accounts v2. Pour plus d’informations, consultez la page [Représenter des clients avec des objets Account](https://docs.stripe.com/connect/use-accounts-as-customers.md).
```curl
curl https://api.stripe.com/v1/customers \
-u "<>:" \
-d "name=Jenny Rosen" \
--data-urlencode "email=jennyrosen@example.com"
```
Lorsque la création aboutit, l’objet [Customer](https://docs.stripe.com/api/customers/object.md) est renvoyé. Vous pouvez l’examiner pour identifier l’`id` du client et stocker cette valeur dans votre base de données pour la récupérer ultérieurement.
Vous pouvez trouver ces clients sur la page [Clients](https://dashboard.stripe.com/customers) du Dashboard.
## Créer un SetupIntent [Côté serveur]
Un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) est un objet qui représente votre intention de configurer un moyen de paiement pour encaisser de futurs paiements.
Cet objet contient la [clé secrète du client](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret), une clé unique que vous devez transmettre à votre application. Cette clé vous permet de réaliser diverses actions sur le client, comme confirmer la configuration et mettre à jour les informations du moyen de paiement, tout en masquant des données sensibles comme l’attribut `customer`. Vous pouvez également utiliser la clé secrète du client pour valider et authentifier les informations de carte par l’intermédiaire des réseaux de cartes de crédit. La clé secrète du client est une information sensible : ne la consignez pas, ne l’intégrez pas dans une URL et ne l’exposez à personne d’autre qu’au client.
### Côté serveur
Sur votre serveur, créez un endpoint qui crée lui-même un SetupIntent et renvoie la clé secrète du client à votre application.
#### curl
```bash
curl https://api.stripe.com/v1/setup_intents/ \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}"
```
Si vous prévoyez d’utiliser la carte pour des paiements futurs uniquement lorsque votre client est présent dans le tunnel de paiement, configurez le paramètre [utilisation](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-usage) sur la valeur *on\_session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) afin d’optimiser votre taux d’autorisation.
### Côté client
Côté client, demandez un SetupIntent auprès de votre serveur.
#### Kotlin
```kotlin
class CheckoutActivity : AppCompatActivity() {
private lateinit var setupIntentClientSecret: String
private fun loadPage() {
// Request a SetupIntent from your server and store its client secret
// Click View full sample to see a complete implementation
}
}
```
## Collecter les informations de carte bancaire [Côté client]
Lorsque votre client soumet le formulaire de paiement, collectez ses informations de carte à l’aide du [CardInputWidget](https://stripe.dev/stripe-android/payments-core/com.stripe.android.view/-card-input-widget/index.html), un composant d’interface utilisateur prêt à l’emploi fourni par le SDK, qui collecte le numéro de carte, la date d’expiration, le CVC et le code postal.
> Lorsque vous enregistrez des informations de carte bancaire pour effectuer ultérieurement des paiements hors session, [demandez au client l’autorisation d’enregistrer sa carte](https://docs.stripe.com/strong-customer-authentication.md#sca-enforcement). Ceci est particulièrement important en Europe, car cette région applique une réglementation particulière sur la réutilisation des cartes. Pour cela, incluez dans votre tunnel de paiement un texte expliquant à l’utilisateur comment vous comptez utiliser sa carte.
Appelez la méthode `getPaymentMethodCard` pour récupérer les informations de carte bancaire de votre client. Transmettez les informations collectées à de nouvelles instances de [PaymentMethodCreateParams](https://stripe.dev/stripe-android/payments-core/com.stripe.android.model/-payment-method-create-params/index.html) et `PaymentMethod.BillingDetails` pour créer une instance de `ConfirmSetupIntentParams`.
#### Kotlin
```kotlin
// Collect card details
val cardInputWidget =
findViewById(R.id.cardInputWidget)
val paymentMethodCard = cardInputWidget.paymentMethodCard
// Later, you will need to attach the PaymentMethod to the Customer it belongs to.
// This example collects the customer's email to know which customer the PaymentMethod belongs to, but your app might use an account id, session cookie, and so on.
val emailInput = findViewById(R.id.emailInput)
val billingDetails = PaymentMethod.BillingDetails.Builder()
.setEmail((emailInput.text ?: "").toString())
.build()
// Create SetupIntent confirm parameters with the above
if (paymentMethodCard != null) {
val paymentMethodParams = PaymentMethodCreateParams
.create(paymentMethodCard, billingDetails, null)
val confirmParams = ConfirmSetupIntentParams
.create(paymentMethodParams, setupIntentClientSecret)
lifecycleScope.launch {
paymentLauncher.confirm(confirmParams)
}
}
```
Pour terminer la configuration, transmettez l’objet `SetupIntentParams` avec l’activité actuelle à [PaymentLauncher confirm](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-launcher/index.html#74063765%2FFunctions%2F-1622557690). La SetupIntent vérifie que les informations de carte utilisées par votre client sont valides sur le réseau. Cependant, la vérification automatique n’est pas toujours effectuée. Pour plus d’informations à ce sujet, consultez la rubrique [Vérifier si une carte est valide sans la débiter](https://support.stripe.com/questions/check-if-a-card-is-valid-without-a-charge). De plus, ne conservez pas de SetupIntents non gérés et de longue durée, car ils pourraient ne plus être valides lorsque vous appelez `PaymentLauncher#confirm()`.
Certains moyens de paiement requièrent des [étapes d’authentification supplémentaires](https://docs.stripe.com/payments/payment-intents/verifying-status.md#next-actions) pour finaliser un paiement. Le SDK gère le flux de confirmation de paiement et d’authentification, ce qui peut impliquer d’afficher des écrans supplémentaires, nécessaires pour l’authentification. Pour plus d’informations sur l’authentification *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments) et la personnalisation de l’expérience d’authentification, consultez la page [Prise en charge de l’authentification 3D Secure sur Android](https://docs.stripe.com/payments/3d-secure.md?platform=android).
Le résultat du flux est renvoyé à votre activité appelante par le rappel fourni, ici `onPaymentResult`. Le [PaymentResult](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-result/index.html) renvoyé par le [PaymentLauncher](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-launcher/index.html) présente les types suivants :
- `Completed` : confirmation ou authentification réussie
- `Canceled` : le client a annulé l’authentification requise
- `Failed` : la tentative d’authentification a échoué, au motif indiqué par la propriété [throwable](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-result/-failed/index.html#257609069%2FProperties%2F-1622557690)
#### Kotlin
```kotlin
private fun onPaymentResult(paymentResult: PaymentResult) {
var title = ""
var message = ""
var restartDemo = false
when (paymentResult) {
is PaymentResult.Completed -> {
title = "Setup Completed"
restartDemo = true
}
is PaymentResult.Canceled -> {
title = "Setup Canceled"
}
is PaymentResult.Failed -> {
title = "Setup Failed"
message = paymentResult.throwable.message!!
}
}
displayAlert(title, message, restartDemo)
}
```
Vous disposez désormais d’un flux permettant de recueillir les informations de carte et de gérer les éventuelles demandes d’authentification. Utilisez la carte de test `4000 0025 0000 3155`, ainsi qu’un CVC, un code postal et une date d’expiration postérieure à la date du jour pour tester le processus d’authentification.
Lorsque le SetupIntent aboutit, l’ID PaymentMethod généré (dans `setupIntent.getPaymentMethodId()`) est enregistré dans l’objet Customer fourni.
## Débiter ultérieurement la carte enregistrée [Côté serveur]
Lorsque vous êtes prêt à débiter votre client hors session, utilisez les identifiants Customer et PaymentMethod pour créer un PaymentIntent. Pour trouver une carte à débiter, [listez](https://docs.stripe.com/api/payment_methods/list.md) les PaymentMethods associés à votre Customer.
#### Accounts v2
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer_account={{CUSTOMERACCOUNT_ID}}" \
-d type=card
```
#### Customers v1
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer={{CUSTOMER_ID}}" \
-d type=card
```
Lorsque vous avez les identifiants Client et PaymentMethod, créez un PaymentIntent avec le montant et la devise du paiement. Réglez quelques autres paramètres pour effectuer un paiement hors session :
- Définissez [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) sur `true` pour indiquer que le client n’est pas dans votre tunnel de paiement lors de cette tentative de paiement. Dans ce cas, le PaymentIntent renvoie une erreur si une authentification est requise.
- Assignez la valeur `true` à la propriété [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) du PaymentIntent, ce qui aura pour effet de générer immédiatement une confirmation lors de la création du PaymentIntent.
- Renseignez l’ID du PaymentMethod dans [payment_method](https://docs.stripe.com/api.md#create_payment_intent-payment_method) et l’ID du client dans [customer](https://docs.stripe.com/api.md#create_payment_intent-customer).
#### curl
```bash
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-d amount=1099 \
-d currency=usd \-d customer="{{CUSTOMER_ID}}" \
-d payment_method="{{PAYMENT_METHOD_ID}}" \
-d off_session=true \
-d confirm=true
```
Inspectez la [propriété d’état](https://docs.stripe.com/payments/paymentintents/lifecycle.md) du PaymentIntent pour confirmer que le paiement a été effectué avec succès. Si la tentative de paiement a réussi, l’état du PaymentIntent est `succeeded` et que le ** (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) est terminé.
### Démarrer un flux de récupération
Si le PaymentIntent a un autre état, le paiement n’a pas abouti et la requête échoue. Informez votre client qu’il doit revenir dans votre application (par exemple par e-mail, SMS ou notification push) pour finaliser le paiement. Nous vous recommandons de mettre en place un flux de récupération dans votre application qui explique pourquoi le paiement a initialement échoué et permet à votre client de réessayer.
Dans votre flux de récupération, récupérez l’objet PaymentIntent via sa *clé secrète du client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)). Vérifiez la valeur [lastPaymentError](https://stripe.dev/stripe-android/payments-core/com.stripe.android.model/-payment-intent/index.html#com.stripe.android.model/PaymentIntent/lastPaymentError/#/PointingToDeclaration/) du PaymentIntent pour découvrir pourquoi la tentative de paiement a échoué. Pour les erreurs de carte, vous pouvez montrer à l’utilisateur le dernier [message](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-message) d’erreur du paiement. Sinon, vous pouvez afficher un message d’échec générique.
#### Kotlin
```kotlin
fun startRecoveryFlow(clientSecret: String) {
val stripe = Stripe(
applicationContext,
PaymentConfiguration.getInstance(applicationContext).publishableKey
)
lifecycleScope.launch {
runCatching {
stripe.retrievePaymentIntent(clientSecret)
}.fold(
onSuccess = { paymentIntent ->
var failureReason =
"Payment failed, try again" // Default to a generic error message
paymentIntent.lastPaymentError?.let { lastPaymentError ->
if (lastPaymentError.type == PaymentIntent.Error.Type.CardError) {
lastPaymentError.message?.let { errorMessage ->
failureReason = errorMessage
// Display the failure reason to your customer
}
}
}
},
onFailure = {
// Handle error
}
)
}
}
```
### Permettre au client de réessayer
Votre flux de récupération doit permettre au client de [mettre à jour](https://docs.stripe.com/api/payment_methods/update.md) ou [supprimer](https://docs.stripe.com/api/payment_methods/detach.md) sa carte enregistrée et de réessayer le paiement. Suivez les mêmes étapes que pour l’acceptation du paiement d’origine, à une différence près : *confirmez* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) l’objet PaymentIntent d’origine qui a échoué en réutilisant sa [clé secrète de client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) plutôt que d’en créer une nouvelle.
Si le paiement échoue parce qu’il nécessite une authentification, réessayez avec l’objet *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) existant plutôt que d’en créer un nouveau.
#### Kotlin
```kotlin
fun startRecoveryFlow(clientSecret: String) {
// ...continued from previous step
val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext)
val paymentLauncher = PaymentLauncher.Companion.create(
this,
paymentConfiguration.publishableKey,
paymentConfiguration.stripeAccountId,
::onPaymentResult
)
val lastPaymentError = paymentIntent.lastPaymentError
val lastPaymentMethodId = lastPaymentError.paymentMethod?.id
if (lastPaymentError?.code == "authentication_required" && lastPaymentMethodId != null) {
// Payment failed because authentication is required, reuse the PaymentMethod
val paymentIntentParams =
ConfirmPaymentIntentParams.createWithPaymentMethodId(
lastPaymentMethodId,
clientSecret // Reuse the existing PaymentIntent
)
// Submit the payment...
paymentLauncher.confirm(paymentIntentParams)
} else {
// Collect a new PaymentMethod from the customer...
}
}
```
## Tester l'intégration
À ce stade, vous devriez avoir une intégration qui :
1. Collecte les informations de carte bancaire sans débiter le client avec un SetupIntent
1. Débite la carte hors session et dispose d’un flux de récupération permettant de gérer les refus de paiement et les demandes d’authentification
Pour vérifier que votre intégration est prête, vous avez à votre disposition plusieurs cartes de test. Vous pouvez les utiliser en mode test avec n’importe quel CVC, code postal et date d’expiration non échue.
| Numéro | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | Transaction réussie et paiement effectué immédiatement. |
| 4000002500003155 | Authentification requise pour l’achat initial, mais la transaction réussit pour les paiements suivants (y compris ceux effectués hors session) dès l’instant que la carte bancaire est configurée avec `setup_future_usage`. |
| 4000002760003184 | Exige l’authentification pour l’achat initial, et la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `authentication_required`. |
| 4000008260003178 | Exige l’authentification pour l’achat initial, mais la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `insufficient_funds`. |
| 4000000000009995 | Échoue toujours (y compris pour l’achat initial) avec un code de refus de paiement `insufficient_funds`. |
Voir la liste complète des [cartes de test](https://docs.stripe.com/testing.md).
# React Native
> This is a React Native for when platform is react-native. View the full page at https://docs.stripe.com/payments/save-and-reuse-cards-only?platform=react-native.
> Nous vous recommandons de suivre les instructions de notre guide [Configurer des paiements futurs](https://docs.stripe.com/payments/mobile/set-up-future-payments.md). N’utilisez ce guide que si vous devez utiliser la confirmation manuelle côté serveur ou si votre intégration nécessite la présentation de moyens de paiement séparément. Si vous avez déjà intégré Elements, consultez le [Guide de migration du Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
L’[API Setup Intents](https://docs.stripe.com/api/setup_intents.md) vous permet d’enregistrer la carte d’un client sans paiement initial. Cette fonction est utile si vous souhaitez configurer des paiements dès l’inscription de vos clients afin de les débiter plus tard, lorsqu’ils sont hors ligne.
Utilisez cette intégration pour configurer des paiements récurrents ou pour créer des paiements ponctuels dont le montant doit être déterminé ultérieurement, généralement après réception du service par votre client.
## Configurer Stripe [Côté serveur] [Côté client]
### Côté serveur
Pour cette intégration, votre serveur doit être doté d’endpoints qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :
#### 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'
```
### Côté client
Le [SDK React Native](https://github.com/stripe/stripe-react-native) est disponible en open source et fait l’objet d’une documentation complète. En interne, il utilise des SDK [Android](https://github.com/stripe/stripe-android) et [iOS natifs](https://github.com/stripe/stripe-ios). Pour installer le SDK React Native de Stripe, exécutez l’une des commandes suivantes dans le répertoire de votre projet (selon le gestionnaire de paquets que vous utilisez) :
#### yarn
```bash
yarn add @stripe/stripe-react-native
```
#### npm
```bash
npm install @stripe/stripe-react-native
```
Ensuite, installez les autres dépendances nécessaires :
- Pour iOS, accédez au directeur **ios** et exécutez `pod install` pour vous assurer que vous installez également les dépendances natives requises.
- Pour Android, il n’y a plus de dépendances à installer.
> Nous vous recommandons de suivre le [guide officiel de TypeScript](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project) pour ajouter la prise en charge de TypeScript.
### Initialisation de Stripe
Pour initialiser Stripe dans votre application React Native, wrappez votre écran de paiement avec le composant `StripeProvider` ou utilisez la méthode d’initialisation `initStripe`. Seule la [clé publiable](https://docs.stripe.com/keys.md#obtain-api-keys) de l’API dans `publishableKey` est nécessaire. L’exemple suivant montre comment initialiser Stripe à l’aide du composant `StripeProvider`.
```jsx
import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';
function App() {
const [publishableKey, setPublishableKey] = useState('');
const fetchPublishableKey = async () => {
const key = await fetchKey(); // fetch key from your server here
setPublishableKey(key);
};
useEffect(() => {
fetchPublishableKey();
}, []);
return (
{/* Your app code here */}
);
}
```
> Utilisez vos [clés de test](https://docs.stripe.com/keys.md#obtain-api-keys) d’API lors de vos activités de test et de développement, et vos clés du [mode production](https://docs.stripe.com/keys.md#test-live-modes) pour la publication de votre application.
## Créer un objet Customer avant la configuration [Côté serveur]
Pour configurer une carte bancaire en vue de paiements futurs, vous devez l’associer à un *client* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Lorsque votre client ouvre un compte chez vous, créez un objet Customer, qui permet de réutiliser des moyens de paiement et d’assurer le suivi de plusieurs paiements.
> #### Utiliser l’API Accounts v2 pour représenter des clients
>
> Si votre intégration utilise des [Accounts configurés par le client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), remplacez les références `Customer` et événement dans les exemples de code par les références équivalentes de l’API Accounts v2. Pour plus d’informations, consultez la page [Représenter des clients avec des objets Account](https://docs.stripe.com/connect/use-accounts-as-customers.md).
```curl
curl https://api.stripe.com/v1/customers \
-u "<>:" \
-d "name=Jenny Rosen" \
--data-urlencode "email=jennyrosen@example.com"
```
Lorsque la création aboutit, l’objet [Customer](https://docs.stripe.com/api/customers/object.md) est renvoyé. Vous pouvez l’examiner pour identifier l’`id` du client et stocker cette valeur dans votre base de données pour la récupérer ultérieurement.
Vous pouvez trouver ces clients sur la page [Clients](https://dashboard.stripe.com/customers) du Dashboard.
## Créer un SetupIntent [Côté serveur]
Un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) est un objet qui représente votre intention de configurer un moyen de paiement pour encaisser de futurs paiements. Le SetupIntent contient la [clé secrète du client](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret), une clé unique que vous devez transmettre à votre application.
Cette clé vous permet de réaliser diverses actions sur le client, comme confirmer la configuration et mettre à jour les informations du moyen de paiement, tout en masquant des données sensibles comme l’attribut `customer`. Vous pouvez également utiliser la clé secrète du client pour valider et authentifier les informations de la carte par l’intermédiaire des réseaux de cartes. La clé secrète du client est une information sensible : ne la consignez pas, ne l’intégrez pas dans une URL et ne l’exposez à personne d’autre qu’au client.
### Côté serveur
Sur votre serveur, créez un endpoint qui crée lui-même un SetupIntent et renvoie la clé secrète du client à votre application.
#### curl
```bash
curl https://api.stripe.com/v1/setup_intents/ \
-u <>: \
-d "customer"="{{CUSTOMER_ID}}"
```
Si vous prévoyez d’utiliser la carte pour des paiements futurs uniquement lorsque votre client est présent dans le tunnel de paiement, configurez le paramètre [utilisation](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-usage) sur la valeur *on\_session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) afin d’optimiser votre taux d’autorisation.
## Collecter les informations de carte bancaire [Côté client]
Collectez en toute sécurité les informations de carte du client avec `CardField`, un composant d’interface utilisateur fourni par le SDK qui collecte le numéro de carte, la date d’expiration, le CVC et le code postal.
Ajoutez le composant `CardField` à votre page de paiement pour recueillir en toute sécurité les informations de carte de vos clients. Utilisez le rappel `onCardChange` pour vérifier les informations non sensibles concernant la carte, telles que la marque, et confirmer que les informations sont complètes.
```javascript
import { CardField, useStripe } from '@stripe/stripe-react-native';
function PaymentScreen() {
// ...
return (
{
console.log('cardDetails', cardDetails);
}}
onFocus={(focusedField) => {
console.log('focusField', focusedField);
}}
/>
);
}
```
> Lorsque vous enregistrez des informations de carte bancaire pour effectuer ultérieurement des paiements hors session, [demandez au client l’autorisation d’enregistrer sa carte](https://docs.stripe.com/strong-customer-authentication.md#sca-enforcement). Ceci est particulièrement important en Europe, car cette région applique une réglementation particulière sur la réutilisation des cartes. Pour cela, incluez dans votre tunnel de paiement un texte expliquant à l’utilisateur comment vous comptez utiliser sa carte.
Pour terminer la configuration, transmettez les informations de carte et de facturation du client à `confirmSetupIntent`. Vous pouvez accéder à cette méthode avec le hook `useConfirmSetupIntent` ou `useStripe`.
```javascript
function PaymentScreen() {
// ...
const { confirmSetupIntent, loading } = useConfirmSetupIntent();
// ...
const handlePayPress = async () => {
// Gather the customer's billing information (for example, email)
const billingDetails: BillingDetails = {
email: 'jenny.rosen@example.com',
};
// Create a setup intent on the backend
const clientSecret = await createSetupIntentOnBackend();
const { setupIntent, error } = await confirmSetupIntent(clientSecret, {
paymentMethodType: 'Card',
paymentMethodData: {
billingDetails,
}
});
if (error) {
//Handle the error
}
// ...
};
return (
// ...
);
}
```
Certains moyens de paiement requièrent des [étapes d’authentification supplémentaires](https://docs.stripe.com/payments/payment-intents/verifying-status.md#next-actions) pour finaliser un paiement. Le SDK gère le flux de confirmation de paiement et d’authentification, ce qui peut impliquer d’afficher des écrans supplémentaires, nécessaires pour l’authentification. Pour tester le processus d’authentification, utilisez la carte de test `4000 0025 0000 3155` avec un CVC, un code postal et une date d’expiration postérieure à la date du jour.
Lorsque le `SetupIntent` réussit, l’ID PaymentMethod généré (dans `setupIntent.paymentMethodID`) est enregistré dans l’objet `Customer` fourni.
## Débiter ultérieurement la carte enregistrée [Côté serveur]
Lorsque vous êtes prêt à débiter votre client hors session, utilisez les identifiants Customer et PaymentMethod pour créer un PaymentIntent. Pour trouver une carte à débiter, [listez](https://docs.stripe.com/api/payment_methods/list.md) les PaymentMethods associés à votre Customer.
#### Accounts v2
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer_account={{CUSTOMERACCOUNT_ID}}" \
-d type=card
```
#### Customers v1
```curl
curl -G https://api.stripe.com/v1/payment_methods \
-u "<>:" \
-d "customer={{CUSTOMER_ID}}" \
-d type=card
```
Lorsque vous avez les identifiants Client et PaymentMethod, créez un PaymentIntent avec le montant et la devise du paiement. Réglez quelques autres paramètres pour effectuer un paiement hors session :
- Définissez [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) sur `true` pour indiquer que le client n’est pas dans votre tunnel de paiement lors de cette tentative de paiement. Dans ce cas, le PaymentIntent renvoie une erreur si une authentification est requise.
- Assignez la valeur `true` à la propriété [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) du PaymentIntent, ce qui aura pour effet de générer immédiatement une confirmation lors de la création du PaymentIntent.
- Renseignez l’ID du PaymentMethod dans [payment_method](https://docs.stripe.com/api.md#create_payment_intent-payment_method) et l’ID du client dans [customer](https://docs.stripe.com/api.md#create_payment_intent-customer).
#### curl
```bash
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-d amount=1099 \
-d currency=usd \-d customer="{{CUSTOMER_ID}}" \
-d payment_method="{{PAYMENT_METHOD_ID}}" \
-d off_session=true \
-d confirm=true
```
### Démarrer un flux de récupération
Si l’état de l’objet PaymentIntent est différent, le paiement n’a pas abouti et la requête échoue. Invitez votre client à revenir dans l’application (par e-mail, SMS ou notification Push, par exemple) afin de terminer le paiement. Nous vous recommandons de créer dans votre application un flux de récupération indiquant le motif de l’échec du paiement initial et permettant au client de réessayer.
Dans votre flux de récupération, récupérez le PaymentIntent à l’aide de sa *clé secrète de client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)), puis vérifiez l’erreur `lastPaymentError` du PaymentIntent pour déterminer le motif de l’échec du paiement. Pour les erreurs de carte, vous pouvez présenter à l’utilisateur le dernier [message](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-message) d’erreur du paiement. Dans les autres cas, affichez un message d’échec générique.
```javascript
function PaymentScreen() {
// ...
const {retrievePaymentIntent} = useStripe();
// ...
const handleRecoveryFlow = async () => {
const {paymentIntent, error} = await retrievePaymentIntent(clientSecret);
if (error) {
Alert.alert(`Error: ${error.code}`, error.message);
} else if (paymentIntent) {
// Default to a generic error message
let failureReason = 'Payment failed, try again.';
if (paymentIntent.lastPaymentError.type === 'Card') {
failureReason = paymentIntent.lastPaymentError.message;
}
}
};
return (
// ...
);
}
```
### Permettre au client de réessayer
Votre flux de récupération doit permettre au client de [mettre à jour](https://docs.stripe.com/api/payment_methods/update.md) ou [supprimer](https://docs.stripe.com/api/payment_methods/detach.md) sa carte enregistrée et de réessayer le paiement. Suivez les mêmes étapes que pour l’acceptation du paiement d’origine, à une différence près : *confirmez* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) l’objet PaymentIntent d’origine qui a échoué en réutilisant sa [clé secrète de client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) plutôt que d’en créer une nouvelle.
Si le paiement échoue parce qu’il nécessite une authentification, réessayez avec l’objet PaymentMethod existant plutôt que d’en créer un nouveau.
```javascript
function PaymentScreen() {
// ...
const {retrievePaymentIntent} = useStripe();
// ...
const handleRecoveryFlow = async () => {
const {paymentIntent, error} = await retrievePaymentIntent(clientSecret);
if (error) {
Alert.alert(`Error: ${error.code}`, error.message);
} else if (paymentIntent) {
// Default to a generic error message
let failureReason = 'Payment failed, try again.';
if (paymentIntent.lastPaymentError.type === 'Card') {
failureReason = paymentIntent.lastPaymentError.message;
}
// If the last payment error is authentication_required, let the customer
// complete the payment without asking them to reenter their details.
if (paymentIntent.lastPaymentError?.code === 'authentication_required') {
// Let the customer complete the payment with the existing PaymentMethod
const {error} = await confirmPayment(paymentIntent.clientSecret, {
paymentMethodType: 'Card',
paymentMethodData: {
billingDetails,
paymentMethodId: paymentIntent.lastPaymentError?.paymentMethod.id,
},
});
if (error) {
// handle error
}
} else {
// Collect a new PaymentMethod from the customer
}
}
};
return (
// ...
);
}
```
## Tester l'intégration
À ce stade, vous devriez avoir une intégration qui :
1. Collecte les informations de carte bancaire sans débiter le client avec un SetupIntent
1. Débite la carte hors session et dispose d’un flux de récupération permettant de gérer les refus de paiement et les demandes d’authentification
Pour vérifier que votre intégration est prête, vous avez à votre disposition plusieurs cartes de test. Vous pouvez les utiliser en mode test avec n’importe quel CVC, code postal et date d’expiration non échue.
| Numéro | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | Transaction réussie et paiement effectué immédiatement. |
| 4000002500003155 | Authentification requise pour l’achat initial, mais la transaction réussit pour les paiements suivants (y compris ceux effectués hors session) dès l’instant que la carte bancaire est configurée avec `setup_future_usage`. |
| 4000002760003184 | Exige l’authentification pour l’achat initial, et la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `authentication_required`. |
| 4000008260003178 | Exige l’authentification pour l’achat initial, mais la transaction échoue pour les paiements suivants (y compris ceux effectués hors session) avec un code de refus de paiement `insufficient_funds`. |
| 4000000000009995 | Échoue toujours (y compris pour l’achat initial) avec un code de refus de paiement `insufficient_funds`. |
Voir la liste complète des [cartes de test](https://docs.stripe.com/testing.md).