Paiements Cash App Pay

Ajoutez la prise en charge de Cash App Pay à votre intégration.

Web

Mobile

Nous vous recommandons d’implémenter l’intégration du tunnel de paiement personnalisé. Le tunnel de paiement personnalisé vous permet d’ajouter facilement Cash App Pay et d’autres moyens de paiement à votre intégration. L’acceptation de Cash App Pay à l’aide d’une intégration API directe consiste à :

Créer un objet PaymentIntent pour suivre un paiement.
Soumettre le paiement à Stripe pour traitement.
Authentifier le paiement (via une redirection d’application mobile ou un code QR).
Gérer les événements post-paiement pour rediriger le client après la réussite ou l’échec d’une commande.

Configurer Stripe
Côté serveur

Pour commencer, vous devez créer un compte Stripe. Inscrivez-vous maintenant.

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

Créer un PaymentIntent
Côté serveur

Un PaymentIntent est un objet qui représente votre intention d’encaisser le paiement d’un client et qui suit le cycle de vie du processus de paiement étape par étape.

Pour créer un PaymentIntent sur votre serveur :

Indiquez le montant à encaisser et la devise.
Ajoutez cashapp à la liste des types de moyens de paiement pour votre PaymentIntent. Assurez-vous que Cash App Pay est activé dans le Dashboard.

Récupérer la clé secrète du client

Le PaymentIntent contient une clé secrète à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client.

Récupérez la clé secrète du client à partir d’un endpoint sur votre serveur, à l’aide de la fonction fetch du navigateur. Cette approche est recommandée si votre côté client est une application d’une seule page, en particulier si elle repose sur un framework front-end moderne tel que React. Créez l’endpoint de serveur qui gère la clé secrète du client :

Récupérez ensuite la clé secrète du client à l’aide JavaScript côté client :

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Soumettre le paiement à Stripe et authentifier les transactions côté client

À cette étape, vous effectuerez des paiements Cash App Pay côté client avec Stripe.js. Pour authentifier une transaction, vous devez rediriger votre acheteur vers Cash App.

Intégrez le script Stripe.js à votre page de paiement en l’ajoutant entre les balises head de votre fichier HTML.

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

Créez une instance de Stripe.js avec le code JavaScript suivant sur votre page de paiement :

client.js
// 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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Utilisez stripe.confirmCashappPayment pour confirmer le PaymentIntent côté client.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Pass the clientSecret obtained from the server in step 2 as the first argument
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
  );
});

Mise en garde

confirmCashappPayment redirige uniquement les navigateurs mobiles vers votre URL return_url, mais pas les navigateurs d’ordinateur de bureau. Vous pouvez rediriger manuellement les clients utilisant un navigateur de bureau vers votre URL de redirection une fois la promesse renvoyée résolue.

Les clients peuvent authentifier les transactions Cash App Pay avec des applications mobiles ou de bureau. Le client utilisé par le client détermine la méthode d’authentification après l’appel de confirmCashappPayment.

Après avoir appelé confirmCashappPayment, les clients sont redirigés vers Cash App pour approuver ou refuser le paiement. Une fois qu’ils ont autorisé le paiement, ils sont redirigés vers la return_url du Payment Intent. Stripe ajoute payment_intent, payment_intent_client_secret, redirect_pm_type et redirect_status comme paramètres de requête d’URL (ainsi que tous les paramètres de requête existants dans la return_url).

Une session d’authentification expire au bout de 60 minutes, puis l’état du PaymentIntent repasse à require_payment_method. Après le changement d’état, le client voit s’afficher une erreur de paiement et doit recommencer le processus de paiement.

FacultatifGérer la redirection et l'authentification manuellement

Nous vous recommandons d’utiliser Stripe.js pour gérer les redirections et l’authentification avec confirmCashappPayment. Cependant, vous pouvez également gérer les redirections et l’authentification manuellement sur votre serveur.

Spécifiez handleActions: false dans l’appel confirmCashappPayment.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Set the clientSecret here you got in Step 2
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method_data: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
    {
      handleActions: false
    },
  ).then((result) => {
    if (result.error) {
      // Display error to your customer.
    } else if (result.paymentIntent.status === "requires_action") {
      const nextAction = result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code;
      const expiresAt = nextAction.qr_code.expires_at;
      if (IS_MOBILE) {
        // This URL redirects the customer to Cash App to approve or decline the payment.
        const mobileAuthUrl = nextAction.mobile_auth_url;
      } else if (IS_DESKTOP) {
        // Render the QR code and display it to the customer using the below image source.
        const imageUrlSvg = nextAction.qr_code.image_url_svg;
        const imageUrlPng = nextAction.qr_code.image_url_png;
      }
    }
  });
});

Si un client paie avec Cash App Pay sur un appareil mobile :

Redirigez le client vers l’URL définie comme propriété result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code.mobile_auth_url. Il est alors redirigé vers Cash App pour autoriser ou refuser le paiement.
Une fois que le client a autorisé le paiement, il est redirigé vers la return_url du Payment Intent. Stripe ajoute payment_intent, payment_intent_client_secret, redirect_pm_type et redirect_status comme paramètres de requête d’URL (ainsi que tous les paramètres de requête existants dans la return_url).
Notez que l’URL mobile_auth_url expire au bout de 30 secondes. Si le client n’est pas redirigé vers mobile_auth_url avant son expiration, appelez stripe.retrievePaymentIntent pour obtenir une nouvelle URL mobile_auth_url.

FacultatifAutorisation et capture distinctes

Vous pouvez séparer l’autorisation de la capture pour créer un paiement maintenant, mais capturer les fonds ultérieurement. Stripe annule le PaymentIntent et envoie un événement payment_intent.canceled si le paiement n’est pas capturé dans un délai de 7 jours.

Si vous savez que vous ne pouvez pas capturer le paiement, nous vous recommandons d’annuler le PaymentIntent plutôt que d’attendre la fin de la période de 7 jours.

Indiquez à Stripe d’autoriser uniquement le montant

Pour indiquer que vous souhaitez séparer l’autorisation de la capture, définissez capture_method sur manual lors de la création du PaymentIntent. Ce paramètre indique à Stripe d’autoriser uniquement le montant sur le compte Cash App Pay du client.

Capturez les fonds

Une fois l’autorisation réussie, l’état du PaymentIntent passe à requires_capture. Pour capturer les fonds autorisés, faites une demande de capture du PaymentIntent.

Le montant total autorisé est capturé par défaut. Vous pouvez également spécifier le montant à capturer amount_to_capture, qui peut être inférieur ou égal au total.

Facultatif Annuler l’autorisation

Si vous devez annuler une autorisation, vous pouvez annuler le PaymentIntent.

FacultatifGérer les événements post-paiement

Stripe envoie un événement payment_intent.succeeded à l’issue du paiement. Utilisez le Dashboard, un webhook 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.

Gérer les événements manuellement dans le Dashboard
Utilisez le Dashboard pour afficher vos paiements de test dans le Dashboard, envoyer des reçus par e-mail, gérer les virements ou réessayer les paiements échoués.
Créer un webhook personnalisé
Créez un gestionnaire de webhook personnalisé pour écouter les événements et créer des tunnels de paiement asynchrones personnalisés. Testez et déboguez votre intégration de webhook localement avec la CLI Stripe.
Intégrer une application prédéfinie
Gérez les événements commerciaux courants, tels que l’automatisation ou le marketing et les ventes, en intégrant une application partenaire.

Tester votre intégration

Pour tester votre intégration, choisissez Cash App Pay comme moyen de paiement et appuyez sur Payer. Pendant le test, vous serez redirigé vers une page de paiement de test où vous pouvez autoriser ou refuser le paiement.

En mode production, le fait d’appuyer sur Payer vous redirige vers l’application mobile Cash App. Vous n’avez pas la possibilité d’approuver ou de refuser le paiement dans l’application Cash. Le paiement est automatiquement approuvé après la redirection.

Échecs de paiement

Cash App Pay utilise plusieurs données pour décider du refus d’une transaction (par exemple, si son modèle d’IA a détecté un risque élevé de fraude pour la transaction, ou si le client a révoqué votre autorisation de débit dans Cash App).

Dans ce cas, le PaymentMethod est détaché et le statut de l’objet PaymentIntent passe automatiquement à requires_payment_method

Hormis le refus d’un paiement, dans le cas d’un PaymentIntent Cash App Pay à l’état requires_action, les clients doivent effectuent le paiement sous 10 minutes une fois qu’ils ont été redirigés vers Cash App. En l’absence d’action sous 10 minutes, le PaymentMethod est détaché et l’état de l’objet PaymentIntent passe automatiquement à requires_payment_method.

Dans ce cas, le composant Payment Element affiche des messages d’erreur et demande à votre client de réessayer avec un autre moyen de paiement.

Codes d’erreur

Le tableau suivant détaille les codes d’erreur courants et les actions recommandées :

Code d’erreur	Action recommandée
`payment_intent_invalid_currency`	Saisissez la devise appropriée. Cash App Pay prend uniquement en charge l’`usd`.
`missing_required_parameter`	Consultez le message d’erreur pour en savoir plus sur le paramètre requis.
`payment_intent_payment_attempt_failed`	Ce code peut apparaître dans le champ last_payment_error.code d’un PaymentIntent. Consultez le message d’erreur pour connaître la raison détaillée de l’échec et obtenir une suggestion de traitement de l’erreur.
`payment_intent_redirect_confirmation_without_return_url`	Spécifiez une URL `return_url` lors de la confirmation d’un PaymentIntent avec Cash App Pay.