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 use PDT properly and display transaction details to your customer, you should fetch the transaction token, variable name "tx", and retrieve 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.

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

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

If you are using this data to fulfil orders, PayPal strongly recommends that you enable IPN to determine when those pending payments are processed. 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 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.