PayPal Instant Payment Notification - 2009 User Guide
Contents
1. payment gross 3 33 mc currency USD business acqrte 1215804264 biz gmail com payment type instant verify sign AFCWxV21C7fd0v3bYYYRCpSSR131AjcbYkD VCCBmpD41Zq yYTxBKkr payer status unverified test_ipn 1 fraud management pending filters 1 Maximum Transaction Amount tax 0 00 txn id 5XN64179EB804362B fraud management pending filters 2 Unconfirmed Address quantity 1 receiver email acgrte 1215804264 biz gmail com first name payer id PUWAJRBB8NM74 receiver id 2RXLTRMGT3M2G item number payment status Completed payment fee 0 45 mc fee 0 45 shipping 0 00 mc gross 3 33 custom charset windows 1252 notify version 2 4 The following example shows an IPN message indicating that a pended transaction has been denied IPN Guide June 2009 39 E Using Fraud Management Filters With IPN txn_type payment date last_name receipt id 0739 3836 3393 2098 residence country US item name payment gross 2 11 mc currency USD business payment type verify sign payer status test ipn 1 fraud management pending filters 1 tax 0 00 txn id 53R82724RM1848354 fraud management pending filters 2 quantity 1 first name virtual terminal 17 09 40 Jul 15 2008 instant unverified PDT acgrte 1215804264 biz gmail com AFCWxV21C7 d0vV3bYYYRCpSSR131ASrKFBPwac7aQm47p8CMLrdParst Maximum Transaction Amount Unconfirmed Addr2. Suspected Freight Forwarder Check 12 Total Purchase Price Minimum 13 IP Address Velocity 14 Risky Email Address Domain Check 15 Risky Bank Identification Number BIN Check 16 Risky IP Address Range 17 PayPal Fraud Model invoice Passthrough variable you can use to identify your Invoice Number for this purchase If omitted no variable is passed back Length 127 characters item namex 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 PayPal will append the number of the item e g item name item name2 and so forth Length 127 characters item number Pass through variable for you to track purchases It will get passed back to you at the completion of the payment If omitted no variable will be passed back to you Length 127 characters mc currency e For payment IPN notifications this is the currency of the payment e For non payment subscription IPN notifications i e txn type signup cancel failed cot or modify this is the currency of the subscription e For payment subscription IPN notifications it is the currency of the payment i e txn type subscr payment IPN Guide June 2009 45 IPN Variable Reference Payment Information Variables Variable Name Description mc fee mc_gross mc_gross x mc handling mc shipping mc shippingx memo num cart items option namel option
3. A German ELV payment is made using Express Checkout Denied You denied the payment This happens only if the payment was previously pending because of possible reasons described for the pending reason variable or the Fraud Management Filters x variable Expired This authorization has expired and cannot be captured Failed The payment has failed This happens only if the payment was made from your customer s bank account Pending The payment is pending See pending reason for more information Refunded You refunded the payment Reversed A payment was reversed due to a chargeback or other type of reversal The funds have been removed from your account balance and returned to the buyer The reason for the reversal is specified in the ReasonCode element Processed A payment has been accepted Voided This authorization has been voided payment type echeck This payment was funded with an eCheck instant This payment was funded with PayPal balance credit card or Instant Transfer 48 June 2009 IPN Guide IPN Variable Reference Payment Information Variables Variable Name Description pending reason This variable is set only if payment status Pending address The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set yo allow you to manually accept or deny each of these payments To change your preference go to the Preferences sec
4. if customer is a business Length 127 characters Customer s primary email address Use this email to provide any credits Length 127 characters Unique customer ID Length 13 characters Payment Information Variables Payment information identifies the amount and status of a payment transaction including fees Variable Name Description auth_amount auth exp auth id auth status exchange rate Authorization amount Authorization expiration date and time in the following format HH MM SS DD Mmm YY YYYY PST Length 28 characters Authorization identification number Length 19 characters Status of authorization Exchange rate used if a currency conversion occurred June 2009 IPN Guide IPN Variable Reference E Payment Information Variables Variable Name Description fraud managment pending fil One or more filters that identify a triggering action associated with one of ters x 7 E the following payment status values Pending Completed Denied where x is a number starting with 1 that makes the IPN variable name unique x is not the filter s ID number The filters and their ID numbers are as follows e AVS No Match 2 AVS Partial Match 3 AVS Unavailable Unsupported 4 Card Security Code CSC Mismatch 5 Maximum Transaction Amount 6 Unconfirmed Address 7 Country Monitor 8 Large Order Number 9 Billing Shipping Address Mismatch 10 Risky ZIP Code 11
5. mc gross X X mc fee X X mc currency X X X X X X X settle amount X X exchange rate X X IPN Guide June 2009 57 58 IPN Variable Reference Subscription Variables Variable Signup Cancel Modify USD Payment Multi Currency Re Payment fund Failed EOT payment gross payment fee Buyer Information first name last name payer business _ name address_name address_street address_city address_state address_zip address_ country payer email payer id payer status payment type Mox XxX ox xo x x o Subscription Information subscr date subscr effective periodl period2 period3 amount 1 amount 2 amount 3 mc amounti mc amount2 recurring X KOKO KO XxX xXx xo Mox Mox ox xo x Mox KO KO O KM 2 x o XX MK KM x Mox Mox A x x x x x wm Mm KK OK Mox x x x o x eM KK OK x x KK X Ko o XX Mm KK OK Ko X June 2009 IPN Guide IPN Variable Reference E Dispute Resolution Variables Multi USD Currency Re Variable Signup Cancel Modify Payment Payment fund Failed EOT reattempt X X X retry at X recur times X X X username X X X X X X X password X X X X X X X subscr id X X X X X X X Dispute Resolution Variables Dispute resolution information identifies the case ID and status associated with a dispute Variable Name Description case creation date Date and time case was registered in the
6. which no debit to the merchant will result PayPal must review the documentation from the credit card company to determine the nature of the dispute and possibly contact the merchant to resolve it Payment Review Using Notifications If PayPal places a payment under review PayPal sends messages containing the payment status and pending reason variables In addition it sends a protection eligibility variable that identifies the kind of protection in force for the transaction The initial IPN or PDT message indicates that the payment is under review e The payment status variable is set to Pending e The pending reason variable is set to PaymentReview A subsequent IPN message indicates the resolution of the payment review e Ifthe transaction was successful and the payment was accepted PayPal sends a notification whose payment status variable is set to Completed e Ifthe transaction failed and the payment was rejected PayPal sends a notification whose payment_ status variable is set to Reversed NOTE PDTs are only available for the initial status 60 June 2009 IPN Guide
7. IPN Guide Introducing IPN IPN Protocol and Architecture The IPN message is not actually part of the response sent to your website Rather the IPN message is sent to the your listener which allows you to take actions that are not directly tied to the operation of your website NOTE The diagram does not show the IPN authentication protocol messages that validate the IPN message IPN is an asynchronous message service meaning that messages are not synchronized with actions on your website Thus listening for an IPN message does not increase the time it takes to complete a transaction on your website The IPN message service does not assume that all messages will be received by your listener in a timely manner Because the internet is not 100 reliable messages can become lost or delayed To handle the possibility of transmission and receipt delays or failures the IPN message service implements a retry mechanism that resends messages at various intervals until you acknowledge that the message has successfully been received Messages may be resent for up to four days after the original message NOTE Unless you are certain that a failure occurred on the the Internet the most likely cause of lost delayed or duplicate IPN messages is faulty logic in the listener itself Because messages can be delivered at any time your listener must always be available to receive and process messages however the retry mechanism also handles the possib
8. Pane option selectionl Transaction fee associated with the payment mc gross minusmc fee equals the amount deposited into the receiver email account Equivalent to payment fee for USD payments If this amount is negative it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction fee Full amount of the customer s payment before transaction fee is subtracted Equivalent to payment gross for USD payments If this amount is negative it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction The amount is in the currency ofmc currency where x is the shopping cart detail item number The sum ofmc gross x should total mc gross Total handling amount associated with the transaction Total shipping amount associated with the transaction This is the combined total of shipping1 and shipping2 Website Payments Standard variables where x is the shopping cart detail item number The shippingx variable is only shown when the merchant applies a shipping amount for a specific item Because profile shipping might apply the sum of shippingx might not be equal to shipping Memo as entered by your customer in PayPal Website Payments note field Length 255 characters If this is a PayPal Shopping Cart transaction number of items in cart Option 1 name as requested by you PayPal appends t
9. What is IPN IPN Guide IPN notifies you when an event occurs that affects a transaction Typically these events represent various kinds of payments however the events may also represent authorizations Fraud Management Filter actions and other actions such as refunds disputes and chargebacks IPN is a message service that PayPal uses to notify you about events These events include the following e Instant payments including Express Checkout and direct credit card payments e eCheck payments and associated status such as pending completed or denied e Payments that may be pending for other reasons such as those being reviewed for potential fraud e Events related to recurring payments and subscriptions e Authorizations which indicate a sale whose payment has not yet been collected e Chargebacks which are initiated by a credit card processor for example when a customer disputes a charge e Disputes which are initiated by a buyer using the PayPal resolution process e Reversals which occur when you win a dispute or a chargeback is canceled e Refunds which you may choose to give In many cases the action that causes the event such as a payment occurs on your website however your website is not the only source of events In many cases events can be generated by Website Payment Standard buttons the PayPal API or by PayPal itself You detect and process IPN messages with a listener sometimes called a handler which i
10. following format HH MM SS DD Mmm YY YYYY PST case id Case identification number Format PP nnn nnn nnn where n is any numeric character case type e chargeback A buyer has filed a chargeback with his credit card company which has notified PayPal of the reason for the chargeback e complaint A buyer has logged a complaint through the PayPal Resolution Center e dispute A buyer and seller post communications to one another through the Resolution Center to try to work out issues without intervention by PayPal IPN Guide June 2009 59 E IPN Variable Reference Payment Review Using Notifications Variable Name Description reason_code Reason for the case Values for case_type set to complaint e non_receipt Buyer claims that he did not receive goods or service e not as described Buyer claims that the goods or service received differ from merchant s description of the goods or service Values for case type set to chargeback e unauthorized e adjustment reimburse A case that has been resolved and close requires a reimbursement e non receipt Buyer claims that he did not receive goods or service e duplicate Buyer claims that a possible duplicate payment was made to the merchant e merchandise Buyer claims that the received merchandise is unsatisfactory defective or damaged e special Some other reason Usually special indicates a credit card processing error for which the merchant is not responsible and for
11. rate recurs 1 is yes blank is no Date PayPal will retry a failed subscription payment Start date or cancellation date depending on whether transaction is subscr signup or subscr cancel Time Date stamp generated by PayPal in the following format HH MM SS DD Mmm YY YYYY PST Date when the subscription modification will be effective only for txn type subscr modify Time Date stamp generated by PayPal in the following format HH MM SS DD Mmm YY YYYY PST ID generated by PayPal for the subscriber Length 19 characters optional Username generated by PayPal and given to subscriber to access the subscription Length 64 characters June 2009 IPN Guide IPN Variable Reference E Subscription Variables Summary of subscription variables Multi USD Currency Re Variable Signup Cancel Modify Payment Payment fund Failed EOT Basic Information business x x x X X X X receiver email X X X X X X X receiver id X X item name X X X X X X X item number X X X X X X X Advanced and Custom Information invoice X X X X X X X custom X X X X X X X option namel X X X X X X X option selecti X X X X X X X onl option name2 X X X X X X X option selecti X X X X X X X on2 Transaction Information payment status X X X pending reason X X reason code X X payment date X X txn id X X parent txn id X X txn type subscr subscr subscr subscr payment subscr subsc signup cancel modify failed r eot Currency and Exchange information
12. will send another single word message INVALID IMPORTANT After you receive the VERIFIED message there are several important checks you must perform before you can assume that the message is legitimate and not already processed Confirm that the payment status is Completed Use the transaction ID to verify that the transaction has not already been processed which prevents duplicate transactions from being processed Validate that the receiver s email address is registered to you Verify that the price item description and so on match the transaction on your website Non IPN Notification Mechanisms You can use IPN with other notification mechanisms For example you can use PDT or the API to determine real time information about a transaction and let IPN notify you of any changes after the transaction occurs If you are using Website Payments Standard you can use PDT to obtain information about the transaction If you are using Express Checkout or Direct Payment the PayPal API notifies you of the status and details of the transaction immediately and automatically In either case you can immediately display to your customer the information being returned from PayPal You should not use IPN for this purpose IPN Guide June 2009 17 Introducing IPN Non IPN Notification Mechanisms 18 June 2009 IPN Guide Implementing an IPN Listener You write your IPN listener in the scripting or prog
13. FIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent Your IPN listener implements the IPN authentication protocol steps 2 3 and 4 in this diagram After successfully completing the protocol your listener or back office or administrative process vets the contents of the message and responds appropriately For example your system can notify the customer of the refund by email IPN Messages Generated by PayPal Some IPN messages generated by PayPal are not directly associated with a web flow PayPal generates an IPN message when external events arise that might affect a transaction such as disputes chargebacks echeck clearing and various recurring payment and subscription events In this case events that trigger IPN messages are not directly related to actions on your website The following diagram shows the steps your listener must take IPN Guide June 2009 13 E Introducing IPN A Sample IPN Message and Response PayPal initiated action Your IPN Listener Your back office and administrative processes Legend gt IPN Message Flow The numbers in diagram correspond to the following steps which implement the IPN message authentication protocol 1 PayPal sends your IPN listener a message that notifies you of the event 2 Your listener sends the complete unaltered message back to PayPal the message must contain the same fields in the sam
14. PN Guide Introducing IPN E IPN Protocol and Architecture Checkout flow Your site Parra 4 Your IPN Listener Your site Your back office and administrative processes Legend Web Flow IPN Message Flow Website Payments Standard The numbers in diagram correspond to the following steps 1 The button action initiates a payment that completes on PayPal 2 PayPal sends your IPN listener a message that notifies you of the event 3 Your listener sends the complete unaltered message back to PayPal the message must contain the same fields in the same order and be encoded in the same way as the original message 4 PayPal sends a single word back which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent Your IPN listener must implement the IPN authentication protocol steps 2 3 and 4 in this diagram After successfully completing the protocol your back office or administrative process vets the contents of the message and responds appropriately For example if the payment status for the transaction is Completed your system can print a packing list or email a password to your customer for downloading digital media IPN Messages Generated by PayPal APIs PayPal generates an IPN message when you invoke an API operation such as DoExpressCheckoutPayment of DoDirectPayment during checkout You can use t
15. PayPal Instant Payment Notification Guide For Professional Use Only Currently only available in English A usage Professional Uniquement Disponible en Anglais uniquement pour l instant Last updated June 26 2009 IPN Guide Document Number 10087 en_US 20090626 2009 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc PayPal Europe Ltd is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution PayPal FSA Register Number 226056 Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal Inc reserves the right to make changes to any information herein without further notice Contents Intended Aud
16. ade In addition to the information on the IPN History page the details contain the following information e Whether this IPN message was the original message or whether it was resent e The last time the message was resent e The URL on which your listener is running NOTE You cannot change the URL if you request PayPal to resend an IPN message it is sent to this URL e The number of retries before the message was successfully acknowledged e The type of IPN message Resending IPN Messages You can use the IPN History page to request that PayPal resend one or more IPN messages You can search the IPN message history for the messages that may need to be resent and then select them IPN Guide June 2009 33 E IPN Operations on PayPal Resending IPN Messages To make a request that PayPal resend IPN messages mark one or more messages for PayPal to resend and click the Resend selected button to make the request Lega Help Securty Center Search PayPal My Accoum Send Money Request Money Merchant Services Products amp Services Shopping Overview AddFunds vitndraw History Resolution Center Profile Instant Payment Notification IPN history Select search criteria below to display search resulls A maximum of 1 000 IPN messages will be displayed Search Dates Range must be within the past 28 days Last 14 days C From To CS Delivery status All default Transaction ID Search results Resend sele
17. aid for Website Payments Pro A new dispute was filed Recurring payment received Recurring payment profile created IPN Guide June 2009 41 RR IPN Variable Reference Transaction and Notification Related Variables Transaction Type txn type Description send money Payment received source is the Send Money tab on the PayPal website subscr cancel Subscription canceled subscr eot Subscription expired subscr failed Subscription signup failed subscr modify Subscription modified subscr payment Subscription payment received subscr signup Subscription started virtual terminal Payment received source is Virtual Terminal web accept Payment received source is a Buy Now Donation or Auction Smart Logos button Transaction and Notification Related Variables Transaction and notification related variables identify the merchant that is receiving a payment or other notification and transaction specific information Variable Name Description business charset custom notify version parent txn id Email address or account ID of the payment recipient that is the merchant Equivalent to the values of receiver email if payment is sent to primary account and business set in the Website Payment HTML NOTE The value of this variable is normalized to lowercase characters Length 127 characters Character set Custom value as passed by you the merchant These are pass through variab
18. ates amp address city SantJose amp quantity l amp averify sign Atk OfCXbDm2hu0OZELryHF5 Y Vb PAUvS 6nMXgysbElEn9v 1XcmSoGtf amp payer email gpmac 1231 902590 pers40paypal com amp txn_id 61E67681CH32 38416 amp payment type instant amp last name User amp address state CAgreceiver email g pmac 1231902686 biz 40paypal com amp payment fee 0 88 amp receiver id S8XGHLYDW9T3S amp txn type express checkout amp item name amp mc currency USD amp item number amp residenc e country US amp test ipn 1 amp handling amount 0 00 amp transaction subject amp payment g ross 19 95 amp shipping 0 00 Variable Notes Information about you receiver email gm 1231902686 _biz paypal com receiver_id S8XGHLYDW9T3S residence_country US Information about the transaction test_ipn 1 transaction subject txn_id 61E67681CH3238416 txn_type express_checkout Information about your buyer payer email gm 1231902590 per paypal com payer_id LPLWNMTBWMFAY payer_status verified first_name Test last name User address city San Jose address country United States address country code US address name Test User address state CA address status confirmed Check email address to make sure that this is not a spoof Testing with the Sandbox Keep this ID to avoid processing the transaction twice Type of transaction IPN Guide June 2009 15 16 Intro
19. cted E Datetime created Messaye ID Status HTTP response code Transaction ID 512512009 12 59 POT C ML 2118634 Sent 200 961051348 R02233017 5125 2009 12 57 POT G 957 H Failed R 5120 2009 15 08 POT 4 635 Failed After you make the request PayPal notifies you that the messages have been resent and updates the status The status indicates that PayPal is resending the message until it actually has been resent 34 June 2009 IPN Guide IPN Operations on PayPal a Resending IPN Messages My Account Send Money Request Money Merchant Services Products amp Services Shopping Instant Payment Notification IPN history Select search criteria below to display search results A maximum of 1 000 IPN messages will be displayed Search Dates Range must be within the past 28 days Last 14 days From Es To Delivery status All default Mi Transaction ID Search results send selected Datetime created Message ID Status HTTP response code Transaction ID 5 25 2009 12 59 PDT CG1 QDDOIG43ML2118653U Sent 200 26J05134FR0233917 5 25 2009 12 57 POT C1 62H89571J0376742L Failed 5120 2009 15 08 POT F FAT Failed resending When the message has been sent your server s response to the HTTP POST is used to update the HTTP response code field A value of 200 indicates that your server successfully received the IPN message Other values typically indicate a server configuration error for the server that hosts your IPN listener For
20. d your system can print a packing list or email a password to your customer for downloading digital media IPN Messages Generated by a Back Office Procedure PayPal generates an IPN message when you perform actions that invoke the PayPal API regardless of whether it is from your website or from a back office or administrative procedure You can use this notification to trigger an email to your customer store information in a CRM or accounting system and so on The following diagram shows both an administrative web flow and the IPN message authentication protocol June 2009 IPN Guide Introducing IPN a IPN Protocol and Architecture Backend Process Your office O E Your back office PayPal API request response PayPa Ir lt and administrative For example RefundTransaction processes Your IPN Listener Legend gt IPN Message Flow PayPal API The numbers in diagram correspond to the following steps 1 Your back office or administrative process invokes a PayPal API operation for example it could invoke the RefundTransaction API operation when your employee issues a refund 2 PayPal sends your IPN listener a message that notifies you of the event 3 Your listener sends the complete unaltered message back to PayPal the message must contain the same fields in the same order and be encoded in the same way as the original message 4 PayPal sends a single word back which is either VERI
21. d s a renv ala Sala fraca ths rere scr an hS S rup rhad ma tack e artare Pae ent Not BARN LET awr iw test Can We Help arara l mf ZTE vaues prosidze in z 12147 be cu arz clc ou mas Zhz dc ans ZTS Talo 75 DR peur da ad 74 Y lt sil na be aul cule Payment mmf randu aesmar cera eran cabe pasren status hur Rr intaimatinn pas cule C BIA 1 X a l ete sear erai parte Bussis inlunnulion Ka fore vor emal Cad ok m tan es bor Mae ie cuus 7 ke rda 3 rvs ths T ertad cem nen Rp AA O SY KITS L vv its Spa x doo oo Ween 6 NN pd reula mwa oe EY rmat shEPIG s te Currency und Currrvnm Y va mm LA RC 44 e fem re ere Transaction Helds hn cera bene ZAS LEA 6 rotry_ ersie Rehinidefraversale LSLS ln as xv Ede iy aba tesiste ARAE HRAS ben ehna Aruanrad and ritam Information ahn X me a fines 12 2 4 June 2009 IPN Testing IPN Troubleshooting Tips 4 Click Send IPN The IPN message is sent to the specified URL and the results of the operation are displayed at the top of the page After Completing This Task If your IPN listener receives a message you know that it is properly installed on your web server The default messages sent by the IPN simulator are valid thus if your listener responds correctly to the message it should receive a VERIFIED message If you do not receive any message or if you
22. ducing IPN A Sample IPN Message and Response Variable address_street 1 Main St address zip 95131 Information about the payment custom handling amount 0 00 item name item number mc currency USD mc fee 0 88 mc gross 19 95 payment date 20 12 59 Jan 13 2009 PST payment fee 0 88 payment gross 19 95 payment status Completed payment type instant protection eligibility Eligible quantity 1 shipping 0 00 tax 0 00 Other information about the transaction notify version 2 6 charset windows 1252 verify sign AtkOfCXbDm2hu0ZELryHFj Y Vb7PAUvS6nM XgysbElEn9v 1 XcmSoGtf Your custom field Kind of payment Status which determines whether the transaction is IPN version can be ignored Before you can trust the contents of the message you must first verify that the message came from PayPal To verify the message you must send back the contents in the exact order they were received and precede it with the command notify validate as follows https www sandbox paypal com cgi bin webscr cmd notify validate amp mc gross 19 95 amp protection eligibility Eli gi blegaddress status conf irmed amp payer id LPLWNMTBWMFAY amp tax 0 00 amp amp payment gross 19 95 amp shipping 0 00 IPN Guide Introducing IPN Non IPN Notification Mechanisms PayPal will then send one single word message VERIFIED if the message is valid otherwise it
23. e order and be encoded in the same way as the original message 3 PayPal sends a single word back which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent After successfully completing the protocol your back office or administrative process vets the contents of the message and responds appropriately For example the IPN messages may trigger you to print shipping labels for items whose payments have cleared investigate disputes and chargebacks store information in an accounting system and so on A Sample IPN Message and Response An IPN message consists of variables that describe the transaction These variables contain information about you your customer and the details of the transaction itself PayPal sends a message similar to the following one for a 19 95 purchase made by Express Checkout 14 June 2009 IPN Guide Introducing IPN A Sample IPN Message and Response mc gross 19 95 amp protection eligibility Eligiblegaddress status confirmed amp pay er id LPLWNMTBWMFAY amp tax 0 00gaddress str t 1 Main St amp payment date 20 3A12 3A59 Jan 13 2C 2009 PST amp payment status Completed amp charset windows 1252 amp address zip 95131 amp first nam e Test mc_ fee 0 884address country code US amp address name Test User amp notify version 2 6 amp custom amp payer status verified add ress country United St
24. eceive IPN messages Enabled to enable your listener 6 Click Save The following screen appears PayPal My Account Send Money Request Money Merchant Services Products amp Services Shopping Instant Payment Notification IPN Back to Profile Summary You have turned on the IPN feature You can view your IPNs on the IPN History page M necessary you can resend IPN messages from that page For more information on using and troubleshooting this feature read more about Instant Payment Notification PN To stop receming IPNs permanent click Turn Off IPN Curremt settings Notification URL hitps0rnycompany conipn_handler Message delivery Enabled Edison Tum omen 7 Click Back to Profile Summary to return to the Profile after activating your listener You also can click Edit settings to modify your notification URL or disable your listener You can click Turn Off IPN to reset your IPN preferences 24 June 2009 IPN Guide Identifying Your IPN Listener to PayPal ina Dynamically Setting the Notification URL Dynamically Setting the Notification URL You can specify an IPN listener for a specific payment In this case PayPal sends the IPN message to the listener specified in the notification URL for a specific button or API operation instead of the listener specified in your Profile To specify a notification URL For a an specify your IPN Listener s URL in the Website Payments Standard button notify url HTML
25. ected by Expanded seller protection SellerProtection Seller is protected by PayPal s Seller Protection Policy None Seller is not protected under Expanded seller protection nor the Seller Protection Policy quantity Quantity as entered by your customer or as passed by you the merchant If this is a shopping cart transaction PayPal appends the number of the item e g quantityl quantity2 IPN Guide June 2009 49 IPN Variable Reference Auction Variables Variable Name Description reason code remaining settle settle amount settle currency shipping shipping method tax transaction entity This variable is set if payment status Reversed Refunded or Cancelled Reversal adjustment reversal Reversal of an adjustment buyer complaint A reversal has occurred on this transaction due to a complaint about the transaction from your customer chargeback A reversal has occurred on this transaction due to a chargeback by your customer chargeback reimbursement Reimbursement for a chargeback chargeback settlement Settlement of a chargeback guarantee A reversal has occurred on this transaction due to your customer triggering a money back guarantee other Non specified reason refund A reversal has occurred on this transaction because you have given the customer a refund NOTE Additional codes may be returned Remaining amount that can be captured with Authorization and Capture Amount that i
26. ed June 2009 37 E Using Fraud Management Filters With IPN txn type virtual terminal payment date 17 11 42 Jul 15 2008 PDT last name receipt id 3075 7371 4622 1677 residence country US pending reason address item name payment gross 3 33 mc currency USD business acqrte 1215804264 biz gmail com payment type instant verify sign APYUGJhXGkUmvFnZf4I5co6CedkKAowZj T4T7GXWIMDnZ0uFLkcq oH payer status unverified test_ipn 1 fraud_management pending filters 1 tax 0 00 txn id 5XN64179EB804362B fraud_management pending filters 2 quantity 1 first name receiver email acgrte 1215804264 biz gmail com payer id PUWAJRBB8NM74 receiver id 2RXLTRMGT3M2G item number payment status Pending shipping 0 00 3 33 Maximum Transaction Amount Unconfirmed Address mc gross custom charset windows 1252 notify version 2 4 NOTE Ifthe transaction is for an authorization or an order the auth status variable may also be set to Pending If a transaction has been pended PayPal sends an IPN message when the payment has been accepted or denied The following example shows an IPN message indicating that a pended transaction has been accepted 38 June 2009 IPN Guide Using Fraud Management Filters With IPN ia txn type virtual terminal payment date 17 11 42 Jul 15 2008 PDT last name receipt id 3075 7371 4622 1677 residence country US item name
27. ersal and either of those payment statuses can be for the full or partial amount of the original transaction fee NOTE This is a deprecated field Usemc fee instead payment fee x Ifthe payment is USD then the value is the same as that formc fee x where x is the record number if the currency is not USD then this is an empty string NOTE This is a deprecated field Usemc fee x instead payment gross Full USD amount of the customer s payment before transaction fee is subtracted Will be empty for non USD payments This is a legacy field replaced by mc gross If this amount is negative it signifies a refund or reversal and either of those payment statuses can be for the full or partial amount of the original transaction payment gross x If the payment is USD then the value for this is the same as that for the mc_gross_x where x is the record number the mass pay item If the currency is not USD this is an empty string NOTE This is a deprecated field Use mc_gross_x instead IPN Guide June 2009 47 E IPN Variable Reference Payment Information Variables Variable Name Description payment status The status of the payment Canceled Reversal A reversal has been canceled For example you won a dispute with the customer and the funds for the transaction that was reversed have been returned to you Completed The payment has been completed and the funds have been added successfully to your account balance Created
28. ess receiver email acgrte 1215804264 biz gmail com payer id PUWAJRBB8NM74 receiver id 2RXLTRMGT3M2G item number payment status Denied shipping 0 00 mc gross 2 11 custom charset windows 1252 notify version 2 4 40 June 2009 IPN Guide IPN Variable Reference PayPal returns related variables for each kind of IPN message Not all variables are returned for each type of transaction e IPN Transaction Types e Transaction and Notification Related Variables e Buyer Information Variables e Payment Information Variables e Auction Variables e Mass Pay Variables e Recurring Payments Variables e Subscription Variables e Dispute Resolution Variables IPN Transaction Types Typically your back end or administrative processes will perform specific actions based on the kind of IPN message received You can use the txn_type variable in the message to trigger the kind of processing you want to perform Transaction Type txn_type Description Credit card chargeback ifthe case type variable contains chargeback adjustment A dispute has been resolved and closed cart Payment received for multiple items source is Express Checkout or the PayPal express checkout masspay merch pmt new case recurring payment recurring payment profile created Shopping Cart Payment received for a single item source is Express Checkout Payment sent using MassPay Monthly subscription p
29. fimred account PayPal does not send an IPN message If you receive an INVALID message e Check that your are posting your response to the correct URL which is https www sandbox paypal com cgi bin webscr or https www paypal com cgi bin webscr depending on whether you are testing in the Sandbox or you are live respectively e Verify that your response contains exactly the same IPN variables and values in the same order preceded with cmd _notify validate IPN Guide June 2009 29 E IPN Testing IPN Troubleshooting Tips e Ensure that you are encoding your response string and are using the same character encoding as the original message NOTE If you receive multiple IPN messages for the same transaction or if messages appear to be out of order this is not necessarily an indication that your listener is malfunctioning For example if you do not respond in time PayPal resends the message You should investigate these situations however because they could be caused by a logic errors or performance problems as well 30 June 2009 IPN Guide IPN Operations on PayPal The IPN History page on PayPal provides additional information to help you troubleshoot IPN messages You can use the IPN History page to determine the status of IPN messages and to resend them if necessary e Using the IPN History e Resending IPN Messages Using the IPN History Use the IPN History page on PayPal to view IPN messages sent t
30. form variable NVP API operation NOTIFYURL field of the DoDirectPayment DoExpressCheckoutPayment or DoReferenceTransaction request SOAP API operation NotifyURL field of the DoDirectPayment DoExpressCheckout Payment or DoReferenceTransaction request NOTE The IPN message will always be sent to your notification URL unless receiving IPNs have been disabled Even though you have not enabled receiving IPN messages in your Profile or you have reset your preference by turning off IPN messages PayPal still sends IPN messages to the notification URL you specify for a specific payment IPN messages not sent because you disabled the preference in your Profile will appear in the IPN history when you enable receiving IPNs After they appear in the history you can choose whether or not to resend them IPN Guide June 2009 25 a Identifying Your IPN Listener to PayPal Dynamically Setting the Notification URL 26 June 2009 IPN Guide IPN Testing After you implement your listener and start it running on your web server you can use the IPN simulator in the Sandbox to send IPN messages to the URL at which your listener is running This tool allows you to verify that you are receiving IPN messages correctly e Testing Your Listener e IPN Troubleshooting Tips Testing Your Listener The first level of testing is to ensure that your IPN listener receives messages and handles them appropriately This level of testing requires you
31. g for manual investigation foreach _POST as key gt value Semailtext key value n n IPN Guide June 2009 21 Ie Implementing an IPN Listener mail Semail Live INVALID IPN Semailtext n n req fclose Sfp gt 22 June 2009 IPN Guide Identifying Your IPN Listener to PayPal After you implement and test your IPN listener you make your listener known to PayPal by specifying the listener s URL in your account s profile Optionally you can override the URL to specify another listener for specific payments e Setting Up IPN Notifications on PayPal e Dynamically Setting the Notification URL Setting Up IPN Notifications on PayPal After you implement and test your IPN listener you identify the listener to PayPal by selecting Instant Payment Notification Preferences from your account s profile You then specify your listener s URL and click the box to activate it Your listener must be located at the URL that you specify in the profile Before you activate your listener on PayPal you should test the listener using the IPN simulator in the Sandbox The steps to set up your listener for Sandbox testing and to set up your listener for live operation on PayPal are the same The only difference is that you log into the Sandbox to set up your listener for Sandbox testing and you log into PayPal to set up your listener for live operation NOTE Sandbox testing goes bey
32. gross for the first IPN you receive from a multi item auction auction multi item since each item from the auction will generate an Instant Payment Notification showing the amount for the entire auction for auction This is an auction payment payments made using Pay for eBay Items or Smart Logos as well as Send Money Money Request payments with the type eBay items or Auction Goods non eBay Mass Pay Variables Mass pay information identifies the amounts and status of transactions related to mass payments including fees Variable Name Description masspay txn id x For Mass Payments a unique transaction ID generated by the PayPal system where x is the record number of the mass pay item Length 19 characters mc currency x For Mass Payments the currency of the amount and fee where x is the record number the mass pay item mc fee x For Mass Payments the transaction fee associated with the payment where x is the record number the mass pay item mc gross x The gross amount for the amount where x is the record number the mass pay item mc_handlingx The x is the shopping cart detail item number The handling cart cart wide Website Payments variable is also included in the mc_handling variable for this reason the sum of mc_handlingx might not be equal to mc handling payment date For Mass Payments the first IPN is the date time when the record set is processed and the second IPN is the date time when all payme
33. he number of the item where x represents the number of the shopping cart detail item e g option namel option name2 Length 64 characters Option 2 name as requested by you PayPal appends the number of the item where x represents the number of the shopping cart detail item e g option name2 option name2 Length 64 characters Option 1 choice as entered by your customer PayPal appends the number of the item where x represents the number of the shopping cart detail item e g option selectionl option selection2 Length 200 characters June 2009 IPN Guide IPN Variable Reference Payment Information Variables Variable Name Description option selection Option 2 choice as entered by your customer PayPal appends the number of the item where x represents the number of the shopping cart detail item e g option selectionl option selection2 Length 200 characters payer status Whether the customer has a verified PayPal account e verified Customer has a verified PayPal account e unverified Customer has an unverified PayPal account payment date Time Date stamp generated by PayPal in the following format HH MM SS DD Mmm YY YYYY PST Length 28 characters payment fee USD transaction fee associated with the payment payment gross minus payment fee equals the amount deposited into the receiver email account Is empty for non USD payments If this amount is negative it signifies a refund or rev
34. his notification to kick off order fulfillment enable digital media downloads store information in a customer relationship management CRM or accounting system and so on The following diagram shows both the web flow and the IPN message authentication protocol IPN Guide June 2009 11 12 Introducing IPN IPN Protocol and Architecture Checkout flow Your site PayPal API request response Parra 4 Your IPN Listener Your site Your back office and administrative processes Legend a gt web Flow IPN Message Flow PayPal API The numbers in diagram correspond to the following steps 1 The API operation initiates a payment on PayPal 2 PayPal sends your IPN listener a message that notifies you of the event 3 Your listener sends the complete unaltered message back to PayPal the message must contain the same fields in the same order and be encoded in the same way as the original message 4 PayPal sends a single word back which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent Your IPN listener must implement the IPN authentication protocol steps 2 3 and 4 in this diagram After successfully completing the protocol your back office or administrative process vets the contents of the message and responds appropriately For example if the payment status for the transaction is Complete
35. ience o oo oaa a a a Revision History gt a s sss e e K A Chapter 1 Introducing IPN IPN Protocol and Architecture 0 0200 eee ee IPN Messages Generated by Website Payments Standard IPN Messages Generated by PayPal APIs IPN Messages Generated by a Back Office Procedure IPN Messages Generated by PayPal cccccc LL A Sample IPN Message and Response 2 Non IPN Notification Mechanisms 0 0 00034 Chapter 2 Implementing an IPN Listener Chapter 3 Identifying Your IPN Listener to PayPal Setting Up IPN Notifications on PayPal 04 Dynamically Setting the Notification URL Chapter 4 IPN Testing Testing Your Listener 00000 eee eee IPN Troubleshooting Tips 2 aaa Chapter 5 IPN Operations on PayPal Using the IPN History 2 2 LL a Resending IPN Messages 1 2 0 LL a Chapter 6 Using Fraud Management Filters With IPN Chapter 7 IPN Variable Reference IPN Transaction Types aoaaa a IPN Guide June 2009 19 23 23 25 27 27 29 31 31 33 37 41 E Contents Transaction and Notification Related Variables 0 200000 04 42 Buyer Information Variables 2 2 0 0 ee RR 43 Payment Information Variables 2 00000 eee ee 44 Auction Variables esea 2 ee 50 Mass Pay Variables 2 e A 51 Recurring Payments Va
36. ility that your listener could become swamped or stop responding The IPN message service should not be considered a real time service Your checkout flow should not wait on an IPN message before it is allowed to complete If your website waits for an IPN message checkout processing may be delayed due to system load and become more complicated because of the possibility of retries IPN Protocol and Architecture IPN Guide IPN is designed to be secure reliable and asynchronous To meet these requirements the protocol requires you to acknowledge receipt of IPN messages The IPN service provides a retry mechanism to handle cases in which a message is not acknowledged for example when a transmission or receipt failure occurs When you enable IPN PayPal sends messages to the IPN listener at the URL you specify in your account s profile You can override the URL to associate other IPN listeners with specific transactions In this case you specify the listener s URL when you set up a Website Payment Standard button or a PayPal API operation The IPN protocol consists of three steps 1 PayPal sends your IPN listener a message that notifies you of the event 2 Your listener sends the complete unaltered message back to PayPal the message must contain the same fields in the same order and be encoded in the same way as the original message June 2009 Introducing IPN IPN Protocol and Architecture 3 PayPal sends a single word bac
37. intentionally attempt to use your listener e Avoid duplicate IPN messages Check that you have not already processed the transaction identified by the transaction ID returned in the IPN message You may need to store transaction IDs returned by IPN messages in a file or database so that you can check for duplicates If the transaction ID sent by PayPal is a duplicate you should not process it again e Because IPN messages can be sent at various stages in a transaction s progress make sure that the transaction s payment status is completed before enabling shipment of merchandise or allowing the download of digital media e Verify that the payment amount actually matches what you intend to charge Although not technically an IPN issue if you do not encrypt buttons it is possible for someone to capture the original transmission and change the price Without this check you could accept a lesser payment than what you expected IPN Messages Generated by Website Payments Standard PayPal generates an IPN message when your customer clicks a Website Payments Standard payment button such as a Buy Now button and completes the transaction on PayPal You can use this notification to kick off order fulfillment enable digital media downloads store information in a customer relationship management CRM or accounting system and so on The following diagram shows both the web flow and the IPN message authentication protocol 10 June 2009 I
38. its true foreach POST as key gt value Handle escape characters which depends on setting of magic quotes if Sget magic quotes exists true amp amp get magic quotes gpc 1 value urlencode stripslashes value else Svalue urlencode value Sreq amp Skey Svalue Post back to PayPal to validate Sheader POST cgi bin webscr HTTP 1 0 r n Sheader Content Type application x www form urlencoded r n Sheader Content Length strlen Sreg r n r n Sfp fsockopen www paypal com 80 Serrno Serrstr 30 Process validation from PayPal if Sfp HTTP ERROR else NO HTTP ERROR fputs Sfp Sheader req while feof Sfp Sres fgets Sfp 1024 if strcmp res VERIFIED 0 TODO Check the payment status is Completed Check that txn_id has not been previously processed Check that receiver email is your Primary PayPal email Check that payment _amount payment currency are correct Process payment If VERIFIED send an email of IPN variables and values to the specified email address foreach _POST as key gt value Semailtext key value n n mail Semail Live VERIFIED IPN Semailtext nin req else if strcmp res INVALID 0 If INVALID send an email TODO Lo
39. k which is either VERIFIED if the message originated with PayPal or INVALID if there is any discrepancy with what was originally sent Your listener must respond to each message whether or not you intend to do anything with it If you do not respond PayPal assumes that the message was not received and resends the message PayPal continues to resend the message periodically until your listener sends the correct message back although the interval between resent messages increases each time The message can be resent for up to four days This resend algorithm can lead to situations in which PayPal resends the IPN message while you are sending back the original message In this case you should send your response again to cover the possibility that PayPal did not actually receive your response the first time You should also ensure that you do not process the transaction associated with the message twice IMPORTANT PayPal expects to receive a response to an IPN message within 30 seconds Your listener should not perform time consuming operations such as creating a process before responding to the IPN message After PayPal verifies the message there are additional checks that your listener or back end or administrative software must take e Verify that you are the intended recipient of the IPN message by checking the email address in the message this handles a situation where another merchant could accidentally or
40. laimed This is for unilateral payments that are unclaimed unique id x For Mass Payments the unique ID from input where x is the record number This allows the merchant to cross reference the payment Length 13 characters Recurring Payments Variables Recurring payments information identifies the amounts and status associated with recurring payments transactions Variable Name Description amount Amount of recurring payment amount per cycle Amount of recurring payment per cycle initial payment amount Initial payment amount for recurring payments next payment date Next payment date for a recurring payment 52 June 2009 IPN Guide IPN Variable Reference Recurring Payments Variables Variable Name Description IPN Guide outstanding balance payment cycle period type product_name product_type profile status recurring payment id rp invoice id time created Outstanding balance for recurring payments Payment cycle for recurring payments Kind of period for a recurring payment Product name associated with a recurring payment Product name associated with a recurring payment Profile status for a recurring payment Recurring payment ID The merchant s own unique reference or invoice number which can be used to uniquely identify a profile Length 127 single byte alphanumeric characters When a recurrng payment was created June 2009 53 54 IPN Variable Reference Recurring Payme
41. ledgement to the message Queued indicates that PayPal is ready to send the message Retrying indicates that message was resent between 1 and 15 times and PayPal continues to be resend the message Disabled indicates that the message will not be resent because the merchant s account has been disabled NOTE If you have requested that PayPal resend the IPN message and the status has not been updated for the attempt resending is appended to the status e g Failed resending e Your server s response to the HTTP POST that delivered the IPN message to your listener For more information about these codes see RFC 2616 Hypertext Transfer Protocol HTTP 1 1 e Ifthe message is related to a PayPal transaction the ID of the PayPal transaction associated with the message you can To see more information about an IPN message click on the message ID The IPN details page appears 32 June 2009 IPN Guide PayPal IPN Operations on PayPal Resending IPN Messages Lea oA Helo Security Center My Account Send Money Request Money Merchant Services Products amp Services Shopping Instant Payment Notification IPN details Message lO 00001643ML211863U Datenime created 5 25 2009 12 59 PDT OriginavResent Resent Latest delivery attempt datetime 5 25 2009 12 59 PDT Notification URL mip410 244 180 155 8090 pn testphp HTTP response code 200 Deliverystatus Sent No ofretries O Transaction ID 134FR 17 IPN ype Transaction m
42. les that are never presented to your customer Length 255 characters Message s version number In the case of a refund reversal or canceled reversal this variable contains the txn id of the original transaction while txn id contains a new ID for the new transaction Length 19 characters 42 June 2009 IPN Guide IPN Variable Reference E Buyer Information Variables Variable Name Description receiver email Primary email address of the payment recipient that is the merchant If the payment is sent to a non primary email address on your PayPal account the receiver email is still your primary email NOTE The value of this variable is normalized to lowercase characters Length 127 characters receiver id Unique account ID of the payment recipient i e the merchant This is the same as the recipient s referral ID Length 13 characters resend Whether this IPN message was resent equals true otherwise this is the original message residence country ISO 3166 country code associated with the country of residence Length 2 characters test ipn Whether the message is a test message It is one of the following values e 1 the message is directed to the Sandbox txn id The merchant s original transaction identification number for the payment from the buyer against which the case was registered txn type The kind of transaction for which the IPN message was sent verify sign Encrypted string used t
43. more information about these codes see RFC 2616 Hypertext Transfer Protocol HTTP 1 1 If you do not see a response code you should check that your sever is running IPN Guide June 2009 35 a IPN Operations on PayPal Resending IPN Messages 36 June 2009 IPN Guide IPN Guide Using Fraud Management Filters With IPN Fraud Management Filter actions are reported in IPN payment messages only when a filter causes the payment to be pended awaiting your review or a when you accept or deny a filter pended payment Filter actions are not reported when filters flag payments for review allow payments to be accepted or cause them to be denied When a payment occurs an IPN message shows the transaction s payment status as Completed regardless of whether a Fraud Management Filter was activated or not There is no special notification for transactions that are flagged by a Fraud Management Filter If a Fraud Management Filter is set to Deny PayPal does not send an IPN message when the filter actually causes the payment to be denied When a transaction is pended however PayPal sends an IPN message containing one or more fraud management pending filters nvariables which identify the filters that caused the payment to be pended where n 1 specifies the first filter and so on In addition the payment status variable is set to Pending The following example shows an IPN message in which two filters cause the transaction to be pend
44. nts Variables Summary of recurring payment variables Variables Profile created message Recurring payment message Basic Information business receiver email X receiver id Transaction Information payment status payment type payment date txn id initial payment status X initail payment txn id txn type created Currency and Exchange mc gross mc fee mc currency payment gross currency code X payment fee Buyer Information first name X last_name X address_name address_street address_city address_state address_zip address_country payer email X June 2009 recurring payment profile Mox Mox KM XK X recurring_payment x eM K KM x XX MK MK KM KM x IPN Guide IPN Variable Reference Subscription Variables Variables Profile created message Recurring payment message payer id payer status residence country address country code address status Recurring Payment recurring payment id rp invoice id product name product type period type payment cycle outstanding balance amount per cycle initial payment amount profile status amount time created next payment date Other Information notify version charset X X X XX wm KR KK mM KM KK x x OK gt lt X XX Mm KR KK mM KK KOK x A x XxX xo x gt lt Subscription Variables Subscription information identifies the amounts and parameters associated with subscription tran
45. nts are completed returned Format HH MM SS DD Mmm YY YYYY PST Length 28 characters IPN Guide June 2009 51 E IPN Variable Reference Recurring Payments Variables Variable Name Description payment status Completed For Mass Payments this means that all of your payments have been claimed or after a period of 30 days unclaimed payments have been returned to you Denied For Mass Payments this means that your funds were not sent and the Mass Payment was not initiated This may have been caused by lack of funds Processed Your Mass Payment has been processed and all payments have been sent reason_code This variable is only set if status Failed 1001 Invalid UserID 1003 Country of Residence check failure 1004 Country of Funding Source check failure receiver email x For Mass Payments the primary email address of the payment recipient where x is the record number of the mass pay item Length 127 characters status X For Mass Payments the status of the payment where x is the record number Completed The payment has been processed regardless of whether this was originally a unilateral payment Failed The payment failed because of insufficient PayPal balance Returned Payment has been returned after 30 days Reversed This is for unilateral payments that were not claimed after 30 days and have been returned to the sender Or the funds have been returned because the Receivers account was locked Unc
46. o validate the authenticity of the transaction Buyer Information Variables Buyer information identifies the buyer or initiator of a transaction by payer ID or email address Additional contact or shipping information may be provided Variable Name Description address country Country of customer s address Length 64 characters address city City of customer s address Length 40 characters address country code ISO 3166 country code associated with customer s address Length 2 characters address name Name used with address included when the customer provides a Gift Address Length 128 characters address state State of customer s address Length 40 characters IPN Guide June 2009 43 44 IPN Variable Reference Payment Information Variables Variable Name Description address status address street address zip contact_phone first name last name payer business name payer email payer id Whether the customer provided a confirmed address It is one of the following values e confirmed Customer provided a confirmed address e unconfirmed Customer provided an unconfirmed address Customer s street address Length 200 characters Zip code of customer s address Length 20 characters Customer s telephone number Length 20 characters Customer s first name Length 64 characters Customer s last name Length 64 characters Customer s company name
47. o you from PayPal and request that messages be resent You can select the IPN messages to review by date range by delivery status and by PayPal transaction Loa Gut Helo Security Center Search PayPal a My Account Send Money Request Money Merchant Services Products amp Services Shopping Overiew AddFunds Withdraw History Resolution Center Profile Instant Payment Notification IPN history Select search criteria below to display search results A maximum of 1 000 IPN messages will be displayed Search Dates Range must be within the past 28 days Last 5 days C From ES To Es Delivery status AMI default Transaction ID Search results Datetimo created Message ID Status HTTP response code Transaction ID 512512009 12 59 POT C1 ODDO1643Mi 211 863U Sent 200 28105134FR0233917 512512009 12 57 POT 62HE9S7 10376742 Failed 25 results per page Resent The search results contain the following information e The date and time that PayPal created the IPN message IPN Guide June 2009 31 aa IPN Operations on PayPal Using the IPN History e Whether this IPN message was the original message or whether it was resent which is indicated by the asterisk in the Date time created column e The IPN message ID assigned by PayPal e The current status which is one of the following values Sent indicates that PayPal sent the message to your IPN listener Failed indicates that PayPal did not receive an acknow
48. ond simply using the IPN simulator The IPN simulator only sends IPN messages to a listener it does not perform the complete operation for example it does not complete a transaction Sandbox testing involves performing the same actions in the Sandbox as you expect to be performed when the listener goes live After you log in follow these instructions to set up your listener 1 Click Profile on the My Account tab 2 Click Instant Payment Notification Preferences in the Selling Preferences column 3 Click Edit IPN Settings to specify your listener s URL and activate the listener The following screen appears IPN Guide June 2009 23 E Identifying Your IPN Listener to PayPal Setting Up IPN Notifications on PayPal PayPal My Account Send Money Request Money Merchant Services Products amp Services Shopping Edit Instant Payment Notification IPN settings Back to Profile Summary PayPal sends IPN messages to the URL thal you specify below To start receiving IPN messages enter the nodfication URL and select Receive IPN messages below To temporarily stop recetving IPN messages select Do not receive IPN messages below PayPal continues to generate and store IPN messages until you selec Receive IPN messages again or turn off IPN Notification URL IPN messages O Receive IPN messages Enabled Do not receive IPN messages Disabled Save Cancel 4 Specify the URL for your listener in the Notification URL field 5 Click R
49. ramming language of your choice and host it on your web server You can use sample code provided by PayPal as a starting point The PayPal SDKs for Website Payments Standard contain sample code in various programming languages that you can modify to create your own listener As a good programming practice as well as to keep things simple your IPN listener should listen for a post from PayPal and dispatch it immediately to another routine or process that handles the business logic associated with the message If your listener is structured in this way it will be a simple and tight loop that listens for a message and dispatches it for processing by your application logic Your listener software must 1 Wait for an HTTP post from PayPal 2 Create a request that contains exactly the same IPN variables and values in the same order preceded with cmd notify validate 3 Post the request to paypal com or sandbox paypal com depending on whether you are going live or testing your listener in the Sandbox 4 Wait for a response from PayPal which is either VERIFIED or INVALID 5 If the response is VERIFIED perform the following checks Confirm that the payment status is Completed PayPal sends IPN messages for pending and denied payments as well do not ship until the payment has cleared Use the transaction ID to verify that the transaction has not already been processed which prevents duplicate tran
50. receive an INVALID message after responding to the original message from PayPal you will need to troubleshoot your listener IPN Troubleshooting Tips IPN failures fall into three categories not receiving any IPN messages from PayPal receiving some but not all IPN messages and receiving INVALID messages from PayPal after responding to a message If you do not receive any IPN messages from PayPal e Check the IPN History page on PayPal It tells you whether PayPal sent the IPN message and whether your listener responded to it It may also provide information about the status of the server on which your listener is running If necessary from this page you can also request that PayPal resend the IPN message e Check that the path to your IPN listener is correct and you are using that path correctly in your IPN notification URL for example the file path is often similar to but not the same as the URL e Verify that your firewall settings are not blocking HTTP POST messages from PayPal e Ifthe logs for your web server are available check the logs to confirm that messages are being sent to your web server and check for any errors that may have occurred If you receive some messages but not others e Verify that your IPN listener is responding to all messages even those you do not intend to process e Check that the account is valid and confirmed for example if you send money to an uncon
51. riables 22 A 52 Subscription Variables g a R e d K ATE a K N R NN R K T R K dR R N 55 Dispute Resolution Variables 1 LL oaoa a a a a a 59 Payment Review Using Notifications 2 20 20 00 0020 ee ee 60 4 June 2009 IPN Guide Preface This document describes the Instant Payment Notification IPN message service Intended Audience This document is intended for merchants implementing IPN Revision History Revision history for Instant Payment Notification Guide TABLE P 1 Revision History Date Description 06 26 09 Added information about IPN messages related to payment review Updated the section about setting up IPN notifications on PayPal and added a note about the delivery of IPN messages to the notify URL 06 10 09 Added IPN history and resend information and added information to the troubleshooting section 03 16 09 Made additions to sample code 02 16 09 First draft IPN Guide June 2009 E Revision History 6 June 2009 IPN Guide Introducing IPN Instant Payment Notification IPN is a message service that notifies you of events related to PayPal transactions You can use it to automate back office and administrative functions such as fulfilling orders tracking customers and providing status and other information related to a transaction e What is IPN e IPN Protocol and Architecture e A Sample IPN Message and Response e Non IPN Notification Mechanisms
52. s a script or program that you write It waits for messages and passes them to various back end or June 2009 Introducing IPN What is IPN administrative processes that respond the messages PayPal provides sample code that you can modify to implement a listener that detects IPN messages The actions to take when your listener is notified of an event are specific to your needs Examples of the kinds of actions you might take when your listener receives an IPN message include the following e Trigger order fulfillment or enable media downloads when a check clears or a payment is made e Update your list of customers e Update accounting records e Create specialized to do lists based on the kind of event You are typically notified of events by email as well but the IPN message service enables you to automate your response to events The following diagram shows how events can occur and how PayPal responds with IPN messages that it sends to your listener Your customers Your site Website Payments Standard button action a Ces 5 or PayPal API request response O IPN Messages Your IPN Listener Your office Your back office and administrative PayPal API request response t processes i The diagram shows requests and responses which are the result of processing button clicks or API operations on PayPal PayPal sends an IPN message when it sends a response to a request June 2009
53. s 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 Currency of settle amount Shipping charges associated with this transaction Format unsigned no currency symbol two decimal places The name of a shipping method from the Shipping Calculations section of the merchant s account profile The buyer selected the named shipping method for this transaction Amount of tax charged on payment PayPal appends the number of the item e g item namel item name2 The taxx variable is included only if there was a specific tax amount applied to a particular shopping cart item Because total tax may apply to other items in the cart the sum of taxx might not total to tax Authorization and Capture transaction entity Auction Variables Auction information identifies the auction for which a payment is made and additional information about the auction 50 June 2009 IPN Guide IPN Variable Reference E Mass Pay Variables Variable Name Description auction buyer id The customer s auction ID Length 64 characters auction closing date The auction s close date in the following format HH MM SS DD Mmm YY YYYY PST Length 28 characters auction multi item The number of items purchased in multi item auction payments It allows you to count the mc gross or payment
54. sactions Variable Name Description amount1 Amount of payment for trial period 1 for USD payments otherwise blank optional IPN Guide June 2009 55 IPN Variable Reference Subscription Variables Variable Name Description amount2 amount3 mc amountl mc_amount2 mc_amount3 password periodl period2 period3 reattempt recur times recurring retry at subscr date subscr effective subscr id username Amount of payment for trial period 2 for USD payments otherwise blank optional Amount of payment for regular subscription period for USD payments otherwise blank Amount of payment for trial period 1 regardless of currency optional Amount of payment for trial period 2 regardless of currency optional Amount of payment for regular subscription period regardless of currency optional Password generated by PayPal and given to subscriber to access the subscription password will be encrypted Length 24 characters optional Trial subscription interval in days weeks months years example a 4 day interval is period1 4 D optional Trial subscription interval in days weeks months or years Regular subscription interval in days weeks months or years Indicates whether reattempts should occur upon payment failures 1 is yes blank is no The number of payment installments that will occur at the regular rate Indicates whether regular
55. sactions from being processed Typically you store transaction IDs in a database so that you know you are only processing unique transactions Validate that the receiver s email address is registered to you This check provides additional protection against fraud Verify that the price item description and so on match the transaction on your website This check provides additional protection against fraud IPN Guide June 2009 19 E Implementing an IPN Listener 6 Ifthe verified response passes the checks take action based on the value of the txn_type variable if it exists otherwise take action based on the value of the reason_code variable 7 If the response is INVALID save the message for further investigation A sample test listener using PHP The following listener sends email to the address specified in the ipn email variable as in https your_host live ipn mail php ipn email email address You can use this listener as a starting point for your own listener rather than send email your listener could take action based on the type of transaction 20 June 2009 IPN Guide Implementing an IPN Listener a lt php error reporting E ALL E NOTICE email GET ipn email Sheader Semailtext T Read the post from PayPal and add cmd req cmd notify validate if function exists get_magic_quotes_gpc get magic quotes ex
56. tion of your Profile authorization You set the payment action to Authorization and have not yet captured funds echeck The payment is pending because it was made by an eCheck that has not yet cleared intl The payment is pending because you hold a non U S account and do not have a withdrawal mechanism You must manually accept or deny this payment from your Account Overview multi currency You do not have a balance in the currency sent and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment You must manually accept or deny this payment order You set the payment action to Order and have not yet captured funds paymentreview The payment is pending while it is being reviewed by PayPal for risk unilateral The payment is pending because it was made to an email address that is not yet registered or confirmed upgrade The payment is pending because it was made via credit card and you must upgrade your account to Business or Premier status in order to receive the funds upgrade can also mean that you have reached the monthly limit for transactions on your account verify The payment is pending because you are not yet verified You must verify your account before you can accept this payment other The payment is pending for a reason other than those listed above For more information contact PayPal Customer Service protection eligibility ExpandedSellerProtection Seller is prot
57. to have your IPN listener running at your notification URL however it does not require you to set up the listener in the Profile You must be logged into the Sandbox to use the IPN simulator To set up and send an IPN message using the simulator 1 Select Instant Payment Notification IPN simulator from Test Tools 2 Enter the URL to receive the notification and the kind of notification you want to test on the following screen E NE p AEAT Home Test Accounts Test Email Instant Payment Notification IPN simulator API Credentials serene Select from the transaction types supported to test the Instant Payment Notification IPN festure Enter the URL of the webpage where you wish to receive IPNs and the transaction type for this test Can We Help General information Visit the PayPal Developer to integration questions or to file a support ticket e eCheck complete eCheck declined When you select the kind of transaction that you want to test a form containing test data appears IPN Guide June 2009 27 28 IPN Testing Testing Your Listener 3 Keep or modify the values of fields that you want to include in the IPN By default only populated fields are displayed You can check the Show all fields box to view all fields The simulator does not check the validity of fields that you change PayPal Sandbox ici Sundbux pnn Ieee dica de instant Payment Notification 1PM simulator at vien d
Download Pdf Manuals
Related Search