Reference transactions

Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Checkout Integration Guide.

A reference transaction is a financial transaction from which subsequent transactions can be derived. For example, When a buyer makes a purchase on your site, PayPal generates a transaction ID, called a reference transaction ID. Later, you can use the reference ID to initiate another transaction.

This topic describes concepts for billing agreements and reference transactions for recurring payments of varying amounts of money on a varying schedule.

• Billing agreements
• Reference transactions
• API operations for reference transactions
• Billing agreement flows
• Implementation options

Note: For concepts about recurring payment on a fixed schedule where PayPal automatically bills the buyer, see Recurring payments.

Billing agreements

A billing agreement is an agreement between a merchant and the buyer. As a merchant, you can create agreements for different kinds of services on your site. A buyer can agree to a billing agreement during a purchase or before a payment is initiated. You can create and buyers can agree to separate agreements for the different services on your site.

The buyer must log into PayPal once to authorize the billing agreement, but is not required to log in again. PayPal maintains the agreement and creates a billing agreement ID, which you can use to initiate subsequent transactions. A billing agreement ID does not expire until the buyer cancels the agreement through the PayPal site.

Reference transactions

When a buyer purchases an item on your site, a reference transaction ID is generated. You can use the reference transaction ID later to initiate subsequent transactions. As a merchant, you can use a reference transaction ID to capture future payments against a billing agreement. The capture future payment transaction is a reference transaction.

For each reference transaction that you initiate, set the transaction amount for a specific time period or when transactions reach a certain amount. Only use reference transaction IDs within the past 730 days. IDs might expire after two years.

Use reference transactions to set up recurring payments for varying amounts of money on a varying schedule. For example:

• A buyer purchases a mobile phone and agrees to monthly billing for the carrier's service.
• A buyer purchases a music video and agrees to pay when the account balance exceeds a specified minimum amount.
• A buyer agrees to future payments for actual usage of utilities, such as gas or electricity.

If you initiate a reference transaction, ensure that the ID is associated with the correct billing agreement. To avoid confusion, PayPal recommends using the billing agreement ID, if available.

API operations for reference transactions

These API operations implement recurring payments using reference transactions:

Billing agreement flows

Use these flows to set up billing agreements and use reference transactions to initiate future payments:

• Setting up a billing agreement with a purchase
• Setting up a billing agreement before payment
• Initiating future payments

Setting up a billing agreement with a purchase

This diagram shows the flow for obtaining a billing agreement ID during an Express Checkout payment:

For detailed parameter descriptions, see the Express Checkout NVP/SOAP API reference.

The following steps correspond to the numbers in the diagram. Your site must take these actions at each step:

Note: If you offer a store account, you can control whether PayPal creates the billing agreement based on buyer signup. To skip the creation of a billing agreement ID if the buyer does not sign up, set SKIPBACREATION to true in the DoExpressCheckout call.

For detailed instructions, see Set up reference transactions.

Setting up a billing agreement before payment

To obtain a billing agreement ID before any payment, modify the previous procedure as follows:

• In step 1, specify 0 for the amount of purchase in the payment details.
  • Optionally, set MAXAMT to the expected average transaction amount (default is 25.00). PayPal uses this value to validate the buyer's payment method for future payments.
• Skip step 5.
• In step 6, call CreateBillingAgreement instead of DoExpressCheckoutPayment.

For detailed instructions, see Set up reference transactions.

Initiating future payments

After you establish a billing agreement, you can initiate a payment to withdraw funds from the buyer's PayPal account without manual intervention. Call DoReferenceTransaction and include these input parameters:

PayPal responds with a reference transaction ID, TRANSACTIONID. Keep the transaction ID for future reference.

DoReferenceTransaction is typically called in response to a buyer confirming a purchase on your site, as shown in this diagram:

You can also call DoReferenceTransaction for a batch of buyers whose utility bills are due. This diagram shows the DoReferenceTransaction message flow for a server-initiated recurring payment.

Implementation options

There are two options for setting up billing agreements and using reference transactions. Use the option that works best for your site:

• Set up a billing agreement during a purchase.
• Set up a billing agreement before initiating a payment.

Note: To set up a fixed amount recurring payment on a fixed schedule where PayPal automatically bills the buyer, see Create a recurring payment profile.

Additional information

• Set up reference transactions
• Set up a recurring payments profile
• Express Checkout API reference
• NVP/SOAP Express Checkout
• Apps 101