Web SDK

Overview

The PPH Web SDK is a single page script and that is integrated on your final Payment or Checkout page.

Note: This is an early beta release with limited functionality compared to the currently available iOS and Android SDKs.

The following restrictions apply to this beta version:

  • Available only to the US region.
  • Available only on Windows desktop/laptop browsers. Phone/Tablet mobile browsers are not supported.
  • The PayPal Chip Card Reader is the only supported reader.
  • USB is the only supported connection method.
  • No multi-card reader support: if two USB readers are connected, the SDK automatically connects to the first one it recognizes.
  • Readers are manually pre-configured for this beta release.
  • No auth/capture model. Transactions are sale only.
  • Vaulting with Braintree is not supported at this time.
  • Reset is not supported: do not reset the card reader in this version for any reason.

Integration

Similar to PayPal Here's iOS and Android SDKs, the Web SDK uses standard OAuth to authenticate. Make sure that you have already created your REST App and have reviewed the Merchant Onboarding section of the documentation. Also, review the GitHub repository for the latest script link and SDK version information.

Setup

PayPal Here Web SDK uses a headless standalone desktop application (PPHWebInterface) to interact with connected card readers. The one-time setup must be done before you can process payments and must be done on each machine. PayPal recommends using a separate setup page for the setupUI. Include the following snippet in your setup page:

<button type="button" id='setupPPH' onclick='onSetupPayPalHereBtnClicked()'>Setup PayPal Here</button>
<script>
function onSetupPayPalHereBtnClicked() {
  pphwebsdk.Setup.startUIFlow(function() {
    // Done
  });
}
</script>

To make sure that the setup has been completed on your computer prior to processing payments, call isSetupComplete. If it hasn’t completed yet, call the startUIFlow as mentioned above. Otherwise, if it has already completed, you can continue on to your payment flow.

<script>
pphwebsdk.Setup.isSetupComplete.then(function() {
    // Continue to payment flow
}).catch(function() {
    // Run startUIFlow to setup SDK
});
</script>

Accepting payments

Once everything has been set up, follow the steps in the order listed here to accept payments:

Note: See Object references later in this section for details on various options for the different objects in this flow.

  1. Create identity. This is similar to the initializeMerchant function of the iOS and Android SDKs. It tells the SDK which merchant account is receiving the payment and in which environment.

    <script>
      var identity = pphwebsdk.Identity.create(access_token).refreshUrl(refresh_url) .environment(environment);
    </script>
    
    Attribute Type Description
    access_token String Required
    Valid access token for the merchant account.
    refresh_url String Optional
    URL that the SDK will reach out to refresh the access token when it expires.
    environment String Required
    Needs to either be live or sandbox.
  2. Payment configuration. Even though you can process transactions with default values, the SDK allows you to customize the flow depending on your needs. The following code snippet creates a default configuration:

    <script>
      var payment_config = pphwebsdk.PaymentConfiguration.create();
    </script>
    
  3. Create order. In order to process payments, you need an order. The following snippet shows how to create an order and add items to it:

    <script>
      var order = pphwebsdk.Order.create();
      order.item('Cake').price(1.00).quantity(3);
      order.item('Coffee').price(2.00).quantity(3);
    </script>
    
  4. Process payment. Once you have the identity, payment configuration, and order ready, you can then accept the payment. The following snippet shows how to process a sale transaction:

    <script>
      pphwebsdk.Payment.create(identity, payment_config).for(order).as(pphwebsdk.Types.PaymentMethod.CARD).sale();
    </script>
    

Object references

The following tables outline the different options for the objects mentioned above:

Payment configuration

Object Description Default
create() Creates a new PaymentConfiguration. N/A
reader() Create card reader object. Auto connects to the connected USB card reader.
subscribeEvents(eventhandler) Subscribe to payment events. No events are subscribed to.

Payment

Object Description
for(order) Reference to the order instance.
as(paymentMethod) Reference to payment method types.
sale() Process the payment as a sale.
refund() Process a refund.

Note: sale() and refund() are action calls that need to be last in the chain, as noted in the samples.

Order

Object Description
item(name) Create a new item.
remove(item) Remove an item.
number(orderNumber) Custom order number. Similar to the invoice number of iOS and Android.
tip(amount) Adds gratuity to the order.

PaymentMethod types

Refer to the samples for more details on the usage of these payment method types.

Type Values
SimulatedAction SWIPE, CHIP, CONTACT_LESS
PaymentMethod CASH, CHECK, KEYIN, CARD

Item

Object Description
quantity(quantity) Quantity of given item(s).
price(price) Price of the individual item.

RefundOrder

Object Description
create() Create a refund for an existing order.
with(invoiceId) This is the PayPal invoice ID that was received as part of the transaction record with the onPaymentSuccess event.
for(refundAmount) Amount to be refunded.
on(transactionNumber) This is the transaction number that was received as part of the transaction record with the onPaymentSuccess event.

Events

Event handlers are functions with required arguments as mentioned below. Refer to the samples for details on how these events are implemented.

Event Argument Description
onPaymentSuccess transactionRecord The transactionRecord will contain the transactionNumber and PayPal invoiceId.
onPaymentFailure error The error will contain a code which is used to get more detail about the error.
onRefundSuccess transactionRecord The transactionRecord will contain the transactionNumber for the refund.
onRefundFailure error The error will contain a code which is used to get more detail about the error.

Samples

Below are some simple samples for event handlers, payment, and refund:

Event handlers

<script>
  var eventhandler = {
    onPaymentSuccess: function (txnRecord) {
      alert('Completed Transaction ' + txnRecord.transactionNumber);
    },
    onPaymentFailure: function (error) {
      alert('Failed Transaction ' + error.code);
    }
  }
</script>

Payment with full options

<script>
  var identity = pphwebsdk.Identity.create('myaccesstoken').refreshUrl('myrefreshUrl');

  var payment_config = pphwebsdk.PaymentConfiguration.create();
  payment_config.reader().subscribeEvents(eventhandler);

  var order = pphwebsdk.Order.create();
  order.item('Cake').price(1.00).quantity(3);
  order.item('Coffee').price(2.00).quantity(3);
  order.tip(1.00);

  var payment = pphwebsdk.Payment.create(identity, payment_config);
  payment.for(order).as(pphwebsdk.Types.PaymentMethod.CARD).sale();
</script>

Refund

<script>
  var identity = pphwebsdk.Identity.create('myaccesstoken').refreshUrl('myrefreshUrl');

  var payment_config = pphwebsdk.PaymentConfiguration.create();
  payment_config.reader().subscribeEvents(eventhandler);

  var order = pphwebsdk.RefundOrder.create().on(transactionNumber).with(invoiceId).for(amount);

  var payment = pphwebsdk.Payment.create(identity, payment_config);
  payment.for(order).as(pphwebsdk.Types.PaymentMethod.CARD).refund();
</script>

When your integration is complete, check the going live page to ensure that you have everything ready for activation. Once that is working, you can implement other customizations that are available with the SDK into your integration.