# Mobile Unified Integration Guide

> Merchant initialized client with intent to capture, authorize or vault, client_id and environment and Smart Payment Button (SPB) is rendered appropriately on both iOS and Android.

# Phase 1

[Initial Setup](##Setup)
[Card Integration](##Card-Integration)
[3DS Integration](##3DS-Integration)
[PayPal Integration](##PayPal-Integration)
[Payment Method with Vaulting Integration](##Vaulting-with-sale)
[Return Buyer Integration](##Return-buyer)
[Vaulting without sale](##Vaulting-Card-Integration)

## Setup

#### Add the Payments SDK to your app (All Modules)

##### Swift Package Manager

In Xcode, add the [package dependency](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app) and enter https://github.com/paypal/iOS-SDK as the repository URL. Tick the checkboxes for the specific PayPal libraries you wish to include.

In your app's source code files, use the following import syntax to include PayPal's Card, 3DS and PayPal libraries:

import Card // Card module
import ThreeDSecure // 3DS module
import PayPal // PayPal module

##### CocoaPods

Include the PayPal pod in your `Podfile`.

pod 'PayPal'

In your app's source code files, use the following import syntax to include PayPal's Card, 3DS and PayPal libraries:

import Card // Card module
import ThreeDSecure // 3DS module
import PayPal // PayPal module

## Card Integration

* Merchant is responsible for all UI rendering
* Merchant calls eligibility API (this is a new requirement) to check if ACDC is enabled and renders Card UI.

// Setup config
let config = CoreConfig(clientID: "<CLIENT_ID>", environment: .sandbox)
let apiClient = APIClient(config: config)

// Merchant calls eligibility API
apiClient.checkEligibility { result in
    switch result {
        case .success(let result):
            // `result.eligibility.acdc` 
            // show credit card form
        case .failure(let error):
case .failure(let error):            // handle the error by accessing `result.localizedDescription`
    }
}

// Merchant has rendered their own card fields to collect: PAN, expiry, security code and billing address info

// Once the customer taps the "Submit" button they can send the data to our API via the SDK

// Create a `CardClient` to approve an order with a Card payment method:
let cardClient = CardClient(apiClient: apiClient)

// Card Data
let card = Card(
    number: "4111111111111111",
    expirationMonth: "01",
    expirationYear: "25",
    securityCode: "123",
    cardholderName: "Jane Smith",
    billingAddress: Address(
        addressLine1: "123 Main St.",
        addressLine2: "Apt. 1A",
        locality: "city",
        region: "IL",
        postalCode: "12345",
        countryCode: "US"
    )
)

// Request Data (can eventually include non-card data [risk data, intent capture/auth, etc...])
let cardRequest = CardRequest(card: card)


// If merchant wants to get Order created by client. Merchant can skip this and just pass orderId too like
// ``` swift
// cardClient.createAndApproveOrder(cardRequest: cardRequest, orderId: orderId) { result in
//    switch result {
//       case .success(let result):
            // Order was created: `result.order.orderId`
            // Authorize or capture the order by making call to merchant's server
//        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
//    }
//}
// ```
let orderRequest = OrderRequest()
var purchaseUnit = PurchaseUnit()
orderRequest.intent = .capture
orderRequest.purchaseUnits = [purchaseUnit]
orderRequest.amount = "20.99"

// Send the request and get back an approved order
cardClient.createAndApproveOrder(cardRequest: cardRequest, orderRequest: orderRequest) { result in
    switch result {
        case .success(let result):
            // Order was approved: `result.order.orderId`
            // Authorize or capture the order by making call to merchant's server
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

#### Buyer/Merchant/Client Journey (no 3DS or SCA)
* Buyer opens merchant's app
* Buyer likes few things, adds to cart and checkout
* Merchant calls eligibility by creating apiClient and renders payment button UI (this UI is created by merchant)
* Assuming buyer clicks card, card UI shows up (this UI is created by merchant)
* Buyer types in card PAN, expiry date, billing address, CVV etc. and approves
* Merchant at this time (on buyer typing in card details and pressing OK) creates card client.
* Merchant creates card and order details (or pass an OrderId) and passes it to card client and calls `createAndApproveOrder`.
* Card client creates order if order details are passed (one call) and confirms-payment-source (second call) and drives the buyer approval workflow. Order is now in APPROVED status
* Post approval merchant gets control back with OrderId on success and either shows error or goes ahead with authorize/capture call on their server.

## 3DS Integration

* Merchant is responsible for all UI rendering outside of the challenege
* Merchant calls eligibility API (this is a new requirement) to check if ACDC is enabled and renders Card UI.

#### The PayPal payment flow uses an ASWebAuthenticationSession. Make sure your ViewController conforms to the ASWebAuthenticationPresentationContextProviding protocol.

class MyViewController: ASWebAuthenticationPresentationContextProviding {

    // MARK: - ASWebAuthenticationPresentationContextProviding
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        UIApplication
            .shared
            .connectedScenes
            .flatMap { ($0 as? UIWindowScene)?.windows ?? [] }
            .first { $0.isKeyWindow }
        ?? ASPresentationAnchor()
    }
}

// Setup config
let config = CoreConfig(clientID: "<CLIENT_ID>", environment: .sandbox)
let apiClient = APIClient(config: config)

// Merchant calls eligibility API
apiClient.checkEligibility { result in
    switch result {
        case .success(let result):
            // `result.eligibility.acdc` 
            // show credit card form
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

// Merchant has rendered their own card fields to collect: PAN, expiry, security code and billing address info

// Once the customer taps the "Submit" button they can send the data to our API via the SDK

let threeDSecureClient = ThreeDSecureClient(apiClient: apiClient)

// Card Data
let card = Card(
    number: "4111111111111111",
    expirationMonth: "01",
    expirationYear: "25",
    securityCode: "123",
    cardholderName: "Jane Smith",
    billingAddress: Address(
        addressLine1: "123 Main St.",
        addressLine2: "Apt. 1A",
        locality: "city",
        region: "IL",
        postalCode: "12345",
        countryCode: "US"
    )
)

// Request Data (can eventually include non-card data [risk data, intent capture/auth, etc...])
let cardRequest = CardRequest(card: card)
// If merchant wants to get Order created by client create orderRequest.
// Merchant can skip this and just pass orderId too like
// ``` swift
// threeDSecureClient.varify(cardRequest: cardRequest, orderId: orderId)
// ```
let orderRequest = OrderRequest()
var purchaseUnit = PurchaseUnit()
orderRequest.intent = .capture
orderRequest.purchaseUnits = [purchaseUnit]
orderRequest.amount = "20.99"

// Send the request and get back an order
threeDSecureClient.createAndApproveOrder(cardRequest: cardRequest, orderRequest: orderRequest) { result in
    switch result {
        case .success(let result):
            
            
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

class MyViewController: ASWebAuthenticationPresentationContextProviding, CardThreeDSecureDelegate {
    ...

    func checkoutWithThreeDSecure() {
        threeDSecureClient.delegate = self
        threeDSecureClient.verify(cardRequest: cardRequest, orderRequest: orderRequest)
    }

    func cardThreeDSecure(_ threeDSecureClient: ThreeDSecureClient, didFinishWithResult result: CardThreeDSecureResult) {
        // Order was approved: `result.order.orderId`
        if (result.order.3DSResponse.liabilityShift == "YES") // ... some merchant logic
        {
            // Authorize or capture the order by making call to merchant's server
        } else {
            // Reject request, retry etc.
        }
    }

    func cardThreeDSecure(_ threeDSecureClient: ThreeDSecureClient, didFinishWithError error: CoreSDKError) {
        // handle the error by accessing `error.localizedDescription`
    }

    func cardThreeDSecureDidCancel(_ threeDSecureClient: ThreeDSecureClient) {
        // the user canceled
    }
}

#### Buyer/Merchant/Client Journey (SCA_ALWAYS or SCA is mandated like in Europe)
* Buyer opens merchant's app
* Buyer likes few things, adds to cart and checkout
* Merchant calls eligibility by creating apiClient and renders payment button UI (this UI is created by merchant)
* Assuming buyer clicks card, card UI shows up (this UI is created by merchant)
* Buyer types in card PAN, expiry date, billing address, CVV etc. and approves
* Merchant at this time (on buyer typing in card details and pressing OK) creates core config and initializes 3DS client.
* MyViewController checkoutWithThreeDSecure is called by merchant.
* 3DS client creates order (one call) and confirm-payment-source (second call). Confirm call returns 3DS contingency.
* API response indicates that a challenege is required
* User is presented the authentication in an ASWebAuthenticationSession (Application cannot read the challenge answer)
* Upon user authentication, the challenege is dismissed. Order is in APPROVED status now along with 3DS response.
* Depending on user action, control comes back to the application with 3DS response details and OrderId,
* Merchant can now authorize or capture the order on their server depending on 3DS result or reject the purchase request.

## PayPal Integration

* Merchant is responsible rendering the PayPal button
* Merchant calls eligibility API (this is a new requirement) to check if PayPal is enabled

#### The PayPal payment flow uses an ASWebAuthenticationSession. Make sure your ViewController conforms to the ASWebAuthenticationPresentationContextProviding protocol.

class MyViewController: ASWebAuthenticationPresentationContextProviding {

    // MARK: - ASWebAuthenticationPresentationContextProviding
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        UIApplication
            .shared
            .connectedScenes
            .flatMap { ($0 as? UIWindowScene)?.windows ?? [] }
            .first { $0.isKeyWindow }
        ?? ASPresentationAnchor()
    }
}

// Setup config
let config = CoreConfig(clientID: "<CLIENT_ID>", environment: .sandbox)
let apiClient = APIClient(config: config)

// Merchant calls eligibility API
apiClient.checkEligibility { result in
    switch result {
        case .success(let result):
            // `result.eligibility.paypal` 
            // show paypal button
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

// Merchant shows PayPal button

// Create a `PayPalWebCheckoutClient`
let payPalClient = PayPalWebCheckoutClient(apiClient: apiClient)

// Create the request (could include amount and other data)
let payPalRequest = PayPalWebCheckoutRequest()
// If merchant wants to get Order created by client create orderRequest.

let orderRequest = OrderRequest()
var purchaseUnit = PurchaseUnit()
orderRequest.intent = .capture
orderRequest.purchaseUnits = [purchaseUnit]
orderRequest.amount = "20.99"

// Send the request and get back an order
PayPalWebCheckoutClient.createAndApproveOrder(cardRequest: cardRequest, orderRequest: orderRequest) { result in
    switch result {
        case .success(let result):
            // Order was created: `result.order.orderId`
            // Authorize or capture the order by making call to merchant's server
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

class MyViewController: ASWebAuthenticationPresentationContextProviding, PayPalWebCheckoutDelegate {
    ...

    func checkoutWithPayPal() {
        payPalClient.delegate = self
        payPalClient.start(request: payPalRequest)
    }

    func payPal(_ payPalClient: PayPalWebCheckoutClient, didFinishWithResult result: PayPalWebCheckoutResult) {
        // Order was approved: `result.order.orderId`
    }

    func payPal(_ payPalClient: PayPalWebCheckoutClient, didFinishWithError error: CoreSDKError) {
        // handle the error by accessing `error.localizedDescription`
    }

    func payPalDidCancel(_ payPalClient: PayPalWebCheckoutClient) {
        // the user canceled
    }
}

#### Buyer Journey
* Buyer opens merchant's app
* Buyer likes few things, adds to cart and checkout
* Merchant calls eligibility by creating apiClient and renders payment button UI (this UI is created by merchant)
* Assuming buyer clicks PayPal
* Merchant at this time (on buyer clicking paypal button) creates PayPalWebCheckout client.
* MyViewController API checkoutWithPayPal is called by merchant.
* This will create order (one call) and confirm-payment-source (second call). Confirm call returns approval link (Hermes flow).
* User is presented the Hermes UI in an ASWebAuthenticationSession (Application cannot read the challenge answer)
* Upon user authentication, the challenege is dismissed. Order is in APPROVED status now.
* Depending on user action, control comes back to the application with OrderId,
* Merchant can now authorize or capture the order on their server.

## Vaulting Card Integration
This is stand alone vaulting. Card is given as an example, stand alone vaulting works similarly for PayPal and Venmo.
* Merchant is responsible for all UI rendering
* Merchant calls eligibility API (this is a new requirement) to check if ACDC is enabled and renders Card UI.

// Setup config
let config = CoreConfig(clientID: "<CLIENT_ID>", environment: .sandbox)
let apiClient = APIClient(config: config)

// Merchant calls eligibility API
apiClient.checkEligibility { result in
    switch result {
        case .success(let result):
            // `result.eligibility.acdc` 
            // show credit card form
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

// Merchant has rendered their own card fields to collect: PAN, expiry, security code and billing address info

// Once the customer taps the "Submit" button they can send the data to our API via the SDK

// Create a `CardClient` to approve an order with a Card payment method:
let cardClient = CardClient(apiClient: apiClient)

let vaultingRequest = VaultRequest()
vaultingRequest.payment_source.card = Card(
    number: "4111111111111111",
    expirationMonth: "01",
    expirationYear: "25",
    securityCode: "123",
    cardholderName: "Jane Smith",
    billingAddress: Address(
        addressLine1: "123 Main St.",
        addressLine2: "Apt. 1A",
        locality: "city",
        region: "IL",
        postalCode: "12345",
        countryCode: "US"
    )
)
vaultingRequest.experience_context.cancelUrl = "deep link URL to go back to the application"
vaultingRequest.experience_context.returnURL = "deep link URL to go back to the application"
vaultingRequest.experience_context.brandName = "brand name of merchant"
vaultingRequest.experience_context.locale = "locale"

// Send the request and get back an order
cardClient.setupVault(vaultingRequest: vaultingRequest) { result in
    switch result {
        case .success(let result):
            // Vault setup token was approved: `result.vault.tokenId`
            // Exchange setup-token with payment-token by calling POST on v3/vault/payment-tokens endpoint on merchant server
            // The above call needs a full scoped access token
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

#### Buyer/Merchant/Client Journey (no 3DS or SCA)
* Buyer opens merchant's app and is setting up his profile or signing up for a service and needs to setup their payment method.
* Merchant calls eligibility by creating apiClient and renders payment button UI
* Assuming buyer clicks card, card UI shows up
* Buyer types in card PAN, expiry date, billing address, CVV etc. and approves
* Merchant at this time (on buyer typing in card details and pressing OK) creates card client.
* Merchant creates card and vault details and passes it to card client and calls `setupVault`.
* Card client creates setup token (one call) and is now in APPROVED status (In case there is 3DS/contingency then flow is similar to one with sale flow)
* Post approval merchant gets control back with Vault Id on success and either shows error or goes ahead with exchanging it with payment-token to be used for future.

## Vaulting with sale
No change in SDK. While creating the order request, merchant needs to pass vault attributes and merchant will get vaulted token back as part of authorize or capture response. For the sake of broader understanding below is how it will work. Card is given as an example but PayPal will work similar.
* Merchant is responsible for all UI rendering outside of the challenege
* Merchant calls eligibility API (this is a new requirement) to check if ACDC is enabled and renders Card UI.

#### The PayPal payment flow uses an ASWebAuthenticationSession. Make sure your ViewController conforms to the ASWebAuthenticationPresentationContextProviding protocol.

class MyViewController: ASWebAuthenticationPresentationContextProviding {

    // MARK: - ASWebAuthenticationPresentationContextProviding
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        UIApplication
            .shared
            .connectedScenes
            .flatMap { ($0 as? UIWindowScene)?.windows ?? [] }
            .first { $0.isKeyWindow }
        ?? ASPresentationAnchor()
    }
}

// Setup config
let config = CoreConfig(clientID: "<CLIENT_ID>", environment: .sandbox)
let apiClient = APIClient(config: config)

// Merchant calls eligibility API
apiClient.checkEligibility { result in
    switch result {
        case .success(let result):
            // `result.eligibility.acdc` 
            // show credit card form
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

// Merchant has rendered their own card fields to collect: PAN, expiry, security code and billing address info

// Once the customer taps the "Submit" button they can send the data to our API via the SDK

let threeDSecureClient = ThreeDSecureClient(apiClient: apiClient)

// Card Data
let card = Card(
    number: "4111111111111111",
    expirationMonth: "01",
    expirationYear: "25",
    securityCode: "123",
    cardholderName: "Jane Smith",
    billingAddress: Address(
        addressLine1: "123 Main St.",
        addressLine2: "Apt. 1A",
        locality: "city",
        region: "IL",
        postalCode: "12345",
        countryCode: "US"
    )
)

// Request Data (can eventually include non-card data [risk data, intent capture/auth, etc...])
let cardRequest = CardRequest(card: card)

let orderRequest = OrderRequest()
orderRequest.vaultAttributes = [vault:"ON_ORDER_COMPLETION"]

threeDSecureClient.createAndApproveOrder(cardRequest: cardRequest, orderRequest: orderRequest) { result in
    switch result {
        case .success(let result):
            // Order was created: `result.order.orderId` and `result.order.3DSresponse`
            if (result.order.3DSResponse.liabilityShift == "YES") // ... some merchant logic
            {
                // Authorize or capture the order by making call to merchant's server
                // Response will have the vaulted token
            } else {
                // Reject request, retry etc.
            }
            
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

class MyViewController: ASWebAuthenticationPresentationContextProviding, CardThreeDSecureDelegate {
    ...

    func checkoutWithThreeDSecure() {
        threeDSecureClient.delegate = self
        threeDSecureClient.verify(request: cardRequest)
    }

    func cardThreeDSecure(_ threeDSecureClient: ThreeDSecureClient, didFinishWithResult result: CardThreeDSecureResult) {
        // Order was created: `result.order.orderId`
    }

    func cardThreeDSecure(_ threeDSecureClient: ThreeDSecureClient, didFinishWithError error: CoreSDKError) {
        // handle the error by accessing `error.localizedDescription`
    }

    func cardThreeDSecureDidCancel(_ threeDSecureClient: ThreeDSecureClient) {
        // the user canceled
    }
}

#### Buyer/Merchant/Client Journey
* Buyer opens merchant's app
* Buyer likes few things, adds to cart and checkout
* Merchant creates core config and api client and calls eligibility to ensure that merchant is eligible to take card payment. Buyer is presented with a UI to take card input (this UI is created by merchant)
* Buyer types in card PAN, expiry date, billing address, CVV etc. and approves
* Merchant at this time (on buyer typing in card details and pressing OK) creates core config and initializes 3DS client.
* 3DS client createAndApproveOrder is called by merchant by passing card and order details (with intent to vault).
* 3DS client creates order (one call) and confirm-payment-source (second call). Confirm call returns 3DS contingency.
* API response indicates that a challenege is required
* User is presented the authentication in an ASWebAuthenticationSession (Application cannot read the challenge answer)
* Upon user authentication, the challenege is dismissed. Order is in APPROVED status now along with 3DS response.
* Depending on user action, control comes back to the application with 3DS response details and OrderId,
* Merchant can now authorize or capture the order on their server depending on 3DS result or reject the purchase request.

## Return buyer
* Merchant is responsible for all UI rendering outside of the challenge
* Merchant calls eligibility API (this is a new requirement) to check if ACDC is enabled and renders Card UI.

// Setup config
let config = CoreConfig(clientID: "<CLIENT_ID>", environment: .sandbox)
let apiClient = APIClient(config: config)

// Merchant calls eligibility API
apiClient.checkEligibility { result in
    switch result {
        case .success(let result):
            // `result.eligibility.acdc` 
            // show credit card form
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}
// Merchant needs to call GET v3/vault/setup-tokens with return customer_id to get all vaulted tokens
// Assuming vaulted token is only card

// Merchant has rendered their card button showing last 4 of vaulted card and expiry etc.

// Customer doesn't input anything, just clicks/approves

let cardClient = CardClient(apiClient: apiClient)

// Card Data - See how there are no raw card details
let card = Card(
    token: Token(
        id: "vaulted_token",
        type: "SETUP_TOKEN"
    )
)

// Request Data (can eventually include non-card data [risk data, intent capture/auth, etc...])
let cardRequest = CardRequest(card: card)

let orderRequest = OrderRequest()
var purchaseUnit = PurchaseUnit()
orderRequest.intent = .capture
orderRequest.purchaseUnits = [purchaseUnit]
orderRequest.amount = "20.99"

cardClient.createAndApproveOrder(cardRequest: cardRequest, orderRequest: orderRequest) { result in
    switch result {
        case .success(let result):
            // Order was created: `result.order.orderId` and `result.order.3DSresponse`
            if (result.order.3DSResponse.liabilityShift == "YES") // ... some merchant logic
            {
                // Authorize or capture the order by making call to merchant's server
            } else {
                // Reject request, retry etc.
            }
            
        case .failure(let error):
            // handle the error by accessing `result.localizedDescription`
    }
}

#### Buyer/Merchant/Client Journey
* Buyer opens merchant's app
* Buyer likes few things, adds to cart and checkout
* Merchant creates core config and api client and calls eligibility to ensure that merchant is eligible to take card payment. Merchant recognizes the buyer, calls Vault APIs to get buyer's vaulted tokens and presents buyer with payment sheet (this UI is created by merchant)
* Buyer clicks on one of their vaulted tokens (assuming card here)
* Merchant at this time (on buyer clicking on card) creates core config and initializes card client (assuming no 3DS).
* 3DS client createAndApproveOrder is called by merchant.
* 3DS client creates order (one call) and confirm-payment-source (second call but this time with token rather than card raw details). Order should be put in APPROVED state (please do not forget to do this)
* Depending on user action, control comes back to the application with OrderId,
* Merchant can now authorize or capture the order on their server.

# Phase 2
Please do:
* Smart Payment Button UI. Merchant should not be calling eligibility etc. On SPB initialization all eligible buttons should be rendered.
* If we are redriving 3DS, hermes flow to a browser and coming back to application, this should be removed. In our ideal integration everything should happen in merchant's app and there should not be any browser redirection.