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 Notifi cation (IPN) 1
IPN in Action 2
Instant Payment Notifi cation
How It Works 5
IPN Variables 5
Restrictions on Field Lengths and Data Types 5
Using IPN
Setting up IPN 13
Notifi cation Validation 13
Specifying Your Notifi 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.
Copyright 2004 PayPal, Inc. All rights reserved
1
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.
Copyright 2004 PayPal, Inc. All rights reserved
2
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.
Copyright 2004 PayPal, Inc. All rights reserved
3
Instant Payment Notification Manual
Step 6: After successfully completing the checks, you can update your database with
the IPN data and process the purchase.
Copyright 2004 PayPal, Inc. All rights reserved
4
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.
Copyright 2004 PayPal, Inc. All rights reserved
5
Instant Payment Notification Manual
VariableValueDescription
Basic Information
business
receiver_email
receiver_id
item_name
item_number
Transaction-specificEmail 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-specificPrimary 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-specificUnique account ID of the payment recipient
(ie., the merchant). This is the same as the
receipient’s referral ID.
Transaction-specificItem 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-specificItem 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-specificQuantity as entered by your customer or
Transaction-specificInvoice number as passed by you, the
Transaction-specificCustom value as passed by you, the
Transaction-specificMemo as entered by your customer in PayPal
Transaction-specificAmount of tax charged on payment.
Transaction-specificOption 1 name as requested by you.
Transaction-specificOption 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.
Copyright 2004 PayPal, Inc. All rights reserved
6
Instant Payment Notification Manual
VariableValueDescription
option_name2
option_selection2
Shopping Cart Information
num_cart_items
Transaction Information
payment_status
Transaction-specificOption 2 name as requested by you.
Transaction-specificOption 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.
Copyright 2004 PayPal, Inc. All rights reserved
7
Instant Payment Notification Manual
VariableValueDescription
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 you, the merchant,
have your Payment Receiving Preferences
set such that you want to manually accept
or deny each of these payments. To change
your preference, go to the Preferences
section of your Profile.
“echeck”The payment is pending because it was made
by an eCheck, which has not yet cleared.
“intl”The payment is pending because you, the
merchant, hold a non-U.S. account and do
not have a withdrawal method. 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.
“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, the merchant, must
upgrade your account to Business or Premier
status in order to receive the funds. You
could also get this status because you, the
merchant, have reached the monthly limit for
transactions on your account.
“verify”The payment is pending because you, the
merchant, 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 customer service
at https://www.paypal.com/cgi-bin/
webscr?cmd=_contact-general.
Copyright 2004 PayPal, Inc. All rights reserved
8
Instant Payment Notification Manual
VariableValueDescription
reason_code
payment_date
txn_id
This variable is only set if payment_status = "Reversed" or
“Refunded”.
“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.
“guarantee”A reversal has occurred on this transaction
due to your customer triggering a moneyback guarantee.
“refund”A reversal has occurred on this transaction
because you have given the customer a
refund.
“other”A reversal has occurred on this transaction
for a reason other than those previously
listed.
Transaction-specificTime/Date stamp generated by PayPal
system [format: “18:30:30 Jan 1, 2000
PST”]
Transaction-specificA unique transaction ID generated by the
PayPal system.
parent_txn_id
txn_type
payment_type
Transaction-specificIn the case of a refund, reversal, or canceled
reversal, this variable contains the txn_id of
the original transation, while txn_id contains
a new ID for the new transaction.
“cart”This payment was sent by your customer via
the PayPal Shopping Cart.
“send_money”This payment was sent by your customer
from the PayPal website, using the Send Money tab.
“web_accept”The payment was sent by your customer
via Buy Now Buttons, Donations, or Smart
Logos.
“echeck”This payment was funded with an eCheck.
“instant”This payment was funded with PayPal
balance, credit card, or Instant Transfer.
Copyright 2004 PayPal, Inc. All rights reserved
9
Instant Payment Notification Manual
VariableValueDescription
Currency and Exchange Information
mc_gross
mc_fee
mc_currency
Transactionspecific for Multiple
Currencies
Transactionspecific for Multiple
Currencies
For payment IPNs, this is the currency of the payment. For nonpayment subscription IPNS, this is the currency of the subscription.
“USD”The currency of the payment is U.S. Dollars.
“GBP”The currency of the payment is Pounds
“USD”The currency of the payment is U.S. Dollars.
“GBP”The currency of the payment is Pounds
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.
Transaction fee associated with the payment.
mc_gross minus mc_fee will equal the
amount deposited into the receiver_email
account. Equivilent 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.
Sterling.
Sterling.
settle_amount
settle_currency
exchange_rate
“EUR”The currency of the payment is Euros.
“CAD”The currency of the payment is Canadian
Dollars.
“JPY”The currency of the payment is Yen.
Transaction-specificAmount 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).
Transactionspecific for Multiple
Currencies
Transactionspecific for Multiple
Currencies
Currency of settle_amount.
Exchange rate used if a currency conversion
occurred.
Copyright 2004 PayPal, Inc. All rights reserved
10
Instant Payment Notification Manual
VariableValueDescription
payment_gross
payment_fee
Auction Information
for_auction
Transaction-specific
for USD payments
only
Transaction-specific
for USD payments
only
“true”This is an auction payment—payments made
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.
USD transaction fee associated with the
payment. payment_gross minus payment_fee will equal the amount deposited into
the receiver email account. Will be empty
for non-USD payments. This is a legacy
field replaced by mc_fee. 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.
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).
auction_buyer_id
auction_closing_
date
auction_multi_item
Buyer Information
first_name
last_name
payer_business_
name
Transaction-specific
for Auctions
Transaction-specific
for Auctions
Transaction-specific
for Auctions
Transaction-specificCustomer’s first name.
Transaction-specificCustomer’s last name.
Transaction-specificCustomer’s company name.
This is the customer’s auction ID.
This is the auction’s close date.
This is a counter used for multi-item auction
payments. It allows you to cumstomize
your script to only count the mc_gross or payment_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.
Copyright 2004 PayPal, Inc. All rights reserved
11
Instant Payment Notification Manual
VariableValueDescription
address_name
address_street
address_city
address_state
address_zip
address_country
address_status
payer_email
payer_id
payer_status
IPN Information
notify_version
Transaction-specificName used with address (Included when the
customer provides a Gift Address).
Transaction-specificCustomer’s street address.
Transaction-specificCity of customer’s address.
Transaction-specificState of customer’s address.
Transaction-specificZip code of customer’s address.
Transaction-specificCountry of customer’s address.
“confirmed” Customer provided a confirmed address.
“unconfirmed”Customer provided an unconfirmed address.
Transaction-specificCustomer’s primary email address. Use this
email to provide any credits.
Transaction-specificUnique customer ID.
“verified” Customer has a Verified PayPal account.
“unverified” Customer has an Unverified PayPal account.
“1.6”The version of the Instant Payment
Notification you are using.
Security Information
verify_sign
Transaction-specificAn encrypted string used to validate the
authenticity of the transaction.
Copyright 2004 PayPal, Inc. All rights reserved
12
Instant Payment Notification Manual
Using IPN
Getting set up to use IPN and validate notifications
Setting up IPN
To set up IPN:
1. Log in to your Business or Premier PayPal account.
2. Click the Profile subtab.
3. Click on the Instant Payment Notification Preferences link in the Selling Preferences column.
4. Click Edit.
5. Click the checkbox and enter the URL at which you would like to receive your
IPN Notifications.
6. Click Save.
Notification Validation
To ensure that a payment has been made into your PayPal account, you must
verify that the email address used as your receiver_email has been registered and
confirmed in your PayPal account.
Once your server has received the Instant Payment Notification, you will need to
confirm it by constructing an HTTP POST to PayPal. Your POST should be sent to
https://www.paypal.com/cgi-bin/webscr. This post-back of the IPN data to a secure
PayPal URL (i.e., https://) prevents 'spoofing,' so you can be sure that the IPN came
from PayPal.
Note: It is possible to implement IPN without SSL (i.e., http://), but then the IPN
data that is received and posted back is not secure.
You must post all of the form variable you received exactly as you received them. You
will also need to append a variable named cmd with the value _notify-validate
(e.g., cmd=_notify-validate) to the POST string.
PayPal will respond to the post with a single word, “VERIFIED” or “INVALID,” in the
body of the response.
Copyright 2004 PayPal, Inc. All rights reserved
13
Instant Payment Notification Manual
When you receive a VERIFIED response, perform the following checks:
1. Check that the payment_status is Completed.
2. If the payment_status is Completed, check the txn_id against the previous
PayPal transaction you have processed to ensure it is not a duplicate.
3. After you have checked the payment_status and txn_id, make sure the
receiver_email is an email address registered in your PayPal account.
4. Check that the price, mc_gross, and currency, mc_currency, are correct for the
item, item_name or item_number.
5. (Optional) To be 100% certain of the authenticity of this tranasaction, you can
check PayPal’s digital certificate if you are using SSL:
Once you have completed the above checks, you may update your database based on
the information provided.
If you receive an INVALID response, you should investigate. In some cases, this
response is caused by an IPN error, possibly from a change in the IPN format. To
determine if it is an IPN error, first examine your code. If you need further assistance,
go to http://www.paypal.com/wf/Payment Notification (IPN).
, click the Seller Tools topic, and then click Instant
Specifying Your Notification URL
If you only need to receive your IPNs at a single URL, you can enter that URL in the
Preferences section of your Profile.
If you would like to receive payment notifications for different payments at different
URLS (i.e. if you need to separate payments made to different websites you run), you
can manually pass the IPN URL with each payment by including it in that payment’s
HTML code. Use the notify_url field to pass this information.
The notify_url for a specific payment will be saved, and any subsequent updates to
that payment (e.g. cleared eCheck) will be sent to that notify_url. When you pass a
notify_url in your HTML code, it will override any preferences you set in your Profile.
Copyright 2004 PayPal, Inc. All rights reserved
14
Instant Payment Notification Manual
Using IPN with Subscriptions and Recurring
Payments
Additional information if you receive PayPal Subscriptions
payments
Subscriptions Variables
In addition to the variables listed in the previous table, the following variables are
included in Subscriptions IPNs:
VariableValueDescription
txn_type
subscr_date
subscr_effective
period1
period2
period3
amount1
“subscr_signup”This IPN is for a subscription sign-up.
“subscr_cancel”This IPN is for a subscription cancellation.
“subscr_failed”This IPN is for a subscription payment failure.
“subscr_payment”This IPN is for a subscription payment.
“subscr_eot”This IPN is for a subscription’s end-of-term.
“subscr_modify”This IPN is for a subscription modification.
Transaction-specificStart date or cancellation date depending on
whether transaction is subscr_signup or subscr_cancel.
Transaction-specificDate when the subscription modification will be
effective (only for txn_type = subscr_modify).
Transaction-specific(optional) Trial subscription interval in days,
weeks, months, years (example: a 4 day interval
is “period1: 4 D”).
Transaction-specific(optional) Trial subscription interval in days,
weeks, months, or years.
Transaction-specificRegular subscription interval in days, weeks,
months, or years.
Transaction-specificAmount of payment for trial period 1 for USD
payments; otherwise blank (optional).
amount2
amount3
mc_amount1
mc_amount2
Copyright 2004 PayPal, Inc. All rights reserved
Transaction-specificAmount of payment for trial period 2 for USD
Transaction-specificAmount of payment for regular subscription
Transaction-specificAmount of payment for trial period 1, regardless
Transaction-specificAmount of payment for trial period 2, regardless
payments; otherwise blank (optional).
period for USD payments; otherwise blank.
of currency (optional).
of currency (optional).
15
Instant Payment Notification Manual
VariableValueDescription
mc_amount3
mc_currency
recurring
reattempt
retry_at
Transaction-specificAmount of payment for regular subscription
period, regardless of currency.
For non-payment subscriptions IPNs (i.e., txn_type = signup, cancel,
failed, eot, or modify), this is the currency of the subscription. For
payment IPNs, it is the currency of the payment (i.e., txn_type = subscr_payment)
“USD”The currency of the subscription is U.S. Dollars.
“GBP”The currency of the subscription is Pounds
Sterling.
“EUR”The currency of the subscription is Euros.
“CAD”The currency of the subscription is Canadian
Dollars.
“JPY”The currency of the subscription is Yen.
Transaction-specificIndicates whether regular rate recurs (1 is yes,
blank is no).
Transaction-specificIndicates whether reattempts should occur upon
payment failures (1 is yes, blank is no).
Transaction-specificDate PayPal will retry a failed subscription
payment.
recur_times
username
password
subscr_id
Transaction-specificThe number of payment installments that will
occur at the regular rate.
Transaction-specific(optional) Username generated by PayPal and
given to subscriber to access the subscription.
Transaction-specific(optional) Password generated by PayPal and
given to subscriber to access the subscription
(password will be hashed).
Transaction-specificID generated by PayPal for the subscriber.
Variables for Each Subscription Type
The following table shows which variables are associated, and may be included, with
each transaction type. Please note that the IPN will only contain variables for which it
has information.
Copyright 2004 PayPal, Inc. All rights reserved
16
Instant Payment Notification Manual
VariableSignupCancelModify
Basic Information
business
receiver_email
receiver_id
item_name
item_number
Advanced and Custom Information
invoice
custom
option_name1
option_selection1
option_name2
option_selection2
Transaction Information
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
XXXX XXX
Payment
(USD)
XX
Payment
(MC)FailedEOT
payment_status
pending_reason
reason_code
payment_date
txn_id
parent_txn_id
txn_type
Currency and Exchange Information
mc_gross
mc_fee
mc_currency
settle_amount
settle_currency
exchange_rate
payment_gross
subscr_
signup
XXXX XXX
subscr_
cancel
subscr_
modify
XX
XX
XX
XX
XX
XX
subscr_payment
XX
XX
XX
XX
XX
XXX
payment_fee
Copyright 2004 PayPal, Inc. All rights reserved
X
17
Instant Payment Notification Manual
VariableSignupCancelModify
Buyer Information
first_name
last_name
payer_business_
name
address_name
address_street
address_city
address_state
address_zip
address_country
address_status
payer_email
payer_id
payer_status
XXXX XXX
XXXX XXX
XXXX X
XXXX X
XXXX X
XXXX X
XXXX X
XXXX X
XXXX X
XXXX XXX
XXXX XXX
XXXX XXX
Payment
(USD)
XX
Payment
(MC)FailedEOT
payment_type
IPN Information
notify_version
Security Information
verify_sign
Subscription Information
subscr_date
subscr_effective
period1
period2
period3
amount1
amount2
amount3
mc_amount1
mc_amount2
XX
XXXX XXX
XXXX XXX
XXX
X
XXX
XXX
XXX
XXX
XXX
XXX
XXX
XXX
Copyright 2004 PayPal, Inc. All rights reserved
18
Instant Payment Notification Manual
VariableSignupCancelModify
mc_amount3
recurring
reattempt
retry_at
recur_times
username
password
subscr_id
XXX
XXX
XXX
XXX
XXXX XXX
XXXX XXX
XXXX XXX
Payment
(USD)
Payment
(MC)FailedEOT
X
Copyright 2004 PayPal, Inc. All rights reserved
19
Instant Payment Notification Manual
Testing IPN
You should always test your IPN implementation with the live PayPal system. Here’s an
easy way to do it:
1. Sign up for a Personal PayPal account if you don’t already have one, and add a
credit card to the account. This will be your “buyer” account.
Note: According to the PayPal User Agreement, you may have one Personal
and one Premier/Business account. Please do not set up any additional
PayPal accounts, as this may result in your account access being limited.
2. Make sure that your Business/Premier account is Verified. This is the account
which uses IPN, your “seller” account.
3. Log in to your buyer account and send money to your seller account, as if you
were making a regular payment. You can send a very small amount, such as
$0.01.
4. Check the results of your IPN test.
5. Log in to your seller account and refund the payment. To refund a payment, go
to the Transaction Details page and click the Refund Payment link at the
bottom. The refund reverses the entire payment, including transaction fees.
Remember that you only have 30 days to refund the payment.
This testing method is free of charge and lets you complete the entire process
yourself. If you would prefer not to open a second PayPal account, you can also have
friends or trusted clients send you test payments, which you can then refund.
Testing tip 1: PayPal recommends you start with one of PayPal’s code samples
available at https://www.paypal.com/ipn under the Code Samples section. There are
code samples for the following development environments.
• ASP/VBScript
• ColdFusion
• Java/JSP
• PERL
• PHP
Copyright 2004 PayPal, Inc. All rights reserved
20
Instant Payment Notification Manual
Testing tip 2: In your Website Payments button HTML code, add or modify the
return and rm variables as follows (replacing the URL with the URL for your website):
Then, from the buyer account, click on the Website Payments button and complete
the transaction. Once you get to the PayPal Payment Complete page, you can use
your browser's View Source function to view the values of the posted IPN variables at
the bottom of the code.
Testing tip 3: You can put debugging print statements into your IPN script. PayPal
recommends creating a debugging mode of your script that you can turn off and on
by commenting or uncommenting a variable. Set the return variable in your Website Payments button HTML code to point to your IPN URL. When you complete the
payment, the output of your script’s print statements will be sent to your browser.
Copyright 2004 PayPal, Inc. All rights reserved
21
Instant Payment Notification Manual
Using IPN with Multiple Currencies
With multiple currencies, you can accept payments in U.S. Dollars, Canadian Dollars,
Euros, Pounds Sterling, and Yen. As a result, your IPNs will then include information
about the currency of the payment. The following overview explains how IPN interacts
with multiple currencies.
Note: If you are using one of PayPal’s Website Payments solutions (e.g. PayPal
Shopping Cart), and would like to be paid in a currency other than U.S. Dollars,
you will need to set up your buttons for your currency of choice. For additional
information, please refer to the PayPal website or the manual for your PayPal
Website Payments Solution.
payment_gross and payment_fee
These variables reflect the amount received and corresponding fee of U.S. Dollar
(USD) payments. If the amount received and fee deducted are in a currency other
than USD, the variables will still appear in your IPN, but will have no values in them.
Note:payment_fee is not always present in IPNs, such as when a payment is
pending.
These values are absent for non-USD payments so that IPN scripts will not process
these amounts as USD. This will intentionally break IPN scripts that do not handle
Multiple Currencies payments if they receive a non-USD payment. However, legacy
IPN scripts will continue to work as before as long as the merchant only receives USD
payments.
Multi-currency IPN Variables
IPNs that use the payment_gross variable will have the following multi-currency
variables added. The variables mc_gross and mc_fee will not be added to IPNs with
txn_type: subscr_signup, subscr_cancel, subscr_modify, subscr_failed, or
subscr_eot.
• mc_gross: Full amount of payment received, before transaction fee.
Note: If payment is in USD, the payment_gross value will equal mc_gross.
• mc_fee: Transaction fee associated with the payment. Variable should function
like “payment_fee” variable (variable does not appear when payment pending,
and so on).
Copyright 2004 PayPal, Inc. All rights reserved
22
Instant Payment Notification Manual
Note: If payment is in USD, the payment_fee value will equal mc_fee.
• mc_currency: Currency of mc_gross, mc_fee, payment_gross, and payment_
fee amounts. The values are (note the capitalization):
– USD
– EUR
– GBP
– CAD
– JPY
For non-payment subscription IPNs, such as signup, cancel, modify, failed, and
eot, mc_currency will refer to the currency of the subscription, rather than the
currency of the payment.
For payment subscription IPNs, mc_currency will refer to the currency of the
payment. Examples 1 & 2 below refer to subscr_payment IPNs.
Example 1: If a user with a USD balance receives a $100 USD payment, the following
variables will be used for the payment:
• mc_gross = payment_gross
• mc_fee = payment_fee
Example 1: USD Payment (subscr_payment IPN)
payment_status = Completed
payment_gross = 100
payment_fee = 3.00
mc_gross = 100
mc_fee = 3.00
mc_currency = USD
Copyright 2004 PayPal, Inc. All rights reserved
23
Instant Payment Notification Manual
Example 2: If a user with a CAD balance receives a $100 CAD payment, the following
variables will be used for the payment:
• mc_gross and mc_fee have values
• payment_gross and payment_fee are blank
Example 2: CAD Payment (subscr_payment IPN)
payment_status = Completed
payment_gross =
payment_fee =
mc_gross =100
mc_fee = 3.00
mc_currency = CAD
Additional Variables
IPNs for payments that are either manually or automatically converted into the
primary currency of the account will include the following three new variables with
information on the conversion:
• settle_amount: Amount that is deposited into the user’s primary balance after
the conversion occurs.
• settle_currency: Currency of settle_amount.
• exchange_rate: Exchange rate used if a conversion transaction occurs.
• pending_reason: In addition, payments that are “pending” because the balance
needs to be manually accepted, either because the account does not currently
have a balance in that currency or because automatic conversion is not turned
on, will have a new IPN pending_reason: pending_reason = multi_currency.
Copyright 2004 PayPal, Inc. All rights reserved
24
Instant Payment Notification Manual
Example 3: If the account is set to automatically convert payments, these variables
will be used to show the conversion. This example is for a user with a USD balance
who receives a payment of 100 GBP:
Example 3: Automatic Conversion of GBP Payment
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
mc_currency = GBP
settle_amount = 145.5
settle_currency = USD
exchange_rate = 1.5
Example 4: If a payment received is pending due to pending_reason = multi_
currency, the first IPN received would not have the settle_amount, settle_
currency, or exchange_rate.
Example 4: Pending Payment
payment_status = Pending
pending_reason = multi_currency
payment_gross =
mc_gross = 100
mc_currency = GBP
Copyright 2004 PayPal, Inc. All rights reserved
25
Instant Payment Notification Manual
The second IPN would contain information about settling the payment. If the payment
is accepted into the account’s primary currency, which is USD in the following
example:
Example 5: Pending - Convert to Primary Currency
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
mc_currency = GBP
settle_amount = 145.5
settle_currency = USD
exchange_rate = 1.5
If the payment is accepted into a balance of the same currency:
Example 6: Pending - Accept to Currency Balance
payment_status = Completed
payment_gross =
payment_fee =
mc_gross = 100
mc_fee = 3.00
mc_currency = GBP
Copyright 2004 PayPal, Inc. All rights reserved
26
Instant Payment Notification Manual
If the payment is denied:
Example 7: Pending - Deny
payment_status = Denied
payment_gross =
mc_gross = 100
mc_currency = GBP
Note: If a user receives a payment into a currency balance and later converts
this amount into another currency balance, the corresponding currency conversion
transaction has no IPN.
Copyright 2004 PayPal, Inc. All rights reserved
27
Instant Payment Notification Manual
Where to Get Help with IPN
PayPal Help
If you need further assistance, go to http://www.paypal.com/wf/, click the Seller
Tools topic, and then click Instant Payment Notification (IPN).
PayPal Developer Discussion Boards
You can also check the PayPal Developer Discussion Boards at
http://www.paypaldev.org for help
Copyright 2004 PayPal, Inc. All rights reserved
28
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.