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