Website Payments Pro Reference Transactions

A reference transaction is a financial transaction from which you can derive subsequent transactions. When a buyer purchases an item on your site, a transaction ID is generated. You can use the transaction ID later to initiate a subsequent transaction. This subsequent transaction is called a reference transaction. For example, a buyer purchases an item on your site, and you use the PayPal transaction ID later to initiate another transaction, which you and the buyer have agreed on. The original transaction must have occurred within the past 730 days because the transaction ID might not be available after two years.

Integration steps

1. Required Meet the prerequisites.
2. Required Get the reference transaction ID.
3. Required Create a reference transaction.

Prerequisites

In the PayPal Sandbox testing environment, reference transactions are automatically enabled for Sandbox accounts created after December 15, 2015. If your Sandbox account was created prior to this date, please contact Merchant Technical Support and request to have reference transactions enabled on your Sandbox account.

Note: Approval from PayPal is required to enable reference transactions for your live account. To request approval for your live account, contact PayPal Customer Support. Merchant Technical Support does not enable reference transactions for live PayPal accounts.

Get the reference transaction ID

Before you can perform a reference transaction against the buyer's card, you must have an original transaction ID from a prior transaction made by the same buyer. This previous transaction can be a zero amount card verification transaction or a transaction with a higher amount.

The original DoDirectPayment request fields include credit card information (for example, the credit card number in the account field), the billing address, and the payment amount. The DoDirectPayment response contains a transaction ID for use in a DoReferenceTransaction call.

Example of the original DoDirectPayment (NVP, SOAP) transaction:

Request

Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=insert_merchant_user_name_here
&PWD=insert_merchant_password_here
&SIGNATURE=insert_merchant_signature_value_here
&METHOD=DoDirectPayment
&VERSION=86
&PAYMENTACTION=Sale     #Indicates that a payment will be processed
&AMT=10    #The amount of payment
&ACCT=4641631486853053    #The credit card number
&CREDITCARDTYPE=VISA    #The type of credit card
&CVV2=123    #The CVV2 number
&FIRSTNAME=James
&LASTNAME=Smith
&STREET=FirstStreet
&CITY=SanJose
&STATE=CA
&ZIP=95131
&COUNTRYCODE=US
&CURRENCYCODE=USD    #The currency, e.g. US dollars
&EXPDATE=052015    #Expiration date of the credit card

Response

&ACK=Success
&AMT=10%2e00
&CURRENCYCODE=USD
&AVSCODE=X
&CVV2MATCH=M
&TRANSACTIONID=9KK85084958471234    #An ID on which to base a DoReferenceTransaction call
...

Create a reference transaction

Call DoReferenceTransaction (NVP, SOAP) to process a payment. Specify a transaction ID in the reference ID field and an amount for the payment.

After you process the following payment, you can process other payments of varying amounts by using the same input fields in subsequent DoReferenceTransaction calls. For example, you might make a subsequent call for an amount of 2, 1, or 3.

Request

Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=insert_merchant_user_name_here
&PWD=insert_merchant_password_here
&SIGNATURE=insert_merchant_signature_value_here
&METHOD=DoReferenceTransaction
&VERSION=86
&AMT=2    #The amount of payment
&CURRENCYCODE=USD    #The currency, e.g. US dollars
&PAYMENTACTION=SALE     #Indicates that a payment will be processed
&REFERENCEID=9KK85084958471234     #Use a transaction ID from a DoDirectPayment response

Response

AVSCODE=X
&CVV2MATCH=M
&ACK=Success
&TRANSACTIONID=7TX32596U93391234     #Transaction ID created in this new DoReferenceTransaction call
&AMT=2%2e00
&CURRENCYCODE=USD
...

Next

Learn about Website Payments Pro and Express Checkout.