Accepter un paiement par prélèvement automatique ACH

Créez un objet Customer lorsque votre client crée un compte auprès de votre entreprise, ou récupérez l’objet Customer existant associé à cet utilisateur. L’association de l’ID de l’objet Customer à votre propre représentation interne d’un client vous permet de récupérer et d’utiliser ultérieurement les informations de paiement enregistrées. Ajoutez une adresse e-mail à l’objet Customer pour activer l’optimisation des utilisateurs connus de Financial Connections.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}}

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.

Côté serveur

Tout d’abord, créez un PaymentIntent sur votre serveur et spécifiez le montant à collecter et la devise usd. Si vous possédez déjà une autre intégration utilisant l’API Payment Intents, ajoutez us_bank_account à la liste des types de moyens de paiement de votre PaymentIntent. Sinon, précisez aussi l’ID de l’objet Customer.

Si vous souhaitez réutiliser le moyen de paiement dans le futur, fournissez le paramètre setup_future_usage avec la valeur off_session.

Par défaut, lors de la collecte des coordonnées bancaires, Financial Connections est utilisé pour vérifier instantanément le compte de votre client. Une option de secours comprenant la saisie manuelle du numéro de compte et la vérification par microversement peut être utilisée. Consultez la documentation relative à Financial Connections pour savoir comment configurer Financial Connections et accéder à des données de compte supplémentaires de façon à optimiser votre intégration ACH. Par exemple, vous pouvez utiliser Financial Connections pour consulter le solde d’un compte avant d’initier le paiement ACH.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account

Côté client

Le PaymentIntent renvoyé contient une clé secrète du client que vous pouvez envoyer au client pour une exécution sécurisée du processus de paiement au lieu de lui transmettre la totalité de l’objet PaymentIntent. Côté client, demandez un PaymentIntent à votre serveur et sauvegardez la clé secrète du client qu’il contient.

import UIKit
import StripePayments

class CheckoutViewController: UIViewController {
  var paymentIntentClientSecret: String?

  func startCheckout() {
      // Request a PaymentIntent from your server and store its client secret
  }
}

Le client peut quitter votre application pour s’authentifier (par exemple, dans Safari ou dans son application bancaire). Pour lui permettre de revenir automatiquement sur votre application après s’être authentifié, configurez un schéma d’URL personnalisé et configurez votre délégué d’application pour qu’il transmette l’URL au SDK. Stripe ne prend pas en charge les liens universels.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

Pour que le paiement aboutisse avec les prélèvements automatiques ACH, vous devez renseigner un nom de client et son adresse e-mail (facultatif). Dans votre application, collectez les informations de facturation requises auprès de votre client :

• Nom complet (prénom et nom)
• Adresse e-mail

Pour créer vos paramètres requis et appeler collectBankAccountForPayment, utilisez la fonction de classe collectUSBankAccountParams dans STPCollectBankAccountParams. Il est nécessaire d’inclure le nom du titulaire du compte dans le paramètre billing_details pour créer un PaymentMethod par prélèvement automatique ACH.

Créez une instance de STPBankAccountCollector pour appeler collectBankAccountForPayment afin de collecter les coordonnées bancaires, puis créez un PaymentMethod, et associez-le au PaymentIntent.

// Build params
let collectParams = STPCollectBankAccountParams.collectUSBankAccountParams(with: name, email: email)

// (optional) Configure the style
let style: STPBankAccountCollectorUserInterfaceStyle = .alwaysLight
let bankAccountCollector = STPBankAccountCollector(style: style)

// Calling this method will display a modal for collecting bank account information
bankAccountCollector.collectBankAccountForPayment(clientSecret: clientSecret,
                                                  returnURL: "https://your-app-domain.com/stripe-redirect",
                                                  params: collectParams,
                                                  from: self) { intent, error in
    guard let intent = intent else {
        // handle error
        return
    }
    if case .requiresPaymentMethod = intent.status {
        // Customer canceled the Financial Connections modal. Present them with other
        // payment method type options.
    } else if case .requiresConfirmation = intent.status {
        // We collected an account - possibly instantly verified, but possibly
        // manually-entered. Display payment method details and mandate text
        // to the customer and confirm the intent once they accept
        // the mandate.
    }
}

Cela charge une fenêtre modale sur la page qui gère la collecte et la vérification des coordonnées bancaires. Une fois le chargement terminé, le PaymentMethod est automatiquement associé au PaymentIntent.

Avant de pouvoir initier le paiement, vous devez obtenir l’autorisation de votre client. Pour ce faire, présentez-lui les conditions du mandat et demandez-lui de les accepter.

Pour vous conformer aux règles de la Nacha, vous devez obtenir l’autorisation d’initier le paiement auprès de votre client. Pour ce faire, présentez-lui les conditions du mandat et demandez-lui de les accepter. Pour en savoir plus, consultez la page sur les mandats.

Lorsque le client accepte les conditions du mandat, vous devez confirmer le PaymentIntent. Utilisez confirmPayment pour mener à bien le paiement une fois que le client a soumis le formulaire.

let paymentIntentParams = STPPaymentIntentParams(clientSecret: clientSecret,
                                            paymentMethodType: .USBankAccount)

STPPaymentHandler.shared().confirmPayment(
    paymentIntentParams, with: self
) { (status, intent, error) in
    switch status {
    case .failed:
        // Payment failed
    case .canceled:
        // Payment was canceled
    case .succeeded:
        // Payment succeeded
    @unknown default:
        fatalError()
    }
}

Sauf échec de l’opération, Stripe renvoie un objet PaymentIntent présentant l’un des états suivants :

Après avoir confirmé le PaymentIntent, un e-mail de confirmation du mandat et les coordonnées bancaires recueillies doivent être envoyés à votre client. Par défaut, Stripe gère cette étape, mais vous pouvez choisir d’envoyer des notifications personnalisées si vous préférez.

Tous les clients ne peuvent pas vérifier instantanément le compte bancaire. Cette étape ne s’applique que si votre client a choisi de se désinscrire du flux de vérification instantanée dans l’étape précédente.

Dans ce cas, Stripe envoie un microversement descriptor_code ou amount si un problème survient au cours de la vérification du compte bancaire. Ces microversements apparaissent sur le relevé en ligne du client sous 1 à 2 jours ouvrables.

• Code de libellé : Stripe envoie un microversement unique de 0,01 USD sur le compte bancaire du client avec un descriptor_code unique à 6 chiffres qui commence par SM. Votre client utilise cette chaîne pour vérifier son compte bancaire.
• Montant : Stripe envoie deux microversements distincts sur le compte bancaire du client avec un code de libellé indiquant ACCTVERIFY. Votre client utilise les montants de ces versements pour vérifier son compte bancaire.

Le résultat de l’appel de méthode confirmPayment dans la configuration précédente est un PaymentIntent avec l’état requires_action. Le PaymentIntent contient un champ next_action qui contient des informations utiles à la vérification.

Si vous avez fourni une adresse e-mail de facturation, Stripe utilise cette dernière pour notifier votre client de la date d’arrivée prévue des versements. L’e-mail envoyé inclut un lien vers la page de vérification hébergée par Stripe, sur laquelle il peut confirmer les montants des versements et effectuer la vérification.

Facultatif : Envoyer des notifications personnalisées par e-mail

Vous pouvez également envoyer des notifications personnalisées par e-mail à votre client. Après avoir configuré les e-mails personnalisés, vous devez préciser comment le client doit répondre à l’e-mail de vérification. Pour ce faire, choisissez une des options suivantes :

• Utilisez la page de vérification hébergée par Stripe. Pour ce faire, utilisez l’URL verify_with_microdeposits[hosted_verification_url] de l’objet next_action pour diriger votre client vers la procédure de vérification.

• Si vous préférez ne pas utiliser la page de vérification hébergée par Stripe, créez un formulaire dans votre application. Vos clients peuvent ensuite l’utiliser pour vous transmettre les montants des microversements et pour vérifier le compte bancaire à l’aide du SDK iOS.

  • Configurez le formulaire de manière à ce qu’il gère au moins le paramètre descriptor code, qui comporte une chaîne à 6 chiffres à des fins de vérification.
  • Stripe vous recommande également de configurer votre formulaire pour qu’il gère le paramètre amounts, car certaines banques utilisées par vos clients peuvent l’exiger.

  Les intégrations transmettent uniquement les paramètres descriptor_code ou amounts. Pour savoir lequel utilise votre intégration, vérifiez la valeur de verify_with_microdeposits[microdeposit_type] dans l’objet next_action.

// Use if you are using a descriptor code, do not use if you are using amounts
STPAPIClient.shared.verifyPaymentIntentWithMicrodeposits(clientSecret: clientSecret,
                                                         descriptorCode: descriptorCode,
                                                         completion: { intent, error in
})

// Use if you are using amounts, do not use if you are using descriptor code
STPAPIClient.shared.verifyPaymentIntentWithMicrodeposits(clientSecret: clientSecret,
                                                         firstAmount: firstAmount,
                                                         secondAmount: secondAmount,
                                                         completion: { intent, error in
})

Lorsque le compte bancaire est vérifié, Stripe renvoie l’objet PaymentIntent avec un status défini sur processing.

La vérification peut échouer pour différentes raisons. L’échec se produit de manière synchrone et vous en êtes informé par un message d’erreur.

{
  "error": {
    "code": "payment_method_microdeposit_verification_amounts_mismatch",
    "message": "The amounts provided do not match the amounts that were sent to the bank account. You have {attempts_remaining} verification attempts remaining.",
    "type": "invalid_request_error"
  }
}

Le prélèvement automatique ACH est un moyen de paiement à notification différée. Ceci signifie que pour recevoir une notification du succès ou de l’échec d’un paiement, il faut compter jusqu’à quatre jours ouvrables après le déclenchement du prélèvement sur le compte du client.

Initialement, le PaymentIntent que vous créez présente l’état processing. Une fois le paiement abouti, l’état du PaymentIntent passe de processing à succeeded.

Nous vous recommandons d’utiliser des webhooks afin de confirmer que le paiement a réussi et d’informer le client que le paiement a été effectué. Vous pouvez également afficher les événements sur le Dashboard Stripe.

Découvrez comment tester des scénarios avec des vérifications instantanées à l’aide de Financial Connections.

Envoyer des e-mails de transaction dans un environnement de test

Une fois que vous avez collecté les coordonnées bancaires et accepté un mandat, envoyez les courriels de confirmation du mandat et de vérification du microversement dans un environnement de bac à sable.

Si votre domaine est {domain} et que votre nom d’utilisateur est {username}, utilisez le format d’e-mail suivant pour envoyer des e-mails de transaction de test : {username}+test_email@{domain}.

Par exemple, si votre domaine est example.com et que votre nom d’utilisateur est info, utilisez le format info+test_email@example.com pour tester les paiements ACH Direct Debit. Ce format garantit que les e-mails sont acheminés correctement. Si vous n’incluez pas le suffixe +test_email, nous n’enverrons pas l’e-mail.

Numéros de comptes de test

Stripe fournit plusieurs numéros de compte de test et les tokens correspondants que vous pouvez utiliser pour vous assurer que votre intégration pour les comptes bancaires saisis manuellement est prête à passer en mode production.

Avant d’effectuer les transactions de test, vous devez vérifier tous les comptes de test pour lesquels le paiement aboutit ou échoue automatiquement. Pour ce faire, utilisez les codes de libellé ou les montants de microversements de test ci-dessous.

Tester des codes de libellé et des montants de microversements

Pour simuler différents scénarios, utilisez ces montants de microversements ou ces codes de libellé 0.01.

Comportement de règlement des tests

Les transactions de test sont réglées instantanément et ajoutées à votre solde de test disponible. Ce comportement diffère de celui du mode production, où les transactions peuvent prendre plusieurs jours pour être réglées dans votre solde disponible.