X-Cart:PayPal

About PayPal

PayPal is one of the most popular online payment options worldwide, and it is also the most popular payment method among X-Cart's customers.

X-Cart software is pre-integrated with PayPal, so any X-Cart store can be easily set up to accept payments through PayPal. X-Cart supports both Standard and Pro PayPal solutions. More information on the PayPal solutions supported by X-Cart is available in the section PayPal Integration Overview.

Instructions on how to begin using PayPal as a payment method in an X-Cart store are available in the section Putting PayPal to Work with X-Cart.

The basics of PayPal integration testing are provided in the section Testing PayPal Integration.

Information about using the Order details page of orders paid through PayPal is available in the section Working with Orders Paid through PayPal.

PayPal Integration Overview

X-Cart supports the following PayPal solutions:

Website Payments Standard

Website Payments Standard is a simple PayPal solution available to merchants worldwide. It provides a payment method that allows your customers to shop on your website and to checkout on PayPal. In a store using Website Payments Standard, customers going to checkout see PayPal as one of the payment methods available for the order. A customer who submits an order selecting PayPal as a payment method is redirected to PayPal website. There he or she can log in to an existing PayPal account and pay using that account, or choose to pay without logging in - simply by providing the details of a credit card or a bank account. Returning to your store website from PayPal, the customer sees a confirmation page. The process of checking out through Website Payments Standard is presented in the scheme below:

Website Payments Pro

Website Payments Pro is an advanced solution composed of two payment capabilities: credit card processing with Direct Payment and PayPal payment processing with Express Checkout.

Direct Payment is a method that allows your customers to pay you with a credit card without leaving your store website. A customer enters his or her credit card information on your site, and the payment is processed in the background with PayPal's Direct Payment API. Data exchange between X-Cart and PayPal server happens transparently to the user. The customer stays on your website throughout the entire process of checkout.

Express Checkout is a fast and convenient method offering a "wallet" capability: your customer uses the billing information stored in his or her PayPal account and does not have to enter payment details or shipping information on your site. Because all the information required for order placement is taken from the customer's PayPal account, the customer may freely skip the step of logging in/getting registered at the store and complete the checkout process anonymously. When using Express Checkout, the customer is redirected to PayPal website. There, the customer logs in or signs up for a new account, selects a funding source and confirms contact and shipping information. Customer information is then passed from the customer's PayPal account to the store and is used to complete the checkout process.

The scheme below demonstrates how checkout happens with Direct Payment and Express Checkout methods:

In an X-Cart store using Website Payments Pro solution, Direct Payment and Express Checkout are provided to customers as two alternative PayPal payment options. The customers themselves choose, which of the two options they wish to use.

X-Cart's implementation of Website Payments Pro is officially PayPal Certified since X-Cart version 4.1.7.

Express Checkout

Merchants who do not wish to process credit cards through PayPal, but would still like to make PayPal available to their customers as a payment option, have the ability to use Express Checkout separately (without Direct Payment). We refer to this option as 'Express Checkout as an additional payment option', or, simply, 'Express Checkout standalone'. To be able to use Express Checkout as an additional payment option, you should sign up for PayPal's Website Payments Pro solution without submitting the Website Payments Pro application; in X-Cart, you should select the option ' Express Checkout' on the PayPal configuration page.

Unlike Website Payments Pro, Express Checkout standalone is not limited to the US and Canada.

Website Payments Pro Payflow Edition

In addition to Website Payments Pro, X-Cart provides support for another PayPal's solution - Website Payments Pro Payflow Edition. If you are from the US or UK and are interested in using this solution, you should discuss the possibility with a US or UK sales representative or account manager from PayPal.

Putting PayPal to Work with X-Cart

If you wish to use PayPal payment method at your X-Cart store, you need to follow these steps:

1. If you haven't yet done so, obtain a verified PayPal business account.

See ' Obtaining a Verified PayPal Business Account'.

2. Apply and get approved for Website Payments Pro.

(This step is required only for Website Payments Pro. Should not be performed for Website Payments Standard or Express Checkout used as an additional payment option):

See ' Applying for Website Payments Pro'.

3. Set up your API access.

(This step is required for Website Payments Pro and for Express Checkout used as an additional payment option):

See ' Setting up Your API Access'.

4. Add PayPal to the list of your store's active payment methods.

See ' Adding PayPal to the List of Your Store's Active Payment Methods'.

5. Adjust PayPal configuration settings on the PayPal configuration page in X-Cart.

See ' Adjusting PayPal Configuration Settings in X-Cart'.

If, after trying one PayPal solution, you decide to switch to a different one, you can readjust your PayPal configuration.

See ' Switching to a Different PayPal Solution'.

If, after enabling PayPal payment method at your store, you decide not to use it, you can delete it.

See ' Deleting PayPal from the List of Your Store's Payment Methods'.

Testing PayPal Integration

Before you make PayPal publicly available as a payment method on your store website, you may want to run some PayPal transactions in test mode to familiarize yourself with PayPal and to ensure that everything works correctly.

Follow these steps:

1. Obtain a verified PayPal business account.
2. Set your store's PayPal integration to work in test mode.
3. Conduct test PayPal transactions.

Obtaining account for testing

Testing of PayPal's Website Payments Standard, Website Payments Pro and Express Checkout solutions is performed using the PayPal Sandbox - a self-contained testing environment for PayPal applications. The Sandbox is a mirror of the real PayPal site except that real financial transactions are not made. To be able to access the PayPal Sandbox, you need to have an account at Developer Central. You do not need an existing live PayPal account in order to sign up for Developer Central. After becoming a member of Developer Central, you will be able to access the Sandbox either directly or by launching it after you log in to Developer Central.

To sign up for a Developer Central account:

1. Go to https://developer.paypal.com.
2. Click 'Sign Up Now'.
3. Follow the on-screen instructions.

After you submit the required information to PayPal, PayPal sends login instructions to the email address you used to sign up. Follow the instructions provided to you in the email message to log in to Developer Central. Now you can create the accounts required for testing.

Basically, you need accounts of two types: Business and Personal. A Personal Sandbox account is needed to make test payments via PayPal, a Business Sandbox account - to accept these payments.

Creating a test account in the Sandbox is easy:

1. After logging in to Developer Central, click 'Sandbox'.
2. Click the link 'Create account'.
3. Select the type of account that you wish to create (Business or Personal).
4. Follow the on-screen instructions to create the account.

After creating the necessary Sandbox accounts, you will be able to log in to the Sandbox as a test user of the necessary type.

To log in to the Sandbox using a specific test account:

1. Log in to Developer Central.
2. Click the 'Sandbox' tab.
3. Select the test user that represents the feature you want to test.
4. Click 'Launch Sandbox'.

Please note the following:

• Sandbox accounts are not in any way tied to your PayPal account on www.paypal.com.
• When creating a Sandbox account, your email address attached to that account does not need to be real. It can be any email address, as long as the email address does not already exist on the Sandbox.
• Email from the Sandbox will never be delivered to the email address you enter. All email generated by the Sandbox is captured and displayed by the Developer Central email client.
• After creating a Sandbox account, you may want to confirm the email address for the sandbox user. Check the email client on Developer Central to confirm your email address.
• After creating a Sandbox account, you can also attach a test credit card and bank account for testing.
• More information about the Sandbox is available in the PayPal's Sandbox User Guide (https://developer.paypal.com/en_US/pdf/PP_Sandbox_UserGuide.pdf).

Testing of PayPal's Website Payments Pro Payflow Edition solution is performed using the PayPal Manager - the same administration interface that you should use for live transactions, https://manager.paypal.com. You will be able to access this interface as soon as you set up your production merchant account.

Setting Your Store's PayPal Integration to Work in Test Mode

Your store's PayPal integration can be set to work in test mode as follows:

Website Payments Standard:

1. Go to the PayPal configuration page in your store's Admin area.
2. From the 'Settings' dialog box, select the desired option ('Website Payments Standard').
3. Adjust the configuration fields for the selected option:
   • Specify your Sandbox Business account.
   • Configure the fields 'Payment for', 'Currency', 'Order prefix' as desired.
   • Set PayPal operating mode to 'Test'.
4. Click the Update button to save the changes.

Website Payments Pro and Express Checkout used as an additional payment option:

1. Log in to your Sandbox Business account to obtain API credentials for the test mode (The Sandbox Business account backoffice is organized similarly to the backoffice of your production PayPal Business account, so API credentials for the test mode can be obtained the same way as described in the section ' Setting up Your API Access', with the difference that the Business account in the Sandbox should be used instead of the production account).
2. Go to the PayPal configuration page in your store's Admin area.
3. From the 'Settings' dialog box, select the desired option ('Website Payments Pro' or 'Express Checkout').
4. Adjust the configuration fields for the selected option:
   • Specify the API access credentials as provided by your Sandbox Business account.
   • Configure the fields 'Currency' and 'Order prefix' as desired.
   • Set PayPal operating mode to 'Test'.
5. Click the Update button to save the changes.

Website Payments Pro Payflow Edition:

1. Go to the PayPal configuration page in your store's Admin area.
2. From the 'Settings' dialog box, select the desired option ('Website Payments Pro Payflow Edition').
3. Adjust the configuration fields for the selected option:
   • Configure the fields 'Vendor', 'Partner', 'User' and 'Password'.
   • Configure the fields 'Currency' and 'Order prefix' as desired.
   • Set PayPal operating mode to 'Test'.
4. Click the Update button to save the changes.

When you return to the list of your store's payment methods after setting PayPal to work in test mode as described above, there should be a warning message below the 'PayPal' entry:

This is normal when X-Cart's PayPal integration is in test mode. Now you can perform test PayPal transactions.

Using PayPal in Test Mode

Website Payments Standard, Website Payments Pro and Express Checkout solutions:

The test accounts that you set up in the PayPal Sandbox allow you to explore how PayPal works for merchants and customers. To find out about the merchant's side of the matter, you need to log in to the Sandbox as a user of the 'Business' type. To make test PayPal payments and to learn about the customer's side of the matter, you need to log in to the Sandbox using a 'Personal' account.

Important: In the test mode, to pay for an order using a PayPal payment method, you need to be logged in to Developer Central. Developer Central sessions time out quickly, so it is recommended you log in to Developer Central shortly before going to checkout. The recommended method for logging in to Developer Central is to open a new window in the web browser being used for viewing the store directly before you click the Checkout button on the Shopping cart page and to use that window for logging in to Developer Central. Please note that, if you happen to go to checkout without previously logging in to Developer Central, or if your Developer Central session expires by the time you begin checking out, you will be able to complete checkout, but the process will be a little less streamlined (After selecting PayPal as a payment method and clicking the Submit order button, you will be offered to log in to Developer Central. After logging in, you will be required to click the Back button of your web browser several times to return to the store's 'Place order' page. There you will need to click the Submit order button again to resume the checkout process.)

Website Payments Pro Payflow Edition solution:

The first time you log in to PayPal Manager, you are in Test status (the Home page of PayPal Manager indicates this). This means that you can run mock or test transactions to familiarize yourself with PayPal Manager and make sure your account is set up correctly. These test transactions are not sent to financial institutions for processing, and no money trades hands.

When you are ready to run actual transactions, you will change to Active, or Live status. To change to Active status or see which status you are in, go to the Home page of PayPal Manager and look at the 'Your Account Status' section on the right side. Even after your account is active, you can still perform test transactions if necessary.

At any time, you can activate your account (change to Live status) by clicking the Activate Your Account button on the Home page.

Make sure you have an internet merchant account before you activate your PayPal services account. Otherwise, your live transactions will fail.

Working with Orders Placed through PayPal

Obtaining information about orders placed through PayPal

Orders that your customers place selecting PayPal as a payment method are accumulated in the 'Orders Management' section of your store, along with all other orders.

The current status of an order placed through PayPal appears in the 'STATUS' box pertaining to that order - the same way as for orders paid by other methods.

Detailed information is available on the 'Order details' page. Information about the payment transaction(s) pertaining to the order appears on the 'Order details' page as follows:

• 'Order info' section of the 'Order details' dialog box: Name of the payment method used, order amount.

• 'Order details (not visible to customer and provider)' section of the 'Order details' dialog box: Advanced info about the transaction by which the customer paid for the order (as received from PayPal and interpreted by X-Cart's PayPal payment module).

• 'PayPal transactions' dialog box (not available for orders paid using Website Payments Standard):

'Original transaction' section - Comprehensive information about the transaction by which the customer paid for the order.

'Refund transactions' section - Information about the refund transaction (or a series of partial refund transactions) by which the original payment was refunded. Is displayed only if the original transaction was refunded by the store administrator.

Understanding the statuses of orders placed through PayPal

As orders placed through PayPal are processed, they receive statuses according to the scheme used by X-Cart (see X-Cart:Orders#Order_Statuses article). The statuses that you can see in the 'STATUS' boxes of PayPal orders are Not finished, Queued, Pre-Authorized, Processed and Failed. These statuses are assigned to orders automatically based on the statuses of the respective payment transactions on PayPal:

When a customer places an order using PayPal as a payment method, the order is created with the status Not finished.

Sometimes it happens that a transaction cannot be processed by PayPal immediately; in this case, PayPal temporarily sets the status of the order to 'Pending'. In X-Cart, PayPal's 'Pending' status corresponds to Queued.

If your store is configured to use PayPal in 'Auth and Capture' mode, the status that follows Not finished or Queued is either Processed or Failed. The status Processed corresponds to the state 'The payment has been successfully processed by PayPal; the customer's card has been charged'. The status Failed corresponds to the state 'The transaction has been declined by PayPal'.

If your store is configured to use PayPal in 'Auth only' mode, the status that follows Not finished or Queued is either Pre-Authorized or Failed. The status Pre-Authorized corresponds to the state 'The payment has been successfully authorized'. The status Failed corresponds to the state 'The payment has been declined by PayPal'.

After the order's status is set to Pre-Authorized, you can either capture the authorized amount or void the transaction. If you choose to perform the 'capture' operation, you use the Capture button; after the authorized amount is captured, the status of the order is set to Processed. If you choose to perform the 'void' operation, you use the Decline button; after the authorization is voided, the status of the order changes to Declined.

Assigning any other statuses to PayPal orders has to be done manually by re-adjusting the value of the 'STATUS' box. For example, if an order successfully processed by PayPal and completed by the store needs to be marked as such, you will have to select Complete from the 'STATUS' box of the respective order and update the status.

Updating information about the transaction by which the customer paid for the order

For orders paid through Website Payments Pro, Website Payments Pro Payflow Edition or Express Checkout, detailed information about the transaction by which the customer paid for the order is displayed in the 'Paypal transactions' dialog box in the 'Orders Management' section (See the 'Original transaction' subsection). You can obtain the latest available information about this transaction at any time: simply click the Update button in the 'Original transaction' section. X-Cart will submit your request to PayPal server and the information in the 'Original transaction' section will be updated.

Issuing refunds

X-Cart allows you to issue refunds for orders paid through Website Payments Pro, Website Payments Pro Payflow Edition and Express Checkout.

Orders paid for using Website Payments Pro or Express Checkout can be refunded either at once (by issuing a single refund transaction for the entire sum of the original transaction) or in portions (by issuing several partial refund transactions one after another). If you choose to do a refund as a series of partial refund transactions, you will have to specify the amount for each of the partial refund transactions separately.

Orders paid for using Website Payments Pro Payflow Edition can be refunded only by issuing a refund for the entire sum of the original transaction at once.

To issue a refund:

1. Open the 'Order details' page of the order that needs to be refunded.
2. Scroll down to the 'PayPal transactions' dialog box.
3. Use the 'Issue refund' section of the 'PayPal transactions' dialog box to create a refund:
   • In the 'Amount' field, enter the amount to be refunded (Available only for Website Payments Pro. For Website Payments Pro Payflow Edition, the refund amount is already specified, and it equals the order amount).
   • In the 'Note' field, provide a note stating the reason of the refund.
   • Click the Create button.

As soon as the refund request is successfully received and processed by PayPal, the refund transaction appears in the 'Refund transactions' section of the 'PayPal transactions' dialog box. For each refund transaction, the following information is available:

• TRANSACTION ID - Transaction ID;
• AMOUNT - Refund amount;
• DATE - Date when the transaction was performed;
• NOTE - Note with which the refund was issued.