Payment Data Transfer
Introduction
Technical Overview
Manual
Code Samples


Technical Overview


Payment Data Transfer (PDT) provides merchants with the ability to display transaction details to buyers who are redirected back to their site upon payment completion.

How It Works

Once you have activated PDT, every time a buyer makes a website payment and is redirected to your return URL, a transaction token will be passed along as a "GET" variable to this return URL. In order to properly use PDT and display transaction details to your customer, you should fetch the transaction token, variable name "tx", and retreive transaction details from PayPal by constructing an HTTP POST to PayPal.

Your POST should be sent to https://www.paypal.com/cgi-bin/webscr. You must post the transaction token using the variable "tx" and the value of the transaction token previously received (e.g. "tx=transaction_token"), and the special identity token using the variable at and the value of your PDT identity token (e.g. "at=identity_token"). You will also need to append a variable named "cmd" with the value "_notify-synch", for example "cmd=_notify-synch", to the POST string.

PayPal will respond to the post with a single word, SUCCESS or FAIL, on one line in the body of the response. When you receive a SUCCESS response, the rest of the body of the response will be the transaction details, one per line, in the format key=value where key and value will both be URL encoded strings. This response data needs to be parsed appropriately and then Web decoded.

Example successful response:
SUCCESS
first_name=Jane+Doe
last_name=Smith
payment_status=Completed
payer_email=janiedoesmith@hotmail.com
payment_gross=3.99
mc_currency=USD
custom=For+the+purchase+of+the+rare+book+Green+Eggs+%26+Ham
...

You may display to your customer whatever payment details you feel are appropriate; however, PayPal recommends including the shipping address, payer email, and amount paid. If you are using PDT to determine when to fulfill an order automatically, confirm that the payment_status is Completed, since the buyer could use methods such as echecks that do not immediately clear.

If you are using this data to fulfill orders, PayPal strongly recommends that you enable to IPN to determine when those pending payments clear. For more information, please refer to the PayPal IPN manual, which is available on the PayPal website.

If the response is FAIL, then you can try reposting back to PayPal to determine if it was a network error that resulted in failure; however, if the second attempt also fails, PayPal recommends checking your script and investigating further:
  • Make sure that the txn_id is not a duplicate to prevent someone from using reusing an old, completed transaction.
  • Validate that the receiver_email is an email address registered in your PayPal account, to prevent the payment from being sent to a fraudster’s account.
  • Check other transaction details, such as the item number and price, to confirm that the price has not been changed.

IPN Variables

For a complete list of all IPN variables and detailed instructions on how to use Instant Payment Notification, please refer to the Website Payments Standard Integration Guide

Adobe Acrobat is required to read PayPal's manuals.