<< Recurring Payments

Reference Transactions

A reference transaction is a financial transaction from which subsequent transactions can be derived. For example, a buyer purchases an item on your site, and you use the PayPal transaction ID or reference transaction ID later to initiate another transaction. A reference transaction must have occurred within the past 365 days because the ID may not be available after a year.

Recurring Payments Using Reference Transactions

Recurring payments using reference transactions enable you to handle payments for varying amounts of money on a varying schedule.

Note If you would like to setup a recurring payment for a fixed amount and on a fixed schedule, and you want PayPal to automatically bill the buyer, see How to Create a Recurring Payment Profile.

The buyer can sign up for a recurring payment using reference transactions as part of the Express Checkout flow or sign up before making a purchase.

Consider the following examples:

  • A buyer purchases a mobile phone and selects a carrier. The buyer pays for the phone using Express Checkout and agrees to monthly billing for the service.
  • A buyer downloads a music video and pays for it with Express Checkout. During checkout, the buyer agrees to make a payment whenever the account balance exceeds a specified minimum amount.
  • A buyer agrees to pay monthly for utilities, such as gas or electricity. The buyer makes no payment at the time of agreement. You can charge the buyer each month for actual use.

These examples represent payment transactions that reoccur periodically, either for a specific time period or when transactions reach a certain threshold. The amount of each transaction varies by use. These kinds of recurring payments are well-suited for processing with reference transactions, which are used in the same way as reference transactions in credit card processing.

When implementing recurring payments using reference transactions, you must initiate each transaction and set each transaction amount. You can also include payment for multiple items in one checkout.

Note PayPal must enable you to use reference transactions. Contact PayPal for details.

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, and the buyer can cancel the agreement by logging in to PayPal.

Billing agreement characteristics:

  • 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:

  • Set up a billing agreement using the Express Checkout API — You must set up a billing agreement using the Express Checkout API before you can use a reference transaction.
    • Set up a billing agreement with an Express Checkout purchase:
      The SetExpressCheckout API operation enables you to set up a billing agreement in addition to a purchase, as part of the checkout processing.
    • Set up a billing agreement before the buyer makes any payment:
      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.
  • Initiate a payment after a billing agreement is established — 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.
  • Obtain the buyer's most recent billing address — You can use BAUpdate (NVP: METHOD=BillAgreementUpdate) to obtain the buyer's most recent billing address.
  • Cancel a billing agreement — 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.

Set Up a Billing Agreement Using the Express Checkout API

You must set up a billing agreement using the Express Checkout API before you can use a reference transaction.

  • Set up a billing agreement with an Express Checkout purchase — Call SetExpressCheckout. Then call DoExpressCheckoutPayment to obtain the billing agreement ID and to initiate an Express Checkout payment.
  • Setup a billing agreement before any payment — In SetExpressCheckout, specify 0 as the amount of the purchase and call CreateBillingAgreement if you only want to obtain a billing agreement ID for later use. (Do not call DoExpressCheckoutPayment, because no payment is involved.)

Set Up a Billing Agreement With an Express Checkout Purchase

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

The numbered steps correspond to the circled numbers. Your site must take the specified actions at each step, as follows:

  1. Call SetExpressCheckout and pass BillingAgreementDetails which includes the following information (see Classic API reference for details):
    • A billing type (NVP: L_BILLINGTYPEn). PayPal recommends that you use MerchantInitiatedBillingSingleAgreement if you need 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.
    • A description of the goods or services associated with the agreement (NVP: L_BILLINGAGREEMENTDESCRIPTIONn).
    • Optionally, the kind of PayPal payment you require (NVP: L_PAYMENTTYPEn).
    • Optionally, a string that you can use for any purpose (NVP: L_BILLINGAGREEMENTCUSTOMn).
  2. PayPal returns a token, which you use in the subsequent steps.
  3. 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. PayPal redirects the buyer's browser to your return page.
  5. Call GetExpressCheckoutDetails to obtain information about the buyer and the buyer's checkout status. PayPal returns checkout details.
  6. Call DoExpressCheckoutPayment to initiate the purchase.
  7. If the buyer accepts the billing agreement, PayPal returns information about the purchase and a billing agreement ID (NVP: 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 call to DoExpressCheckout.

Set Up a Billing Agreement Before Any Payment

To obtain a billing agreement ID before any payment, modify the previous procedure as follows (see Classic API reference for details):

  • 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 the value to validate the buyer's payment method for future payments.
  • Skip step 5.
  • In step 6, call CreateBillingAgreement instead of DoExpressCheckoutPayment.

Initiate a Payment after a Billing Agreement is Established

After you establish a billing agreement, you can initiate a payment, which withdraws funds from the buyer's PayPal account without manual intervention. Call DoReferenceTransaction to use a reference transaction.

Call DoReferenceTransaction and include the following information (see Classic API reference for details):

  • A reference ID (NVP: REFERENCEID that associates the buyer to a billing agreement. Typically, the ID is the billing agreement ID; however, you can also use the ID associated with a reference transaction.
  • A payment action (NVP: PAYMENTACTION, such as an Authorization or final Sale.
  • Payment details, including the amount of the payment.

PayPal responds with a reference transaction ID (NVP: TRANSACTIONID) that you can keep for future reference and other information about the transaction.

You most likely call DoReferenceTransaction in response to the buyer confirming a purchase on your site. The following diagram shows the DoReferenceTransaction message flow for a buyer making a purchase from your site.

PayPal does not require that you have a buyer on your site. For example, you could call DoReferenceTransaction for each buyer in a batch of buyers whose utility bills are due. The following diagram shows the DoReferenceTransaction message flow for a server-initiated recurring payment.

Obtain the Most Recent Billing Address

You can use BAUpdate (NVP: METHOD=BillAgreementUpdate) to obtain the buyer's most recent billing address (see Classic API reference for details).

Note This feature applies to all new and existing reference transaction-based billing agreements and preapproved payment-originated agreements.

To obtain the billing address, call BAUpdate without passing a value in the BillingAgreementStatus field. The billing address is returned in the BAUpdate response.

Cancel a Billing Agreement

You can use BAUpdate (NVP: METHOD=BillAgreementUpdate) to cancel a billing agreement.

To cancel an agreement, call BAUpdate and include the following information (see Classic API reference for details):

  • A reference ID (NVP: REFERENCEID) that associates the buyer to a billing agreement. Typically, the ID is the billing agreement ID; however, you can also use a ID from a reference transaction.
  • An action, which must be Canceled, in the BillingAgreementStatus field.

PayPal responds with the billing agreement ID and other information about the buyer whose agreement was canceled. Although a buyer can log in to PayPal to manage agreements, the BAUpdate API operation enables the buyer to cancel the agreement from your site without logging in to PayPal. You can provide your own page for maintaining agreements with the buyer.

The following diagram shows the message flow to cancel a billing agreement from your page:

Parallel Payments >>