3DS2 iOS SDK

通过此 SDK，您可以通过 Adyen 接受 3D Secure 2.0 付款。

安装

此 SDK 可通过 CocoaPods、Carthage 或手动安装获取。

CocoaPods

  1. 将 pod 'Adyen3DS2' 添加到您的 Podfile 中。
  2. 运行 pod install。

Carthage

  1. 将 github "adyen/adyen-3ds2-ios" 添加到您的 Cartfile 中。
  2. 运行 carthage update。
  3. 按照 Carthage Readme 中的描述，将 framework 与您的 target 链接。

动态 xcFramework

将动态 XCFramework/Dynamic/Adyen3DS2.xcframework 拖到您通用 target 设置中的 Frameworks, Libraries, and Embedded Content 部分。 当询问时，选择“如果需要则复制项目”。

静态 xcFramework

  1. 将静态 XCFramework/Static/Adyen3DS2.xcframework 拖到您通用 target 设置中的 Frameworks, Libraries, and Embedded Content 部分。
  2. 确保未嵌入静态 Adyen3DS2.xcframework。
  3. 在 Adyen3DS2.xcframework 内部选择 Adyen3DS2.bundle，并选中“如果需要则复制项目”，然后选择“添加”。
  4. 隐私清单应包含/合并在您的应用 bundle 中。

Swift Package Manager

  1. 按照 Apple 的 Adding Package Dependencies to Your App 指南，了解如何添加 Swift Package 依赖项。
  2. 使用 https://github.com/Adyen/adyen-3ds2-ios 作为仓库 URL。
  3. 指定版本至少为 2.2.1。

⚠️ 使用 Swift Package Manager 添加 Adyen3DS2 时，请务必使用 Xcode 12.0+。

⚠️ Xcode 12.0 和 12.1 的 Swift Package Manager 在导入二进制依赖项时存在 已知问题。 此处描述了一种解决方法。

用法

创建交易

首先，使用从您调用 /authorise 获取的附加数据创建 ADYServiceParameters 的实例。 然后，使用 ADYService 上的类方法创建一个新服务。 此服务可用于创建新交易。

ADYServiceParameters *copy = [[ADYServiceParameters alloc] initWithDirectoryServerIdentifier:... // Retrieved from Adyen.
                                                                    directoryServerPublicKey:... // Retrieved from Adyen.
                                                             directoryServerRootCertificates:...]; // Retrieved from Adyen.

[ADYService serviceWithParameters:parameters appearanceConfiguration:nil completionHandler:^(ADYService *service) {
    NSError *error = nil;
    ADYTransaction *transaction = [service transactionWithMessageVersion:@"2.1.0" error:&error];
    if (transaction) {
        ADYAuthenticationRequestParameters *authenticationRequestParameters = [transaction authenticationRequestParameters];
        // Submit the authenticationRequestParameters to /authorise3ds2.
    } else {
        NSString *errorRepresentation = [error base64Representation];
        // Submit `errorRepresentation` to [Adyen backend](https://docs.adyen.com/api-explorer/Payment/64/post/authorise3ds2).
    }
}];

在您调用 Adyen 后端 时使用 transaction 的 authenticationRequestParameters。

⚠️ [ADYService transactionWithMessageVersion:error:] 需要传递消息版本，请填写与 AReq 中相同的消息版本，您应该能够从 3DS 服务器在启动付款时的响应中获取消息版本，如果您使用 Adyen 3DS 服务器，请参阅 文档。

⚠️ 保持对您的 ADYTransaction 实例的引用，直到交易完成。

⚠️ 如果您的应用程序支持 Mac catalyst 或 iPad OS 多窗口/多场景，则建议在场景之间共享 ADYTransaction/ADYService 对象，以防购物者在一个窗口上开始交易并在交易进行中切换到另一个窗口。

执行质询

如果需要质询，请使用从您调用 Adyen 后端 获取的附加数据中的值创建 ADYChallengeParameters 的实例。

NSDictionary *additionalData = ...; // Retrieved from Adyen.
ADYChallengeParameters *parameters = [ADYChallengeParameters challengeParametersWithServerTransactionIdentifier:additionalData[@"threeds2.threeDS2ResponseData.threeDSServerTransID"]
                                                                                         threeDSRequestorAppURL:[NSURL URLWithString:@"{YOUR_APP_URL}"] // Or nil if for example you're using protocol version 2.1.0
                                                                                       ACSTransactionIdentifier:additionalData[@"threeds2.threeDS2ResponseData.acsTransID"]
                                                                                             ACSReferenceNumber:additionalData[@"threeds2.threeDS2ResponseData.acsReferenceNumber"]
                                                                                               ACSSignedContent:additionalData[@"threeds2.threeDS2ResponseData.acsSignedContent"]];

⚠️ 由于最近对 3D Secure 协议的更新，我们强烈建议您将 threeDSRequestorAppURL 参数作为 通用链接 提供。

使用这些质询参数对您先前创建的 transaction 执行质询

[transaction performChallengeWithParameters:parameters completionHandler:^(ADYChallengeResult *result, NSError *error) {
    if (result) {
        NSString *transactionStatus = [result transactionStatus];
        // Submit the transactionStatus to /authorise3ds2.
    } else if (error) {
        // An error occurred.
        
        // collect the error context information if available
        NSString* _Nullable serverTransactionIdentifier = [[error userInfo] valueForKey:ADYProtocolErrorServerTransactionIdentifierKey];
        NSString* _Nullable acsTransactionIdentifier = [[error userInfo] valueForKey:ADYProtocolErrorACSTransactionIdentifierKey];
        NSString* _Nullable sdkTransactionIdentifier = [[error userInfo] valueForKey:ADYProtocolErrorSDKTransactionIdentifierKey];
        NSString* _Nullable errorDetails = [[error userInfo] valueForKey:ADYProtocolErrorDetailKey];
        NSString* _Nullable errorDomain = [[error userInfo] valueForKey:ADYProtocolErrorDomain];
        NSString* _Nullable errorLocalizedDescription = [[error userInfo] valueForKey:NSLocalizedDescriptionKey];
        
        NSString *errorRepresentation = [error base64Representation];
        // Submit `errorRepresentation` to [Adyen backend](https://docs.adyen.com/api-explorer/Payment/64/post/authorise3ds2)

        // Submit the transactionStatus = "U" to [Adyen backend](https://docs.adyen.com/api-explorer/Payment/64/post/authorise3ds2).
    } else {
        // Should never happen
    }
}];

当质询成功完成后，在您第二次调用 Adyen 后端 时，在 result 中提交 transactionStatus。

自定义 UI

SDK 提供了一些自定义选项，以确保质询流程的 UI 适合您应用程序的外观和风格。 这些自定义选项可通过 ADYAppearanceConfiguration 类获得。 要使用它们，请创建 ADYAppearanceConfiguration 的实例，配置所需的属性，并在初始化 ADYService 期间传递它。

例如，要将“Continue”按钮设为红色并更改其圆角半径

ADYAppearanceConfiguration *appearanceConfiguration = [ADYAppearanceConfiguration new];
[[appearanceConfiguration buttonAppearanceForType:ADYAppearanceButtonTypeContinue] setBackgroundColor:[UIColor redColor]];
[[appearanceConfiguration buttonAppearanceForType:ADYAppearanceButtonTypeContinue] setTextColor:[UIColor whiteColor]];
[[appearanceConfiguration buttonAppearanceForType:ADYAppearanceButtonTypeContinue] setCornerRadius:3.0f];

[ADYService serviceWithParameters:parameters appearanceConfiguration:appearanceConfiguration completionHandler:...];

获取 SDK 版本

如果您想获取当前使用的 sdk 版本 - 例如发送到 /authorise 端点，您可以使用它来获取

NSString* threeDS2SDKVersion = ADY3DS2SDKVersion();

let threeDS2SDKVersion = ADY3DS2SDKVersion()

另请参阅

许可证

此 SDK 在 Apache License 2.0 版本下可用。 有关更多信息，请参阅 LICENSE 文件。