Введение в Stripe API для Java

1. обзор

Stripe - это облачная службаenables businesses and individuals to receive payments over the internet, которая предлагает как клиентские библиотеки (JavaScript и собственные мобильные), так и серверные библиотеки (Java, Ruby, Node.js и т. д.).

Stripe обеспечивает уровень абстракции, который уменьшает сложность приема платежей. В результатеwe don’t need to deal with credit card details directly – instead, we deal with a token symbolizing an authorization to charge.

В этом руководстве мы создадим образец проекта Spring Boot, который позволяет пользователям вводить кредитную карту, а позже будет взимать с карты определенную сумму, используяStripe API for Java.

2. зависимости

Чтобы использоватьStripe API for Java в проекте, мы добавляем соответствующую зависимость к нашемуpom.xml:


    com.stripe
    stripe-java
    4.2.0

Мы можем найтиits latest version in the Maven Central repository.

В нашем примере проекта мы будем использоватьspring-boot-starter-parent:


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

Мы также будем использоватьLombok для сокращения шаблонного кода, аThymeleaf будет механизмом шаблонов для доставки динамических веб-страниц.

Поскольку мы используемspring-boot-starter-parent для управления версиями этих библиотек, нам не нужно включать их версии вpom.xml:


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


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


    org.projectlombok
    lombok

Обратите внимание, чтоif you’re using NetBeans, you may want to use Lombok explicitly with version 1.16.16, поскольку ошибка в версии Lombok, поставляемой с Spring Boot 1.5.2, заставляет NetBeans генерировать множество ошибок.

3. API-ключи

Прежде чем мы сможем связаться со Stripe и произвести платежи по кредитной карте, нам нужноregister a Stripe account and obtain secret/public Stripe API keys.

После подтверждения учетной записи мы войдем в систему, чтобы получить доступ кStripe dashboard. Затем мы выбираем «API ключи» в боковом меню слева:

Будет две пары секретных / открытых ключей -one for test and one for live. Давайте оставим эту вкладку открытой, чтобы мы могли использовать эти ключи позже.

4. Общий поток

Снятие средств с кредитной карты будет выполнено в пять простых шагов, включая внешний интерфейс (запуск в браузере), внутренний интерфейс (наше приложение Spring Boot) и Stripe:

Пользователь заходит на страницу оформления заказа и нажимает кнопку «Оплатить картой».
Пользователю предоставляется диалоговое окно наложения Stripe Checkout, где заполняются данные кредитной карты.
Пользователь подтверждает «Pay <сумма>», который будет:
- Отправить кредитную карту Stripe
- Получить токен в ответе, который будет добавлен к существующей форме
- Отправьте эту форму с суммой, открытым ключом API, электронной почтой и токеном на наш сервер
Наш бэкэнд связывается со Stripe с токеном, суммой и секретным ключом API.
Бэк-энд проверяет чередующийся ответ и предоставляет пользователю обратную связь об операции.

Мы рассмотрим каждый шаг более подробно в следующих разделах.

5. Форма оформления заказа

Stripe Checkout - этоcustomizable, mobile ready, and localizable widget, который отображает форму для ввода данных кредитной карты. Благодаря включению и настройке «checkout.js» он отвечает за:

Отображение кнопки «Оплатить картой»
Отображение диалогового окна платежного оверлея (запускается после нажатия кнопки «Оплатить картой»)
Проверка кредитной карты
Функция «Запомнить меня» (связывает карту с номером мобильного телефона)
Отправьте кредитную карту в Stripe и замените ее токеном в прилагаемой форме (активируется после нажатия кнопки «Оплатить <сумма>»)

Если нам нужно осуществлять больший контроль над формой оформления заказа, чем это предусмотрено Stripe Checkout, мы можем использоватьStripe Elements.

Далее мы проанализируем контроллер, который готовит форму, а затем саму форму.

5.1. контроллер

Начнем с создания контроллераprepare the model with the necessary information that the checkout form needs.

Во-первых, нам потребуетсяcopy the test version of our public key from the Stripe dashboard и использовать его для определения STRIPE_PUBLIC_KEY как переменной среды. Затем мы используем это значение в полеstripePublicKey.

Мы также вручную устанавливаемcurrency иamount (выраженные в центах) здесь просто для демонстрационных целей, но в реальном приложении мы могли бы установить идентификатор продукта / продажи, который может использоваться для получения фактического ценности.

Затем мы перейдем к представлению оформления заказа, содержащему форму оформления заказа:

@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";
    }
}

Что касается ключей Stripe API, вы можете определить их как переменные среды для каждого приложения (тест или жить).

Как и в случае с любым паролем или конфиденциальной информацией, лучше не использовать секретный ключ в вашей системе контроля версий.

5.2. Form

Кнопка «Оплатить картой» и диалоговое окно оформления заказа включают добавление формы со скриптом внутри, правильно настроенной с помощью атрибутов данных:


    
    Price:

Сценарий «checkout.js» автоматически запускает запрос к Stripe прямо перед отправкой, который затем добавляет токен Stripe и адрес электронной почты пользователя Stripe как скрытые поля «stripeToken» и «stripeEmail» .

Они будут отправлены на наш сервер вместе с другими полями формы. Атрибуты данных скрипта не передаются.

Мы используем Thymeleaf для визуализации атрибутов «data-key», «data-amount» и «data-currency«.

Сумма («data-amount») используется только для целей отображения (вместе с «data-currency»). Единица измерения - центы используемой валюты, поэтому мы делим ее на 100, чтобы отобразить.

Открытый ключ Stripe передается Stripe после того, как пользователь просит оплатить. Do not use the secret key here, as this is sent to the browser.с

6. Зарядка

Для обработки на стороне сервера нам нужно определить обработчик запроса POST, используемый формой оформления заказа. Давайте посмотрим на классы, которые нам понадобятся для операции заряда.

6.1. Сущность ChargeRequest

Давайте определим POJOChargeRequest, который мы будем использовать как бизнес-объект во время операции начисления:

@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. обслуживание

Давайте запишем классStripeService вcommunicate 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);
    }
}

Как было показано вCheckoutController,the secretKey field is populated from the STRIPE_SECRET_KEY environment variable that we copied from the Stripe dashboard.

После инициализации службы этот ключ используется во всех последующих операциях Stripe.

Объект, возвращаемый библиотекой Stripe, представляетcharge operation и содержит полезные данные, такие как идентификатор операции.

6.3. контроллер

Наконец, давайте запишемcontroller that will receive the POST request made by the checkout form and submit the charge to Stripe через нашStripeService.

Обратите внимание, что параметр «ChargeRequest» автоматически инициализируется параметрами запроса «amount», «stripeEmail» и «stripeToken», включенными в форму:

@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";
    }
}

В случае успеха мы добавляем в модель статус, идентификатор операции, идентификатор начисления и идентификатор транзакции сальдо, чтобы мы могли позже показать их пользователю (раздел 7). Это сделано, чтобы проиллюстрировать некоторую часть содержимогоcharge object.

НашExceptionHandler будет иметь дело с исключениями типаStripeException, которые возникают во время операции зарядки.

Если нам нужна более детальная обработка ошибок, мы можем добавить отдельные обработчики для подклассовStripeException, таких какCardException,RateLimitException илиAuthenticationException.

Представление «result» отображает результат операции зарядки.

7. Отображение результата

HTML-код, используемый для отображения результата, является базовым шаблоном Thymeleaf, который отображает результат операции начисления. ChargeController отправляет сюда пользователя, независимо от того, была ли операция зарядки успешной или нет:



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

В случае успеха пользователь увидит некоторые детали операции зарядки:

В случае ошибки пользователю будет выдано сообщение об ошибке, возвращаемое Stripe:

8. Заключение

В этом руководстве мы показали, как использовать Stripe Java API для снятия средств с кредитной карты. В будущем мы могли бы повторно использовать наш серверный код для обслуживания собственного мобильного приложения.

Для проверки всего потока платежей нам не нужно использовать настоящую кредитную карту (даже в тестовом режиме). Вместо этого мы можем полагаться наStripe testing cards.

Операция зарядки - одна из многих возможностей, предлагаемых Java-интерфейсом Stripe. The official API reference проведет нас через весь набор операций.

Образец кода, использованный в этом руководстве, можно найти в папкеGitHub project.

TOC

Введение в Stripe API для Java