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.

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:

API call Description
SetExpressCheckout Sets up a billing agreement and processes a purchase as part of the checkout process.
CreateBillingAgreement Sets up a billing agreement without a purchase.
DoReferenceTransaction Initiates a merchant pull payment. After a billing agreement is set up, this is the only call you need to make.
BAUpdate (Optional) Obtains the buyer's most recent billing address when you set METHOD=BillAgreementUpdate. Also enables a buyer to cancel a billing agreement from your site.
Note: A buyer can also cancel a billing agreement by logging in PayPal directly.

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

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:

Step Call Description
1 SetExpressCheckout Pass these BillingAgreementDetails:
  • L_BILLINGTYPEn — Use MerchantInitiatedBillingSingleAgreement for only one billing agreement between you and the buyer. Use MerchantInitiatedBilling to create a billing agreement between you and the buyer each time you call DoExpressCheckoutPayment.
  • L_BILLINGAGREEMENTDESCRIPTIONn — A description of the goods or services associated with the agreement.
  • L_PAYMENTTYPEn — The type of PayPal payment. (Optional)
  • L_BILLINGAGREEMENTCUSTOMn — A string that you can use for any purpose. (Optional)
2 - PayPal returns a token, which you use in the subsequent steps.
3 Redirect Redirect the buyer's browser to PayPal, which allows the buyer to log in or set up an account to pay for the purchase. PayPal presents the buyer with a confirmation page.
4 Redirect PayPal redirects the buyer's browser to your return page.
5 GetExpressCheckoutDetails PayPal returns information about the buyer and the buyer's checkout status.
6 DoExpressCheckoutPayment Initiates the purchase.
7 - If the buyer accepts the billing agreement, PayPal returns information about the purchase and a billing agreement ID, BILLINGAGREEMENTID. Save the ID for reference transactions or recurring payments.

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:

Parameter Description
REFERENCEID A reference ID that associates the buyer to a billing agreement or reference transaction. PayPal recommends using the billing agreement ID, if available.
PAYMENTACTION A payment action, such as an Authorization or final Sale.
AMT Total cost of the transaction to the buyer.

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.

Change payment methods

If you integrated your application with the PayPal NVP/SOAP billing agreement, you can give your buyers the option to change the payment method for a specific transaction.

Implementation options

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

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