ssossossosso
Documentation Home »User Guide »Payment »Payment Configuration
current version

Payment Configuration

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,