Advanced Features Guide

Reference Transactions
Introduction to Reference Transactions
4
58 April 2012 Express Checkout Advanced Features Guide
Billing Agreements
You must have the buyer’s agreement to obtain funds from the buyer’s account. The buyer
must log in to PayPal once to agree, but after that, PayPal does not require the buyer to log in.
This agreement represents a billing agreement between you and the buyer. PayPal maintains
the agreement.
The buyer can agree during the Express Checkout flow, as in the case of purchasing a mobile
phone purchase or downloading a music video. Or the buyer can agree before initiating a
payment, as in the case of signing up for automatic utility payments.
PayPal creates a billing agreement ID that represents the agreement. The billing agreement ID
is also associated with a transaction. You can use the billing agreement ID to derive a
subsequent transaction in the same way that you use a reference transaction ID.
A reference transaction must have occurred within the past 365 days because the ID may not
be available after a year. The billing agreement ID does not establish a time frame. It is good
until canceled by the buyer. A buyer may have more than one billing agreement ID for your
site. This could occur if the buyer established separate agreements for different kinds of
service. If you use a reference transaction ID to initiate a reference transaction, you must make
sure that the ID is associated with the correct billing agreement.
To avoid confusion, PayPal recommends that you use the billing agreement ID whenever it is
available, instead of the reference transaction ID.
API Operations for Reference Transactions
Several API operations implement recurring payments using reference transactions:
 Express Checkout API operations enable you to set up a billing agreement as part of the
checkout processing, as in the examples of a mobile phone purchase or a music video
download. These operations eliminate the need for a separate step to create the billing
agreement.
 The DoReferenceTransaction API operation initiates a payment, which is sometimes
called a merchant pull payment because you initiate the payment, not the buyer. After a
billing agreement has been established, this is the only API operation you must call.
 The CreateBillingAgreement API operation enables you to set up a billing agreement
without requiring a purchase. Use it in place of DoExpressCheckoutPayment to allow a
buyer to set up a billing agreement before making a payment, as in the example of a buyer
preparing to make a monthly utility payment.
 You can use the BAUpdate API (NVP: METHOD=BillAgreementUpdate) to enable a
buyer to cancel a billing agreement while on your site. The buyer also can cancel a billing
agreement by logging in to PayPal directly; thus, this API operation may not be required.
 You can use BAUpdate (NVP: METHOD=BillAgreementUpdate) to obtain the buyer’s
most recent billing address.