# Smart/Accelerated Checkout via API

Build a "smarter" more "intelligent" checkout experience that ultimately helps buyer accelerate through the checkout funnel and improve overall conversion using the power of PayPal REST APIs.

# Know before you code
The integration involves a combination of below APIs to deliver the "smart" checkout solution that helps accelerate your customer through the checkout journey.
* **OTP API** - An API that helps validate customer identity via OTP
* **Payment Eligibility API (In Progress)** - An API that displays list of payment marks (Apple Pay, PayPal, Google Pay) + Saved Instruments (PYPL Vault, Merchant Vault)
* **Orders API** - Flagship PPCP API to create order and authorize/capture payment
* **Payments API** - Flagship PPCP API for post payment operations (voids, refunds, auth/capture).
* **Vault API** - Flagship PPCP API Access contents of merchant vault for given a customer.id by merchant

# Integration
An API based integration that leverages existing payment APIs (v2/orders, v2/payments, v3/vault) that will be the way merchants integrate with to get the PPCP solution.

The integration can be API Only or API with JS SDK

## Step 1 : Customer Identity : OTP API
Use the matching customers returned for the specified email to paint an OTP challenge for your customer.

Below is an API only solve for Identity - merchants might prefer the OTP Drop-in proposed by AXO team as it gives us greater control on legal messaging that might help us scale better.

## Send OTP

### Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/sendotp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{ "phone": "5166332032" }'

### Response

{
    HTTP 200
}

## Verify OTP
Merchant will design an OTP validation process according to our [OTP Branding Guidelines]() and upon successful authentication data is returned to the merchant

### Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/verifyotp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{ "phone": "5166332032", "code": "123456"}'

### Response

{
    auth_code: "asfkj23jlkj3lkjdi393k",
}

Use the 'auth_code' as an input to Payment Eligibility API to fetch instruments from the buyers PayPal FI Vault.

## Step 2 : Fetch Eligible Payment Methods

Merchants use the API to display the list of payment methods that the buyer can pay with. This is often described as a "pay-wall" that shows the list of payment options available to the buyer.

The API will return a combination of payment marks (PayPal Apple Pay, Google Pay) + payment methods that have been stored in a "vault" (PayPal FI + Merchant Vault for a given customer)

### Request

The API takes "auth_code" as one of the inputs to pull instruments from the PayPal FI Wallet. If it's not provided and only "customer.id" is provided it will pull only from the merchant vault and if both are provided it will provide a de-duped list of payment methods.

Please note depending on the "Identity" conversations it can take other inputs like IP Address ... to help make eligibility "smarter"

curl -v -X POST https://api-m.sandbox.paypal.com/v2/payment\eligible-payment-methods
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{ 

           "customer": {
                "country_code": "USA",
                "id": "customer_4029352050",
                "channel": "IOS",
                "auth_code":"asfkj23jlkj3lkjdi393k" OR "email":"[e-mail]"
            },
            "purchase_units": [
                {
                    "merchant": {
                        "merchant_id": "NGHNXQ95SRMUY"
                    },
                    "amount": {
                        "value": "150.00",
                        "currency": "USD"
                    }
                }
              ]
              }
     }'

### Response

{
    "payment_source" : {
        "paypal" : {
            "eligible" : "true",
            "confidence":"100%",
            "payment_tokens": [
               {
                   "id":"fgh656",
                   "brand":"VISA",
                   "last_digits":"3331"
               },
               {
                   "id":"fgh653",
                   "brand":"VISA",
                   "last_digits":"2345"
               },
               {
                   "id":"fEh653",
                   "brand":"AMEX",
                   "last_digits":"2345"
               },                
            }]
        },
        "paypal_credit" : {
            "eligible" : "false"
        },
        "pay_later" : {
            "eligible" : "false"
        },
        "card" : {
            "eligible" : "true",
            "payment_tokens": [
               {
                   "id":"abc656",
                   "brand":"MASTERCARD",
                   "last_digits":"3331"
               },
               {
                   "id":"def653",
                   "brand":"VISA",
                   "last_digits":"2345"
               },
               {
                   "id":"ghi653",
                   "brand":"AMEX",
                   "last_digits":"2345"
               },                
            }]
        }
        ...
    }
}

### Step 3: Create Order & Authorize/Capture

Below are existing APIs that take the payment-tokens returned as part of Step 2 as inputs and create the order and authorize/capture it.

* [Create Order](https://developer.paypal.com/docs/api/orders/v2/#orders_create)
* [Authorize/Capture Order](https://developer.paypal.com/docs/api/orders/v2/#orders_capture)

------
## Further Considerations

1. Depending on legal considerations a "OTP" drop-in component might be a better approach than the API for most LE's who do not mind showing it. Most Global Accounts will prefer a pure API approach. Needs discovery and further analysis by legal
2. Depending on the "signals" that we need sometimes prescence of an "SDK" might give us better signals but this is a losing proposition in the long run given the way browsers are clamping down on cookie sharing and overall privacy concers (think Apple).
3. Good to Have - Although the above does not show a JS SDK + API Integration it would be preferable to build something in the JS SDK that wraps the Payment Eligibility API but without expending a lot of effort in building a full feldged drop-in component.

--------------------------------

## Optional : Add/View Address

Provides option to add/view addresses stored within the PayPal Vault and/or Merchant Vault for a given customer.

Below examples shows information added to a Merchant Vault only:

Refer v3/sample/addresses/101_create_address_idempotent.json in https://github.paypal.com/ApiSpecifications-R/vault.PaymentTokensSpecification/pull/149/files
### Request

curl -v -X POST 'https://api-m.sandbox.paypal.com/v3/vault/customers/c_124233534523/addresses' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
        "address": {
            "name": {
                "given_name": "John",
                "surname": "Doe"
            },
            "address_line_1": "2211 N First Street",
            "address_line_2": "Building 17",
            "admin_area_2": "San Jose",
            "admin_area_1": "CA",
            "postal_code": "95131",
            "country_code": "US"
        }
    }
}'

### Response

{
            "id": "c_124233534523",
            "address_id": "4w",
            "create_time": "2022-04-01T21:20:49Z",
            "update_time": "2022-04-01T21:20:49Z",
            "name": {
                "given_name": "John",
                "surname": "Doe"
            },
            "address_line_1": "2211 N First Street",
            "address_line_2": "Building 17",
            "admin_area_2": "San Jose",
            "admin_area_1": "CA",
            "postal_code": "95131",
            "country_code": "US",
            "links": [
                {
                    "href": "https://api-m.paypal.com/v3/vault/customers/customer_402935/addresses/4w",
                    "rel": "self",
                    "method": "GET"
                },
                {
                    "href": "https://api-m.paypal.com/v3/vault/customers/customer_402935/addresses/4w",
                    "rel": "edit",
                    "method": "PATCH"
                },
                {
                    "href": "https://api-m.paypal.com/v3/vault/customers/customer_402935/addresses/4w",
                    "rel": "delete",
                    "method": "DELETE"
                }
            ]
        }

## Things to follow up
1. Need to confirm if Order API ACDC will create a guest account and store card info at Vault V3 & FI Vault?
2. For remembered guests, only query guest accounts with the public credential + remember flag=true.
3. BT use case, where we should store the remembered guests and their ards?  PayPal identity and FI vault?
4. BT use case, will FI vaulted card be stored at the BT vault after the transaction is complete?
5. Auth code can be an UAT, email is embeded in the token with signature.