PayPal Here Web SDK

Important: PayPal Here is deprecated. PayPal doesn't accept new integrations but continues to support existing integrations.

Overview

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

The following restrictions apply to this SDK:

• Available only to the US region.
• Available only on Windows desktop/laptop browsers. Phone/Tablet mobile browsers are not supported.
• 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.

Note: The card readers that are supported with this SDK are the Chip Card Reader, the Chip and Tap Reader, and the Verifone P400 reader. You can order the Chip Card Reader from our web store as normal but the Chip and Tap readers and P400 readers need manual configuration to allow the USB connection. Therefore, if you would like to order Chip and Tap readers or Verifone P400 readers, please send an email to pph-inquiry@paypal.com.

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>

function onSetupPayPalHereBtnClicked() {
  pphwebsdk.Setup.startUIFlow().then(function (completionStep) {
      // PPHWebInterface has been installed and, if clicked, a test of the connected card reader was completed.
      // setup is complete
  });
}

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.

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

Note: The isSetupComplete() method should be the first thing that you run and the response of that should dictate the next step in the process. If it's a success you will continue on with the payment flow and if it's not, then you should run startUIFlow to complete the setup.

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. For more information on token management, please refer to the PayPal Here Onboarding Process.

     var identity = pphwebsdk.Identity.create(access_token).refreshUrl(refresh_url).environment(environment);
   

   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	Enum	Required Needs to either be pphwebsdk.Types.Environment.LIVE or pphwebsdk.Types.Environment.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. Payment configuration is required for subscribing to events and customizing the payment flow. The following code snippet creates a default configuration:

     var payment_config = pphwebsdk.PaymentConfiguration.create();
   

   Starting with version 1.1.1, the reader connection is handled by the payment configuration. You will create a reader object and then specify the connection type and reader manufacturer.

         var reader = payment_config.reader();
         reader.connectionType(pphwebsdk.Types.ReaderConnectionType.USB);
         reader.manufacturer(pphwebsdk.Types.Manufacturers.MIURA);
   
   

   Object	Description	Values
   connectionType()	Accepts enum value for the reader connection type.	pphwebsdk.Types.ReaderConnectionType.USB
   manufacturer()	Accepts enum value for the reader being connected to.	pphwebsdk.Types.Manufacturers.MIURA pphwebsdk.Types.Manufacturers.INGENICO pphwebsdk.Types.Manufacturers.VERIFONE

   Note: The MIURA manufacturer correlates to the Chip Card Reader, the INGENICO manufacturer correlates to the Chip and Tap Reader, and the VERIFONE manufacturer correlates to the Verifone P400 reader which is only available for use with the Web SDK at this time.

3. Create order. In order to process payments or refunds, you need an order. The following snippet shows how to create an order for a payment and add items to it:

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

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:

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

   As part of the payment flow, the SDK will automatically prompt for any reader firmware updates that may be available. You'll need to subscribe to the success or failure events on the Reader object to get the status of said updates:

   // Readers will automatically prompt for the update if there is one available. There are two events, on the Reader object, that will fire after an update.
   pphwebsdk.Reader.subscribe
     .firmwareUpdateSuccess(function (upgradedDevice) {
       // Reader firmware update was a success
     })
     .firmwareUpdateFailure(function (err) {
       // Reader firmware update failed - handle accordingly
     });
   

   When the reader firmware update is done successfully, the SDK will simply continue on with the payment flow without you having to action anything. If the not now option was pressed on the reader firmware update UI, then you will need to call pendingUpdateInstall() to trigger that firmware update flow and install the update. If there is a firmware update, it needs to be completed successfully before you will be able to process another transaction. You can also call pendingUpdateInstall() prior to making a payment if you'd like to proactively check for any firmware updates available.

   pphwebsdk.Reader.pendingUpdateInstall();
   

Object references

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

Payment configuration

Payment

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

Order

PaymentMethod types

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

Item

Order for refund

Events

Event handlers are functions that are subscribed to as part of the PaymentConfiguration. These events may have arguments as mentioned below. Refer to the samples for details on how these events are implemented.

Samples

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

Event handlers

  var payment_config = pphwebsdk.PaymentConfiguration.create();
  payment_config.subscribe
    .onConnectReaderSuccess(function (details) {
      //Details of card reader provided
    })
    .onConnectReaderFailure(function (err) {
      //Unable to connect to reader - handle error scenario
    })
    .onMerchantInitializeSuccess(function (merchant) {
      //Merchant initialized successfully
    })
    .onMerchantInitializeFailure(function (err) {
      //Unable to intialize merchant - handle error scenario
    })
    .onPaymentSuccess(function (txnRecord) {
      //Payment success
    })
    .onPaymentFailure(function (err) {
      //Payment failed - handle error scenario
    });

Payment with full options

  var identity = pphwebsdk.Identity.create(access_token).refreshUrl(refresh_url).environment(environment);

  var payment_config = pphwebsdk.PaymentConfiguration.create();
  payment_config.subscribe
    .onConnectReaderSuccess(function (details) {
      //Details of card reader provided
    })
    .onConnectReaderFailure(function (err) {
      //Unable to connect to reader - handle error scenario
    })
    .onMerchantInitializeSuccess(function (merchant) {
      //Merchant initialized successfully
    })
    .onMerchantInitializeFailure(function (err) {
      //Unable to intialize merchant - handle error scenario
    })
    .onPaymentSuccess(function (txnRecord) {
      //Payment success
    })
    .onPaymentFailure(function (err) {
      //Payment failed - handle error scenario
    });

  var reader = payment_config.reader();
  reader.connectionType(pphwebsdk.Types.ReaderConnectionType.USB);
  reader.manufacturer(pphwebsdk.Types.Manufacturers.MIURA);

  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();

Refund

  var identity = pphwebsdk.Identity.create(access_token).refreshUrl(refresh_url).environment(environment);

  var payment_config = pphwebsdk.PaymentConfiguration.create();
  payment_config.subscribe
    .onRefundSuccess(function (txnRecord) {
      //Payment success
    })
    .onRefundFailure(function (err) {
      //Payment failed - handle error scenario
    });

  var reader = payment_config.reader();
  reader.connectionType(pphwebsdk.Types.ReaderConnectionType.USB);
  reader.manufacturer(pphwebsdk.Types.Manufacturers.MIURA);

  var order = pphwebsdk.Order.create().on(txnId).with(ppInvoiceId).for(totalAmount);

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

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.