Introduction à l’API Stripe pour Java

Introduction à l'API Stripe pour Java

1. Vue d'ensemble

Stripe est un service basé sur le cloud queenables businesses and individuals to receive payments over the internet et offre à la fois des bibliothèques côté client (JavaScript et mobile natif) et des bibliothèques côté serveur (Java, Ruby, Node.js, etc.).

Stripe fournit une couche d'abstraction qui réduit la complexité de la réception des paiements. En conséquence,we don’t need to deal with credit card details directly – instead, we deal with a token symbolizing an authorization to charge.

Dans ce didacticiel, nous allons créer un exemple de projet Spring Boot qui permet aux utilisateurs de saisir une carte de crédit et, plus tard, débitera la carte d'un certain montant à l'aide desStripe API for Java.

2. Les dépendances

Pour utiliser lesStripe API for Java dans le projet, nous ajoutons la dépendance correspondante à nospom.xml:


    com.stripe
    stripe-java
    4.2.0

Nous pouvons trouverits latest version in the Maven Central repository.

Pour notre exemple de projet, nous allons exploiter lesspring-boot-starter-parent:


    org.springframework.boot
    spring-boot-starter-parent
    1.5.2.RELEASE

Nous utiliserons égalementLombok pour réduire le code standard, etThymeleaf sera le moteur de modèle pour fournir des pages Web dynamiques.

Puisque nous utilisons lesspring-boot-starter-parent pour gérer les versions de ces bibliothèques, nous n'avons pas besoin d'inclure leurs versions danspom.xml:


    org.springframework.boot
    spring-boot-starter-web


    org.springframework.boot
    spring-boot-starter-thymeleaf


    org.projectlombok
    lombok

Notez queif you’re using NetBeans, you may want to use Lombok explicitly with version 1.16.16, puisqu'un bogue dans la version de Lombok fournie avec Spring Boot 1.5.2 fait que NetBeans génère beaucoup d'erreurs.

3. Clés API

Avant de pouvoir communiquer avec Stripe et exécuter les frais de carte de crédit, nous devonsregister a Stripe account and obtain secret/public Stripe API keys.

Après avoir confirmé le compte, nous nous connecterons pour accéder auxStripe dashboard. Nous choisissons ensuite «Clés API» dans le menu de gauche:

Il y aura deux paires de clés secrètes / publiques -one for test and one for live. Laissons cet onglet ouvert afin que nous puissions utiliser ces clés plus tard.

4. Flux général

La charge de la carte de crédit se fera en cinq étapes simples, impliquant le front-end (exécuté dans un navigateur), le back-end (notre application Spring Boot) et le Stripe:

Un utilisateur accède à la page de paiement et clique sur «Payer avec la carte».
La boîte de dialogue de superposition de Stripe Checkout est présentée à l’utilisateur.
Un utilisateur confirme avec «Payer » ce qui:
- Envoyer la carte de crédit à Stripe
- Obtenir un jeton dans la réponse qui sera ajouté au formulaire existant
- Envoyez ce formulaire avec le montant, la clé publique API, l'e-mail et le jeton à notre serveur principal.
Notre back-end contacte Stripe avec le jeton, le montant et la clé API secrète.
Vérifications effectuées par l’arrière-plan Relever la réponse et fournir à l’utilisateur un retour sur l’opération.

Nous couvrirons chaque étape plus en détail dans les sections suivantes.

5. Formulaire de paiement

Stripe Checkout est uncustomizable, mobile ready, and localizable widget qui rend un formulaire pour introduire les détails de la carte de crédit. Grâce à l'inclusion et à la configuration de «checkout.js», il est responsable de:

Rendu du bouton "Payer avec la carte"
Rendu de la boîte de dialogue de superposition de paiement (déclenché après avoir cliqué sur "Payer par carte")
Validation de carte de crédit
Fonction «Mémoriser mes informations» (associe la carte à un numéro de téléphone portable)
Envoi de la carte de crédit à Stripe et remplacement par un jeton dans le formulaire joint (déclenché après avoir cliqué sur «Payer »)

Si nous devons exercer plus de contrôle sur le formulaire de paiement que celui fourni par Stripe Checkout, nous pouvons utiliserStripe Elements.

Nous analyserons ensuite le contrôleur qui prépare le formulaire, puis le formulaire lui-même.

5.1. Manette

Commençons par créer un contrôleur versprepare the model with the necessary information that the checkout form needs.

Tout d'abord, nous devonscopy the test version of our public key from the Stripe dashboard et l'utiliser pour définir STRIPE_PUBLIC_KEY en tant que variable d'environnement. Nous utilisons ensuite cette valeur dans le champstripePublicKey.

Nous définissons égalementcurrency etamount (exprimés en cents) manuellement ici uniquement à des fins de démonstration, mais dans une application réelle, nous pourrions définir un identifiant de produit / vente qui pourrait être utilisé pour récupérer le réel valeurs.

Ensuite, nous enverrons à la vue de paiement qui contient le formulaire de paiement:

@Controller
public class CheckoutController {

    @Value("${STRIPE_PUBLIC_KEY}")
    private String stripePublicKey;

    @RequestMapping("/checkout")
    public String checkout(Model model) {
        model.addAttribute("amount", 50 * 100); // in cents
        model.addAttribute("stripePublicKey", stripePublicKey);
        model.addAttribute("currency", ChargeRequest.Currency.EUR);
        return "checkout";
    }
}

En ce qui concerne les clés d’API Stripe, vous pouvez les définir en tant que variables d’environnement par application (test par rapport à vivre).

Comme pour tout mot de passe ou toute information sensible, il est préférable de garder la clé secrète hors de votre système de contrôle de version.

5.2. Form

Le bouton "Payer avec la carte" et la boîte de dialogue de paiement sont inclus en ajoutant un formulaire avec un script à l'intérieur, correctement configuré avec les attributs de données:


    
    Price:

Le script «checkout.js» déclenche automatiquement une demande à Stripe juste avant la soumission, qui ajoute ensuite le jeton Stripe et l'e-mail de l'utilisateur Stripe en tant que champs masqués «stripeToken» et «stripeEmail» .

Ceux-ci seront soumis à notre back-end avec les autres champs de formulaire. Les attributs de données de script ne sont pas soumis.

Nous utilisons Thymeleaf pour rendre les attributs «data-key», «data-amount» et «data-currency».

Le montant («data-amount») est utilisé uniquement à des fins d'affichage (avec «data-currency»). Son unité est exprimée en centimes de la devise utilisée, nous la divisons donc par 100 pour l'afficher.

La clé publique Stripe est transmise à Stripe après que l'utilisateur a demandé de payer. Do not use the secret key here, as this is sent to the browser.

6. Opération de charge

Pour le traitement côté serveur, nous devons définir le gestionnaire de demandes POST utilisé par le formulaire de paiement. Jetons un coup d'œil aux classes dont nous aurons besoin pour l'opération de charge.

6.1. Entité ChargeRequest

Définissons le POJOChargeRequest que nous utiliserons en tant qu'entité commerciale lors de l'opération de facturation:

@Data
public class ChargeRequest {

    public enum Currency {
        EUR, USD;
    }
    private String description;
    private int amount;
    private Currency currency;
    private String stripeEmail;
    private String stripeToken;
}

6.2. Un service

Écrivons une classeStripeService danscommunicate the actual charge operation to Stripe:

@Service
public class StripeService {

    @Value("${STRIPE_SECRET_KEY}")
    private String secretKey;

    @PostConstruct
    public void init() {
        Stripe.apiKey = secretKey;
    }
    public Charge charge(ChargeRequest chargeRequest)
      throws AuthenticationException, InvalidRequestException,
        APIConnectionException, CardException, APIException {
        Map chargeParams = new HashMap<>();
        chargeParams.put("amount", chargeRequest.getAmount());
        chargeParams.put("currency", chargeRequest.getCurrency());
        chargeParams.put("description", chargeRequest.getDescription());
        chargeParams.put("source", chargeRequest.getStripeToken());
        return Charge.create(chargeParams);
    }
}

Comme indiqué dans lesCheckoutController,the secretKey field is populated from the STRIPE_SECRET_KEY environment variable that we copied from the Stripe dashboard.

Une fois le service initialisé, cette clé est utilisée dans toutes les opérations de stripes suivantes.

L'objet retourné par la bibliothèque Stripe représente lescharge operation et contient des données utiles comme l'ID d'opération.

6.3. Manette

Enfin, écrivons lescontroller that will receive the POST request made by the checkout form and submit the charge to Stripe via nosStripeService.

Notez que le paramètre «ChargeRequest» est automatiquement initialisé avec les paramètres de requête «amount», «stripeEmail» et «stripeToken» inclus dans le formulaire:

@Controller
public class ChargeController {

    @Autowired
    private StripeService paymentsService;

    @PostMapping("/charge")
    public String charge(ChargeRequest chargeRequest, Model model)
      throws StripeException {
        chargeRequest.setDescription("Example charge");
        chargeRequest.setCurrency(Currency.EUR);
        Charge charge = paymentsService.charge(chargeRequest);
        model.addAttribute("id", charge.getId());
        model.addAttribute("status", charge.getStatus());
        model.addAttribute("chargeId", charge.getId());
        model.addAttribute("balance_transaction", charge.getBalanceTransaction());
        return "result";
    }

    @ExceptionHandler(StripeException.class)
    public String handleError(Model model, StripeException ex) {
        model.addAttribute("error", ex.getMessage());
        return "result";
    }
}

En cas de succès, nous ajoutons le statut, l'identifiant de l'opération, l'identifiant de la facturation et l'identifiant de la transaction de solde au modèle afin que nous puissions les montrer plus tard à l'utilisateur (chapitre 7). Ceci est fait pour illustrer certains des contenus descharge object.

NosExceptionHandler traiteront les exceptions de typeStripeException lancées pendant l'opération de charge.

Si nous avons besoin d'une gestion des erreurs plus fine, nous pouvons ajouter des gestionnaires séparés pour les sous-classes deStripeException, telles queCardException,RateLimitException ouAuthenticationException.

La vue «result» rend le résultat de l'opération de charge.

7. Affichage du résultat

Le code HTML utilisé pour afficher le résultat est un modèle Thymeleaf de base qui affiche le résultat d’une opération de facturation. L'utilisateur est envoyé ici par lesChargeController si l'opération de charge a réussi ou non:



    
        Result
    
    
        
        
            Success!
            Id.: 
            Status: 
            Charge id.: 
            Balance transaction id.: 
        
        Checkout again

En cas de succès, l'utilisateur verra quelques détails de l'opération de facturation:

En cas d'erreur, le message d'erreur renvoyé par Stripe sera présenté à l'utilisateur:

8. Conclusion

Dans ce didacticiel, nous avons montré comment utiliser l'API Stripe Java pour débiter une carte de crédit. À l'avenir, nous pourrions réutiliser notre code côté serveur pour servir une application mobile native.

Pour tester l'ensemble du flux de charge, nous n'avons pas besoin d'utiliser une vraie carte de crédit (même en mode test). Nous pouvons nous fier àStripe testing cards à la place.

L’opération de facturation est l’une des nombreuses possibilités offertes par l’API Java Stripe. The official API reference nous guidera à travers l'ensemble des opérations.

L'exemple de code utilisé dans ce didacticiel se trouve dans lesGitHub project.

TOC

Introduction à l’API Stripe pour Java