Add FraudProtection Docs (#184)

* Update PayPalDataCollector to take a core config and remove PayPalDataCollectorEnvironment enum.

* Add FraudProtection to list of cocoapods dependencies.

* Add FraudProtection docs.

* Update CHANGELOG.

* Sort filenames in xcodeproj.

* Fix lint errors.

* Add canImport statements for CorePayments imports in the FraudProtection module.

* Add @testable import for CorePayments in PayPalDataCollector test.

* Add CorePayments.framework to link step for FraudProtection module in xcodeproj.

Author: sshropshire

CHANGELOG.md

@@ -7,7 +7,11 @@
   * Add `CardVaultRequest` and `CardVaultResult` types for interacting with `vault` method
   * Add `CardVaultDelegate` protocol to receive success and failure results
   * Add `CardVaultDelegate` property to `CardClient`
-  
+* Breaking Changes
+  * FraudProtection
+    * Update `PayPalDataCollector` constructor to require a configuration instead of an environment
+    * Remove `PayPalDataCollectorEnvironment` enum
+
 ## 0.0.10 (2023-08-14)
 * PayPalNativePayments
   * Bump `PayPalCheckout` to `1.0.0`

Package.swift

@@ -62,7 +62,7 @@ let package = Package(
         ),
         .target(
             name: "FraudProtection",
-            dependencies: ["PPRiskMagnes"]
+            dependencies: ["CorePayments", "PPRiskMagnes"]
         ),
         .binaryTarget(
             name: "PPRiskMagnes",

PayPal.podspec

@@ -37,6 +37,7 @@ Pod::Spec.new do |s|
 
   s.subspec "FraudProtection" do |s|
     s.source_files = "Sources/FraudProtection/*.swift"
+    s.dependency "PayPal/CorePayments"
     s.vendored_frameworks = "Frameworks/XCFrameworks/PPRiskMagnes.xcframework"
   end
 

PayPal.xcodeproj/project.pbxproj

@@ -64,6 +64,8 @@
 		BC04837427B2FC7300FA7B46 /* URLSession+URLSessionProtocol.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC04837327B2FC7300FA7B46 /* URLSession+URLSessionProtocol.swift */; };
 		BC0A82A5270B9533006E9A21 /* ConfirmPaymentSourceRequest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 06CE009F26F3DF100000CC46 /* ConfirmPaymentSourceRequest.swift */; };
 		BC0A82A6270B9954006E9A21 /* ConfirmPaymentSourceRequest_Tests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 065A4DC226FCE1D20007014A /* ConfirmPaymentSourceRequest_Tests.swift */; };
+		BC171FB12A8C156300B26DCB /* CoreConfig+MagnesSDK.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC171FB02A8C156300B26DCB /* CoreConfig+MagnesSDK.swift */; };
+		BC171FB22A8D6FE500B26DCB /* CorePayments.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 80B9F85126B8750000D67843 /* CorePayments.framework */; };
 		BC43406F27E91C2700F70193 /* PayPalCheckout in Frameworks */ = {isa = PBXBuildFile; productRef = BC43406E27E91C2700F70193 /* PayPalCheckout */; };
 		BC7F8123275FC1350011EDC8 /* CardRequest.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC7F8122275FC1350011EDC8 /* CardRequest.swift */; };
 		BC900B7D27AC307A00D48DBA /* PayPalNativeCheckoutDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = BC900B7C27AC307A00D48DBA /* PayPalNativeCheckoutDelegate.swift */; };
@@ -123,7 +125,6 @@
 		CB1A48052822BCED00BD8184 /* ImageAsset.swift in Sources */ = {isa = PBXBuildFile; fileRef = CB1A48042822BCED00BD8184 /* ImageAsset.swift */; };
 		CB1AC3C22982CDB10081AED6 /* MockNativeCheckoutProvider.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3D25238B273979170099E4EB /* MockNativeCheckoutProvider.swift */; };
 		CB22C018291049500097E592 /* PayPalPayLaterButton_Tests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CB22C017291049500097E592 /* PayPalPayLaterButton_Tests.swift */; };
-		CB38546327F4B616003CE179 /* PayPalDataCollectorEnvironment.swift in Sources */ = {isa = PBXBuildFile; fileRef = CB38546227F4B616003CE179 /* PayPalDataCollectorEnvironment.swift */; };
 		CB4BE27D2847AF6F00EA2DD1 /* SCA.swift in Sources */ = {isa = PBXBuildFile; fileRef = CB4BE27C2847AF6F00EA2DD1 /* SCA.swift */; };
 		CB4BE27E2847EA7D00EA2DD1 /* WebAuthenticationSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = BE4F784827EB629100FF4C0E /* WebAuthenticationSession.swift */; };
 		CB4BE2802847F01000EA2DD1 /* CardDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = CB4BE27F2847F01000EA2DD1 /* CardDelegate.swift */; };
@@ -249,6 +250,7 @@
 		80FC261C29847AC7008EC841 /* HTTP_Tests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HTTP_Tests.swift; sourceTree = "<group>"; };
 		BC04836E27B2FB3600FA7B46 /* URLSessionProtocol.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = URLSessionProtocol.swift; sourceTree = "<group>"; };
 		BC04837327B2FC7300FA7B46 /* URLSession+URLSessionProtocol.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "URLSession+URLSessionProtocol.swift"; sourceTree = "<group>"; };
+		BC171FB02A8C156300B26DCB /* CoreConfig+MagnesSDK.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "CoreConfig+MagnesSDK.swift"; sourceTree = "<group>"; };
 		BC7F8122275FC1350011EDC8 /* CardRequest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CardRequest.swift; sourceTree = "<group>"; };
 		BC900B7C27AC307A00D48DBA /* PayPalNativeCheckoutDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PayPalNativeCheckoutDelegate.swift; sourceTree = "<group>"; };
 		BC9C18D327D2775A0019B541 /* MockDeviceInspector.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MockDeviceInspector.swift; sourceTree = "<group>"; };
@@ -310,7 +312,6 @@
 		CB1A47FD2820C10700BD8184 /* PaymentButtonFundingSource.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PaymentButtonFundingSource.swift; sourceTree = "<group>"; };
 		CB1A48042822BCED00BD8184 /* ImageAsset.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ImageAsset.swift; sourceTree = "<group>"; };
 		CB22C017291049500097E592 /* PayPalPayLaterButton_Tests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PayPalPayLaterButton_Tests.swift; sourceTree = "<group>"; };
-		CB38546227F4B616003CE179 /* PayPalDataCollectorEnvironment.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PayPalDataCollectorEnvironment.swift; sourceTree = "<group>"; };
 		CB4BE27C2847AF6F00EA2DD1 /* SCA.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SCA.swift; sourceTree = "<group>"; };
 		CB4BE27F2847F01000EA2DD1 /* CardDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CardDelegate.swift; sourceTree = "<group>"; };
 		CB4BE285284802C200EA2DD1 /* PaymentSource.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PaymentSource.swift; sourceTree = "<group>"; };
@@ -404,6 +405,7 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				BC171FB22A8D6FE500B26DCB /* CorePayments.framework in Frameworks */,
 				BCF735E327D158B400A52E03 /* PPRiskMagnes.xcframework in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -612,13 +614,13 @@
 		BCF735C127D157CD00A52E03 /* FraudProtection */ = {
 			isa = PBXGroup;
 			children = (
+				BC171FB02A8C156300B26DCB /* CoreConfig+MagnesSDK.swift */,
 				BCF735EC27D1650800A52E03 /* DeviceInspector.swift */,
 				BCF735EE27D1652100A52E03 /* DeviceInspectorProtocol.swift */,
 				BCF735E827D15D2600A52E03 /* MagnesSDKProtocol.swift */,
 				BC9C18D727D279C70019B541 /* MagnesSDKResult.swift */,
 				BCF735EA27D160E800A52E03 /* MagnesSetupParams.swift */,
 				BCF735E627D15AB800A52E03 /* PayPalDataCollector.swift */,
-				CB38546227F4B616003CE179 /* PayPalDataCollectorEnvironment.swift */,
 			);
 			name = FraudProtection;
 			path = Sources/FraudProtection;
@@ -1388,7 +1390,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				BCF735EF27D1652100A52E03 /* DeviceInspectorProtocol.swift in Sources */,
-				CB38546327F4B616003CE179 /* PayPalDataCollectorEnvironment.swift in Sources */,
+				BC171FB12A8C156300B26DCB /* CoreConfig+MagnesSDK.swift in Sources */,
 				BCF735E727D15AB800A52E03 /* PayPalDataCollector.swift in Sources */,
 				BCF735EB27D160E800A52E03 /* MagnesSetupParams.swift in Sources */,
 				BCF735E927D15D2600A52E03 /* MagnesSDKProtocol.swift in Sources */,

Sources/FraudProtection/PayPalDataCollectorEnvironment.swift Sources/FraudProtection/CoreConfig+MagnesSDK.swift

@@ -1,12 +1,12 @@
 import PPRiskMagnes
+#if canImport(CorePayments)
+import CorePayments
+#endif
 
-/// Enum of environments to use with PayPalDataCollector
-public enum PayPalDataCollectorEnvironment {
-    case sandbox
-    case live
-
+extension CoreConfig {
+    
     var magnesEnvironment: MagnesSDK.Environment {
-        switch self {
+        switch environment {
         case .sandbox:
             return .SANDBOX
         case .live:

Sources/FraudProtection/PayPalDataCollector.swift

@@ -1,9 +1,12 @@
 import Foundation
 import PPRiskMagnes
+#if canImport(CorePayments)
+import CorePayments
+#endif
 
 /// Enables you to collect data about a customer's device and correlate it with a session identifier on your server.
 public class PayPalDataCollector {
-
+    
     // MARK: - Properties
 
     private let magnesSDK: MagnesSDKProtocol
@@ -14,13 +17,13 @@ public class PayPalDataCollector {
 
     /// Construct an instance to collect device data to send to your server.
     /// - Parameter environment: enviroment for the data collector
-    public convenience init(environment: PayPalDataCollectorEnvironment) {
-        self.init(environment: environment, magnesSDK: MagnesSDK.shared(), deviceInspector: DeviceInspector())
+    public convenience init(config: CoreConfig) {
+        self.init(config: config, magnesSDK: MagnesSDK.shared(), deviceInspector: DeviceInspector())
     }
 
     /// internal constructor for testing
-    init(environment: PayPalDataCollectorEnvironment, magnesSDK: MagnesSDKProtocol, deviceInspector: DeviceInspectorProtocol) {
-        self.magnesEnvironment = environment.magnesEnvironment
+    init(config: CoreConfig, magnesSDK: MagnesSDKProtocol, deviceInspector: DeviceInspectorProtocol) {
+        self.magnesEnvironment = config.magnesEnvironment
         self.magnesSDK = magnesSDK
         self.deviceInspector = deviceInspector
     }

UnitTests/FraudProtectionTests/DeviceInspector_Tests.swift

@@ -20,7 +20,7 @@ class DeviceInspector_Tests: XCTestCase {
         #else
             let sut = DeviceInspector()
             let newIdentifier = UUID()
-            let result = sut.paypalDeviceIdentifier(newIdentifier: newIdentifier)
+            let result = sut.payPalDeviceIdentifier(newIdentifier: newIdentifier)
 
             XCTAssertNotEqual(newIdentifier.uuidString, result)
         #endif

UnitTests/FraudProtectionTests/PayPalDataCollector_Tests.swift

@@ -1,20 +1,24 @@
 import XCTest
+@testable import CorePayments
 @testable import FraudProtection
 
 class PayPalDataCollector_Tests: XCTestCase {
 
     private var deviceInspector = MockDeviceInspector()
     private var magnesSDK = MockMagnesSDK()
-
+    
+    let sandboxConfig = CoreConfig(clientID: "mockClientID", environment: .sandbox)
+    let liveConfig = CoreConfig(clientID: "mockClientID", environment: .live)
+    
     func testCollectDeviceData_setsMagnesEnvironmentToSANDBOX() {
-        let sut = PayPalDataCollector(environment: .sandbox, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: sandboxConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         _ = sut.collectDeviceData()
 
         XCTAssertEqual(.SANDBOX, magnesSDK.capturedSetupParams?.env)
     }
 
     func testCollectDeviceData_setsMagnesEnvironmentToLIVE() {
-        let sut = PayPalDataCollector(environment: .live, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: liveConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         _ = sut.collectDeviceData()
 
         XCTAssertEqual(.LIVE, magnesSDK.capturedSetupParams?.env)
@@ -23,28 +27,28 @@ class PayPalDataCollector_Tests: XCTestCase {
     func testCollectDeviceData_setsMagnesAppGUIDToTheCurrentDeviceID() {
         deviceInspector.stubPayPalDeviceIdentifierWithValue("sample_device_identifier")
 
-        let sut = PayPalDataCollector(environment: .sandbox, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: sandboxConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         _ = sut.collectDeviceData()
 
         XCTAssertEqual("sample_device_identifier", magnesSDK.capturedSetupParams?.appGuid)
     }
 
     func testCollectDeviceData_disablesMagnesRemoteConfiguration() {
-        let sut = PayPalDataCollector(environment: .sandbox, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: sandboxConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         _ = sut.collectDeviceData()
 
         XCTAssertEqual(false, magnesSDK.capturedSetupParams?.isRemoteConfigDisabled)
     }
 
     func testCollectDeviceData_disablesMagnesBeacon() {
-        let sut = PayPalDataCollector(environment: .sandbox, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: sandboxConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         _ = sut.collectDeviceData()
 
         XCTAssertEqual(false, magnesSDK.capturedSetupParams?.isBeaconDisabled)
     }
 
     func testCollectDeviceData_setsMagnesSourceToPAYPAL() {
-        let sut = PayPalDataCollector(environment: .sandbox, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: sandboxConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         _ = sut.collectDeviceData()
 
         XCTAssertEqual(.PAYPAL, magnesSDK.capturedSetupParams?.source)
@@ -55,7 +59,7 @@ class PayPalDataCollector_Tests: XCTestCase {
         let magnesResult = MockMagnesSDKResult(payPalClientMetaDataId: "new_client_metadata_id")
         magnesSDK.stubCollectDeviceData(forArgs: args, withValue: magnesResult)
 
-        let sut = PayPalDataCollector(environment: .sandbox, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
+        let sut = PayPalDataCollector(config: sandboxConfig, magnesSDK: magnesSDK, deviceInspector: deviceInspector)
         let result = sut.collectDeviceData(additionalData: ["sample": "data"])
 
         let expected = """

docs/FraudProtection/README.md

@@ -0,0 +1,73 @@
+# Fraud Protection
+
+The FraudProtection module in the PayPal SDK enables merchants to collect user device data and associate it with payment transactions to reduce the risk of processing a fraudulent transaction.
+
+Follow these steps to add fraud protection:
+
+1. [Setup a PayPal Developer Account](#setup-a-paypal-developer-account)
+2. [Add FraudProtection Module](#add-fraudprotection-module)
+3. [Go Live](#go-live)
+
+## Setup a PayPal Developer Account
+
+You will need to set up authorization to use the PayPal Payments SDK. 
+Follow the steps in [Get Started](https://developer.paypal.com/api/rest/#link-getstarted) to create a client ID. 
+
+You will need a server integration to create an order and capture funds using [PayPal Orders v2 API](https://developer.paypal.com/docs/api/orders/v2). 
+For initial setup, the `curl` commands below can be used in place of a server SDK.
+
+## Add FraudProtection Module
+
+### 1. Add the Payments SDK FraudProtection module to your app
+
+#### Swift Package Manager
+
+In Xcode, add the PayPal SDK as a [package dependency](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app) to your Xcode project. Enter https://github.com/paypal/paypal-ios as the package URL. Tick the `FraudProtection` checkbox to add the Fraud Protection library to your app.
+
+#### CocoaPods
+
+Include the `FraudProtection` sub-module in your `Podfile`:
+
+```ruby
+pod 'PayPal/FraudProtection'
+```
+
+### 2. Initiate the Payments SDK
+
+Create a `CoreConfig` using a [client id](https://developer.paypal.com/api/rest/):
+
+```swift
+let config  = CoreConfig(clientID:"<CLIENT_ID>", environment: .sandbox)
+```
+
+Create a `PayPalDataCollector` to retrieve a PayPal Client Metadata ID (CMID). You can use a CMID when calling Authorize or Capture to add fraud protection to your transactions.
+
+```swift
+let payPalDataCollector = PayPalDataCollector(config: config)
+let cmid = payPalDataCollector.collectDeviceData()
+```
+
+### 3. Send PayPal-Client-Metadata-Id Header on Capture / Authorize
+
+To enable fraud protection, add a `PayPal-Client-Metadata-Id` HTTP header to your call to Capture (or Authorize), and set its value to the `cmid` value obtained in the previous step:
+
+```bash
+# for capture
+curl --location --request POST 'https://api.sandbox.paypal.com/v2/checkout/orders/<ORDER_ID>/capture' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <ACCESS_TOKEN>' \
+--header 'PayPal-Client-Metadata-Id: <CMID>' \
+--data-raw ''
+
+# for authorize
+curl --location --request POST 'https://api.sandbox.paypal.com/v2/checkout/orders/<ORDER_ID>/authorize' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <ACCESS_TOKEN>' \
+--header 'PayPal-Client-Metadata-Id: <CMID>' \
+--data-raw ''
+```
+
+## Go Live
+
+Follow [these instructions](https://developer.paypal.com/api/rest/production/) to prepare your integration to go live.
+