Adyen for Java开发人员
#java #payment #integration

在当今的数字时代，通过API（应用程序编程界面）连接不同应用程序的能力对于任何现代平台都是必不可少的。 API允许设计复杂的工作流程，从而在需要交换数据并提供服务的系统之间进行通信。

开发人员可以使用不同的语言和框架直接消费剩余的API，但库的采用是创建无摩擦集成的最有效途径，从而提高生产力和开发人员的经验。

在以前的blog中，我们解释了使用Adyen API库的好处。现在，让我们更具体地探索Java开发人员可用的选择和优势。

在本文中..
•发现Adyen Java库，最新版本中的新内容，以及如何引导新应用程序或升级现有的应用程序。

Adyen Java图书馆

Adyen Java库是提供给Java开发人员或将与Adyen API合作的Java开发人员的工具包。它使他们能够专注于用例及其功能方面，而图书馆负责必要的基础工作，例如连接设置，安全功能（身份验证，加密和令牌化），验证，异常处理等等。

库为我们每个公共API的包装器都包含文档。无论您是要实施付款流，平台集成，发行，资本管理还是API管理您只需要使用此库。当您扩大集成和访问新产品或服务的范围时，库已经设置并且附加代码很小。

好处

Java库带来了Java生态系统典型的以下优势：

  • 轻松访问，可在Maven Central上获得 使用软件包以确保封装并避免姓名冲突
  • 内置JSON支持GSON
  • 自定义异常类（apiexception）提供一致的异常处理
  • 依赖关系管理：使用dependerabot或翻新新的Adyen Java库版本
  • 全面的单元测试覆盖范围：检查单元测试以查看如何调用服务并定义模型的示例
  • 内置的HTTP客户端（具有额外代理支持），可以选择覆盖和使用您自己的实现。

支持的API

所有Adyen产品在Java库的最新版本中得到支持。

  • 在线付款：您需要处理付款和任何高级用例所需的一切：结帐，付款，经常付款
  • 销售点：销售点（POS）付款终端的管理
  • 管理：公司和商家帐户的配置，商店，付款终端
  • 平台和金融产品：与Adyen合作进行平台。帐户结构，入职，付款流，嵌入式金融服务

Java库中的新内容

Java Library V20升级提供了许多新功能以及一些重大改进。

重大的重新设计可能是最值得注意的变化，因为它使图书馆与Adyen API目录和命名约定相一致。此更新使您能够快速找到与API相对应的相关Java服务（即使用Checkout API时的结帐服务）。通过在Adyen文档，API资源管理器和代码样本中保持一致性，您可以轻松找到所需的信息。

另一个重大变化是采用OpenAPI驱动的代码生成。现在使用OpenAPI Generator生成了映射请求和响应有效载荷的Java类，以确保代码符合合同（即规范），从而避免了错误和不一致。

还有其他有价值的改进，以确保图书馆全面（所有API版本都更新到最新版本，对平台和嵌入式金融服务都有支持）， fast （提供JSON处理的内置方法）和 Easy （添加适配器类映射每个付款方式）。

入门

Adyen Java库需要最低设置。确保匹配先决条件（Java 11，有效的API键），然后使用您喜欢的构建工具在Java项目中添加依赖项。

maven 

<dependency>
  <groupId>com.adyen</groupId>
  <artifactId>adyen-java-api-library</artifactId>
  <version>20.0.0</ver

gradle 

dependencies {
  implementation 'com.adyen:adyen-java-api-library:20.0.0'
}

设置将访问Adyen服务的客户端

// Setup Client and Service
Client client = new Client("Your X-API-KEY", Environment.TEST);

// PaymentsApi service
PaymentsApi paymentsApi = new PaymentsApi(client);

使用相关服务和模型访问该功能，例如，在使用结帐时，您可以获取可用付款方式的列表：

PaymentMethodsRequest paymentMethodsRequest = new PaymentMethodsRequest();
paymentMethodsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
PaymentMethodsResponse resp = paymentsApi.paymentMethods(paymentMethodsRequest);

// print available payment methods
resp.getPaymentMethods().stream().forEach(System.out::println);

使用管理API（即生成客户端密钥）时该方法相似：

// Management ClientKeyMerchantLevel service
ClientKeyMerchantLevel merchantLevel = new ClientKeyMerchantLevel(client);

// generate Client Key
GenerateClientKeyResponse resp = merchantLevel.generateNewClientKey("YOUR_MERCHANT_ACCOUNT", "YOUR_API_CREDENTIAL_ID");

System.out.println(resp.getClientKey());

使用Webhooks

Adyen Java库为Webhooks提供了支持，Webhooks是Adyen平台的重要功能。 Java库通过提供传入有效载荷（NotificationRequeStiTem）的模型以及辅助类（HMACVALIDATOR）来验证HMAC签名来简化这一点。

// YOUR_HMAC_KEY from the Customer Area
String hmacKey = "YOUR_HMAC_KEY";
String notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
HMACValidator hmacValidator = new HMACValidator();

NotificationHandler notificationHandler = new NotificationHandler();
NotificationRequest notificationRequest = notificationHandler.handleNotificationJson(notificationRequestJson);

// fetch first (and only) NotificationRequestItem
var notificationRequestItem = notificationRequest.getNotificationItems().stream().findFirst();

if (notificationRequestItem.isPresent()) {
    // Handle the notification
    if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) {
     // Process the notification based on the eventCode
 // …
    } else {
// Non valid NotificationRequest
 throw new RuntimeError("Invalid HMAC signature");
    }
}

Image description

您的应用程序是否已经使用了Adyen Java库？您想使用此最新版本吗？那么本节是给您的。

Adyen Java库V20带来了许多新功能，但同时引入了几个破裂的变化。尽管影响现有的工作代码从来都不是个好消息，但有时需要设计设计。库的重新设计，代码生成和许多其他改进正在解决矛盾之处并删除旧版代码。

新版本可以更好地帮助您实施工作流程和用例，并允许您轻松地集成新产品和功能在Adyen平台上可用时。

迁移您的代码

所有Java模型都是基于OpenAPI规范创建的，该规范会导致各种修改，例如软件包，类和字段的重新定位和重命名。

通用模型（即地址，姓名，bankAccount等）不再共享。每个软件包都定义了所需的模型。尽管这会导致Java类的重复，但它确保了对服务的良好封装。

通知已重命名为webhooks，例如，类GenericNotification现在是GenericWebhook（注意，此类包括您的应用程序可能使用的常数），并且NotificationHookhookler已成为Webhookhookhookhandler。

。

如果您使用 Checkout API 您需要考虑以下更改：

  • 单个结帐类已被删除，以为每个结帐功能提供不同的服务类别：PaymentsAPI，Recurringapi，修改，修改等。每个服务都对应于结帐API的功能（sub-folder）（请参阅API（请参阅API）探索者）确保库与API之间的一致性。
  • com.adyen.model.amount现在是com.adyen.model.checkout.amount
  • com.adyen.model.checkout.details.storepayment方法详细信息现在是com.adyen.model.checkout.Checkout.storepayment方法详细信息
  • PaymentsRequest已更名为PaymentRequest，PaymentsResponse已更名为PaymentResponse
  • 已删除了几种辅助方法（Setamountdata，setCarddata，Isaushorited，getCardholdName），以使Java模型仅提供getter/setter方法，并始于OpenAPI规范和API Explorer文档。

格森

另一个重大变化是引入GSON作为首选的JSON处理框架。这应该对应用程序透明，因为该库负责提供将JSON有效载荷转换为Java对象的序列化和避免逻辑。

您可以在每个模型中找到执行JSON处理的方法：

public static CardDetailsRequest fromJson(String jsonString) throws IOException {
   return JSON.getGson().fromJson(jsonString, CardDetailsRequest.class);
 }


public String toJson() {
   return JSON.getGson().toJson(this);
 }
}

在处理webhooks的情况下，您可以利用内置方法，例如：

@PostMapping("/webhooks/notifications")
public ResponseEntity<String> webhooks(@RequestBody  ) throws Exception {
  // from JSON string to object
  var notificationRequest = NotificationRequest.fromJson(json);

  // consume event

升级重复的付款样本

让我们看一个用例，以及将现有应用程序升级到Adyen Java Library v20时该怎么办。

在GitHub上，您可以找到一个Java示例应用程序，该应用程序演示了如何实施付款订阅。这是提供音乐订阅服务的网站的简化版本。基本上有2个流：

  • 购物者可以购买订阅，保存重复付款的卡详细信息（又名Tokenization）
  • 网站管理员可以代表购物者付款（例如，在订阅订阅时每月），并可选地到期

Image description
第一步是更新应用程序中的依赖项版本。它使用gradle，因此我们需要在build.gradle中更改theadyen-java-library版本

implementation 'com.adyen:adyen-java-api-library:20.0.0'

新版本（如上所述）已重构包和类，因此我们需要更新几个导入并用PaymentsAPI替换结帐类：

import com.adyen.model.checkout.Amount;
import com.adyen.model.checkout.CreateCheckoutSessionRequest;
import com.adyen.model.checkout.CreateCheckoutSessionResponse;
import com.adyen.service.checkout.PaymentsApi;

@RestController
@RequestMapping("/api")
public class SubscriptionResource {

// PaymentsApi service class 
private final PaymentsApi paymentsApi;
// …

其他类和更新的引用：

  • PaymentsRequest和PaymentmessResponse已重命名为PaymentRequest和Payment Response：进口和类名必须更新
  • 定义付款方式的类称为CheckoutPaymentMethod

修订的代码段，使用令牌看起来像：

PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.setMerchantAccount(“YOUR_MERCHANT_ACCOUNT”);
paymentRequest.setAmount
(new Amount().currency("EUR").value(1199L));
paymentRequest.setReference(orderRef);
paymentRequest.setShopperInteraction(PaymentRequest.ShopperInteractionEnum.CONTAUTH);
paymentRequest.setShopperReference(Storage.SHOPPER_REFERENCE);
paymentRequest.setRecurringProcessingModel(PaymentRequest.RecurringProcessingModelEnum.SUBSCRIPTION);
paymentRequest.setPaymentMethod(new CheckoutPaymentMethod(new StoredPaymentMethodDetails().storedPaymentMethodId(“abc123”));

PaymentResponse response = this.paymentsApi.payments(paymentRequest);

最终，我们需要更新Webhook处理程序，以利用内置方法，以将JSON有效载荷置于Java对象

// processing incoming webhooks
@PostMapping("/webhooks/notifications")
public ResponseEntity<String> webhooks(@RequestBody String json) 
throws Exception {


   // from JSON string to object
   NotificationRequest notificationRequest = NotificationRequest.fromJson(json);


// fetch first (and only) NotificationRequestItem
Optional<NotificationRequestItem> notificationRequestItem = 
notificationRequest.getNotificationItems().stream().findFirst();
if (notificationRequestItem.isPresent()) {
// consume webhooks
// ………

下一步

是时候进行编码了。

对于新的起动器而言，最简单的方法是查看Adyen Java库的最简单方法是查看Java Spring sample application。该示例使用Web插入和Java库来演示结帐用例。

使用one click using Gitpod运行该应用程序，然后浏览源代码，以了解如何获得可用的付款方式，执行交易并处理Webhooks提供的异步事件。

如果您正在升级现有应用程序，则上面的升级部分将指导您进行更改以及如何处理它们。当然，我们准备为您提供帮助，以防万一不清楚或需要其他详细信息。

我们期待听到您有关图书馆的反馈，缺少或可以改进的内容。加入我们的survey，让我们知道如何改善它们并使您的开发人员体验更好。