Website Payments Pro Reference Transactions

DocsDeprecatedLast 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.

Integration steps

1.RequiredMeet the prerequisites.
2.RequiredGet the reference transaction ID.
3.RequiredCreate a reference transaction.
4.OptionalPrepare for 3-D Secure.

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.

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:

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.

Important:

  • After PayPal implements 3-D Secure for reference transactions, if you use DoReferenceTransaction to update card information, PayPal will decline the transaction and return error code 12002 to 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 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
...

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

  1. Call DoDirectPayment, passing 3-D Secure authentication data, and obtain the transaction ID.
  2. To complete a reference transaction, call DoReferenceTransaction using 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 12002 error 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.

  1. (Optional) Call GetTransactionDetails to 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.
  2. Call DoDirectPayment to 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.

Next

Learn about Website Payments Pro and Express Checkout.