Setting Up Billing Agreements through PayPal

A billing agreement is a purchase/sales agreement between the store and the customer that is signed/authorized on the side of a payment service. With the Billing Agreements functionality introduced in Magento Enterprise Edition 1.9 and Magento Community Edition 1.4.1, individual customers purchasing products from a web store on regular basis can place sales orders without entering payment information again and again; they can simply grant the authorization to the payment system once.

In other words, a billing agreement is a payment method that allows customers to place orders without providing payment details to the store. After the customer signs a billing agreement with the store on the side of the payment service, the latter provides the store and the customer with the reference ID for the signed billing agreement. The reference ID is a unique number assigned to a billing agreement by the payment system. During further purchases, the customer selects the billing agreement as the payment method and uses the billing agreement reference ID. No other payment information is required for placing an order. The payment system verifies billing agreement information and whether the payment can be fulfilled by the reference ID specified by the customer. After the payment system performs the payment transaction, the reference ID is returned to the Magento system and an order is placed. After a billing agreement is signed with PayPal, the store owner can charge the customer’s PayPal account directly.

Currently Magento supports using only the PayPal payment system for the Billing Agreement functionality. Prior to using the Billing Agreements functionality, the store administrator must contact the PayPal Merchant Technical Services to enabling the billing agreements (reference transactions) for their PayPal merchant account.

In this article...

Enabling and Configuring Billing Agreements

Prior to creating and using billing agreements in Magento Enterprise Edition 1.9, the store administrator needs to first enable and configure billing agreements in the system:

  1. In the Magento Admin Panel, choose System > Configuration. Select the PayPal tab on the left.
  2. In the PayPal Billing Agreement Settings panel, you can set the following values:
  • To add billing agreements as a payment option in the Payment Information section of the shopping cart Checkout page, set the Enabled field to Yes. During the checkout process, the billing agreement payment option will become visible after the customer creates any billing agreements in her or his customer account.
  • In the Title field, enter the name of the billing agreement payment option that will be available to customers on the Billing Agreements tab of the customer account and in the Payment Information section of the shopping cart Checkout page.
  • If there are a number of payment methods to be used in the shopping cart, in the Sort Order field determine the order the billing agreement option will be displayed in the Payment Information section of the shopping cart Checkout page in the frontend.
  • In the Payment Action field, choose the way payments will be authorized in the PayPal payment system and the entities that will be created in the backend as a result of the payment procedure. The following options are available:
    • Authorization - payments are only authorized at the side of the PayPal system and only an order is created in the backend of your store. The store administrator needs to log on to the merchant account on the PayPal site and capture the transaction.
    • Sale- a payment is authorized and captured at PayPal's side and as a result an order and an invoice are created in the backend of your store.
  • Choose customers of which countries can use this method of payment in the Payment Applicable From field.
  • In the Debug Mode field, specify whether data messages about all sent to the payment system and received from it information will be written into the system log file. Note that credit card related information is NOT written to the log file in order to prevent credit card fraud.
  • In the Transfer Cart Line Items field, choose whether shopping cart lines, i.e. items and their prices, are transferred separately line by line or they are transferred as one whole with their price total value.
  • The customer is able to create billing agreements from the customer account if the Allow in Billing Agreements Wizard option is enabled in the configuration.
  • Click the [Save Config] button.

    Creating a Billing Agreement

    After the Billing Agreement functionality is enabled in the Magento backend configuration (System > Configuration > PayPal > Paypal Billing Agreement Settings panel), billing agreements can be created by customers and merchants in the following ways:

      Creating a billing agreement from the customer account in the frontend — the customer uses the Billing Agreement wizard, which redirects him or her to the PayPal web site where a billing agreement is signed.
      Submitting a billing agreement with an order — after choosing the corresponding payment method, the customer is redirected to the PayPal web site where a billing agreement is signed.
      Creating an order from the Admin Panel with a billing agreement.

    Note: Currently only the PayPal Express Checkout payment method supports the Billing Agreement functionality.

    Creating a Billing Agreement from Customer Account

    A customer can create a billing agreement by signing into her or his customer account, selecting the billing agreement payment method, and starting the Billing Agreement wizard located on the Billing Agreements tab.

    The following diagram provides a general overview of a billing agreement being created from the customer account.


    When a billing agreement is created, it is submitted to the PayPal payment method gateway and is recorded to the customer account with its reference information.

    The number of billing agreements that a customer can create in the customer account is not limited and fully depends on customer’s needs. Except creating billing agreements, the customer can also cancel some or all of them on the Billing Agreement page of the customer account.

    Billing agreements created by the customer can be either of the Active or Canceled statuses. Canceled billing agreements cannot be reactivated. If necessary, the customer will need to create a new billing agreement.


    When checking out products from the shopping cart, the customer who has already signed a billing agreement with PayPal can choose the PayPal Billing Agreement payment method in the Payment Information section of the checkout page and select the necessary billing agreement reference ID from the drop-down list that becomes available.

    When the customer clicks the Place Order button, the billing agreement reference ID and sales order payment details are transferred to the PayPal payment system. After the payment system confirms the payment, a sales order is created in Magento.

    If the payment action selected for the PayPal Billing Agreement payment method in the backend configuration is Sale, as soon as the customer places an order, the PayPal payment service transfers the order amount from the customer’s account to the merchant’s one and both a sales order and an invoice are created in Magento. With the Authorization payment action selected, only a sales order is created.

    Submitting a Billing Agreement with an Order

    As it has been previously noted, a billing agreement can be created with a sales order during a shopping cart checkout, in case no billing agreements are yet created for the customer. Refer to the following diagram for more information on the mentioned flow.


    If the customer purchasing items from the web store does not yet have a billing agreement with PayPal, she or he can choose the PayPal Express Checkout method of payment, select the Sign a billing agreement to streamline further purchases with PayPal check box, and be redirected to the PayPal payment system where the customer payment information is available and the billing agreement can be signed.


    After a billing agreement with the store is signed, the customer is redirected back to the Magento frontend where an order is placed. A corresponding record appears in the billing agreements list. The following topic describes how the store administrator can manage customer’s billing agreements from the Admin panel.

    The customer having no billing agreements yet can also create a billing agreement from the mini shopping cart or from a product page by clicking the PayPal Express Checkout button. This opens a dialog box that asks the customer whether he or she would like to sign a billing agreement with the PayPal payment system. If the customer cancels creating a billing agreement, the order is created in a regular way through the PayPal payment system.


    Creating a Sales Order with a Billing Agreement

    On customer’s request, the merchant or customer service rep can create a sales order and after filling in all required information for order currency, items, billing and shipping addresses, she or he needs to select the PayPal Billing Agreement payment method and specify the reference number for a specific billing agreement.


    Managing Billing Agreements

    Managing Billing Agreements in Sales Management Area

    The list of all billing agreements for all customers is available under Sales > Billing Agreements. Here, the store administrator can filter the records by the customer or billing agreement information (billing agreement reference ID, status, or creation date). A specific record provides general information about the selected billing agreement and about all sales orders that relate to it.

    The store administrator can view, cancel, and/or delete customer's billing agreements in the sales management area or in the customer management areas.


    The store administrator can either cancel or delete the selected billing agreement by clicking the corresponding buttons located in the upper right part of the Billing Agreement page. An already canceled billing agreement can only be deleted by the administrator.

    During a shopping cart checkout, the customer who already has a billing agreement created from the customer account can choose whether to use an existing billing agreement or to create a new one.

    Managing Billing Agreements in Customer Management Area

    Billing agreements created by a single customer can be seen on the Billing Agreements tab of the customer account page in the backend (Customers > Manage Customers). From here, the store administrator can open a required billing agreement to view its general information and sales orders relating to it, cancel a billing agreement or delete it.


    Removing Website References to Billing Agreements When Not in Use

    Even if you disable billing agreements in System > Configuration > PayPal tab > Paypal Billing Agreement Settings panel, the Billing Agreements tab will still appear in the customer account area by default. The customer will not be able to create billing agreements if you’ve disabled the functionality, but many merchants would prefer that navigation that is not applicable be removed.

    Currently the best way to remove that link from the customer account area is to modify your theme slightly. The billing agreements navigation/link is created in the layout file in app/design/frontend/base/default/layout/sales/billing_agreement.xml. You should never edit the files in the base package, but you can see the code there that declares and creates that link.

    To remove the link, copy this file (and its directory structure) to your custom theme and delete or comment out the code that creates the link as shown below:

    <layout version="0.1.0">
          <reference name="customer_account_navigation" >
             <!—Comment out or delete the following block of code as shown-->
             <!--<action method="addLink" translate="label">
                     <label>Billing Agreements</label
                 </action> -->
    . . .

    Note: Normally we would recommend overwriting just this block or link in a local.xml file or another theme-specific xml file, but the removeLink and removeLinkbyUrl methods are not available currently for the account left navigation.

  • Discussion: