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

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.

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

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

Response

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

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

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

Response

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

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

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.