Website Payments Pro Reference Transactions
DocsLegacyLast updated: September 8th 2022, @ 6:04:23 pm
Important: PayPal isn't accepting new users for this feature, and we require existing users to upgrade to our Advanced Debit and Credit solution that supports EMV 3DS (3DS 2.0) for PSD2. Our Advanced Debit and Credit solution enables highly customizable custom-card fields and reduced PCI Compliance requirements. For more information, see Set up advanced credit and debit card payments.
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.
|1.||Required||Meet the prerequisites.|
|2.||Required||Get the reference transaction ID.|
|3.||Required||Create a reference transaction.|
|4.||Optional||Prepare for 3-D Secure.|
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.
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
Note: PayPal will implement 3-D Secure authentication for reference transactions in September 2019. Merchants in the UK who need to perform Strong Customer Authentication can use the information in Prepare for 3-D Secure to plan for their 3-D Secure integration updates.
Example of the original
DoDirectPayment (NVP, SOAP) transaction:
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
&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
DoReferenceTransaction (NVP, SOAP) to process a payment. Specify a transaction ID in the reference ID field and an amount for the payment.
- After PayPal implements 3-D Secure for reference transactions, if you use
DoReferenceTransactionto update card information, PayPal will decline the transaction and return error code
12002to indicate a failure for not providing 3-D Secure authentication data. Merchants in the UK who need to perform Strong Customer Authentication can use the information in Prepare for 3-D Secure to plan for their 3-D Secure integration updates.
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
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
AVSCODE=X &CVV2MATCH=M &ACK=Success &TRANSACTIONID=7TX32596U93391234 #Transaction ID created in this new DoReferenceTransaction call &AMT=2%2e00 &CURRENCYCODE=USD ...
(Optional) Prepare for 3-D Secure
PayPal will implement 3-D Secure authentication for reference transactions in September 2019, and you can use the information in this section to plan for your 3-D Secure integration updates.
For UK merchants, Strong Customer Authentication (SCA), a requirement of the second Payment Services Directive (PSD2), goes into effect on September 14, 2019. With SCA, cardholder-initiated transactions will require two forms of authentication in order to be processed. Merchant-initiated transactions don't have the same requirements. In most cases, existing reference transaction integrations are unaffected by the SCA requirement of PSD2 because a reference transaction is a merchant-initiated transaction. However, the following reference transaction scenarios do require SCA:
- Setting up a new reference transaction
- Updating card information in an existing reference transaction
To set up a new reference transaction, complete the following steps:
DoDirectPayment, passing 3-D Secure authentication data, and obtain the transaction ID.
- To complete a reference transaction, call
DoReferenceTransactionusing the transaction ID.
To update card information for an existing reference transaction, complete the following steps:
Important: If you're using card information stored in a 3rd-party vault and the card number in the vault changes between reference transactions, you might get an
12002error code to indicate a failure for not providing 3-D Secure authentication data. Follow the steps in this section to update the card information for the reference transaction.
- (Optional) Call
GetTransactionDetailsto retrieve non-card related information, such as shipping address, for the transaction. Retrieving this information for your customer saves them the effort of re-entering information you already have.
DoDirectPaymentto provide updated card, billing address information, and 3-D Secure authentication data.
You can use the new transaction ID returned by
DoDirectPayment to complete future reference transactions that don't require card updates.
Learn about Website Payments Pro and Express Checkout.