ssossossosso
Documentation Home »User Guide »Payment
current version

Payment

To facilitate global B2B sales, OroCommerce administrator enables valid payment methods for particular locations and integrates local payment providers or the best payment options whenever it is possible.

When submitting an order, the customer may have several payment options to choose from. They depend on the payment address that is collected at the checkout. Once address is provided, OroCommerce evaluates payment methods against the special payment rules and exposes only the options recommended for the particular location and/or based on other order details. After the customer user has selected the payment method, they are prompted to enter payment details and proceed to the checkout.

Depending on the payment method, payment may be processed immediately or may be delayed for the pre-configured period of time, or until a particular event (e.g. until the order is ready for delivery).

After the payment details were provided, the sales person can view the payment history, and capture the delayed payment.

When the payment term is selected, the payment is considered to be captured in full and the payment information is not available.

Payment Providers

For detailed information about payment provider services supported in OroCommerce, please see the following sections.

PayPal Payments Services

PayPal Services Overview

OroCommerce supports integration with PayPal to offer the following payment methods:

  • PayPal Payflow Gateway
  • PayPal Payments Pro
  • PayPal Payflow Gateway Express Checkout
  • PayPal Payments Pro Express Checkout

PayPal Payflow Payment Gateway vs PayPal Payments Pro

PayPal Payflow is a secure payment gateway that receives information about payments via debit and credit cards, authorizations, captures, etc., processes this information and sends payment transactions to the external payment processor that handles the credit card payments.

PayPal Payment Pro uses PayPal Payflow Payment Gateway and PayPal payment processor.

Ordinary vs Express Checkout

For ordinary checkout, a customer user enters the card number, issue date, and, optionally, cvv code. This information is kept in their browser until it is sent directly to the payment gateway server (avoiding the website). Ordinary checkout in OroCommerce enables delayed payment capture. Express checkout helps the customer user complete payment immediately using the credit card payment capture form hosted by PayPal or via their paypal account.

Payment Configuration External Prerequisites

For detailed information about configuration steps that should precede the integration with the payment provider in OroCommerce, please see the following sections:

Prerequisites for PayPal Services Integration

Before adding a PayPal Payflow Gateway as a payment method in OroCommerce, create a PayPal Payflow Gateway Manager Account and create a dedicated API transaction user for every instance of OroCommerce. You might need a separate instance for a sandbox, test, staging/pre-production, and production environment.

Register a Business Account with PayPal

To register business account and enable express checkout for your OroCommerce PayPal integration, follow the next steps:

  1. Open https://developer.paypal.com/ and click Log In.

  2. On the login page that opens, click Sign Up.

  3. On the following page, select Business Account and click Continue.

  4. Select the service plan (Payment Pro, Payments Standard, or Express Checkout).

    The Get Started page opens.

  5. Type in your email.

    The Sign up for a Business account page opens.

  6. Enter the password and password confirmation.

  7. Provide your business contact information.

  8. Read the PayPal User Agreement.

  9. Click Agree and Continue.

    On the following page, select your type of business and provide the requested additional information.

  10. Provide the requested personal information.

  11. Click Submit.

    The PayPal Business Account opens.

  12. In the Account Setup, confirm your email, link your bank account, and configure the credit card statement.

Create a Sandbox Test Account

Test sandbox PayPal account is identical to the regular PayPal account but is hosted in the sandbox environment.

To create a sandbox test account, follow the next steps:

  1. Log on to the https://developer.paypal.com/ with the credentials generated in the previous step.
  2. Navigate to the Dashboard and click Accounts in the Sandbox section.
  3. Click Create Account to create new sandbox account.
  4. Fill in the account details (Account Type, Email Address, Password, PayPal Balance) and click Create Account.

Register a PayPal Payflow Gateway Account

To create a PayPal Payflow Gateway Account:

  1. Open https://registration.paypal.com/ and click Continue.

  2. Select your payment processor from the list.

  3. Fill in the required fields in the Account Information section, confirm you have read the PayPal Gateway Agreement in the Term and Conditions section, and click Continue.

  4. Follow the on-screen guidance to prepare for integration: login to the Payflow Manager and create one or more API Transaction User(s).

  5. To test the Express Checkout and Bill Me Later payment methods, click Set up PayPal Developer Sandbox link and enter PayPal Sandbox Email address.

    Note

    If you do not have a PayPal Sandbox account yet, register at http://developer.paypal.com.

  6. Now you have Payflow Gateway Account and you can use PayPal Payments Pro and Payflow Gateway in your applications.

Configure PayPal Manager Account to Accept Payments

To accept payments in OroCommerce, you need to configure your PayPal Manager Account using the following steps:

  • Enable secure token and silent post
  • Enable reference transactions
  • Disable fraud protection for test environments
  • Enable fraud protection for production environments
Enable Secure Token and Silent Post

OroCommerce requires enabling secure token and silent post features.

To enable these features:

  1. Login to the https://manager.paypal.com/:

    1. Enter the partner name (e.g. PayPal) and PayPal Payflow Gateway account login and password.
    2. Click Log In. For the first log on, PayPal prompts you to type in answers for security question. Remember it for further authentication during the following logins.
  2. Navigate to the Service Settings and click the Set Up link in the Hosted Checkout Pages group.

  3. In the Security Options section, set Enable Secure Token to Yes.

  4. In the Silent Post for Data Transfer section, set Use Silent Post to Yes and enable the Void transaction when my server fails to receive data sent by the silent post.

Enable Reference Transactions

OroCommerce depends on the reference transactions. To ensure they are enabled:

  1. Login to the https://manager.paypal.com/ as described in the previous section.
  2. Navigate to the Account Administration > Manage Security > Transaction Settings in the menu.
  3. Set Allow reference transactions to Yes.
  4. Click Confirm (twice).

Note

There might be a significant delay before this change comes into affect (up to several hours). During this time your reference transactions could be rejected by PayPal.

Disable Fraud Protection for Test Environments

Disable Fraud Protection for the Test Setup to avoid your test transaction being blocked. Test transactions may look suspicions due to unusual behaviour and eventual failures because of the invalid data:

  1. Login to the https://manager.paypal.com/ as described in the Enable Secure Token and Silent Post section.
  2. Navigate to the Service Settings > Fraud Protection > Edit Standard Filters in the menu.
  3. Unselect all the filters and click Deploy.

Note

There might be a significant delay before this change comes into affect (up to several hours). During this time your transactions may be caught by the fraud filter which will lead to the payment failure.

Enable Fraud Protection for Production Environments

Enable Fraud Protection for any customer facing environments where real purchases might happen:

  1. Login to the https://manager.paypal.com/ as described in the Enable Secure Token and Silent Post section.
  2. Navigate to the Service Settings > Fraud Protection > Edit Standard Filters in the menu.
  3. Select all the filters and click Deploy.

Note

There might be a significant delay before this change comes into affect (up to several hours). During this time the fraud filter is disabled and any transactions may impose a security risk due to the reduced protection. Limit access to the Front Store and disable related payment methods until you confirm that the fraud filters are on and catch the suspicious and illegal transactions.

Configure PayPal Manager Account to Work with Express Checkout

Using Express Checkout requires the following configuration in the Manager Account.

  1. Login to the https://manager.paypal.com/ as described in the Enable Secure Token and Silent Post section.

  2. Navigate to the Service Settings > Hosted Checkout Pages > Set Up.

  3. In the PayPal Express Checkout section, set Enable PayPal Express Checkout and Enable PayPal Credit to Yes, enter PayPal email address for production deployments and PayPal sandbox email address for sandbox and test deployments. Use the business account email (as in Register a Business Account with PayPal).

  4. Save changes.

Now you can configure Express Checkout as a payment option in OroCommerce.

Create an API Transaction User

To create an API Transaction User:

  1. Login to the https://manager.paypal.com/ as described in the Enable Secure Token and Silent Post section.
  2. Navigate to the account administration and click on the Add User link.
  1. Enter the administrator password to authorize user creation.
  2. Provide user personal information (contact name, phone, and email).
  3. Enter user login information (user login name and password).
  4. Select the user role.
  5. Set status to Active.
  6. Click Update.

The basic user login information is securely delivered to the provided email.

Payment Configuration in OroCommerce

System Configuration

You can control the following options on the system configuration level. Click on the link to get to the detailed configuration instructions.

Integration with Payment Providers

You may configure integration with third-party payment providers to offer their payment services for the quotes and orders placed using OroCommerce.

Out of the box, you may integrate OroCommerce with the following systems and services:

Generic Payment End-to-End Flow in OroCommerce

Any third party payment system integration involves the following steps to enable it for the OroCommerce Front Store customers:

  1. A B2B seller signs up for payment provider services (e.g. PayPal Business Account).

  2. A B2B seller administrator or integrator obtains integration information using the service information resulting from the first step (e.g. partner ID, partner login credentials, etc.). Integration information may include credentials, security tokens, etc. These details may be generated by the payment provider for a B2B seller, or a B2B seller may generate some of these items using the payment provider services.

  3. Sometimes for secure connection, a B2B seller administrator or integrator supplies the payment provider with identification and authentication artefacts, like secure public key, secure certificate or authentication token. Private tunnel and proxy may be used for advanced security of the payment related traffic.

    Note

    Every sandbox, testing, and production environment should use a unique, dedicated set of integration details. Usually, payment service providers allow test mode access with debug level information. It is crucially important to use the test and debug set of access details only for the test and sandbox environments.

    Warning

    Never use test integration access in production mode or on the production servers as this might expose your customers to the sever security risks.

  4. Once the integration and connection details are available, the B2B seller administrator or integrator may setup an integration of the payment provider services into OroCommerce.

  5. Next, the administrator may limit the availability of the particular payment methods (enabled by the payment provider services integration) using the payment rule configuration.

  6. Once the payment configuration is complete, the payment methods may be used by customer users during the checkout. Payment may be captured immediately or authorized for delayed capture.

  7. A sales person can view payment history and capture the delayed payment (e.g. when the order is complete and is ready for shipping).

These steps are detailed below with the detailed information about every supported payment service configuration and use.

Integration Details

Common for Any Payment Integration

Basic information about the payment is shared among all payment methods and includes:

  • Name – the payment method name that is shown as an option for payment configuration in the OroCommerce Management Console.
  • Label – the payment method name/label that is shown as a payment option for the buyer in the OroCommerce Store Front on the checkout.
  • Short label – the payment method name/label that is shown in the order details in the OroCommerce Management Console and Front Store after the order is submitted.
  • Status – set the status to Active to enable the integration.
Sample
PayPal Payment Actions

Payment action parameters are configured per payment method. Available options are similar for all payment methods and include the following options:

  • Authorize
  • Authorize and Charge

In Payment Action, you select the strategy for the payment processing on the checkout.

Payment Transactions for Authorize

Note

When the Authorize payment action is configured in PayPal integration settings, the buyer is never charged immediately after they submit the order.

After the buyer enters their card details, their payment information is validated.

If Zero Amount Authorization is enabled in the PayPal integration settings, the payment may be initially authorized with zero amount transaction (account verification).

If Zero Amount Authorization is disabled in the PayPal integration settings, the card details are stored locally in the buyer’s browser until they are used in further transactions for this order or until the buyer leaves the checkout pages (navigate from the page, closed it or cancel the checkout).

Note

OroCommerce server never stores buyer’s sensitive payment information (complete card number, expiration date, and cvv code).

Transaction response from the payment gateway also does not contain sensitive information about buyer’s card. It serves as an identifier of the initial authorization that is solely handled by the payment gateway.

After the buyer submits the order on the Order Review step, the total purchase amount may be put on hold (temporarily blocked) on their account to guarantee that they have enough funds to finalize the purchase.

Note

If Zero Amount Authorization is enabled and Authorization for Required Amount is disabled in PayPal integration settings, the total purchase amount will NOT be blocked in the buyer’s account.

Payment Transactions for Authorize and Charge

Note

When the Authorize and Charge payment action is configured in PayPal integration settings, the buyer is charged immediately after they submit the order.

After the buyer enters their card details, their payment information is validated.

If Zero Amount Authorization is enabled in the PayPal integration settings, the payment may be initially authorized with zero amount transaction.

If Zero Amount Authorization is disabled in the PayPal integration settings, the card details are stored locally in the buyer’s browser and are used in further transactions for this order.

Note

OroCommerce server never stores buyer’s payment information (complete card number, expiration date, and cvv code).

Transaction response from the payment gateway does not contain any information about buyer’s card. It serves as an identifier of the initial authorization that is solely handled by the payment gateway.

After the buyer submits the order on the Order Review step, the total purchase amount is captured from their account. This is executed as another transaction.

Custom for PayPal Integration

PayPal integrations include the following additional integration information:

  • Basic Information and Display Options:
    • Common Payment Integration Details (name, label, and short label) for the ordinary PayPal payment.
    • Allowed Credit Card Types – Select one or more items from the list of the credit card types. Supported types are Visa, Mastercard, Discover, American Express. Press and hold Ctrl/Shift and click on the items to select.
  • Integration settings:
  • Advanced Settings:
    • Payment Actions (Authorize or Authorize and Charge) for the ordinary PayPal payment.
    • Debug Mode – when enabled, the PayPal includes more detailed information in the response. This mode may be helpful when troubleshooting payment-related issues.
    • Require CVV Entry – when enabled, the buyer is prompted to enter their credit card CVV. When enabled, the CVV is verified during payment authorization by the payment processor.
    • Zero Amount Authorization – enables Zero Amount authorization request – a transaction that authorizes further payment with the same payment details. When enabled, the buyer can reuse this payment information for the further orders.
    • Authorization for Required Amount – enables blocking the required amount on the buyer’s credit card to ensure that they have sufficient balance to be charged for the order later. This option is valid only when Zero Amount Authorization is enabled and only when Authorize payment action is selected.
  • Connection Options:
    • Use Proxy – when enabled, any request to the PayPal will be routed through the proxy server using Proxy Host and Proxy Port values provided in the following parameters.
    • Proxy Host – the host name or the IP address of the proxy server that routes the requests to and from OroCommerce.
    • Proxy Port – the port that is used by the proxy server that routes the requests to and from OroCommerce.
    • Enable SSL Verification – when enabled, OroCommerce validates the PayPal certificate in the responses from the PayPal API to secure from the man-in-the-middle attack. If the certificate is not valid, the response is ignored and payment processing fails. It is recommended to keep this option enabled for production and most test deployments. You might need to disable the SSL verification for OroCommerce internal tests with no real PayPal integration (e.g. when you are testing checkout workflow customization).
  • Express Checkout:

PayPal Integration Configuration Details. Part 1

PayPal Integration Configuration Details. Part 2

PayPal Integration Configuration Details. Part 3

Check/Money Order

This section describes the steps that are necessary to expose check/money order as a payment method for OroCommerce orders and quotes.

To enable Check/Money Order payment:

  1. Navigate to the Manage Integrations page by clicking System > Integrations > Manage Integrations in the main menu.

  2. Click Create Integration and select Check/Money Order as the integration type:

  3. Type in the Common Integration Details:

    • Name – the payment method name that is shown as an option for payment configuration in the OroCommerce Management Console.
    • Label – the payment method name/label that is shown as a payment option for the buyer in the OroCommerce Store Front on the checkout.
    • Short label – the payment method name/label that is shown in the order details in the OroCommerce Management Console and Front Store after the order is submitted.
    • Status – set the status to Active to enable the integration.
  4. In the Pay To box, enter the name of the company or a person to file a payment for. In the Send To box, provide directions and the address to send the check or money order to. This information will be shared with the customer together with other payment instructions during the checkout.

  5. Set status to Active to enable the integration.

  6. Click Save.

Next, set up a payment rule that enables this payment method for all or some customer orders.

Payment Terms

In OroCommerce, you can use payment terms configured per customer to help them use the payment conditions guaranteed by their contract with your company.

Payment term is a set of conditions required for the sale to be completed, e.g. the period that is allowed to a buyer to pay off the amount due. Payment terms may also include cash in advance requirement, cash collection on delivery, a deferred payment period of 10/20/30 days, etc.

To use Payment Terms in your OroCommerce Front Store, you need to Enable Payment Terms as Integration and then Create Payment Terms with the conditions you would like to offer your buyers. You can Link Payment Term to a Customer Based on Their Sales Agreement.

Enable Payment Terms as Integration

This section describes the steps that are necessary to expose payment terms as a payment method for OroCommerce orders and quotes.

To enable payment using payment terms:

  1. Navigate to the Manage Integrations page by clicking System > Integrations > Manage Integrations in the main menu.

  2. Click Create Integration and select Payment Terms as integration type:

  3. Type in the Common Integration Details:

    • Name – the payment method name that is shown as an option for payment configuration in the OroCommerce Management Console.
    • Label – the payment method name/label that is shown as a payment option for the buyer in the OroCommerce Store Front on the checkout.
    • Short label – the payment method name/label that is shown in the order details in the OroCommerce Management Console and Front Store after the order is submitted.
    • Status – set the status to Active to enable the integration.
  4. Set status to Active to enable the integration.

  5. Click Save.

Next, set up a payment rule that enables this payment method for all or some customer orders, create individual payment terms based on the sales agreement with your customers to cover all the agreed payment terms/options, and bind your customers to their respective payment term. You may use only one payment term per B2B customer.

Create Payment Terms

To create a new Payment Term:

  1. Navigate to Sales > Payment Terms using the main menu.
  1. Click Create Payment Term. The following page opens:
  1. Type in the label that is informative for both the sales person and the customer buyer, as it will be exposed as one of the payment options for both parties.
  2. Tick the Has Payment Term box for the customers who will use this payment term.
  3. Click Save.

PayPal Payflow Gateway and PayPal Payments Pro

This section describes the steps that are necessary to expose either PayPal Payflow Gateway and PayPal Payflow Gateway Express Checkout or PayPal Payments Pro and PayPal Payments Pro Express Checkout as payment methods for OroCommerce orders and quotes.

Note

Integration steps for PayPal Payments Pro and PayPal Payflow Gateway are exactly the same. The only difference is the integration type that indicates the way OroCommerce shall treat the integration.

Note

Before you begin, see PayPal Services overview and learn about PayPal integration prerequisites – the preparation steps that should be performed on the PayPal service side.

To enable PayPal Payflow Gateway or PayPal Payment Pro payments:

  1. Navigate to the Manage Integrations page by clicking System > Integrations > Manage Integrations in the main menu.

  2. Click Create Integration and select either PayPal Payflow Gateway or PayPal Payment Pro as integration type.

  3. Type in the Common Integration Details:

    Note

    • In the Basic Information and Display Options, provide name, label and short label for the PayPal Payflow Gateway/PayPal Payment Pro method.
    • In the Express Checkout section, provide different name, label and short label to identify the PayPal Payflow Gateway/PayPal Payment Pro Express Checkout method.
    • Name – the payment method name that is shown as an option for payment configuration in the OroCommerce Management Console.
    • Label – the payment method name/label that is shown as a payment option for the buyer in the OroCommerce Store Front on the checkout.
    • Short label – the payment method name/label that is shown in the order details in the OroCommerce Management Console and Front Store after the order is submitted.
    • Status – set the status to Active to enable the integration.
  4. Fill in the PayPal Specific Integration Details:

    • Basic Information and Display Options:
      • Common Payment Integration Details (name, label, and short label) for the ordinary PayPal payment.
      • Allowed Credit Card Types – Select one or more items from the list of the credit card types. Supported types are Visa, Mastercard, Discover, American Express. Press and hold Ctrl/Shift and click on the items to select.
    • Integration settings:
    • Advanced Settings:
      • Payment Actions (Authorize or Authorize and Charge) for the ordinary PayPal payment.
      • Debug Mode – when enabled, the PayPal includes more detailed information in the response. This mode may be helpful when troubleshooting payment-related issues.
      • Require CVV Entry – when enabled, the buyer is prompted to enter their credit card CVV. When enabled, the CVV is verified during payment authorization by the payment processor.
      • Zero Amount Authorization – enables Zero Amount authorization request – a transaction that authorizes further payment with the same payment details. When enabled, the buyer can reuse this payment information for the further orders.
      • Authorization for Required Amount – enables blocking the required amount on the buyer’s credit card to ensure that they have sufficient balance to be charged for the order later. This option is valid only when Zero Amount Authorization is enabled and only when Authorize payment action is selected.
    • Connection Options:
      • Use Proxy – when enabled, any request to the PayPal will be routed through the proxy server using Proxy Host and Proxy Port values provided in the following parameters.
      • Proxy Host – the host name or the IP address of the proxy server that routes the requests to and from OroCommerce.
      • Proxy Port – the port that is used by the proxy server that routes the requests to and from OroCommerce.
      • Enable SSL Verification – when enabled, OroCommerce validates the PayPal certificate in the responses from the PayPal API to secure from the man-in-the-middle attack. If the certificate is not valid, the response is ignored and payment processing fails. It is recommended to keep this option enabled for production and most test deployments. You might need to disable the SSL verification for OroCommerce internal tests with no real PayPal integration (e.g. when you are testing checkout workflow customization).
    • Express Checkout:

    PayPal Integration Configuration Details. Part 1

    PayPal Integration Configuration Details. Part 2

    PayPal Integration Configuration Details. Part 3

  5. Click Save.

Next, set up a payment rule that enables these payment methods (PayPal Payflow Gateway and PayPal Payflow Gateway Express Checkout and/or PayPal Payment Pro and PayPal Payment Pro Express Checkout) for all or some customer orders.

Delete Payment Integration

This section describes the steps that are necessary to delete integration with the payment provider and disable payment methods they offer in OroCommerce orders and quotes.

To delete an integration and related payment methods:

  1. Navigate to the Manage Integrations page by clicking System > Integrations > Manage Integrations in the main menu.

  2. Hover over the more actions menu on the right side of the line with the necessary integration and click .

    The confirmation box is shown.

    If any payment rule depends on the integration that is being deleted, the affected payment methods in those payment rules will be disabled. The payment rule might also be disabled if none of its payment methods remain enabled.

  3. If necessary, review the payment rules using the link in the confirmation box.

    Note

    The payment rules open in a new tab in your browser.

  4. Once you are ready to delete the integration, click Delete.

The payment methods created due to this integration are no longer usable in OroCommerce and cannot be enabled in the payment rule.

Payment Rules Configuration

You can configure one or more payment rules that enable the payment methods for the provided destinations.

Create a Payment Rule

To create a payment rule:

  1. Ensure that the integration(s) for the payment method(s) you plan to use (PayPal Payflow Gateway, PayPal Payments Pro, etc.) is already configured.

  2. Navigate to the list of payment rules by clicking System > Payment Rules in the main menu.

  3. In the General Information section:

    1. Tick the Enabled box to activate the payment rule. You may keep it unselected while you are drafting and testing the conditions.
    2. Specify the payment rule name and sort order to set the priority compared to other payment rules.
    3. Select the payment currency.
    4. Select the Stop Further Rule Processing, if you would like to prevent applying other payment rules with lower priority.
  4. In the Destinations section, add one or more destinations to apply this payment rule to.

    1. Click + Add. The following box appears:

    2. Specify the destination (e.g. select a Country, or select a Country and State; for the most granularity you may provide a distinct list of Postal Codes to apply the payment rule for.

  5. In the Conditions section, specify the expression that describes the conditions when this payment rule should be applied. For example, account = 1.

    For detailed information about the expression language used in the shipping and payment rules, please, see the Expression Language for Shipping and Payment Rules guide.

  6. In the Payment Method Configurations section, you may enable one or more payment methods with this payment rule. To add a payment method, select it from the list and click + Add.

    Warning

    Only one unique payment method per integration may be selected in the payment rule.

    To enable several PayPal Payflow Gateway options with different payment settings, create a separate shipping rule for every unique option. You still can use one copy of PayPal Payflow Gateway and one copy of PayPal Payflow Gateway Express Checkout in the same payment rule, as these are different payment methods.

  7. Click Save.

Enable a Payment Rule

To enable a payment rule:

  1. Navigate to the list of shipping rules by clicking System > Payment Rules in the main menu.
  2. Hover over the more actions menu to the right of the item and click .

After the payment rule is enabled,

Checkout

After the integration is complete, the customer user may select one of the payment methods that are shown after the connectivity check and payment rules evaluation.

PayPal Payflow Gateway with no CVV Required

PayPal Payments Pro with Require CVV Entry Enabled

PayPal Payments Pro Express Checkout