Help Article

How do I use Express Checkout with Reference Transactions?

This page explains how to set up a billing agreement between a merchant and customer at checkout time. The checkout flow is almost identical to a normal PayPal payment, except for a section at the bottom that tells the customer they're agreeing to allow their PayPal account to be automatically billed for any future payments to this merchant.

Part 1: Set up a billing agreement Here's an example of the initial API call:
 
USER=xxxxxxxxx_api1.emaildomain.com
PWD=xxxxxxxxxx
SIGNATURE=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
METHOD=SetExpressCheckout
VERSION=97
RETURNURL=https://localhost/return.php
CANCELURL=https://localhost/cancel.php
PAYMENTREQUEST_0_PAYMENTACTION=Sale
PAYMENTREQUEST_0_AMT=10.00
PAYMENTREQUEST_0_CURRENCYCODE=USD
DESC=anystring
L_BILLINGTYPE0=MerchantInitiatedBilling

In this example:
  • The PAYMENTREQUEST_0_AMT parameter indicates that we're charging the customer $10 at checkout time and setting up a billing agreement. This amount may be zero if you don't want to charge anything at checkout time.
  • The L_BILLINGTYPE0 parameter tells PayPal to create a billing agreement with the customer.

You receive a standard SetEC response, similar to the following:
 
TOKEN=EC-33K52113XK720820U
TIMESTAMP=2013-04-02T17:37:51Z
CORRELATIONID=26b817b79a164
ACK=Success
VERSION=97
BUILD=5613839

Then you redirect the customer to the PayPal.com checkout as usual, with the token in the URL:

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=<TOKEN GOES HERE>

After signing in and clicking through to agree and continue, the customer will be redirected back to the RETURNURL you specified in the initial call — with the token appended to the URL as usual:

https://localhost/return.php?TOKEN=EC-33K52113XK720820U&PAYERID=WN26CFVF7686J

At this point you may do the normal GetExpressCheckoutDetails call:
 
USER=xxxxxxxxx_api1.emaildomain.com
PWD=xxxxxxxxxx
SIGNATURE=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
METHOD=GetExpressCheckoutDetails
VERSION=97
TOKEN=EC-33K52113XK720820U

You parse out the returned data and get ready for your DoExpressCheckoutPayment API call to commit the transaction. This is the same as for normal transactions:
 
USER=xxxxxxxxx_api1.emaildomain.com
PWD=xxxxxxxxxx
SIGNATURE=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
METHOD=DoExpressCheckoutPayment
VERSION=97
TOKEN=EC-33K52113XK720820U
PAYERID=WN26CFVF7686J
PAYMENTREQUEST_0_PAYMENTACTION=Sale
PAYMENTREQUEST_0_AMT=10.00
PAYMENTREQUEST_0_CURRENCYCODE=USD

This is where the "magic" happens. You get back the BillingAgreementID:
   
TOKEN=EC-33K52113XK720820U
BILLINGAGREEMENTID=B-8X696660S75886610
TIMESTAMP=2013-04-02T17:51:16Z
CORRELATIONID=ef731342d2410
ACK=Success
VERSION=97
BUILD=5613839
PAYMENTINFO_0_TRANSACTIONID=32S29225GU031052G
PAYMENTINFO_0_TRANSACTIONTYPE=expresscheckout
PAYMENTINFO_0_PAYMENTTYPE=instant
PAYMENTINFO_0_ORDERTIME=2013-04-02T17:51:16Z
PAYMENTINFO_0_AMT=10.00
PAYMENTINFO_0_FEEAMT=0.59
PAYMENTINFO_0_TAXAMT=0.00
PAYMENTINFO_0_CURRENCYCODE=USD
PAYMENTINFO_0_PAYMENTSTATUS=Completed
PAYMENTINFO_0_PENDINGREASON=None
PAYMENTINFO_0_REASONCODE=None
PAYMENTINFO_0_PROTECTIONELIGIBILITY=Eligible
PAYMENTINFO_0_PROTECTIONELIGIBILITYTYPE=ItemNotReceivedEligible,UnauthorizedPaymentEligible
PAYMENTINFO_0_ERRORCODE=0
PAYMENTINFO_0_ACK=Success

At this point the initial checkout is complete. You should store the Billing Agreement ID in your database for later referencing when you want to charge the customer.

 
Part 2: Reference a billing agreement Our sample billing agreement ID from the example in Part 1 was B-8X696660S75886610. The ID for a particular customer is what you should reference at some future point to create a new transaction that charges the customer.

Here's an example:
   
USER=xxxxxxxxx_api1.emaildomain.com
PWD=xxxxxxxxxx
SIGNATURE=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
METHOD=DoReferenceTransaction
VERSION=97
PAYMENTACTION=SALE
AMT=39.99
CURRENCYCODE=USD
REFERENCEID=B-8X696660S75886610

The API response tells you if it completed:
   
BILLINGAGREEMENTID=B-8X696660S75886610
TIMESTAMP=2013-04-02T18:10:48Z
CORRELATIONID=2c4e19585056
ACK=Success
VERSION=97.0
BUILD=5479129
TRANSACTIONID=4GD876515D445183S
TRANSACTIONTYPE=merchtpmt
PAYMENTTYPE=instant
ORDERTIME=2013-04-02T18:10:47Z
AMT=39.99
FEEAMT=1.46
TAXAMT=0.00
CURRENCYCODE=USD
PAYMENTSTATUS=Completed
PENDINGREASON=None
REASONCODE=None
PROTECTIONELIGIBILITY=Ineligible
PROTECTIONELIGIBILITYTYPE=None

Note: Reference Transactions aren't enabled by default; you must apply through PayPal's Business Support or your Account Executive to obtain this feature on a Live PayPal account.

To obtain the feature on a Sandbox (test) account for development purposes, first log in to developer.paypal.com with a Live account, then create a Business account in the Sandbox.
Reference Transactions are enabled by default on Sandbox accounts that were created after December 15, 2015. If your Sandbox account was created before this date, send a message to your technical contact at PayPal with that account's email, and ask for Reference Transactions to be enabled.

For help resolving this issue or others, visit PayPal's Contact Customer Service page.
We’re sorry. The page you’re looking for is no longer available. To search again or contact us, please visit our Help Centre.