Contents

Adyen/adyen-3ds2-ios

With this SDK, you can accept 3D Secure 2.0 payments via Adyen.

Installation

The SDK is available via CocoaPods, Carthage or via manual installation.

CocoaPods

  1. Add pod 'Adyen3DS2' to your Podfile.
  2. Run pod install.

Carthage

  1. Add github "adyen/adyen-3ds2-ios" to your Cartfile.
  2. Run carthage update.
  3. Link the framework with your target as described in Carthage Readme.

Dynamic xcFramework

Drag the dynamic XCFramework/Dynamic/Adyen3DS2.xcframework to the Frameworks, Libraries, and Embedded Content section in your general target settings. Select "Copy items if needed" when asked.

Static xcFramework

  1. Drag the static XCFramework/Static/Adyen3DS2.xcframework to the Frameworks, Libraries, and Embedded Content section in your general target settings.
  2. Make sure the static Adyen3DS2.xcframework is not embedded.
  3. Select Adyen3DS2.bundle inside Adyen3DS2.xcframework and check "Copy items if needed", then select "Add".
  4. The privacy manifest should be included/merged in your app bundle.

Swift Package Manager

  1. Follow Apple's [Adding Package Dependencies to Your App](

https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app ) guide on how to add a Swift Package dependency.

  1. Use https://github.com/Adyen/adyen-3ds2-ios as the repository URL.
  2. Specify the version to be at least 2.2.1.

:warning: Please make sure to use Xcode 16.0+ when adding Adyen3DS2 using Swift Package Manager.

:warning: Swift Package Manager for Xcode 16.0 and 12.1 has a know issue when it comes to importing binary dependencies. A workaround is described here.

Usage

### Creating a transaction

First, create an instance of `ADYServiceParameters` with the additional data retrieved from your call to `/authorise`.
Then, use the class method on `ADYService` to create a new service. This service can be used to create a new transaction.
```objc
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).
    }
}];
```

Use the `transaction`'s `authenticationRequestParameters` in your call to [Adyen backend](https://docs.adyen.com/api-explorer/Payment/64/post/authorise3ds2).

:warning: _`[ADYService transactionWithMessageVersion:error:]` requires the message version to be passed, please fill in the same message version as in the AReq, you should be able to get the message version decided by the 3DS server from its response when initiating the payment, if you use the Adyen 3DS server please see [the documentation](https://docs.adyen.com/api-explorer/#/Payment/v64/post/authorise__reqParam_threeDS2RequestData-messageVersion)._

:warning: _Keep a reference to your `ADYTransaction` instance until the transaction is finished._

:warning: _If your application supports Mac catalyst or iPad OS multi-window/multi-scene, then its recommended to share the `ADYTransaction`/`ADYService` object(s) between scenes for the case if the shopper starts a transaction on one window and switch to another while the transaction is in progress._

### Performing a challenge

In case a challenge is required, create an instance of `ADYChallengeParameters` with values from the additional data retrieved from your call to [Adyen backend](https://docs.adyen.com/api-explorer/Payment/64/post/authorise3ds2).

```objc
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"]];
```

:warning: _Because of recent updates to the 3D Secure protocol, we strongly recommend that you provide the `threeDSRequestorAppURL` parameter as a [universal link](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content?language=objc)._

Use these challenge parameters to perform the challenge with the `transaction` you created earlier:
```objc
[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
    }
}];
```

When the challenge is completed successfully, submit the `transactionStatus` in the `result` in your second call to [Adyen backend](https://docs.adyen.com/api-explorer/Payment/64/post/authorise3ds2).

### Customizing the UI

The SDK provides some customization options to ensure the UI of the challenge flow fits your app's look and feel. These customization options are available through the `ADYAppearanceConfiguration` class. To use them, create an instance of `ADYAppearanceConfiguration`, configure the desired properties and pass it during initialization of the `ADYService`.

For example, to make the Continue button red and change its corner radius:
```objc
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:...];
```

### Get the SDK version

If you want to get the currently used sdk version - for example to send to the [`/authorise` end point](https://docs.adyen.com/api-explorer/#/Payment/v64/post/authorise__reqParam_threeDS2RequestData-sdkVersion), you can get it using:

```
NSString* threeDS2SDKVersion = ADY3DS2SDKVersion();
```

```
let threeDS2SDKVersion = ADY3DS2SDKVersion()
```

See also

SDK Reference Reporting security issues. Security best practices. Data security at Adyen.

License

This SDK is available under the Apache License, Version 2.0. For more information, see the LICENSE file.

Package Metadata

Repository: Adyen/adyen-3ds2-ios

Stars: 20

Forks: 15

Open issues: 3

Default branch: master

Primary language: objective-c

License: Other

README: README.md