Difference between revisions of "X-Cart:Adjusting PayPal Configuration Settings in X-Cart"

From X-Cart 4 Classic
Jump to: navigation, search
(Adjusting the settings for Website Payments Pro and Website Payments Pro Payflow Edition)
(PayPal Payments Pro configuration settings)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The page allowing you to adjust PayPal configuration settings can be accessed by clicking the link 'Configure' below PayPal entry in the <u>'Payment methods</u>' dialog box. The page is titled '<u>Payment gateways</u>', and it contains a dialog box titled '<u>Settings</u>'. The upper part of the '<u>Settings</u>' dialog box provides names of PayPal solutions pre-integrated with X-Cart and allows you to choose a solution that you would like to use at your store. The lower part provides a set of fields that need to be adjusted to configure the selected solution (The contents of the lower part changes depending on the solution selected).
+
After you choose the PayPal payment method you would like to use at your store, you must adjust its configuration settings. The configuration settings for the chosen PayPal payment method are displayed in the lower part of the PayPal configuration page.
  
To adjust the configuration settings for your store's PayPal payment method, you need to select the PayPal solution that you wish to use and to adjust the respective set of configuration fields that will appear in the lower part of the dialog box.
+
This article provides notes on adjusting the configuration settings for specific PayPal payment methods.
  
== Adjusting Website Payments Standard settings ==
 
  
To adjust settings for PayPal Standard:
+
== PayPal Payments Standard configuration settings ==
  
1. In the '<u>Settings</u>' dialog box, select the '<u>Website Payments Standard</u>' option:
+
The page where you adjust the configuration settings for <u>PayPal Payments Standard</u> is as follows:
 +
:[[File:Pp_payments_standard.png|border]]
 +
You need to adjust the following fields:
 +
:* '''Account''': The email address you use to access your PayPal Business account.
 +
:* '''Description of the purchase that will be displayed on PayPal payment page''': A generic description of the purchase that should be displayed to the customer (i.e. books. music, etc). This field is optional.
 +
:* '''Currency''': The currency that should be used for payments via this method.
 +
:* '''Order prefix''': Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.<br />{{Note1 | '''Note:''' The "Order prefix" field is required when using the same PayPal account for several online stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
 +
:* '''Test/Live mode''': PayPal operating mode ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:PayPal#Testing_your_PayPal_payment_methods | Testing your PayPal payment methods]]').
 +
:* '''Action to be performed on order placement''': Choose ''Auth only'' or ''Auth and Capture''.
 +
:* '''Address override''': When this option is enabled, the address specified by the customer during checkout in X-Cart and passed from X-Cart to PayPal overrides the PayPal member's stored address. The customer is shown the passed-in address but cannot edit it. When this option is disabled, the customer can edit the passed-in address or select another address that he/she has stored with PayPal.<br />{{Note1|'''Note:''' Disabling this option may lead to a situation when the address specified by the customer during checkout in X-Cart and saved in the X-Cart order details differs from the address in the relevant PayPal transaction details. This can cause confusion as to which address the order should be shipped to.}}
 +
If you have opted in for the ''Auth only'' action to be performed on order placement or if you are going to process refunds via X-Cart back-office, you must also provide your API access credentials. API access will be used to establish connection between X-Cart and PayPal API to perform Capture/Void/Refund transactions.
 +
:: {{Note1|'''Note:''' Help on retrieving your API access credentials is available here: [http://qwyx.co/apihowto http://qwyx.co/apihowto].}}
 +
Adjust the following fields:
 +
:* '''API access username''': Your API access username as provided in your PayPal account profile.
 +
:* '''API access password''': Your API access password as provided in your PayPal account profile.
 +
:* '''Use PayPal authentication method''': The type of authentication method that you wish to use (''API signature'' or ''API certificate'').<br />The simplest authentication method is using an API Signature, an encrypted string value that you include with your API calls to identify yourself. Use this method if you want the fastest and easiest way to use the PayPal API.<br />An API Certificate is a file that you download from PayPal that contains a private key and public certificate which identify you to PayPal. Use this method if you have full control of your web server and are familiar with SSL encryption.<br />If you choose to use an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <u><xcart_dir>/payment/certs/</u>, where <u><xcart_dir></u> is the name of the directory in which X-Cart is installed.
 +
:* '''API certificate filename''': If you have chosen ''API certificate'' as your PayPal authentication method, specify the filename of your API certificate.
 +
:* '''API signature''': If you have chosen ''API signature'' as your PayPal authentication method, copy and paste your API signature into this field.
 +
<br /><br />
  
 +
== Website Payments Pro Hosted configuration settings ==
 +
The page where you adjust the configuration settings for <u>Website Payments Pro Hosted</u> is as follows:
 +
: [[File:Pp_hosted.png|border]]
 +
You need to adjust the following fields:
 +
:* '''API Access username''' and '''API Access password''': Your API username and API password as provided by your PayPal account.<br />{{Note1|'''Note''': Help on retrieving your API username and API password, as well as your API signature/certificate, is available here: http://qwyx.co/apihowto }}
 +
:* '''Use PayPal authentication method''': The type of authentication method that you are going to use (Signature or Certificate).<br />The simplest authentication method is using an API Signature, an encrypted string value that you include with your API calls to identify yourself. Use this method if you want the fastest and easiest way to use the PayPal API.<br />An API Certificate is a file that you download from PayPal that contains a private key and public certificate which identify you to PayPal. Use this method if you have full control of your web server and are familiar with SSL encryption.<br />If you have chosen an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <u><xcart_dir>/payment/certs/</u>, where <u><xcart_dir></u> is the name of the directory in which X-Cart is installed.
 +
:* '''API certificate filename''': If you have chosen ''API certificate'' as your PayPal authentication method, specify the filename of your API certificate.
 +
:* '''API signature''': If you have chosen ''API signature'' as your PayPal authentication method, copy and paste your API signature into this field.
 +
:* '''Currency''': The currency that should be used for payments via this method.
 +
:* '''Test/Live mode''': PayPal operating mode ('Live' should be selected for live stores, 'Test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:PayPal#Testing_your_PayPal_payment_methods | Testing your PayPal payment methods]]').
 +
:* '''Action to be performed on order placement''': ''Auth only'' or ''Auth and Capture''.
 +
:* '''Order prefix''':  Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.<br />{{Note1 | '''Note:''' The "Order prefix" field is required when using the same PayPal account for several online stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
 +
:* '''Payflow vendor''': The Login ID or merchant login you created when you signed up for PayPal Merchant Services. The user is also the vendor, unless you have created additional accounts (users) within PayPal Manager.
 +
:* '''Payflow partner''': The PayPal partner/reseller through which you registered for your Payflow account.
 +
The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:
 +
:* '''Express Checkout specific: Gradient color:''' Gradient fill color of the border around the cart review area.
 +
:* '''Express Checkout specific: Header Image URL:''' Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.<br />We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.
 +
<br /><br />
  
[[Image:pp_standard.gif|center|533px]]
+
== PayPal Payments Pro configuration settings ==
  
 +
The following notes refer only to <u>PayPal Payments Pro</u> payment method using PayPal API. For notes on the configuration settings for <u>Website Payments Pro Payflow Edition</u> (the PayPal Payments Pro method using Payflow API), see the [[X-Cart:Adjusting_PayPal_Configuration_Settings_in_X-Cart#Website Payments Pro Payflow Edition configuration settings | Website Payments Pro Payflow Edition configuration settings]] section.<br /><br />
 +
The page where you adjust the configuration settings for <u>PayPal Payments Pro</u> is as follows:
 +
: [[File:Pp_payments_pro.png|border]]
 +
To ensure that PayPal integration will work correctly for your store, you must configure PayPal Payments Pro in X-Cart in exactly the same way as you have configured PayPal Payments Pro (PayPal API) in X-Payments:
 +
:* '''Select payment method configured on X-Payments side''': Select the name of the payment configuration you will use.
 +
:* '''API Access username''' Same as contents of the "API Access Username" field for the selected payment configuration in X-Payments.
 +
:* '''API Access password''': Same as contents of the "API Access Password" field for the selected payment configuration in X-Payments.
 +
:* '''Use PayPal authentication method''': The type of authentication method specified in the "API method" field for the selected payment configuration in X-Payments. If you have chosen an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <u><xcart_dir>/payment/certs/</u>, where <u><xcart_dir></u> is the name of the directory in which X-Cart is installed.
 +
:* '''API certificate filename''': If you have chosen ''API certificate'' as your PayPal authentication method, specify the filename of your API certificate.
 +
:* '''API signature''': If you have chosen ''API signature'' as your PayPal authentication method, copy and paste your API signature into this field.
 +
:* '''Currency''': The currency specified in the "Currency" field for the selected payment configuration in X-Payments.
 +
:* '''Test/Live mode''': The PayPal operating mode specified in the "Test/Live mode" field for the selected payment configuration in X-Payments.
 +
:* '''Action to be performed on order placement''': The action specified in the "Initial transaction" field for the selected payment configuration in X-Payments.
 +
:* '''Order prefix''':  The order prefix specified in the "Order prefix" field for the selected payment configuration in X-Payments.
 +
The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:
 +
:* '''Express Checkout specific: Gradient color:''' Gradient fill color of the border around the cart review area.
 +
:* '''Express Checkout specific: Header Image URL:''' Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.<br />We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.
 +
<br /><br />
  
2. Adjust the fields in the lower part of the dialog box as follows:
+
== Website Payments Pro Payflow Edition configuration settings ==
  
* <u>Account</u>: The email address you use to access your PayPal Business account.
+
The page where you adjust the configuration settings for <u>Website Payments Pro Payflow Edition</u> is as follows:
* <u>Payment for</u>: A generic description of the products being sold. This field will show what the customer is buying (i.e. books. music, etc). This field is optional.
+
:[[Image:Pp_pro_payflow_edition.png|border]]
* <u>Currency</u>: The currency to be used for PayPal payment transactions.
+
To ensure that PayPal integration will work correctly for your store, you must configure Website Payments Pro Payflow Edition in exactly the same way as you have configured PayPal Payments Pro (Payflow API) in X-Payments:
* <u>Order prefix</u>: Your trading name or any other prefix that will help you identify a payment transaction as originating from this store.
+
:* '''Select payment method configured on X-Payments side''': Select the name of the payment configuration you will use.
 +
:* '''Partner''': Same as contents of the "Partner name" field for the selected payment configuration in X-Payments.
 +
:* '''Merchant login''': Same as contents of the "Merchant login" field for the selected payment configuration in X-Payments.
 +
:* '''User''': Same as contents of the "User" field for the selected payment configuration in X-Payments.
 +
:* '''Password''': Same as contents of the "Password" field for the selected payment configuration in X-Payments.
 +
:* '''Currency''': The currency specified in the "Currency" field for the selected payment configuration in X-Payments.
 +
:* '''Test/Live mode''': The PayPal operating mode specified in the "Test/Live mode" field for the selected payment configuration in X-Payments.
 +
:* '''Action to be performed on order placement''': The action specified in the "Initial transaction" field for the selected payment configuration in X-Payments.
 +
:* '''Order prefix''':  The order prefix specified in the "Order prefix" field for the selected payment configuration in X-Payments.
 +
The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:
 +
:* '''Express Checkout specific: Gradient color:''' Gradient fill color of the border around the cart review area.
 +
:* '''Express Checkout specific: Header Image URL:''' Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.<br />We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.
 +
:* '''Express Checkout specific: Page Style:''' Name of the page style that you created in your PayPal profile. If you haven't created one, leave this blank.
  
{{Note1 | '''Note:''': The "Order prefix" field is required when using the same PayPal account for several on-line stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
+
To create your custom PayPal payment page, follow these steps:
 +
:# Log in to your PayPal account at https://www.paypal.com.
 +
:# Find '''Custom payment pages''' and click the <u>Update</u> link to the right of it.
 +
:# Click '''Add'''.
 +
:# In the '''Page Style Name''' box, enter a name for the page style. (You can use any name you want, as long as it's not "PayPal".)
 +
:# Enter your other design parameters in the spaces provided.
 +
:# When finished, click '''Save'''.
  
* <u>Action to be performed on order placement</u>: The mode in which you wish payment transactions to be performed via PayPal on order placement (Auth only or Auth and Capture).
+
For instructions on how to customize page styles and create Page Style Names, see the [https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_MerchantSetupAdministrationGuide.pdf Merchant Setup and Administration Guide].
 +
<br /><br />
 +
== Express Checkout configuration settings==
  
* <u>Test/Live mode</u>: PayPal operating mode ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:Testing_PayPal_Integration | Testing X-Cart's PayPal Integration]]').
+
The page where you adjust the configuration settings for <u>PayPal Express Checkout</u> is as follows:
 +
:[[File:Pp_express_checkout.png|border]]
 +
Start by choosing the type of credentials you will use for Express Checkout:
 +
:* '''E-Mail address to accept PayPal payments''': This option allows you to start accepting Express Checkout payments immediately by simply plugging in the email address where you would like to receive payments. With this option enabled only basic Express Checkout functionality will be available (no support for Auth initial transactions with subsequent Capture/Refund). This option is a good choice for beginner merchants: you will be able to create a PayPal account later after you have received a real transaction from your customers.
 +
:* '''API credentials for payments and post-checkout operations''': This option should be selected if you are going to use "post-checkout operations" in your store (Auth initial transactions with subsequent Capture/Refund).
 +
If you have selected the '''API credentials for payments and post-checkout operations''' option, specify your API credentials:
 +
:: {{Note1|'''Note:''' Help on retrieving your API access credentials is available here: [http://qwyx.co/apihowto http://qwyx.co/apihowto].}}
 +
:* '''API access username''': Your API access username as provided in your PayPal account profile.
 +
:* '''API access password''': Your API access password as provided in your PayPal account profile.
 +
:* '''Use PayPal authentication method''': The type of authentication method that you wish to use (''API signature'' or ''API certificate'').<br />The simplest authentication method is using an API Signature, an encrypted string value that you include with your API calls to identify yourself. Use this method if you want the fastest and easiest way to use the PayPal API.<br />An API Certificate is a file that you download from PayPal that contains a private key and public certificate which identify you to PayPal. Use this method if you have full control of your web server and are familiar with SSL encryption.<br />If you choose to use an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <u><xcart_dir>/payment/certs/</u>, where <u><xcart_dir></u> is the name of the directory in which X-Cart is installed.
 +
:* '''API certificate filename''': If you have chosen ''API certificate'' as your PayPal authentication method, specify the filename of your API certificate.
 +
:* '''API signature''': If you have chosen ''API signature'' as your PayPal authentication method, copy and paste your API signature into this field.
 +
After providing your credentials, adjust the rest of the fields:
 +
:* '''Action to be performed on order placement''': (This setting is available only to users of the API access username - API access password - API signature/certificate type of credentials) Choose ''Auth only'' or ''Auth and Capture''.
 +
:* '''Test/Live mode''': PayPal operating mode ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:Testing_PayPal_Integration | Testing X-Cart's PayPal Integration]]').
 +
:* '''Currency''': The currency that should be used for payments via this method.
 +
:* '''Order prefix''': Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.<br />{{Note1 | '''Note:''' The "Order prefix" field is required when using the same PayPal account for several online stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
 +
The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:
 +
:* '''Gradient color:''' Gradient fill color of the border around the cart review area.
 +
:* '''Header Image URL:''' Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.<br />We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.<br /><br />
 +
'''Important:'''
 +
:* If you intend to use Express Checkout, you must make the ''Title'' field not required on the User Profile page in X-Cart Admin area. Express Checkout does not return this value when checkout is completed on the PayPal side, so if this field is required, X-Cart will not be able to complete checkout without it.
 +
:* If you want PayPal Express Checkout to be available to your customers in the US and Canada, make sure the ''State'' field is available to them during profile creation. If this field is not specified in the customer profile, PayPal Express Checkout will not function correctly.
 +
<br /><br />
  
3. Click the '''Update''' button to save the changes.
+
== PayPal Payments Advanced configuration settings ==
 +
The page where you adjust the configuration settings for <u>PayPal Payments Advanced</u> is as follows:
 +
:[[File:Pp_payments_advanced.png|border]]
 +
You need to adjust the following fields:
 +
:* '''Partner''': Partner ID of the partner that signed you up for the account. If you signed up directly through PayPal, this will be "PayPal".
 +
:* '''Merchant login''': The merchant login name that you chose when you signed up for the service.
 +
:* '''User''': The username that you have set up for running transactions. If you have not specifically set up a username to run transactions, then this will be the same as the "Merchant login".
 +
:* '''Password''': The password for the user account denoted in the "User" field.<br />{{Note1|'''Note:''' The values for the fields ''Partner name'', ''Merchant login'', ''User'' and ''Password'' are your Payflow API credentials that were set up when you created your PayPal Manager (Payflow) account. They are the same as your PayPal Manager login at https://paypal.manager.com.}}
 +
:* '''Currency''': The currency that should be used for payments via this method.
 +
:* '''Test/Live mode''': PayPal operating mode. ('Live' should be selected for live stores, 'Test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:Testing_PayPal_Integration | Testing X-Cart's PayPal Integration]]').
 +
:* '''Action to be performed on order placement''': Choose ''Auth'' or ''Auth and capture''.
 +
:* '''Order prefix''': Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.<br />{{Note1 | '''Note:''' The "Order prefix" field is required when using the same PayPal account for several online stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
 +
The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance of PayPal Express Checkout pages and the design of PayPal Payments Advanced embedded template so they look like your own pages, giving the customer a consistent visual presentation:
 +
:* '''Gradient color''': Gradient fill color of the border around the cart review area.
 +
:* '''Header Image URL''': Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.<br />We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.
 +
:* '''Section border color''': The color of the border around the embedded template.
 +
:* '''Section header text color''': The color of text in the embedded template header.
 +
:* '''Payment button background color''': The color of the '''Pay Now'''/'''Submit''' button.
 +
:* '''Payment button text color''': The color of the text on the '''Pay Now'''/'''Submit''' button.
 +
:* '''Express Checkout specific: Page Style''': Name of the page style that you created in your PayPal profile. If you haven't created one, leave this blank.
  
== Adjusting the settings for Website Payments Pro and Website Payments Pro Payflow Edition ==
+
To create your custom PayPal payment page, follow these steps:
 +
:# Log in to your PayPal account at https://www.paypal.com.
 +
:# Find '''Custom payment pages''' and click the <u>Update</u> link to the right of it.
 +
:# Click '''Add'''.
 +
:# In the '''Page Style Name''' box, enter a name for the page style. (You can use any name you want, as long as it's not "PayPal".)
 +
:# Enter your other design parameters in the spaces provided.
 +
:# When finished, click '''Save'''.
  
For PayPal Pro, X-Cart provides two options: '<u>Website Payments Pro</u>' and '<u>Website Payments Pro Payflow Edition</u>'.
+
For instructions on how to customize page styles and create Page Style Names, see the [https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_MerchantSetupAdministrationGuide.pdf Merchant Setup and Administration Guide].
 +
<br /><br />
 +
'''Important''':
 +
:* To enhance the security of your PayPal Payments Advanced/Payflow Link account, PayPal recommends that you enable the '''Secure Token''' setting in your PayPal Manager account. To enable this setting, log in to PayPal Manager, then go to '''Service Settings''' > '''Hosted Checkout Pages''' > '''Set Up''', and set '''Enable Secure Token''' to ''Yes''. When you are done, click '''Save Changes'''.
 +
<br /><br />
  
'''To adjust settings for Website Payments Pro:'''
+
== Payflow Link configuration settings ==
 
+
The page where you adjust the configuration settings for <u>Payflow Link</u> is as follows:
1. In the '<u>Settings</u>' dialog box, select the option '<u>Website Payments Pro</u>':
+
:[[File:Pp_payflow_link.png|border]]
 
+
The configuration settings for <u>Payflow Link</u> should be adjusted the same way as for [[#PayPal Payments Advanced configuration settings | PayPal Payments Advanced]].<br /><br />
 
+
'''Important''':
[[Image:pp_pro.gif|center|535px]]
+
:* To enhance the security of your PayPal Payments Advanced/Payflow Link account, PayPal recommends that you enable the '''Secure Token''' setting in your PayPal Manager account. To enable this setting, log in to PayPal Manager, then go to '''Service Settings''' > '''Hosted Checkout Pages''' > '''Set Up''', and set '''Enable Secure Token''' to ''Yes''. When you are done, click '''Save Changes'''.
 
 
 
 
2. Adjust the fields in the lower part of the dialog box as follows:
 
 
 
* <u>API Access username</u> and <u>API Access password</u>: Your API Username and API Password as provided by your PayPal account.
 
* <u>Use PayPal authentication method</u>: The authentication method that you would like to use (API Signature or API Certificate).
 
* <u>API certificate filename</u>: The location of your API certificate file (Only needs to be completed if you selected API Certificate as your PayPal authentication method).
 
* <u>API signature</u>: Your API Signature (Only needs to be completed if you selected API Signature as your PayPal authentication method).
 
* <u>Currency</u>: The currency to be used for PayPal payment transactions.
 
* <u>Test/Live mode</u>: PayPal operating mode. ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:Testing_PayPal_Integration | Testing X-Cart's PayPal Integration]]').
 
* <u>Action to be performed on order placement</u>: The mode in which you wish payment transactions to be performed via PayPal on order placement (Auth only or Auth and Capture).
 
* <u>Order prefix</u>: The prefix that will help you identify a payment transaction as originating from this store.
 
 
 
{{Note1 | '''Note:''': The "Order prefix" field is required when using the same PayPal account for several on-line stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
 
 
 
3. Click the '''Update''' button to save the changes.
 
 
 
'''To adjust settings for Website Payments Pro Payflow Edition:'''
 
 
 
1. In the '<u>Settings</u>' dialog box, select the option '<u>Website Payments Pro Payflow Edition</u>':
 
 
 
 
 
[[Image:pp_payflow.gif|center|533px]]
 
 
 
 
 
2. Adjust the fields in the lower part of the dialog box as follows:
 
 
 
* <u>Vendor</u>: The vendor name (login ID).
 
* <u>Partner</u>: The partner name.
 
* <u>User</u>: Your user name, if used.
 
* <u>Password</u>: Your password.
 
 
 
{{Note1 | '''Note:''': The values for the fields 'Vendor', 'Partner', 'User' and 'Password' are supplied to you by PayPal after you sign up for Website Payments Pro Payflow Edition.}}
 
 
 
* <u>Currency</u>: The currency to be used for PayPal payment transactions.
 
* <u>Test/Live mode</u>: PayPal operating mode. ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section '[[X-Cart:Testing_PayPal_Integration | Testing X-Cart's PayPal Integration]]').
 
* <u>Action to be performed on order placement</u>: The mode in which you wish payment transactions to be performed via PayPal on order placement (Auth only or Auth and Capture).
 
* <u>Order prefix</u>:  The prefix that will help you identify a payment transaction as originating from this store.
 
 
 
{{Note1 | '''Note:''': The "Order prefix" field is required when using the same PayPal account for several on-line stores (refer to [[X-Cart:PayPal#This_invoice_has_already_been_paid._For_more_information.2C_please_contact_the_merchant | this article]] for more details).}}
 
 
 
3. Click the '''Update''' button to save the changes.
 
 
 
No matter whether you configure Website Payments Pro or Website Payments Pro Payflow Edition, you will end up with two 'PayPal' entries under '<u>Payment Methods</u>': one for Direct Payment and one for Express Checkout:
 
 
 
 
 
[[Image:paypal_method2.gif|center|618px]]
 
 
 
 
 
The names of PayPal methods suggested by X-Cart ('PayPal Pro: DirectPayment' and 'PayPal Pro: ExpressCheckout'), although quite informative for the store administrator, may not be informative enough for your customers. You by no means have to use the suggested names 'as is'. If you wish to change the names of your PayPal payment options, simply edit the corresponding names in the METHODS column and click the '''Update''' button.
 
 
 
== Adjusting Express Checkout settings ==
 
 
 
To adjust settings for Express Checkout as an additional payment option:
 
 
 
1. In the '<u>Settings</u>' dialog box, select the '<u>Express Checkout</u>' option:
 
 
 
 
 
[[Image:pp_exp_ch.gif|center|535px]]
 
 
 
 
 
2. Adjust the fields in the lower part of the dialog box the same way as for Website Payments Pro.
 
 
 
{{Note1 | '''Notes:'''<br/>
 
*To use Express Checkout you must make the "Title" field not required on the User Profile page in the X-Cart Admin area. Express Checkout does not return the value of this field when the checkout is completed on the PayPal side, so if this field is required, X-Cart will not be able to complete checkout without it.<br/>
 
 
 
*If you want PayPal Express Checkout to be available for customers from the US and Canada, make sure that the 'State' field is available to them during profile creation. If the 'State' field is not specified in the customer profile, PayPal Express Checkout will not function correctly.}}
 
 
 
[[Category:X-Cart user manual]]
 
  
 
[[Category:X-Cart user manual]]
 
[[Category:X-Cart user manual]]

Latest revision as of 11:39, 12 December 2013

After you choose the PayPal payment method you would like to use at your store, you must adjust its configuration settings. The configuration settings for the chosen PayPal payment method are displayed in the lower part of the PayPal configuration page.

This article provides notes on adjusting the configuration settings for specific PayPal payment methods.


PayPal Payments Standard configuration settings

The page where you adjust the configuration settings for PayPal Payments Standard is as follows:

Pp payments standard.png

You need to adjust the following fields:

  • Account: The email address you use to access your PayPal Business account.
  • Description of the purchase that will be displayed on PayPal payment page: A generic description of the purchase that should be displayed to the customer (i.e. books. music, etc). This field is optional.
  • Currency: The currency that should be used for payments via this method.
  • Order prefix: Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.
    Note: The "Order prefix" field is required when using the same PayPal account for several online stores (refer to this article for more details).
  • Test/Live mode: PayPal operating mode ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section ' Testing your PayPal payment methods').
  • Action to be performed on order placement: Choose Auth only or Auth and Capture.
  • Address override: When this option is enabled, the address specified by the customer during checkout in X-Cart and passed from X-Cart to PayPal overrides the PayPal member's stored address. The customer is shown the passed-in address but cannot edit it. When this option is disabled, the customer can edit the passed-in address or select another address that he/she has stored with PayPal.
    Note: Disabling this option may lead to a situation when the address specified by the customer during checkout in X-Cart and saved in the X-Cart order details differs from the address in the relevant PayPal transaction details. This can cause confusion as to which address the order should be shipped to.

If you have opted in for the Auth only action to be performed on order placement or if you are going to process refunds via X-Cart back-office, you must also provide your API access credentials. API access will be used to establish connection between X-Cart and PayPal API to perform Capture/Void/Refund transactions.

Note: Help on retrieving your API access credentials is available here: http://qwyx.co/apihowto.

Adjust the following fields:

  • API access username: Your API access username as provided in your PayPal account profile.
  • API access password: Your API access password as provided in your PayPal account profile.
  • Use PayPal authentication method: The type of authentication method that you wish to use (API signature or API certificate).
    The simplest authentication method is using an API Signature, an encrypted string value that you include with your API calls to identify yourself. Use this method if you want the fastest and easiest way to use the PayPal API.
    An API Certificate is a file that you download from PayPal that contains a private key and public certificate which identify you to PayPal. Use this method if you have full control of your web server and are familiar with SSL encryption.
    If you choose to use an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <xcart_dir>/payment/certs/, where <xcart_dir> is the name of the directory in which X-Cart is installed.
  • API certificate filename: If you have chosen API certificate as your PayPal authentication method, specify the filename of your API certificate.
  • API signature: If you have chosen API signature as your PayPal authentication method, copy and paste your API signature into this field.



Website Payments Pro Hosted configuration settings

The page where you adjust the configuration settings for Website Payments Pro Hosted is as follows:

Pp hosted.png

You need to adjust the following fields:

  • API Access username and API Access password: Your API username and API password as provided by your PayPal account.
    Note: Help on retrieving your API username and API password, as well as your API signature/certificate, is available here: http://qwyx.co/apihowto
  • Use PayPal authentication method: The type of authentication method that you are going to use (Signature or Certificate).
    The simplest authentication method is using an API Signature, an encrypted string value that you include with your API calls to identify yourself. Use this method if you want the fastest and easiest way to use the PayPal API.
    An API Certificate is a file that you download from PayPal that contains a private key and public certificate which identify you to PayPal. Use this method if you have full control of your web server and are familiar with SSL encryption.
    If you have chosen an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <xcart_dir>/payment/certs/, where <xcart_dir> is the name of the directory in which X-Cart is installed.
  • API certificate filename: If you have chosen API certificate as your PayPal authentication method, specify the filename of your API certificate.
  • API signature: If you have chosen API signature as your PayPal authentication method, copy and paste your API signature into this field.
  • Currency: The currency that should be used for payments via this method.
  • Test/Live mode: PayPal operating mode ('Live' should be selected for live stores, 'Test' - for testing. Information on using PayPal in test mode is provided in the section ' Testing your PayPal payment methods').
  • Action to be performed on order placement: Auth only or Auth and Capture.
  • Order prefix: Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.
    Note: The "Order prefix" field is required when using the same PayPal account for several online stores (refer to this article for more details).
  • Payflow vendor: The Login ID or merchant login you created when you signed up for PayPal Merchant Services. The user is also the vendor, unless you have created additional accounts (users) within PayPal Manager.
  • Payflow partner: The PayPal partner/reseller through which you registered for your Payflow account.

The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:

  • Express Checkout specific: Gradient color: Gradient fill color of the border around the cart review area.
  • Express Checkout specific: Header Image URL: Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.
    We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.



PayPal Payments Pro configuration settings

The following notes refer only to PayPal Payments Pro payment method using PayPal API. For notes on the configuration settings for Website Payments Pro Payflow Edition (the PayPal Payments Pro method using Payflow API), see the Website Payments Pro Payflow Edition configuration settings section.

The page where you adjust the configuration settings for PayPal Payments Pro is as follows:

Pp payments pro.png

To ensure that PayPal integration will work correctly for your store, you must configure PayPal Payments Pro in X-Cart in exactly the same way as you have configured PayPal Payments Pro (PayPal API) in X-Payments:

  • Select payment method configured on X-Payments side: Select the name of the payment configuration you will use.
  • API Access username Same as contents of the "API Access Username" field for the selected payment configuration in X-Payments.
  • API Access password: Same as contents of the "API Access Password" field for the selected payment configuration in X-Payments.
  • Use PayPal authentication method: The type of authentication method specified in the "API method" field for the selected payment configuration in X-Payments. If you have chosen an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <xcart_dir>/payment/certs/, where <xcart_dir> is the name of the directory in which X-Cart is installed.
  • API certificate filename: If you have chosen API certificate as your PayPal authentication method, specify the filename of your API certificate.
  • API signature: If you have chosen API signature as your PayPal authentication method, copy and paste your API signature into this field.
  • Currency: The currency specified in the "Currency" field for the selected payment configuration in X-Payments.
  • Test/Live mode: The PayPal operating mode specified in the "Test/Live mode" field for the selected payment configuration in X-Payments.
  • Action to be performed on order placement: The action specified in the "Initial transaction" field for the selected payment configuration in X-Payments.
  • Order prefix: The order prefix specified in the "Order prefix" field for the selected payment configuration in X-Payments.

The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:

  • Express Checkout specific: Gradient color: Gradient fill color of the border around the cart review area.
  • Express Checkout specific: Header Image URL: Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.
    We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.



Website Payments Pro Payflow Edition configuration settings

The page where you adjust the configuration settings for Website Payments Pro Payflow Edition is as follows:

Pp pro payflow edition.png

To ensure that PayPal integration will work correctly for your store, you must configure Website Payments Pro Payflow Edition in exactly the same way as you have configured PayPal Payments Pro (Payflow API) in X-Payments:

  • Select payment method configured on X-Payments side: Select the name of the payment configuration you will use.
  • Partner: Same as contents of the "Partner name" field for the selected payment configuration in X-Payments.
  • Merchant login: Same as contents of the "Merchant login" field for the selected payment configuration in X-Payments.
  • User: Same as contents of the "User" field for the selected payment configuration in X-Payments.
  • Password: Same as contents of the "Password" field for the selected payment configuration in X-Payments.
  • Currency: The currency specified in the "Currency" field for the selected payment configuration in X-Payments.
  • Test/Live mode: The PayPal operating mode specified in the "Test/Live mode" field for the selected payment configuration in X-Payments.
  • Action to be performed on order placement: The action specified in the "Initial transaction" field for the selected payment configuration in X-Payments.
  • Order prefix: The order prefix specified in the "Order prefix" field for the selected payment configuration in X-Payments.

The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:

  • Express Checkout specific: Gradient color: Gradient fill color of the border around the cart review area.
  • Express Checkout specific: Header Image URL: Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.
    We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.
  • Express Checkout specific: Page Style: Name of the page style that you created in your PayPal profile. If you haven't created one, leave this blank.

To create your custom PayPal payment page, follow these steps:

  1. Log in to your PayPal account at https://www.paypal.com.
  2. Find Custom payment pages and click the Update link to the right of it.
  3. Click Add.
  4. In the Page Style Name box, enter a name for the page style. (You can use any name you want, as long as it's not "PayPal".)
  5. Enter your other design parameters in the spaces provided.
  6. When finished, click Save.

For instructions on how to customize page styles and create Page Style Names, see the Merchant Setup and Administration Guide.

Express Checkout configuration settings

The page where you adjust the configuration settings for PayPal Express Checkout is as follows:

Pp express checkout.png

Start by choosing the type of credentials you will use for Express Checkout:

  • E-Mail address to accept PayPal payments: This option allows you to start accepting Express Checkout payments immediately by simply plugging in the email address where you would like to receive payments. With this option enabled only basic Express Checkout functionality will be available (no support for Auth initial transactions with subsequent Capture/Refund). This option is a good choice for beginner merchants: you will be able to create a PayPal account later after you have received a real transaction from your customers.
  • API credentials for payments and post-checkout operations: This option should be selected if you are going to use "post-checkout operations" in your store (Auth initial transactions with subsequent Capture/Refund).

If you have selected the API credentials for payments and post-checkout operations option, specify your API credentials:

Note: Help on retrieving your API access credentials is available here: http://qwyx.co/apihowto.
  • API access username: Your API access username as provided in your PayPal account profile.
  • API access password: Your API access password as provided in your PayPal account profile.
  • Use PayPal authentication method: The type of authentication method that you wish to use (API signature or API certificate).
    The simplest authentication method is using an API Signature, an encrypted string value that you include with your API calls to identify yourself. Use this method if you want the fastest and easiest way to use the PayPal API.
    An API Certificate is a file that you download from PayPal that contains a private key and public certificate which identify you to PayPal. Use this method if you have full control of your web server and are familiar with SSL encryption.
    If you choose to use an API SSL client-side certificate as your credential, install the certificate on the web server in the directory <xcart_dir>/payment/certs/, where <xcart_dir> is the name of the directory in which X-Cart is installed.
  • API certificate filename: If you have chosen API certificate as your PayPal authentication method, specify the filename of your API certificate.
  • API signature: If you have chosen API signature as your PayPal authentication method, copy and paste your API signature into this field.

After providing your credentials, adjust the rest of the fields:

  • Action to be performed on order placement: (This setting is available only to users of the API access username - API access password - API signature/certificate type of credentials) Choose Auth only or Auth and Capture.
  • Test/Live mode: PayPal operating mode ('live' should be selected for live stores, 'test' - for testing. Information on using PayPal in test mode is provided in the section ' Testing X-Cart's PayPal Integration').
  • Currency: The currency that should be used for payments via this method.
  • Order prefix: Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.
    Note: The "Order prefix" field is required when using the same PayPal account for several online stores (refer to this article for more details).

The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance PayPal Express Checkout pages so they look like your own pages, giving the customer a consistent visual presentation:

  • Gradient color: Gradient fill color of the border around the cart review area.
  • Header Image URL: Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.
    We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.

Important:

  • If you intend to use Express Checkout, you must make the Title field not required on the User Profile page in X-Cart Admin area. Express Checkout does not return this value when checkout is completed on the PayPal side, so if this field is required, X-Cart will not be able to complete checkout without it.
  • If you want PayPal Express Checkout to be available to your customers in the US and Canada, make sure the State field is available to them during profile creation. If this field is not specified in the customer profile, PayPal Express Checkout will not function correctly.



PayPal Payments Advanced configuration settings

The page where you adjust the configuration settings for PayPal Payments Advanced is as follows:

Pp payments advanced.png

You need to adjust the following fields:

  • Partner: Partner ID of the partner that signed you up for the account. If you signed up directly through PayPal, this will be "PayPal".
  • Merchant login: The merchant login name that you chose when you signed up for the service.
  • User: The username that you have set up for running transactions. If you have not specifically set up a username to run transactions, then this will be the same as the "Merchant login".
  • Password: The password for the user account denoted in the "User" field.
    Note: The values for the fields Partner name, Merchant login, User and Password are your Payflow API credentials that were set up when you created your PayPal Manager (Payflow) account. They are the same as your PayPal Manager login at https://paypal.manager.com.
  • Currency: The currency that should be used for payments via this method.
  • Test/Live mode: PayPal operating mode. ('Live' should be selected for live stores, 'Test' - for testing. Information on using PayPal in test mode is provided in the section ' Testing X-Cart's PayPal Integration').
  • Action to be performed on order placement: Choose Auth or Auth and capture.
  • Order prefix: Your trading name or any other prefix that will help you to identify a payment transaction as originating from this store.
    Note: The "Order prefix" field is required when using the same PayPal account for several online stores (refer to this article for more details).

The page also inludes options for presenting the checkout pages that appear when the buyer logs into PayPal during checkout. You can use them to customize the appearance of PayPal Express Checkout pages and the design of PayPal Payments Advanced embedded template so they look like your own pages, giving the customer a consistent visual presentation:

  • Gradient color: Gradient fill color of the border around the cart review area.
  • Header Image URL: Logo to be displayed on the header of the PayPal payment pages. Enter the URL for an image that is a maximum size of 750 pixels wide by 90 pixels high; larger images will be cut to this size. The image must be in a valid graphics format such as .gif, .jpg or .png. The image will appear at the top left of the payment page.
    We recommend that you enter an image URL only if the image is stored on a secure (https) server. Otherwise, your customer's web browser will display a message that the payment page contains nonsecure items.
  • Section border color: The color of the border around the embedded template.
  • Section header text color: The color of text in the embedded template header.
  • Payment button background color: The color of the Pay Now/Submit button.
  • Payment button text color: The color of the text on the Pay Now/Submit button.
  • Express Checkout specific: Page Style: Name of the page style that you created in your PayPal profile. If you haven't created one, leave this blank.

To create your custom PayPal payment page, follow these steps:

  1. Log in to your PayPal account at https://www.paypal.com.
  2. Find Custom payment pages and click the Update link to the right of it.
  3. Click Add.
  4. In the Page Style Name box, enter a name for the page style. (You can use any name you want, as long as it's not "PayPal".)
  5. Enter your other design parameters in the spaces provided.
  6. When finished, click Save.

For instructions on how to customize page styles and create Page Style Names, see the Merchant Setup and Administration Guide.

Important:

  • To enhance the security of your PayPal Payments Advanced/Payflow Link account, PayPal recommends that you enable the Secure Token setting in your PayPal Manager account. To enable this setting, log in to PayPal Manager, then go to Service Settings > Hosted Checkout Pages > Set Up, and set Enable Secure Token to Yes. When you are done, click Save Changes.



Payflow Link configuration settings

The page where you adjust the configuration settings for Payflow Link is as follows:

Pp payflow link.png

The configuration settings for Payflow Link should be adjusted the same way as for PayPal Payments Advanced.

Important:

  • To enhance the security of your PayPal Payments Advanced/Payflow Link account, PayPal recommends that you enable the Secure Token setting in your PayPal Manager account. To enable this setting, log in to PayPal Manager, then go to Service Settings > Hosted Checkout Pages > Set Up, and set Enable Secure Token to Yes. When you are done, click Save Changes.