# Accepter un paiement PayPal Comment accepter les paiements PayPal, un portefeuille électronique populaire auprès des entreprises européennes. # API Direct ## Configurer Stripe [Côté serveur] Pour commencer, vous devez créer un compte Stripe. [Inscrivez-vous maintenant](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 un PaymentIntent [Côté serveur] Stripe utilise un objet de paiement, appelé [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md), pour suivre et gérer tous les états du paiement jusqu’à sa finalisation. Créez un `PaymentIntent` sur votre serveur, en spécifiant le montant à collecter et la devise. Si vous avez déjà créé une intégration à l’aide de [l’API Payment Intents](https://docs.stripe.com/payments/payment-intents.md), ajoutez `paypal` à la liste des [types de moyens de paiement](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) de votre PaymentIntent. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=eur \ -d "payment_method_types[]=paypal" ``` Le PaymentIntent renvoyé contient la *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)), qui est utilisée pour finaliser le paiement de manière sécurisée au lieu de transmettre la totalité de l’objet PaymentIntent. Renvoyez la clé secrète au client pour pouvoir l’utiliser ultérieurement. #### Inclure une description personnalisée Par défaut, les détails de la commande sur la page d’activité d’achat des utilisateurs PayPal affichent le montant de la commande. Vous pouvez modifier cette configuration en saisissant une description personnalisée dans la propriété `description`. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=eur \ -d "description=A sample description" \ -d "payment_method_types[]=paypal" ``` #### Personnaliser la langue préférée Par défaut, la page d’autorisation PayPal est localisée en fonction de variables telles que le pays de l’entreprise. Vous pouvez définir la langue préférée de votre client à l’aide de la propriété `preferred_locale`. La valeur doit être un code de langue à deux caractères en minuscules, suivi d’un trait d’union (`-`), suivi d’un code de pays à deux caractères en majuscules. Par exemple, la valeur pour un utilisateur de langue française en Belgique serait `fr-BE`. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=eur \ -d "payment_method_types[]=paypal" \ -d "payment_method_options[paypal][preferred_locale]=fr-BE" ``` Vous pouvez définir la page d’autorisation PayPal en fonction des paramètres locaux préférés de votre client grâce à la propriété [preferred_locale](https://docs.stripe.com/payments/paypal/accept-a-payment.md#customize-the-preferred-locale). Consultez le tableau suivant pour connaître les paramètres locaux pris en charge : | Valeur | Région | Pays | | ------ | ----------- | --------------------- | | cs-CZ | Tchèque | République tchèque | | da-DK | Danois | Danemark | | de-AT | Allemand | Autriche | | de-DE | Allemand | Allemagne | | de-LU | Allemand | Luxembourg | | el-GR | Grec | Grèce | | en-GB | Anglais | Royaume-Uni | | fr-FR | Anglais | États-Unis d’Amérique | | es-ES | Espagnol | Espagne | | fi-FI | Finnois | Finlande | | fr-BE | Français | Belgique | | fr-FR | Français | France | | fr-LU | Français | Luxembourg | | hu-HU | Hongrois | Hongrie | | it-IT | Italien | Italie | | nl-BE | Néerlandais | Belgique | | nl-NL | Néerlandais | Pays-Bas | | pl-PL | Polonais | Pologne | | pt-PT | Portugais | Portugal | | sk-SK | Slovaque | Slovaquie | | sv-SE | Suédois | Suède | #### Libellés de relevé bancaire avec PayPal Le libellé qui apparaît sur le relevé bancaire de l’acheteur est défini par PayPal et est par défaut `PAYPAL *YOUR_BUSINESS_NAME`. Si vous définissez le champ `statement_descriptor` lors de la création du `PaymentIntent`, sa valeur est ajoutée à celle définie par PayPal, dans la limite de 22 caractères. Par exemple, si le nom de votre entreprise dans PayPal est `BUSINESS` et que vous configurez `statement_descriptor` sur `order_id_1234`, la mention `PAYPAL *BUSINESS order` apparaîtra sur le relevé de compte bancaire de vos clients. ## Soumettre le paiement à Stripe [Côté client] Lorsqu’un client clique pour payer avec PayPal, utilisez Stripe.js pour soumettre le paiement à Stripe. [Stripe.js](https://docs.stripe.com/payments/elements.md) est la bibliothèque JavaScript de base pour créer les tunnels de paiement : elle gère automatiquement les opérations complexes telles que la redirection décrite ci-dessous, et facilite l’extension de votre intégration à d’autres moyens de paiement. Incluez le script Stripe.js sur votre page de paiement en l’ajoutant à la section `head` de votre fichier HTML. ```html Checkout ``` Créez une instance de Stripe.js avec le code JavaScript suivant sur votre page de paiement. ```javascript // Set your publishable key. Remember to change this to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>'); ``` Pour créer un paiement côté client, transmettez la [clé secrète du client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) de l’objet `PaymentIntent` créé à [l’étape 2](https://docs.stripe.com/payments/paypal/accept-a-payment.md#create-payment-intent). La clé secrète du client est distincte des clés API authentifiant vos requêtes à l’API Stripe. Elle doit être utilisée avec prudence, car elle peut servir à réaliser le paiement. Ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne la dévoilez à personne d’autre que votre client. ### Confirmer le paiement PayPal Appelez [stripe.confirmPayPalPayment](https://docs.stripe.com/js/payment_intents/confirm_paypal_payment) pour rediriger votre client vers PayPal pour finaliser le paiement. Ajoutez une URL `return_url` pour indiquer la page vers laquelle Stripe doit rediriger votre client une fois le paiement effectué. Vous pouvez également ajouter le paramètre `return_url` pour les nouveaux moyens de paiement PayPal, mais ce n’est pas obligatoire lorsque vous utilisez un moyen de paiement PayPal préalablement configuré avec un SetupIntent ou un PaymentIntent qui inclut `setup_future_usage`. ```javascript // Redirects away from the client const {error} = await stripe.confirmPayPalPayment( '{{PAYMENT_INTENT_CLIENT_SECRET}}', { return_url: 'https://example.com/checkout/complete', } ); if (error) { // Inform the customer that there was an error. } ``` Si vous versez vos fonds PayPal à l’aide de PayPal, le montant de l’[opération sur solde](https://docs.stripe.com/api.md#balance_transaction_object) associée au paiement sera égal à zéro quel que soit le montant du paiement, car l’opération représente l’argent transféré vers et depuis votre solde Stripe. En revanche, pour PayPal, les fonds sont versés sur votre solde PayPal et aucun montant n’est versé sur votre solde Stripe. Dans ce cas, l’opération sur solde inclut également les frais qui lui sont associés. En savoir plus sur la [préférence de versement](https://docs.stripe.com/payments/paypal/choose-settlement-preference.md). ### Effectuer la redirection Les paramètres de requête d’URL suivants sont fournis lorsque Stripe redirige le client vers l’URL `return_url`. | Paramètre | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `payment_intent` | L’identifiant unique du `PaymentIntent`. | | `payment_intent_client_secret` | La [clé secrète du client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) de l’objet `PaymentIntent`. | Vous pouvez également ajouter vos propres paramètres de requête lorsque vous fournissez `return_url`. Ceux-ci resteront activés pendant toute la durée du processus de redirection. Le paramètre `return_url` doit correspondre à une page de votre site web sur laquelle l’état du paiement est fourni. Vous devez vérifier l’état du `PaymentIntent` lors de l’affichage de la page de retour. Vous pouvez le faire en utilisant la fonction `retrievePaymentIntent` de Stripe.js et en transmettant `payment_intent_client_secret`. ```javascript (async () => { const url = new URL(window.location); const clientSecret = url.searchParams.get('payment_intent_client_secret'); const {paymentIntent, error} = await stripe.retrievePaymentIntent(clientSecret); if (error) { // Handle error } else if (paymentIntent && paymentIntent.status === 'succeeded') { // Handle successful payment } })(); ``` Vous trouverez le nom, l’adresse e-mail, l’ID du payeur et l’ID de la transaction du payeur dans la propriété [payment_method_details](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details-paypal). | Champ | Valeur | | ---------------- | ------------------------------------------------- | | `payer_email` | L’adresse e-mail du payeur sur son compte PayPal. | | `payer_name` | Le nom du payeur sur son compte PayPal. | | `payer_id` | L’identifiant unique du compte PayPal du payeur. | | `transaction_id` | Un ID de transaction unique généré par PayPal. | #### Json ```json { "charges": { "data": [ {"payment_method_details": { "paypal": { "payer_id": "H54KFE9XXVVYJ", "payer_email": "jenny@example.com", "payer_name": "Jenny Rosen", "transaction_id": "89W40396MK104212M" }, "type": "paypal" }, "id": "src_16xhynE8WzK49JbAs9M21jaR", "object": "source", "amount": 1099, "client_secret": "src_client_secret_UfwvW2WHpZ0s3QEn9g5x7waU", "created": 1445277809, "currency": "eur", "flow": "redirect", "livemode": true, "statement_descriptor": null, "status": "pending", "type": "paypal", "usage": "single_use" } ], "object": "list", "has_more": false, "url": "/v1/charges?payment_intent=pi_1G1sgdKi6xqXeNtkldRRE6HT" }, "payment_method_options": { "paypal": {} }, "payment_method_types": [ "paypal" ], "id": "pi_1G1sgdKi6xqXeNtkldRRE6HT", "object": "payment_intent", "amount": 1099, "client_secret": "pi_1G1sgdKi6xqXeNtkldRRE6HT_secret_h9B56ObhTN72fQiBAuzcVPb2E", "confirmation_method": "automatic", "created": 1579259303, "currency": "eur", "livemode": true, "next_action": null } ``` ## Optional: Gérer les événements post-paiement Stripe envoie un événement [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) à l’issue du paiement. Utilisez le Dashboard, un *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) personnalisé ou une solution partenaire pour recevoir ces événements et exécuter des actions, comme envoyer une confirmation de commande par e-mail à votre client, enregistrer la vente dans une base de données ou lancer un workflow de livraison. Plutôt que d’attendre un rappel de votre client, écoutez ces événements. En effet, côté client, l’acheteur pourrait fermer la fenêtre de son navigateur ou quitter l’application avant l’exécution du rappel. Des personnes malveillantes peuvent en profiter pour manipuler la réponse. Si vous configurez votre intégration de manière à écouter les événements asynchrones, cela vous permettra également d’accepter de nouveaux moyens de paiement plus facilement à l’avenir. Apprenez-en davantage sur les [différences entre les différents moyens de paiement pris en charge](https://stripe.com/payments/payment-methods-guide). ### Recevoir des événements et exécuter des actions métier Plusieurs options s’offrent à vous pour recevoir et exécuter des actions métier. #### Manuellement Utilisez le Dashboard pour consulter tous vos paiements Stripe, envoyer des reçus par e-mail, gérer les virements et relancer les paiements ayant échoué. - [Afficher vos paiements tests dans le Dashboard](https://dashboard.stripe.com/test/payments) #### Code personnalisé Créez un gestionnaire de webhooks pour écouter des événements et créer des tunnels de paiement asynchrones personnalisés. Testez et déboguez votre intégration de webhooks en local, grâce à la CLI Stripe. - [Créer un webhook personnalisé](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) #### Applications préconfigurées Intégrez une application partenaire pour gérer les événements métier courants, comme l’[automatisation](https://stripe.partners/?f_category=automation), le [marketing ou les ventes](https://stripe.partners/?f_category=marketing-and-sales). ## Optional: Gérer la redirection PayPal manuellement Stripe.js vous aide à ajouter d’autres moyens de paiement à votre intégration. Cependant, vous pouvez rediriger vos clients manuellement vers votre serveur. 1. Créez et *confirmez* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) un PaymentIntent de type `paypal`. En spécifiant `payment_method_data`, vous créez un PaymentMethod qui est utilisé immédiatement avec ce PaymentIntent. Vous devez également fournir dans le champ `return_url` l’URL vers laquelle le client est redirigé une fois qu’il a finalisé son paiement. Vous pouvez fournir vos propres paramètres de requête dans cette URL. Ces paramètres seront inclus dans l’URL finale à l’issue du flux de redirection. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=eur \ -d "payment_method_types[]=paypal" \ -d "payment_method_data[type]=paypal" \ --data-urlencode "return_url=https://example.com/checkout/complete" \ -d confirm=true ``` 1. Vérifiez que le `PaymentIntent` a l’état `requires_action` et que le type de `next_action` est `redirect_to_url`. #### Json ```json {"status": "requires_action", "next_action": { "type": "redirect_to_url", "redirect_to_url": { "url": "https://hooks.stripe.com/...", "return_url": "https://example.com/checkout/complete" } }, "id": "pi_1G1sgdKi6xqXeNtkldRRE6HT", "object": "payment_intent", ... } ``` 1. Redirigez le client vers l’URL fournie dans la propriété `next_action.redirect_to_url.url`. Cet exemple de code fourni ici n’a qu’une valeur illustrative : la méthode de redirection peut différer sur votre framework Web. #### Ruby ```ruby if payment_intent.status == 'requires_action' && payment_intent.next_action.type == 'redirect_to_url' url = payment_intent.next_action.redirect_to_url.url redirect(url) end ``` Le client est redirigé vers l’URL `return_url` une fois qu’il a effectué le paiement. Les paramètres de la requête d’URL `payment_intent` et `payment_intent_client_secret` sont inclus avec tous vos propres paramètres. Stripe recommande de configurer un [endpoint de webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) pour configurer l’état d’un paiement par voie programmatique. ## Optional: Autoriser un paiement et le saisir ultérieurement PayPal prend en charge [l’autorisation et la capture distinctes](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md). Si vous avez opté pour la [réception des fonds sur votre compte Stripe](https://docs.stripe.com/payments/paypal/choose-settlement-preference.md), vos autorisations sont valables pendant 10 jours. Stripe réautorise automatiquement le paiement pour prolonger la période d’autorisation de 10 jours supplémentaires, ce qui correspond à un total de 20 jours. Si la réautorisation ne fonctionne pas, Stripe fait expirer le paiement au bout de 10 jours. Écoutez le webhook [charge.expired](https://docs.stripe.com/api/events/types.md#event_types-charge.expired) pour connaître la date de fin de la période d’autorisation. Si vous avez choisi de [recevoir les fonds sur PayPal](https://docs.stripe.com/payments/paypal/choose-settlement-preference.md), vos autorisations restent valides durant 3 jours. Stripe tente de prolonger la période d’autorisation de 3 jours supplémentaires. Pour bénéficier d’une période d’autorisation garantie étendue pouvant aller jusqu’à 10 jours, appelée *honor period* dans PayPal, contactez le [service de support de PayPal](https://www.paypal.com/nu/cshelp/business). ### Indiquez à Stripe d’autoriser seulement Pour indiquer que vous souhaitez une autorisation et une capture séparées, définissez [capture_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) sur `manual` lors de la création du PaymentIntent. Ce paramètre indique à Stripe de n’autoriser que le montant figurant sur le compte PayPal du client. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=eur \ -d capture_method=manual \ -d "payment_method_types[]=paypal" \ -d "payment_method_data[type]=paypal" \ -d confirm=true \ --data-urlencode "return_url=http://example.com" ``` Une fois l’autorisation accordée, Stripe envoie un événement [payment_intent.amount_capturable_updated](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.amount_capturable_updated). Pour en savoir plus, consultez notre [guide des événements](https://docs.stripe.com/api/events.md). ### Capturer les fonds Une fois l’autorisation réussie, l’[état](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) du PaymentIntent passe à `requires_capture`. Pour capturer les fonds autorisés, faites une requête de [capture](https://docs.stripe.com/api/payment_intents/capture.md) PaymentIntent. Le montant total autorisé est capturé par défaut ; vous ne pouvez pas capturer un montant supérieur à cette valeur, mais vous pouvez capturer un montant inférieur. ```curl curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \ -u "<>:" \ -d amount_to_capture=750 ``` ### (Facultatif) Annuler l’autorisation Si vous devez annuler une autorisation, vous pouvez [annuler le PaymentIntent](https://docs.stripe.com/refunds.md#cancel-payment) correspondant. ## Optional: Activer les moyens de paiement asynchrones sur PayPal Par défaut, Stripe autorise uniquement les moyens de paiement synchrones sur PayPal. Vous recevez ainsi une [notification immédiate](https://docs.stripe.com/payments/payment-methods.md#payment-notification) vous informant de la réussite ou de l’échec de chaque paiement. Si vous autorisez les moyens de paiement asynchrones, vous pouvez recevoir des [notifications différées](https://docs.stripe.com/payments/payment-methods.md#payment-notification) pour certains paiements. Vous devrez alors utiliser des [endpoints de webhook](https://docs.stripe.com/payments/payment-methods.md#webhooks) pour recevoir des notifications concernant la réussite ou l’échec de certains paiements. Pour activer les paiements asynchrones sur PayPal, contactez le [service Support de Stripe](https://support.stripe.com/contact). ## Optional: Codes d'erreur Il s’agit des codes d’erreur les plus courants lors d’une intégration avec PayPal. Si une requête à l’API PayPal a renvoyé l’erreur, elle inclut un code d’émission PayPal et l’ID de débogage associé à la requête. Vous pouvez utiliser cet ID de débogage lorsque vous contactez le [service de support de PayPal](https://www.paypal-support.com/) pour obtenir de l’aide sur votre problème. | Code d’erreur | Détails | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `country_code_invalid` | Le code de pays indiqué dans l’adresse de livraison n’est pas valide. | | `incorrect_address` | L’adresse de livraison indiquée n’est pas valide. Cette erreur peut aussi être déclenchée si le pays spécifié nécessite également une ville ou un code postal. Pour plus d’informations, veuillez vérifier le message d’erreur et contacter le [service de support PayPal](https://www.paypal-support.com/) en lui fournissant le `Debug ID` et le code `PayPal issue`. | | `payment_method_not_available` | Le moyen de paiement `paypal` n’est pas disponible pour l’instant. Cette erreur peut être due à une expiration du délai d’attente ou à un problème de serveur lors de la connexion à l’API PayPal. | | `payment_method_provider_decline` | La transaction est refusée par PayPal. Cela est généralement dû aux paramètres de protection contre la fraude de l’entreprise à une violation de conformité, ou au fait que le payeur n’est pas en mesure de payer avec l’instrument de financement choisi. Pour plus d’informations, veuillez vérifier le message d’erreur et contacter le [service de support de PayPal](https://www.paypal-support.com/) en lui fournissant le `Debug ID` et le code `PayPal issue`. | | `payment_method_provider_timeout` | La requête a expiré pour Paypal. Dans la plupart des cas, il s’agit d’une erreur temporaire et vous pouvez relancer la requête après quelques instants. | | `payment_method_unactivated` | Le moyen de paiement `paypal` n’est pas activé pour votre compte Stripe. | | `payment_method_unexpected_state` | La requête a échoué pour PayPal. Cela peut se produire si le compte d’entreprise du client a été verrouillé, limité, ou fermé par PayPal, ou si le compte Paypal du payeur est limité. Pour plus d’informations, examinez le message d’erreur et contactez le [service de support de PayPal](https://www.paypal-support.com/) en lui fournissant le `Debug ID` et le code `PayPal issue`. | ## Optional: Tester l'intégration PayPal Pour simuler un paiement réussi sur votre intégration PayPal, utilisez vos [clés API de test](https://docs.stripe.com/keys.md#test-live-modes) et accédez à la page de redirection. Cette page vous donne la possibilité d’**Autoriser** ou de **Faire échouer** l’authentification de l’utilisateur selon plusieurs scénarios test. Lorsque vous sélectionnez **Autoriser le paiement test**, le PaymentIntent passe de l’état `requires_action` à `succeeded`. Pour tester un échec d’authentification de l’utilisateur, utilisez vos clés API de test et accédez à la page de redirection. Sur cette page, cliquez sur **Faire échouer le paiement test**. Votre PaymentIntent bascule alors de l’état `requires_action` à `requires_payment_method`. Pour simuler les scénarios d’intégration et d’échec les plus communs pour les paiements PayPal, transmettez des valeurs `email` correspondant aux modèles de la section [Scénarios test](https://docs.stripe.com/payments/paypal/accept-a-payment.md?platform=web#test-scenarios) lorsque vous créez le PaymentIntent dans les [informations de facturation](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_data-billing_details). Par exemple, lors de la confirmation du PaymentIntent côté serveur, voilà à quoi ressemble une requête qui simule une transaction refusée par PayPal : ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=eur \ -d "payment_method_types[]=paypal" \ -d "payment_method_data[type]=paypal" \ --data-urlencode "payment_method_data[billing_details][email]=transaction_refused@example.com" ``` ### Scénarios de test | E-mail type | Scénario | Explication | | ------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.*payee_account_restricted@.*` | Compte marchand soumis à des restrictions | Si votre compte marchand est limité par PayPal, la capture ou l’autorisation du paiement échoue avec l’erreur `payment_method_unexpected_state`. Pour faire échouer l’autorisation, veuillez indiquer une adresse e-mail correspondant à ce modèle au moment de l’autorisation. | | `.*transaction_refused@.*` | Transaction refusée | Si la transaction est refusée par PayPal, la capture du paiement échoue avec l’erreur `payment_method_provider_decline`. | | `.*instrument_declined@.*` | Instrument de paiement refusé | Si l’instrument présenté est refusé par le prestataire de services de paiement ou la banque, ou bien qu’il ne peut pas être utilisé pour ce paiement, la capture du paiement échoue avec l’erreur `payment_method_provider_decline`. | | `.*authorization_expired@.*` | Capturer manuellement un paiement autorisé | Si l’autorisation a déjà expiré, la capture du paiement autorisé échoue avec l’erreur `capture_charge_authorization_expired`. |