Northstar Native SDK Client Spec

BT SDK Card Client

initized with an API client
Two top level functions


- (void)tokenizeCard:(BTCard *)card 
        completion:(void (^)(BTCardNonce *tokenizedCard, NSError *error))completion

params: card object and completion
flow:
- merchant uses SDK to create a nonce of the input card
- merchant passes nonce to their server, which creates and executes the transcation



- (void)tokenizeCard:(BTCardRequest *)request 
             options:(NSDictionary *)options 
          completion:(void (^)(BTCardNonce * _Nullable, NSError * _Nullable))completionBlock

params: card request and completion
internally invoked by the other tokenizeCard function

Northstar implementation

Example integration



























// Create a CardClient instance
val cardClient = CardClient(config)

// Create an OrderRequest and Card
val orderRequest = OrderRequest(
    purchaseUnitList = listOf(
        PurchaseUnit(
            amount = Amount(
                currencyCode = CurrencyCode.USD,
                value = "10.00"
            )
        )
    )
)
val card = Card(number = "4032036247327321", expiry = "2024-11")

// Execute order
cardClient.executeOrder(orderRequest, card) { result ->
    when(result) {
        is Success -> {
            // Transaction was executed
        }
        is Failure -> {
            // Error executing transaction
        }
    }
}

1. Create CardClient








CardClient(_ config:) {
    // Use dependency injection to satisfy dependencies 
    // instead of exposing them publicly through the constructor 
    
    // This is something we can add later on iOS if we want to first 
    // getthings working before exploring DI solutions
    self.apiClient = Resolver.resolve()
}

The config object passed in here should live in Core and contain all the shared parameters that a merchant would need to give the SDK in order to perform its operations. Some values that should live in this config:

ClientID
Environment
Access token?
others?

2a. Execute transaction passing in an OrderRequest

To consume card transaction with no card validation and an order request object:
- https://developer.paypal.com/docs/api/orders/v2/#orders_create
- Order is created, and immediately executed. The intent is required to be CAPTURE, and the status of the order after creation will be COMPLETED
API Doc Reference: https://hackmd.io/oo00FrwyQEe3aT4NI8WcuA?view#Option-1-Create-and-authorizecapture-card-order-immediately




































client.executeOrder(order: OrderRequest, card: Card) { result in
    // POST to /v2/checkout/orders/
    // request body contains: 
    {
        "purchase_units": [ 
            <Purchase_Unit Definition> 
            https://developer.paypal.com/docs/api/orders/v2/#definition-purchase_unit_request
        ],
        "payment_source":{
            "card":{
                "number":"4032036247327321",
                "expiry":"2024-12"
            }
        }
    }

    // response <https://developer.paypal.com/docs/api/orders/v2/#orders-create-response>: 
        - Order Response object
            - Order ID
            - Intent (always CAPTURE)
            - purchase_units
            - status (always COMPLETED)
            - Other response params found here: https://ppaas/api/3719176155270030?tab=apiReference&operation_id=post-_v2_checkout_orders

    // vend result to merchant through completion handler
    switch result {
         case .success(let orderResponse):
             orderResponse.orderID
             orderResponse.intent
             orderResponse.purchaseUnits
             orderResponse.status
             orderResponse. ? 
        case .failure(let error):
            // transaction failed - human readable error information
    }
}

2b. Execute transaction passing in an OrderID

Executes a transaction given an order ID and a Card object
API Doc Reference: https://hackmd.io/oo00FrwyQEe3aT4NI8WcuA?view#Option-3-Create–authorizecapture


































client.executeOrder(orderID: String, card: Card) { result in
    // POST to either:
        `v2/checkout/orders/<order_id>/authorize` 
        `v2/checkout/orders/<order_id>/capture`
    // request: 
    {
        "payment_source":{
            "card":{
                "number":"4032036247327321",
                "expiry":"2024-12"
            }
        }
    }

    // response: 
        - Order Response object
            - Order ID
            - Intent (always CAPTURE)
            - purchase_units
            - status (always COMPLETED)
            - Other response params found here: https://ppaas/api/3719176155270030?tab=apiReference&operation_id=post-_v2_checkout_orders

    // vend result to the merchant
    switch result {
         case .success(let orderResponse):
             orderResponse.orderID
             orderResponse.intent
             orderResponse.purchaseUnits
             orderResponse.status
             orderResponse. ? 
        case .failure(let error):
            // transaction failed - human readable error information
    }
}

Issues and Questions

Token Source

The desire is for a merchant to be able to pass us a token generated from any source (v1/payments, v2/orders, others?)
- per Mark
EC Tokens generated from the v1 API are not compatible with the v2 order actions:
- v2/checkout/orders/<order_id>/authorize
- v2/checkout/orders/<order_id>/capture
In order to satisfy #1 natively, we would need some ability to determine the token source AND properly handle / type the responses from the different potential token sources (ie INTENT values are different between v1 and v2 APIs)
Possible solution:
Since this is a problem that will need to be solved by all three platforms (JS, Android, iOS), does it make sense to put this logic and response formatting behind a GraphQL layer that is universally targeted instead of targeting the orders API directly?

Authorization Intent
- Using the v2 API, does an intent value of authorize make sense for unbranded card transactions?

Merchant usecase for card validation
- Currently, the validation endpoint is marked INTERNAL. Is there a reason we would want this exposed? Without this endpoint, there wouldn't be a way for a merchant to do card validation using the orders API

/v2/checkout/orders/{OrderID}/validate-payment-method

Possible implementation of card validation (if it becomes externally available)

To consume card transaction with card validation:
- Post to: /v2/checkout/orders/{OrderID}/validate-payment-method
- Order can be created client side or server side
- Documentation: https://hackmd.io/oo00FrwyQEe3aT4NI8WcuA?view#Option-2-Create–validate–approve–authorizecapture
Do we need to provide the ability for the merchant to validate the card data before order execution?

 clientConfig.validate(orderID: orderID, card: Card) { result in
     // validates card data against above API
     response: 
        response object would match the above order object
 }

Create transaction and capture separately

/v2/checkout/orders/:orderId/validate-payment-method
Order created, then captured or authorized separately
Documentation: https://hackmd.io/oo00FrwyQEe3aT4NI8WcuA?view#Option-3-Create–authorizecapture
Questions:
If a user authorizes a card transaction and wants to capture the same transaction at a future point in time, would the merchant need to pass the card object in again, or would they pass in some part of the authorization response?
What is the format of the capture / authorization response, and what should be vended to the user?

Minh Nguyen

2021/08/20 18:21:56

nonce

I think nonce would be one great option we might wanna support in the future (for vaulting purpose) :D right now I think Orders API works with BT nonce (someone can correct me from wrong): "payment_source": { "token": { "id": <nonce> "type": "NONCE" } } I don't know if Orders API team would add a new endpoint similar to/wrapping BT's tokenizeCard in the future tho... maybe that's an open question we can ask. (Edited)

jonathajones

2021/08/20 20:48:47

Wouldn't vaulting just relate to paypal users? also someone correct me if i'm off base here :) no idea if we'll use nonces for vaulting - we'll probably follow the lead of the JS SDK for that i think

2021/08/20 21:35:42

yea maybe just something for the future. And you're right!!!!! probably they'd need to have a PayPal account for that.

2021/08/20 18:22:38

authorize

maybe I'm missing something. Can you explain why authorize might not make sense for unbranded card with v2 API? :-ss (Edited)

2021/08/20 20:46:57

If a user creates an order request with an `authorize` intent and executes on it here, how should they go about capturing the order? would they need to hold a local reference to the card object until they need to `capture` the transaction? my understanding is if you just pass the order ID, they would also need to pass a buyer access token along with it, which we wouldn't have (since card transactions do not necessarily involve paypal users)

2021/08/20 21:32:09

I think if a buyer has already confirm payment source for an order (we call confirm-payment-source endpoint with the card object), then the card is already associated with the order. So when capturing the order, merchant just need to call capture with the orderId? (Edited)

2021/08/20 23:24:33

This would be using the third option you identified in your orders API investigation: `Option 3: Create + authorize/capture`, so there would not e a call to `confirm`. (Edited)

2021/08/20 23:27:09

The flow, as I understand it, would be to call `v2/checkout/orders/<order_id>/authorize` with the order ID and the card payment source. once you do that, you have an authorized transaction, but you haven't `capture`d it yet. in order to capture it, would you only pass in the order id? in other flows (ie paypal) you need to also supply some authentication (BAT) along with the order ID, so i was assuming the paradigm would be similar here. (Edited)

Sarah Koop

2021/08/23 13:59:21

others?

It would be awesome if this config could also include supported payment/card types for the merchant. I don't know if that exists in orders/v2 currently (Edited)

2021/08/23 14:00:24

```kotlin= // Create a CardClient instance val cardClient = CardClient(config) // Create an OrderRequest and Card val orderRequest = OrderRequest( purchaseUnitList = listOf( PurchaseUnit( amount = Amount( currencyCode = CurrencyCode.USD, value = "10.00" ) ) ) ) val card = Card(number = "4032036247327321", expiry = "2024-11") // Execute order cardClient.executeOrder(orderRequest, card) { result -> when(result) { is Success -> { // Transaction was executed } is Failure -> { // Error executing transaction } } } ```

It might be helpful to align with orders/v2 terms like createOrder and captureOrder instead of request and execute (Edited)

2021/08/24 14:13:11

Ahh I didn't add option 3 in, Sarah did :D Hmm but I'm thinking (gotta test to make sure) if an order has already been authorized with a payment source, then when merchant does capture later on, they wouldn't have to pass in the payment source again. (Edited)

2021/08/24 14:14:12

and by buyer access token, do you mean the token we get with v1/oauth2/token? (Edited)

Samantha Cannillo

2021/08/24 15:01:50

EC Tokens generated from the v1 API are not compatible with the v2 order actions:

We need to double check on this, but it was my understanding from the PPCP project that the merchants server SDK should be responsible for creating the orderID and for authorizing/capturing that orderID. It has to do something with the scope of the auth token needed to perform these actions shouldn't live on the client. (Edited)

2021/08/24 15:03:02

If a user authorizes a card transaction and wants to capture the same transaction at a future point in time, would the merchant need to pass the card object in again, or would they pass in some part of the authorization respons

Or - they get back the orderID and can do what they want with it? (Edited)

2021/08/24 15:03:23

ost to: [/v2/checkout/orders/{OrderID}/validate-payment-method

IIRC - Rahul said we aren't using this endpoint. Again, we need to double check! (Edited)

Northstar Native SDK Client Spec

BT SDK Card Client

Northstar implementation

Example integration

1. Create CardClient

2a. Execute transaction passing in an OrderRequest

2b. Execute transaction passing in an OrderID

Issues and Questions

Possible implementation of card validation (if it becomes externally available)

Read more

User Profile Data and Domain Layers

Mobile Competencies

Auth Latency Reporting

Untitled