7 PayPal
This chapter covers EFTLink integration with PayPal.
EFTLink General
This document assumes static EFTLink configuration. When deploying with a POS that supports dynamic configuration, all property settings referred to below should be set on the POS, and not directly into local property files. It should be read in conjunction with the Oracle Retail EFTLink Framework Installation and Configuration Guide.
System Architecture
PayPal is a REST service architecture. EFTLink connects to it using HTTP POST with JSON pay load.
Fileset
In addition to standard EFTLink files, PayPal uses:
-
cores/PayPal/PayPalCore.jar
– executable code for the PayPal EFTLink core. -
paypal.properties
– configuration settings to specify which features are enabled and to define communication parameters for the interface with PayPal REST service. -
paypal_dynamic.properties
- dynamic configuration file that contains the encrypted credentials needed for authenticating with PayPal.
Language
The translation files for this core should not require alteration,
but if necessary then this can be accomplished by amending the relevant Lang<CC>_<Core>.properties
within the base eftlink
folder.
The language used will follow the language set in the EFTLink framework; see the Oracle Retail EFTLink Framework Installation and Configuration Guide, EFTLink General Information, Translation section.
EftlinkConfig.properties
DisplayLanguage = EN
Supported country codes are CN, DE, EN, ES, FR, IT, JP, NL, PT, RU and SV.
Core Class Name
PayPal core is not a standalone primary core but an EWallet core. This is setup together with a different primary core in a multi core environment. The following example needs to be set manually in EFTLinkConfig.properties
. In this example, there are 2 cores. The primary one is OPI Retail core and PayPal is the EWallet core.
NumEPSCores=2
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore
EPSCore1 = oracle.eftlink.paypal.PayPalCore
EwalletCore = 1
Merchant Account OnBoarding
Before processing PayPal transactions, you need to create two REST API apps (Location and Payment) in PayPal's portal. This process is described in the section Setting up the API Caller Account of the PayPal document In-Store QR Code Integration for Direct Merchant Partners. You need to get this from PayPal.
After creation, you should have the client ID and client secret credentials for each API. Send the client ID of both apps to your PayPal contact. PayPal sets up the permission for the accounts. Once permission is set up, you need to encrypt these credentials in file.
See the section below, Encrypting PayPal's Credentials, on how to accomplish this. Once encrypted, you can now enroll your store location. This is done by Xstore sending the login request to EFTLink. Once the store is enrolled successfully, you can process payments, reversal, and verified refunds.
Encrypting PayPal's Credentials
-
Assuming you installed EFTLink in C:\eftlink. Copy all files from C:\eftlink\cores\PayPal except the jar file to C:\eftlink.
-
Open a command terminal. Go to C:\eftlink directory. Make sure you have Java in your Windows system path. If not set it first.
-
First, create the key store file that will hold the encryption and decryption key. Execute the command below.
The script creates a data directory on C:\eftlink with the paypal.keystore file in it.
encrypt-paypal.bat -k
-
You can now encrypt the client ID and client secret of both the location and payment API. On the command terminal, execute the command below.
This will ask you to enter the client ID and client secret of your location and payment API respectively.
The script writes the encrypted values together with the initialization vector into paypal_dynamic.properties file.
encrypt-paypal.bat -e
Configuration Settings
The full set of configuration properties is defined and commented
in paybylink.properties
.
Key Settings
Settings that may be different for each POS.
Table 7-1 PaybyLink - Key Settings
Setting | Description | Default | Example |
---|---|---|---|
store.name |
Name of the store. |
NA |
|
store.id |
Store ID |
NA |
|
store.address.line1 |
Store's street address. |
NA |
|
store.address.city |
Store's city address. |
NA |
|
store.address.state |
Store's state address. |
NA |
|
store.address.country |
Store's country address. |
NA |
|
store.address.postalCode |
Store's postal code. |
NA |
|
store.latitude |
Store's latitude location. |
NA |
|
store.longitude |
Store's longitude location. |
NA |
|
Secondary Settings
These settings are normally correct at their default values but can be overridden if necessary.
Table 7-2 PayPal - Secondary Settings
Setting | Description | Default | Example |
---|---|---|---|
store.availability |
Whether this location is currently open for business. |
open |
|
store.tabType |
The type of tab supported at this location. |
none |
|
store.mobility |
The mobile setting for this location. |
fixed |
|
store.gratuityType |
The type of gratuity that is accepted by this location. |
none |
|
capture.endpoint |
The capture service end point context. |
/v2/retail/captures |
|
token.endpoint |
The token service end point context. |
/v1/oauth2/token |
|
location.endpoint |
The location service end point context. |
/retail/merchant/v1/locations |
|
cancel.endpoint |
The end point context for cancelling payment or refund. |
/v2/retail/cancel |
|
base.api.url |
Base URL of PayPal's services. |
https://api.paypal.com |
|
connect.timeout |
Timeout in milliseconds when connecting to PayPal. |
5000 |
|
payment.read.timeout |
Read timeout in milliseconds for PayPal's payment related services.(ex. capture.cancel,refund). |
300000 |
|
other.read.timeout |
Read timeout in milliseconds for PayPal's services non-payment related service.(ex. token service). |
120000 |
|
merchant.category.code |
Merchant category code. |
5965 |
|
qr.code.max.length |
The maximum digits of the QR code. |
18 |
|
crypto.keygenType |
Specifies the keygen type to use for the internal encryption processing. |
AES |
|
crypto.cipherType |
Specifies the cipher type to use for the internal encryption processing. |
AES/GCM/PKCS5Padding |
|
crypto.keySize |
Sets size of the keystore key. Note: When keysize is greater than 128, you may get java.security.InvalidKeyException: Illegal key size or default parameters. If this happens you will need to download additional Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files and extract those files to $JAVA_HOME/jre/lib/security/ |
128 |
|
crypto.iterations |
Specifies the number of iterations to use for the internal encryption processing. |
100000 |
|
crypto.factoryinstance |
Sets crypto factory instance for keystore password encryption. |
PBKDF2WithHmacSHA512 |
|
crypto.secretkeyspec |
Sets crypto secret key spec for keystore password encryption. |
AES |
|
crypto.keystoretype |
Sets keystore type |
JKS |
crypto.keystoretype = JKS |
crypto.digest |
Sets digest for keystore password. |
SHA-512 |
|
crypto.hashbyteSize |
Sets hash byte size for keystore password. |
384 |
|
Supported Functions
Below is a list of supported functionalities of the interface to PayPal. Many functionalities are provided by PayPal. (Please refer to interface specification for details) but are not implemented because of the business requirement.
Table 7-3 PayPal - Supported Functions
Function | Description |
---|---|
Payment |
Sends payment request to PayPal. The user initiates the payment by scanning a PayPal application generated QR code from the customer's mobile phone. If successful, appropriate receipts will be printed at the end of transaction. |
Reversal |
Sends reversal request to PayPal. This will reverse a transaction specified by the transaction ID, found on the receipt, which must be captured by the POS and pass on to EFTLink. |
Refund |
Sends refund request to PayPal. This will refund a transaction with specified amount. |
Store Registration |
This is accomplished by either Xstore v20 sending the login request or running the built in LocationService console application within the core. |