This asset type has been deprecated as of version 6.6.0. For more information, please view the Matrix 6.6.0 Release Notes.

The PayPal Payment Gateway assets allow you to create a payment gateway using the PayPal online payment system (https://www.paypal.com). Paypal's payment gateway is a secure payment service linking an online store of a web site with a PayPal Merchant Account to process e-commerce transactions.

To create a PayPal payment gateway, several assets must be configured. These assets define the settings of the payment gateway.

• Paypal Configuration: this asset stores the information regarding the security and encryption of the PayPal transactions.
• Paypal Business Account: this asset stores information regarding the Merchant Account that will receive payments from the PayPal transactions. Successful PayPal transactions are stored as Paypal Order assets in this asset.
• Paypal Payment Button: this asset configures a variety of PayPal payment options available through buttons on your e-commerce Site. The button types available are:
  • Buy Now: this button allows users to make single-item purchases on the e-commerce store.
  • Donate: this button allows users to make donations to a specified organisation or service.
  • Add to Cart: this button allows users to add items to a Shopping Cart maintained on the PayPal website. Once an item has been added to their cart, a user can choose to continue shopping on the e-commerce store or proceed to the checkout process, purchasing the item(s) in their cart.
  • View Cart: this button allows users to view the items currently stored in their PayPal Shopping Cart. They can remove items from their cart, update item quantities or proceed to the checkout process.
• Paypal IPN Receiver: this asset receives an Instant Payment Notification (IPN) for each successful payment from the PayPal payment gateway.

Once you have added the PayPal payment gateway, you can configure their settings on their associated asset screens. The majority of these screens are the same or similar to those for a Standard Page and are described in the Asset Screens manual. In this chapter, we will discuss the Details screen, which is different for this assets.

Paypal Configuration Details Screen

The Details screen for the Paypal Configuration asset allows you to set up this asset. For more information about the Status, Future Status, Thumbnail and Details sections, refer to the Details Screen chapter of the Asset Screens manual.

Payment Button Configuration

This section allows you to set the secret string for the PayPal transactions.

• Custom Parameter Secret String: Enter a set of values to use as the secret string for the Custom Variable. This will encrypt the variable, protecting it from malicious activities. By default, a default secret string will be entered into this field. It is recommended you change these values to create a unique secret string.

Paypal Business Account Details Screen

The Details screen for the Paypal Business Account asset allows you to set up the business account. For more information about the Status, Future Status, Thumbnail and Details sections, refer to the Details Screen chapter of the Asset Screens manual.

Payment Business Account Information

This section allows you to configure the details of the Merchant Account to receive payments from the PayPal payment gateway.

• Paypal Account Type: select whether the PayPal account is a Live or Sandbox PayPal account. The PayPal Sandbox site is a functional testing environment that can be used for integration purposes when setting up an e-commerce system. It is recommended that a Sandbox account be used when configuring the PayPal payment gateway before switching to the PayPal Live site.

  Because the settings of the asset are unique to the account type, separate Paypal Business Accounts should be created for both Live and Sandbox accounts. This will allow you to easily switch between the two when modifying the PayPal payment gateway.

• Merchant Account ID: enter the merchant ID or business email address of the Merchant Account. PayPal will provide this information.
• Public Certificate Path: enter the path to the Public Certificate file. This certificate must be generated using OpenSSL. The public certificate must be installed on the system and selected in this field to establish the Merchant Account setup. If an invalid path or file is selected, the message The path to Public Certificate Path is not valid.
• Public Certificate ID: enter the certificate ID, supplied by PayPal, which corresponds to the certificate selected in the Public Certificate Path field. This ID must be entered to establish the Merchant Account setup.
• Private Key Path:enter the path to the Private Key file. This key must be generated using OpenSSL. The private key must be installed on the system and selected in this field to establish the Merchant Account setup. If an invalid path or file is selected, the message The path to Private Key Path is not valid.
• Paypal Certificate Path: enter the path to the Paypal Certificate file, supplied by PayPal. This file must be installed on the system and selected in this field to establish the Merchant Account setup. If an invalid path or file is selected, the message The path to Paypal Certificate Path is not valid.

The certificates, keys and IDs for the Paypal Business Account are unique to the selected Merchant Account. Because of this, you should be logged in to the selected account on the PayPal site when generating these files. For more information on obtaining the files required for the Paypal Business Account, visit Paypal.

Send Emails On Error

This section allows you to send an email to a specified email address when errors occur on the PayPal payment gateway.

• Email: enter the email address that will receive the error email. If this field is left blank, the system tech email will be used.
• Send emails on error? : select whether or not to send the error emails. If this field is set to Yes, an email will be sent to the email address supplied in the Email field.

Paypal Payment Button Details Screen

The fields available on the Details screen of the Paypal Payment Button will change depending on the Button Type of the Paypal button. When a Paypal Payment Button is first created, it will be configured as a Buy Now button. For more information about the Status, Future Status, Thumbnail and Details sections, refer to the Details Screen chapter of the Asset Screens manual.

Button Details (Buy Now)

This section allows you to configure the Buy Now button for the PayPal payment gateway, selecting the details of the button and its corresponding item.

• Button Type: select the button type of the Paypal button. By default, this field is set to Buy Now.
• Item name: enter a name for the item being sold by the Paypal button.
• Item ID: enter an item ID variable for the item being sold. For example, the asset ID of the item could be used in this field. This field is not mandatory.
• Price: enter the price of the item being sold. Please note that the currency symbol should not be used. For example, 4.50.
• Currency: select the currency of the price of the item being sold. The following currencies are available:
  • Great British Pound (GBP)
  • Australian Dollar (AUD)
  • United States Dollar (USD)
  • Euro (EUR)
  • Japanese Yen (JPY)

  By default, this field is set to GBP.

• Undefined quantity: select whether or not users will be allowed to select the quantity of the item they are purchasing. If this field is set to Yes, users will be able to select the amount of items being purchased, during the payment process. By default, this field is set to Yes.
• Paypal Business Account: select a configured Paypal Business Account asset to use as the account that will accept payments from this button.
• Paypal Configuration: select a configured Paypal Configuration asset to provide encryption of the PayPal button.
• Custom variable: enter a variable that will pass information back to Squiz Matrix after a successful transaction. For example if userid=%globals_user_assetid%,assetid=123 was entered into this field, a successful PayPal transaction will return the user ID of the user who completed the transaction with the value 123, representing the asset ID of the item they purchased. This information can be extracted by an IPN Receiver asset and can be used to generate the PayPal IPN Received trigger event. For more information, refer to the IPN Receiver section of this chapter.
• Notify URL: enter the URL of the IPN Receiver asset that will receive Instant Payment Notifications from a successful transaction. For more information, refer to the IPN Receiver section of this chapter.
• Return URL:enter the URL of the page that the user will be returned to after completing the PayPal payment process.
• Cancel URL: enter the URL of the page that the user will be returned to if the PayPal payment process is cancelled.
• Image URL: enter the URL of the Buy Now button image. By default, this field will have the URL of PayPal's default Buy Now button image for Great Britain.
• Extra variables: enter any additional variables to apply to the PayPal Buy Now button. These variables will respond when a user clicks the Buy Now button, affecting the payment process. For example, entering tax_rate=0.1 into this field, will apply a tax rate of 10% onto the payment amount. For a full list of available variables, visit https://www.paypal.com/developer.

Button Details (Donate)

This section allows you to configure the Donate button for the PayPal payment gateway, selecting the organisation the donation will be made to and the amount of money to donate.

Many of the fields available in this section are the same or similar to those for a Buy Now button. For more information on these fields, refer to the Button Details (Buy Now) section above.

• Organisation name/service: enter the name of the organisation or service that the donations will be made to.
• Donation ID: enter a donation ID variable for the item being sold. For example, the name of your current fund-raising campaign. This field is not mandatory
• Amount: enter the amount of money that users will be able to donate. Please note that the currency symbol should not be used. For example, 10. If this field is left blank, users will be able to enter the amount of money they wish to donate during PayPal's checkout process.

By default, the Image URL field of the Paypal Payment Button will be set to PayPal's default Buy Now button. If you have changed the button type of the PayPal button, you will need to change this field so that the correct button image is displayed on your Site.

Button Details (Add to Cart)

This section allows you to configure the Add to Cart button for the PayPal payment gateway, selecting the details of the button and its corresponding item.

Many of the fields available in this section are the same or similar to those for a Buy Now button. For more information on these fields, refer to the Button Details (Buy Now) section in this chapter.

• Paypal Shopping Cart opens in: select whether this button will open the PayPal Shopping Cart in A new window/tab or The same window/tab. If this field is set to A new window/tab, when the Add to Cart button is selected, the PayPal Shopping Cart will open in a separate browser window to the one currently being viewed. On the other hand, if this field is set to The same window/tab, the PayPal Shopping Cart will open in the same browser window. By default, this field is set to A new window/tab.
• Shopping URL: enter a destination URL for users returning to your e-commerce store after selecting PayPal's Continue Shopping button. For example, you may wish to return users to the home page of your e-commerce store so they can continue shopping for items.

Button Details (View Cart)

This section allows you to configure the View Cart button for the PayPal payment gateway, selecting the details of the button.

The fields available in this section are the same or similar to those for the Buy Now and Add to Cart buttons. For more information on these fields, refer to the Button Details (Buy Now) section in this chapter.

Paypal IPN Receiver Details Screen

The Details screen for the Paypal IPN Receiver allows you to set up this asset. For more information about the Status, Future Status, Thumbnail and Details sections, refer to the Details Screen chapter of the Asset Screens manual.

IPN Receiver Details

This section allows you to configure the assets that will receive the IPN completed events.

• Target asset: select the asset that will receive the IPN completed event when a successful PayPal transaction is made.
• Target asset ID parameter name: select the ID parameter name of the asset ID of the item bought during a successful PayPal purchase. This parameter can be passed to the IPN Receiver using the Custom Variable and Notify URL fields on the PayPal Payment Button Details screen. For example, if the custom variable aid=123 is passed to the IPN Receiver, entering aid into this field will use the value 123 as the asset ID of the target asset. The asset specified in this field will receive the IPN completed event when a successful PayPal transaction is made.

The asset receiving an IPN completed event from the Paypal IPN Receiver can generate a PayPal IPN Received Trigger Event. For more information, refer to the Trigger Events chapter in the Triggers manual.

Paypal Order

E-commerce orders made through the PayPal payment gateway are stored under the Paypal Business Account asset as Paypal Order assets. These orders are stored under the following folders:

• Pending Orders: e-commerce orders processed by the PayPal payment gateway but are not yet completed are stored in this folder. For example, the PayPal may be waiting for confirmation of currency conversion or an eCheque may have not yet been processed.
• Completed Orders: e-commerce orders that are successfully processed by the PayPal payment gateway are stored in this folder.

The Details screen of a Paypal Order provides information on the order including a summary of the order. For more information on the Status, Future Status and Thumbnail sections, refer to the Details Screen chapter in the Asset Screens manual.

Order Details

This section displays the price and status of the order payment.

• Unique Transaction ID: the ID of the PayPal transaction will be displayed in this field.
• Payment Status: the status of the payment will be displayed in this field. For example, Completed or Processing.
• Incomplete Reason: a message explaining the reason the PayPal order is not yet completed will be displayed in this field. For example, if the order is pending payment.
• Total Amount: the total amount paid during the PayPal transaction will be displayed in this field, including the currency.

Summary

This section displays a summary of the order. An example of the Summary section of the Details screen:

In the Order Receipt field, a summary of the e-commerce order will be displayed, including ordered items and total cost.

Custom Information

This section displays system information of the order. An example of the Custom Information section of the Details screen:

In the Custom Information field, the system information of the e-commerce order will be displayed, including custom variables, button and target asset IDs, and IPN event information.