PayPal client app

This is a client app to integrate PayPal payment methods and package tracking into commercetools-based shop. It is dedicated to be used with PayPal commercetools connector. An integration example in a commercetools frontend demo shop can be found in our CoFe integration example repository and viewed at https://poc-mediaopt2.frontend.site.

Some additional details on the integration of the client are also provided in the docs folder on github.

The client app is built with React and uses the PayPal JS SDK.

In here we explain how to use the client app and get payment methods to work.

Installation

Please refer to the connector documentation for the installation of the connector and if you use commercetools frontend for your storefront refer to commercetools official documentation.

The client can be directly installed to the shop frontend using npm:

npm i paypal-commercetools-client

The client is react-based, so for other frameworks it is needed to load the React script in project stack.

And then the components are imported directly from the package, see for example the payment form in CoFe integration.

Usage

The client app provides a set of components to handle different payment methods. The components accept a set of props to configure the payment process. The general properties are the same for all payment methods, while some payment methods have also own specific properties.

General properties

API endpoints

For all Api endpoints it is your responsibility to develop this API. These endpoints are responsible for communication with commercetools backend. Our implementation can be found in the CoFe integration example repository controllers folder. The return types are provided in the client types folder.

Property	Type/request type	Request response	Description	Our implementation
createPaymentUrl	string /POST	CreatePaymentResponse	The url that gets called to the endpoint of the connect app to create a payment in commercetools.	createPayment
getSettingsUrl	string /POST	GetSettingsResponse	The url that gets called to the endpoint of the connect app to get settings of PayPal in commercetools.	getPayPalSettings
createOrderUrl	string /POST	CreateOrderResponse	The url that gets called to the endpoint of the connect app to create a PayPal order in commercetools.	createPayPalOrder
onApproveUrl	string /POST	OnApproveResponse	The url that gets called to the endpoint of the connect app to capture a PayPal order in commercetools.	capturePayPalOrder
authorizeOrderUrl	string /POST	OnApproveResponse	The url that gets called to the endpoint of the connect app to authorize a PayPal order in commercetools.	authorizePayPalOrder

other general properties

• onApproveRedirectionUrl: string If you want to redirect to a page in onApprove step then set it to this property. It is useful for the buy now process and its review page.

• cartInformation: object
  Information about the customers cart to crate payments with. Structure:

  account: {
    email: string;
  };
  billing: {
    firstName: string;
    lastName: string;
    streetName: string;
    streetNumber: string;
    city: string;
    country: string;
    postalCode: string;
  };
  shipping: {
    firstName: string;
    lastName: string;
    streetName: string;
    streetNumber: string;
    city: string;
    country: string;
    postalCode: string;
  };
  

• purchaseCallback: (result: any) => void
  Function to execute after a successful purchase.

• requestHeader: object Information that you want to send to the server as a header. Structure for CoFe:

  "Frontastic-Session": string;
  "Commercetools-Frontend-Extension-Version": string;
  

• shippingMethodId: string
  The id of the selected shipping. It will be sent back in the create purchase call to calculate the correct shipping costs.

• options: object options will pass to PayPalScriptProvider component and you can see the structure on PayPal documentation. ReactPayPalScriptOptions.

Vaulting properties

These properties are used when you want to set up vaulting during purchase.

• enableVaulting: boolean
  Set true if you want to enable vaulting in the payment method.

• getUserInfoUrl: string
  POST-Request - we get a GetUserInfoResponse
  It is your responsibility to develop this API
  The URL that gets called to the endpoint of the connect app to get some information related to vaulting for the logged-in user. Communicates with commercetools backend
  See getUserInfo in our CoFe integration example repository

Vaulting for purchase later

In addition to Vaulting properties we have the following properties to vault for purchase later.

• createVaultSetupTokenUrl: string
  POST-Request - we get a CreateVaultSetupTokenResponse
  It is your responsibility to develop this API
  The URL that gets called to the endpoint of the connect app to create a vault setup token for the logged-in user. Communicates with commercetools backend
  See createVaultSetupToken in our CoFe integration example repository

• approveVaultSetupTokenUrl: string
  POST-Request - we get a ApproveVaultSetupTokenResponse
  It is your responsibility to develop this API
  The URL that gets called to the endpoint of the connect app to approve a vault setup token for the logged-in user. Communicates with commercetools backend
  See approveVaultSetupToken in our CoFe integration example repository

Payment specific properties

In addition, each payment component comes with its own specific properties.

PayPal

PayPal components props are based on PayPal props and you can see them on PayPal official documentation PayPalButtonsComponentOptions.

• paypalMessages: object Pass this object here if you want to show the PayPal Messages in the PayPal component. In order to see the structure check the parameters of PayPalMessages.

PayPalMessages

PayPal messages props are based on PayPalMessages props and you can see them on PayPal official documentation PayPalMessagesComponentOptions.

ApplePay

• applePayDisplayName: string
  Name of your store.

GooglePay

Have a look at Google's specification for a detailed explanation of the options

• environment: string
  "TEST" or "PRODUCTION";
• allowedCardNetworks: string[] One or more card networks that you support, also supported by the Google Pay API.
• allowedCardAuthMethods: string
  "PAN_ONLY" (cards on file) and "CRYPTOGRAM_3DS" (Android powered device token)
• callbackIntents: string[]
  Specifies intents for PaymentDataCallback
• apiVersion: number
  Major API version
• apiVersionMinor: number
  Minor API version
• totalPriceStatus: string
  "FINAL" or "ESTIMATED"
• buttonColor: string
• buttonType: string
• buttonRadius: number
• buttonSizeMode: string
• verificationMethod: string

CardFields

• authenticateThreeDSOrderUrl: string POST-Request Communicates with commercetools backend to get the 3d Secure validation results and returns an object with the liability_shift, enrollment_status, and authentication_status.
  See the examples in our CoFe integration example repository

HostedFields

HostedFields are deprecated; CardFields is the preferred way to use advanced card payments.

• getClientTokenUrl: string
  POST-Request - we get a ClientTokenResponse
  It is your responsibility to develop this API
  The URL that gets called to the endpoint of the connect app to get the client token to use in PayPalHostedFieldsProvider component in commercetools. Communicates with commercetools backend
  See getClientToken in our CoFe integration example repository

PaymentTokens

If you want to get a list of vaulted payments you can use this component. It will also give you the avility to remove the vaulted account.

You need to pass properties that are mentioned in the Vaulting properties section and also pass the following specific property.

• removePaymentTokenUrl: string
  POST-Request - we get a GetUserInfoResponse
  It is your responsibility to develop this API
  The URL that gets called to the endpoint of the connect app to remove a Payment Token in the PaymentTokens component in commercetools. Communicates with commercetools backend
  See removePaymentToken in our CoFe integration example repository

PayUponInvoice

It is your responsibility to check the eligibility and enable Pay upon Invoice with Ratepay in the PayPal business account.

You need to pass general properties and also pass the following specific properties:

• merchantId: string
  Identifier of the merchant, can be found in PayPal Account Settings > Business Information > PayPal Merchant ID.
• pageId: string Describes the type of the page at which checkout is called, the supported values can be found at Modify the code section of the PayPal Pay Upon Invoice Documentation
• invoiceBenefitsMessage:string
  Optional parameter that allows to set custom message for describing the benefits of payment upon invoice. If you provide the custom value you must inform the buyer that they have 30 days to pay Ratepay via bank transfer.
• customLocale: string
  Optional parameter that allows to set the Pay Upon Invoice interface language. Supported values are 'en' for English and 'de' for German.

See also

A brief description of the integration of the client to commercetools frontend and the json with the payment methods properties can be found in the docs folder. For the workflows of the full integration including connector, client and commercetools frontend please refer to connector documentation.

Support

If you need support with the integration, please write a mail to [email protected]