IPN Field References

This & That Store Tools

An example of:

Field References

Use these references to insert a field into your transaction results page. The page will be parsed by your IPN back-end solution and field references will be replaced with the appropriate value.

Note that there are two classes of field references. One class, characterized by lower case names concatenated with an underscore, is PayPal IPN variables. The other class, characterized by capitalized names concatenated together as one word, is product database variables. The two classes are used to help keep you aware of the source of the information.

Reference	Description
%%%txn_id%%%	A unique transaction ID generated by the PayPal system
%%%business%%%	Email address or account ID of the payment recipient (i.e., the merchant). Equivalent to "receiver_email" if payment sent to primary account.
%%%receiver_email%%%	Primary email address of the payment recipient (i.e., the merchant). If the payment is sent to a non-primary email address on your PayPal account, the receiver_email will still be your primary email
%%%item_name%%%	Item name as passed by you, the merchant. Or, if not passed by you, as entered by your customer. If this is a shopping cart transaction we will append the number of the item (e.g. item_name1, item_name2)
%%%item_number%%%	Item number as passed by you, the merchant. If this is a shopping cart transaction we will append the number of the item (e.g. item_number1, item_number2)
%%%quantity%%%	Quantity as entered by your customer or as passed by you, the merchant. If this is a shopping cart transaction we will append the number of the item (e.g. quantity1, quantity 2)
%%%invoice%%%	Invoice number as passed by you, the merchant. Your customer is not able to view or edit this. It must be unique per transaction
%%%custom%%%	Custom value as passed by you, the merchant. This is a pass-through variable that is never presented to your customer
%%%memo%%%	Memo as entered by your customer in web accept note field
%%%tax%%%	Amount of tax charged on payment
%%%option_name1%%%	Option 1 Name as requested by you
%%%option_selection1%%%	Option 1 Choice as entered by your customer
%%%option_name2%%%	Option 2 Name as requested by you
%%%option_selection2%%%	Option 2 Choice as entered by your customer
%%%num_cart_items%%%	If this is a shopping cart transaction, number of items in cart
%%%payment_status%%%	May be "Completed," "Pending," "Failed," or "Denied." When completed the funds are successfully in your account balance. When pending see %%%pending_reason below. Failed will only occur when the customer attempted to use an "eCheck" and their bank declined to honor the transaction. Denied can only occur if you deny a payment during the time it is pending.
%%%pending_reason%%%	May be "echeck," "multi_currency," "intl," "verify," "address," "upgrade," "unilateral," or "other." eCheck indicates the payment has not yet cleared. Multi_currency indicates that your account is not set to automatically convert and accept the transaction currency and that the payment must be manually accepted. Intl indicates you hold an international account and acceptance must be manually performed. Verify occurs if your account is not yet verified. Address indicates the customer did not include a confirmed shipping address and your account setting requires manual acceptance or denial of such a transaction. Upgrade indicates that you PayPal account must be upgraded to a business or premier account to accept this credit card transaction. Unilateral indicates that the payment was made to an unconfirmed email address. Other indicates you must contact PayPal customer service to determine the pending reason.
%%%payment_date%%%	Time/Date stamp generated by PayPal system [format: "18:30:30 Jan 1, 2000 PST"]
%%%mc_gross%%%	Full amount of the customer's payment, before transaction fee is subtracted.
%%%mc_fee%%%	Transaction fee associated with the payment. "mc_gross" minus "mc_fee" will equal the amount deposited into the "receiver_email" account.
%%%mc_currency%%%	May be "USD," "GBP," "EUR," "CAD," or "JPY." Indicates the currency of the transaction: U.S. dollars, British pounds sterling, Euros, Canadian dollars, or Japanese Yen, respectively.
%%%settle_amount%%%	Amount that is deposited into the account's primary balance after a currency conversion from automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment
%%%settle_currency%%%	Currency of settle_amount
%%%exchange_rate%%%	Exchange rate used if a currency conversion occurred
%%%txn_type%%%	May be "web_accept," "cart," or "send_money." Web_accpat indicates the payment was sent by your customer via Single Item Purchases, Donations, or Auction Smart Logos. Cart indicates the payment was sent by your customer via the Shopping Cart feature. Send_money indicates this payment was sent by your customer from the PayPal website, using the "Send Money" tab.
%%%for_auction%%%	This is an auction payment. (Payments made using AuctionFinder or Smart Logos, as well as Send Money/Money Request payments with the type "Goods-Auction")
%%%first_name%%%	Customer's first name
%%%last_name%%%	Customer's last name
%%%address_name%%%	Name used with address (Included when the customer provides a Gift Address)
%%%address_street%%%	Customer's street address
%%%address_city%%%	City of customer's address
%%%address_state%%%	State of customer's address
%%%address_zip%%%	ZIP of customer's address
%%%address_country%%%	Country of customer's address
%%%address_status%%%	May be "confirmed" or " unconfirmed." Confirmed indicates the customer provided a Confirmed Address. Unconfirmed indicates the customer provided a Unconfirmed Address.
%%%payer_email%%%	Customer's primary email address. Use this email to provide any credits.
%%%payer_id%%%	Unique customer ID
%%%payer_status%%%	May be "verified," "unverified," or "intl_verifed." Verified indicates the customer has a Verified U.S. PayPal account. Unverified indicates the customer has an Unverified U.S. PayPal account. Intl_verified indicates the customer has a Verified International PayPal account.
%%%payment_type%%%	May be "eCheck" or "instant." eCheck indicates this payment was funded with an eCheck. Instant indicates this payment was funded with PayPal balance, credit card, or Instant Transfer.
%%%notify_version%%%	The version of the Instant Payment Notification you are using. Your IPN Solution is designed to work with version 1.4.
%%%verify_sign%%%	An encrypted string used to validate the authenticity of the transaction.
%%%ItemName%%%	The item name as specified in the products database. (Duplicate of %%%item_name%%% from PayPal.)
%%%ItemPrice%%%	The item price as specified in the products database.
%%%ItemAvail%%%	Item availability as specified in the products database.
%%%ItemPath%%%	File system path to product if appropriate.
%%%ItemSaveAsName%%%	Used as the suggested name when the item is attached to an email.
%%%ItemAttachType%%%	The MIME attachment type if appropriate.
%%%ItemComment%%%	This comment is typically html (but it can be plain text) displayed in the results page.

Demarcation References

In addition to specifying field references, demarcation references may be specified to allow sections to be optionally included/excluded and to demark areas for repetition as required (i.e. items in a PayPal shopping cart). Note that an area marked for optional inclusion may be nested within another area, either one marked for repetition or one marked for optional inclusion. Also note that demarcation references may be repeated.

Occasionally, to achieve the desired formatting, it may be necessary to insert demarcation references into the html code. The reference may not be visible when viewing the result.

Reference	Description
%%%start_cart%%%	Within the html page created for purchases made by PayPal shopping cart this reference marks the beginning of the section where all items will be listed.
%%%end_cart%%%	This reference marks the end of the cart section.
%%%product_detail%%%	The point at which product details, as specified in the product database, are inserted.
%%%error_type%%%	Short statement of the nature of the error. This field reference should only be used on the error.htm file. For enhanced security, refrain from using this field reference at all.
%%%start_download%%%	For items offered for download, this marks the beginning of the section that will be included.
%%%end_download%%%	The end of the optional download section.
%%%start_email%%%	For items automatically sent via email, this marks the beginning of the section that will be included.
%%%end_email%%%	The end of the optional email section.

If by chance you notice that a field reference entry you make is automatically changed to begin and end with %25%25%25 instead of %%% (when using a field reference in a hyperlink, for instance) by your html editor, don't be concerned. Your IPN Solution automatically checks for this sequence and treats them as %%% during parsing. However, %%% is strictly reserved. Under no circumstances may it successfully be used other than for field references. Should you use it, no harm will come, it will just be ignored.