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:
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
- 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
totrue
in theDoExpressCheckout
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.
- Optionally, set
- Skip step 5.
- In step 6, call
CreateBillingAgreement
instead ofDoExpressCheckoutPayment
.
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.
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.