PayPal Instant Payment Notification - 2004 User Guide

Instant Payment Notiﬁ cation Manual

A hands-on guide to understanding and using Instant Payment Notiﬁ cation

Last Revision: February 12, 2004

PayPal Instant Payment Notification Manual

Notice of Liability

The information in this manual is distributed in an “as is” basis. All information provided in this document is provided with good will. The authors and publishers of this manual are not responsible for loss, or purported loss due to any contents of this publication.

Table of Contents

Introduction to Instant Payment Notiﬁ cation (IPN) 1

IPN in Action 2

Instant Payment Notiﬁ cation

How It Works 5

IPN Variables 5

Restrictions on Field Lengths and Data Types 5

Using IPN

Setting up IPN 13

Notiﬁ cation Validation 13

Specifying Your Notiﬁ cation URL 14

Using IPN with Subscriptions and Recurring Payments

Subscriptions Variables 15

Variables for Each Subscription Type 16

Testing IPN

Using IPN with Multiple Currencies

payment_gross and payment_fee 22

Multi-currency IPN Variables 22

Additional Variables 24

Where to Get Help with IPN

PayPal Help 28

PayPal Developer Discussion Boards 28

Instant Payment Notification Manual

Introduction to Instant Payment Notification (IPN)

Automate online payments with back-end server-to-server integration

PayPal’s Instant Payment Notification (IPN) allows you to integrate PayPal payments with your website’s back-end operations. IPN provides immediate notification and confirmation of PayPal payments you receive, allowing you to:

• Customize your website’s response to customer purchases in real-time.

• Track customers through the notification’s “pass through” variables.

• Automate your fulfillment operations.

• Store transaction information in your own database.

Once you activate IPN, you will receive an IPN when a payment is first sent which will state the status of the payment (Completed or Pending). If the payment was “Pending,” you will receive another IPN when the payment clears, fails, or is denied.

IPN can be seamlessly integrated with each of the PayPal Website Payments solutions (Buy Now Buttons, PayPal Shopping Cart, Subscriptions and Recurring Payments, and Donations), as well as with regular PayPal “Send Money” payments, and lets you focus on selling, not on manually tracking your orders.

Get the most out of your online business today: start using IPN.

Instant Payment Notification Manual

IPN in Action

How IPNs are sent

Step 1: Your buyer comes to your website and clicks on a PayPal Buy Now button to

make a purchase.

Step 2: After your buyer checks the payment details and sends the payment, he will

see a confirmation page, as shown in the following diagram.

Instant Payment Notification Manual

Step 3: At the time the payment is made, PayPal will post a notification to your server

at the URL you specified. All of your customer’s payment information and a piece of encrypted code will be included in this notification.

Step 4: On receiving the notification, your server will send the information, including

the encrypted code, back to a secure PayPal URL. PayPal will authenticate the transaction by checking the encrypted string. This post-back of the IPN data to PayPal prevents “spoofing,” so you can be sure the IPN came from PayPal. Upon verification, PayPal will send your server a “VERIFIED” or “INVALID” response.

Step 5: When you receive a VERIFIED response, you need to perform several checks

before fulfilling the order.

Note: An INVALID response should be treated as suspicious, and should be investigated.

• Confirm that the payment status is Completed, since IPNs are also sent for status types such as Pending or Failed.

• Check that the transaction ID is not a duplicate — this prevents a fraudster from using an old, completed transaction.

• Validate that the receiver_email is truly your account — this prevents the payment from being sent to a fraudster’s account.

• Check other transaction details, such as item number and price, to confirm that the price hasn’t been changed.

Instant Payment Notification Manual

Step 6: After successfully completing the checks, you can update your database with

the IPN data and process the purchase.

Instant Payment Notification Manual

Instant Payment Notification

Back-end server-to-server integration

Instant Payment Notification allows you to integrate your PayPal payments with your website’s back-end operations, so you get immediate notification and authentication of the PayPal payments you receive.

Note: To activate Instant Payment Notification, you will need to go to your Profile to enter the URL at which you would like to receive notification posts. For more information, please refer to the Setting Up IPN section of this document, which begins on page 13.

How It Works

When a customer makes a payment to you or a payment is reversed or refunded, PayPal will post a notification to your server at the URL you specified. Included in this notification will be all of your customer’s payment information (e.g. customer name, payment amount) as well as a piece of encrypted code. When your server receives a notification, it will then post the information, including the encrypted code, back to a secure PayPal URL. PayPal will authenticate the transaction and send confirmation of its validity back to your server.

After you have activated Instant Payment Notification, your server will be sent a notification every time you receive a payment. This notification will be sent as a hidden “FORM POST” to the URL you specified, and will include all of the payment information. The FORM variables for these notifications are listed in the following table.

IPN Variables

The following variables work for all Send Money, Buy Now, PayPal Donations, and PayPal Shopping Cart IPNs. If you are using IPN to receive Subscriptions payment notifications, you will need to support additional variables. Please note that the IPN variables are case-sensitive. Most values are lower-case, but payment_status is non- standard with the first letter capitalized (e.g., Completed). For more information on these additional variables, please refer to the Variables for Each Subscription Type section of this document, which begins on page 17.

Restrictions on Field Lengths and Data Types

IPN posts contain only alphanumeric characters. The maximum field length for each returned field is 127 characters, with the exception of the custom field, which has a maximum length of 255 characters. The unique PayPal Transaction ID will always be 17 characters long.

Instant Payment Notification Manual

Variable Value Description

Basic Information

business

receiver_email

receiver_id

item_name

item_number

Transaction-specific Email address or account ID of the payment

recipient (i.e., the merchant). Equivalent to receiver_email if payment is sent to primary account, and essentially an echo of the business variable passed in the Website Payment button HTML code.

Transaction-specific 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.

Transaction-specific Unique account ID of the payment recipient

(ie., the merchant). This is the same as the receipient’s referral ID.

Transaction-specific 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_name1, item_name2).

Transaction-specific Item number as passed by you, the

merchant. If this is a shopping cart transaction, PayPal will append the number of the item (e.g., item_number1, item_

number2).

quantity

Advanced and Custom Information

invoice

custom

memo

tax

option_name1

option_selection1

Transaction-specific Quantity as entered by your customer or

Transaction-specific Invoice number as passed by you, the

Transaction-specific Custom value as passed by you, the

Transaction-specific Memo as entered by your customer in PayPal

Transaction-specific Amount of tax charged on payment.

Transaction-specific Option 1 name as requested by you.

Transaction-specific Option 1 choice as entered by your customer.

as passed by you, the merchant. if this is a shopping cart transaction, we will append the number of the item (e.g. quantity1, quantity2).

merchant. Your customer is not able to view or edit this. It must be unique per transaction.

merchant. These are pass-through variables that are never presented to your customer

Website Payments note field.

Instant Payment Notification Manual

Variable Value Description

option_name2

option_selection2

Shopping Cart Information

num_cart_items

Transaction Information

payment_status

Transaction-specific Option 2 name as requested by you.

Transaction-specific Option 2 choice as entered by your customer.

Transaction-specific for PayPal Shopping Cart

“Canceled_Reversal” This means a reversal has been canceled;

“Completed” If referring to an initial purchase, this means

“Denied” You, the merchant, denied the payment.

“Failed” The payment has failed. This will only

If this is a PayPal Shopping Cart transaction, number of items in cart.

for example, you, the merchant, won a dispute with the customer and the funds for the transaction that was reversed have been returned to you.

the payment has been completed and the funds have successfully been added to your account balance.

This will only happen if the payment was previously pending due to one of the following pending reasons.

happen if the payment was made from your customer’s bank account.

“Pending” The payment is pending; see the pending_

reason variable for more information. Please note, you will receive another Instant Payment Notification when the status of the payment changes to "Completed," "Failed," or "Denied."

“Refunded” You, the merchant, refunded the payment.

"Reversed" This means that 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 customer. The reason for the reversal is given by the reason_code variable.

+ 21 hidden pages