IPN and PDT Variables

PayPal returns related variables for each kind of IPN or PDT message. Not all variables are returned for each type of transaction.

IPN and PDT variable names are case-sensitive. All constant values are lowercase, except those for payment_status, whose constant values have an initial capital letter.

Note: Values posted by IPN are URL-encoded. For example, a colon in the value http://... is encoded as %3A in an IPN post, as in http%3A//...

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 if the 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 Shopping Cart.
express_checkout Payment received for a single item; source is Express Checkout
masspay Payment sent using Mass Pay
merch_pmt Monthly subscription paid for PayPal Payments Pro
mp_cancel Billing agreement cancelled
mp_signup Created a billing agreement
new_case A new dispute was filed
payout A payout related to a global shipping transaction was completed.
pro_hosted Payment received; source is Website Payments Pro Hosted Solution.
recurring_payment Recurring payment received
recurring_payment_expired Recurring payment expired
recurring_payment_failed

Recurring payment failed
This transaction type is sent if:

  • The attempt to collect a recurring payment fails
  • The "max failed payments" setting in the customer's recurring payment profile is 0
    In this case, PayPal tries to collect the recurring payment an unlimited number of times without ever suspending the customer's recurring payments profile.
recurring_payment_profile_cancel Recurring payment profile canceled
recurring_payment_profile_created Recurring payment profile created
recurring_payment_skipped Recurring payment skipped; it will be retried up to 3 times, 5 days apart
recurring_payment_suspended Recurring payment suspended
This transaction type is sent if PayPal tried to collect a recurring payment, but the related recurring payments profile has been suspended.
recurring_payment_suspended_due_to_max_failed_payment Recurring payment failed and the related recurring payment profile has been suspended
This transaction type is sent if:
  • PayPal's attempt to collect a recurring payment failed
  • The "max failed payments" setting in the customer's recurring payment profile is 1 or greater
  • the number of attempts to collect payment has exceeded the value specified for "max failed payments"
    In this case, PayPal suspends the customer's recurring payment profile.
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 payment 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 any of the following:
  • A Direct Credit Card (Pro) transaction
  • A Buy Now, Donation or Smart Logo for eBay auctions 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 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
charset Character set
custom Custom value as passed by you, the merchant. These are pass-through variables that are never presented to your customer
Length: 255 characters
ipn_track_id Internal; only for use by MTS and DTS
notify_version Message's version number
parent_txn_id 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
receipt_id Unique ID generated during guest checkout (payment by credit card without logging in).
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:
  • 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 to 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
address_status Whether the customer provided a confirmed address. It is one of the following values:
  • confirmed – Customer provided a confirmed address.
  • unconfirmed – Customer provided an unconfirmed address.
address_street Customer's street address.
Length: 200 characters
address_zip Zip code of customer's address.
Length: 20 characters
contact_phone Customer's telephone number.
Length: 20 characters
first_name Customer's first name
Length: 64 characters
last_name Customer's last name
Length: 64 characters
payer_business_name Customer's company name, if customer is a business
Length: 127 characters
payer_email Customer's primary email address. Use this email to provide any credits.
Length: 127 characters
payer_id 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 Authorization amount
auth_exp Authorization expiration date and time, in the following format: HH:MM:SS DD Mmm YY, YYYY PST
Length: 28 characters
auth_id Authorization identification number
Length: 19 characters
auth_status Status of authorization
echeck_time_processed The time an eCheck was processed; for example, when the status changes to Success or Completed. The format is as follows: hh:mm:ss MM DD, YYYY ZONE, e.g. 04:55:30 May 26, 2011 PDT.
exchange_rate Exchange rate used if a currency conversion occurred.
fraud_managment_pending_filters_x One or more filters that identify a triggering action associated with one of 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:
  • 1 - 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 - 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 Pass-through 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_name1, item_name2, and so forth).
Length: 127 characters
item_numberx 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. If this is a shopping cart transaction, PayPal will append the number of the item (e.g., item_number1, item_number2, and so forth)
Length: 127 characters
mc_currency
  • For payment IPN notifications, this is the currency of the payment.
  • For non-payment subscription IPN notifications (i.e., txn_type= signup, cancel, failed, eot, or modify), this is the currency of the subscription.
  • For payment subscription IPN notifications, it is the currency of the payment (i.e., txn_type = subscr_payment)
mc_fee Transaction fee associated with the payment. mc_gross minus mc_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.
mc_gross 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.
mc_gross_x The amount is in the currency of mc_currency, where x is the shopping cart detail item number. The sum of mc_gross_x should total mc_gross.
mc_handling Total handling amount associated with the transaction.
mc_shipping Total shipping amount associated with the transaction.
mc_shippingx 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 Memo as entered by your customer in PayPal Website Payments note field.
Length: 255 characters
num_cart_items If this is a PayPal Shopping Cart transaction, number of items in cart.
option_name1 Option 1 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_name1, option_name2).
Length: 64 characters
option_name2 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_selection1 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_selection1, option_selection2).
Length: 200 characters
option_selection2 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_selection1, option_selection2).
Length: 200 characters
payer_status Whether the customer has a verified PayPal account.
  • verified – Customer has a verified PayPal account.
  • unverified – Customer has an unverified PayPal account.
payment_date Time/Date stamp generated by PayPal, in the following format: HH:MM:SS Mmm DD, YYYY PDT
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 reversal, 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. Use mc_fee instead.
payment_fee_x If the payment is USD, then the value is the same as that for mc_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. Use mc_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.
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: A German ELV payment is made using Express Checkout.

Denied: The payment was denied. This happens only if the payment was previously pending because of one of the reasons listed 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.
pending_reason

This variable is set only if payment_status is 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 section 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 profiles's Payment Receiving Preferences option set to automatically convert and accept this payment. As a result, 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 reviewed by PayPal for risk.

regulatory_review: The payment is pending because PayPal is reviewing it for compliance with government regulations. PayPal will complete this review within 72 hours. When the review is complete, you will receive a second IPN message whose payment_status/reason code variables indicate the result.

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 before you can 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 protected 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. quantity1, quantity2).
reason_code

This variable is set if payment_status is Reversed, Refunded, Canceled_Reversal, or Denied.

adjustment_reversal: Reversal of an adjustment.

admin_fraud_reversal: The transaction has been reversed due to fraud detected by PayPal administrators.

admin_reversal: The transaction has been reversed by PayPal administrators.

buyer-complaint: The transaction has been reversed due to a complaint from your customer.

chargeback: The transaction has been reversed due to a chargeback by your customer.

chargeback_reimbursement: Reimbursement for a chargeback.

chargeback_settlement: Settlement of a chargeback.

guarantee: The transaction has been reversed because your customer exercised a money-back guarantee.

other: Unspecified reason.

refund: The transaction has been reversed because you gave the customer a refund.

regulatory_block: PayPal blocked the transaction due to a violation of a government regulation. In this case, payment_status is Denied.

regulatory_reject: PayPal rejected the transaction due to a violation of a government regulation and returned the funds to the buyer. In this case, payment_status is Denied.

regulatory_review_exceeding_sla: PayPal did not complete the review for compliance with government regulations within 72 hours, as required. Consequently, PayPal auto-reversed the transaction and returned the funds to the buyer. In this case, payment_status is Denied. Note that "sla" stand for "service level agreement".

unauthorized_claim: The transaction has been reversed because it was not authorized by the buyer.

unauthorized_spoof: The transaction has been reversed due to a customer dispute in which an unauthorized spoof is suspected.

Note: Additional codes may be returned.
remaining_settle Remaining amount that can be captured with Authorization and Capture
settle_amount Amount that is deposited into the account's primary balance after a currency conversion from automatic conversion (through your Payment Receiving Preferences) or manual conversion (through manually accepting a payment).
settle_currency Currency of settle_amount.
shipping Shipping charges associated with this transaction.
Format: unsigned, no currency symbol, two decimal places.
shipping_method 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.
tax Amount of tax charged on payment. PayPal appends the number of the item (e.g., item_name1, 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.
transaction_entity Authorization and Capture transaction entity

Auction Variables

Auction information identifies the auction for which a payment is made and additional information about the auction.

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_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. Format: HH:MM:SS DD Mmm YYYY PST
Length: 28 characters
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_x

This variable is set only if status = Failed.
1001 Receiver's account is invalid
1002 Sender has insufficient funds
1003 User's country is not allowed
1004 User's credit card is not in the list of allowed countries of the gaming merchant
3004 Cannot pay self
3014 Sender's account is locked or inactive
3015 Receiver's account is locked or inactive
3016 Either the sender or receiver exceeded the transaction limit
3017 Spending limit exceeded
3047 User is restricted
3078 Negative balance
3148 Receiver's address is in a non-receivable country or a PayPal zero country
3535 Invalid currency
3547 Sender's address is located in a restricted State
3558 Receiver's address is located in a restricted State
3769 Market closed and transaction is between 2 different countries
4001 Internal error
4002 Internal error
8319 Zero amount
8330 Receiving limit exceeded
9302 Transaction was declined
11711 Per-transaction sending limit exceeded
14159 Transaction currency cannot be received by the recipient
14550 Currency compliance
14764 Regulatory review - Pending
14765 Regulatory review - Blocked
14767 Receiver is unregistered
14768 Receiver is unconfirmed
14769 Youth account recipient
14800 POS cumulative sending limit exceeded

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 an insufficient PayPal balance.
Returned: When an unclaimed payment remains unclaimed for more than 30 days, it is returned to the sender.
Reversed: PayPal has reversed the transaction.
Unclaimed: This is for unilateral payments that are unclaimed.
Pending: The payment is pending because it is being reviewed for compliance with government regulations. The review will be completed and the payment status will be updated within 72 hours.
Blocked: This payment was blocked due to a violation of government regulations.
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
outstanding_balance Outstanding balance for recurring payments
payment_cycle Payment cycle for recurring payments
period_type Kind of period for a recurring payment
product_name Product name associated with a recurring payment
product_type Product name associated with a recurring payment
profile_status Profile status for a recurring payment
recurring_payment_id Recurring payment ID
rp_invoice_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
time_created When a recurring payment was created
Table 1. Summary of recurring payment variables

Variables

Profile created message

Recurring payment message

Basic Information

business

X
receiver_email X X
receiver_id

X
Transaction Information

payment_status

X
payment_type

X
payment_date

X
txn_id

X
initial_payment_status X

initial_payment_txn_id

X
txn_type recurring_payment_profile_created recurring_payment
Currency and Exchange

mc_gross

X
mc_fee

X
mc_currency

X
payment_gross

X
currency_code X X
payment_fee

X
Buyer Information

first_name X X
last_name X X
address_name

X
address_street

X
address_city

X
address_state

X
address_zip

X
address_country

X
payer_email X X
payer_id X X
payer_status X X
residence_country X X
address_country_code

X
address_status

X
Recurring Payment

recurring_payment_id X X
rp_invoice_id X X
product_name X X
product_type X X
period_type X X
payment_cycle X X
outstanding_balance X X
amount_per_cycle X X
initial_payment_amount X X
profile_status X X
amount X X
time_created X X
next_payment_date X X
Other Information

notify_version X X
charset X X

Subscription Variables

Subscription information identifies the amounts and parameters associated with subscription transactions.

Variable Name

Description

amount1 Amount of payment for trial period 1 for USD payments; otherwise blank (optional).
amount2 Amount of payment for trial period 2 for USD payments; otherwise blank (optional).
amount3 Amount of payment for regular subscription period for USD payments; otherwise blank.
mc_amount1 Amount of payment for trial period 1, regardless of currency (optional).
mc_amount2 Amount of payment for trial period 2, regardless of currency (optional).
mc_amount3 Amount of payment for regular subscription period, regardless of currency.
password (optional) Password generated by PayPal and given to subscriber to access the subscription (password will be encrypted).
Length: 24 characters
period1 (optional) Trial subscription interval in days, weeks, months, years (example: a 4 day interval is "period1: 4 D").
period2 (optional) Trial subscription interval in days, weeks, months, or years.
period3 Regular subscription interval in days, weeks, months, or years.
reattempt Indicates whether reattempts should occur upon payment failures (1 is yes, blank is no).
recur_times The number of payment installments that will occur at the regular rate.
recurring Indicates whether regular rate recurs (1 is yes, blank is no).
retry_at Date PayPal will retry a failed subscription payment.
subscr_date 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
subscr_effective 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
subscr_id ID generated by PayPal for the subscriber.
Length: 19 characters
username (optional) Username generated by PayPal and given to subscriber to access the subscription.
Length: 64 characters
Table 2. Summary of subscription variables

Variable

Signup

Cancel

Modify

USD Payment

Multi-CurrencyPayment

Re-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_name1 X X X X X

X X
option_selection1 X X X X X

X X
option_name2 X X X X X

X X
option_selection2 X X X X X

X X

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_ signup subscr_ cancel subscr_ modify

subscr_payment

subscr_ failed subscr_eot

Currency and Exchange information

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

payment_gross

X

X X
payment_fee

X

Buyer Information

first_name X X X X X

X X
last_name X X X X X

X X
payer_business_name X X X X X

X

address_name X X X X X

X

address_street X X X X X

X

address_city X X X X X

X

address_state X X X X X

X

address_zip X X X X X

X

address_ country X X X X X

X

payer_email X X X X X

X X
payer_id X X X X X

X X
payer_status X X X X X

X X
payment_type

X X

Subscription Information

subscr_date X X X

subscr_ effective

X

period1 X X X

period2 X X X

period3 X X X

amount1 X X X

amount2 X X X

amount3 X X X

mc_amount1 X X X

mc_amount2 X X X

mc_amount3 X X X

recurring X X X

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 following format: HH:MM:SS DD Mmm YY, YYYY PST
case_id Case identification number.
Format: PP-nnn-nnn-nnn-nnn where n is any numeric character.
case_type
  • chargeback: A buyer has filed a chargeback with his credit card company, which has notified PayPal of the reason for the chargeback.
  • complaint: A buyer has logged a complaint through the PayPal Resolution Center.
  • dispute: A buyer and seller post communications to one another through the Resolution Center to try to work out issues without intervention by PayPal.
reason_code Reason for the case.
Values for case_type set to complaint:
  • non_receipt: Buyer claims that he did not receive goods or service.
  • not_as_described: Buyer claims that the goods or service received differ from merchant's description of the goods or service.
  • unauthorized_claim: Buyer claims that an unauthorized payment was made for this particular transaction.

Values for case_type set to chargeback:

  • unauthorized
  • adjustment_reimburse: A case that has been resolved and closed requires a reimbursement.
  • non_receipt: Buyer claims that he did not receive goods or service.
  • duplicate: Buyer claims that a possible duplicate payment was made to the merchant.
  • merchandise: Buyer claims that the received merchandise is unsatisfactory, defective, or damaged.
  • special: Some other reason. Usually, special indicates a credit card processing error for which the merchant is not responsible and for 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.

Global Shipping Program Message Variables

PayPal generates an IPN message for transactions related to ebay's Global Shipping Program. In particular, these messages relate to the Third Party Litigator (3PL) domestic fulfillment center address where merchants should ship merchandise intended for buyers.

Variable

Description

fulfillment_address_country Country of fulfillment center address Length: 64 characters
fulfillment_address_city City of fulfillment center address Length: 40 characters
fulfillment_address_country_code ISO 3166 country code associated with fulfillment center address Length: 2 characters
fulfillment_address_name Name used with fulfillment center address Length: 128 characters
fulfillment_address_state State of fulfillment center address Length: 40 characters
fulfillment_address_street Street of fulfillment center address Length: 200 characters
fulfillment_address_zip Zip code of fulfillment center address Length: 20 characters

Pay Message Variables

PayPal generates an IPN message that contains information about the pay request or payment in response to the Adaptive Payments Pay and ExecutePayment API operations.

Variable

Description

transaction_type The type of transaction. Possible values are:
  • Adaptive Payment PAY
    This notification occurs when is a payment is made due to a Pay Request. The variables for the Adaptive Payment Pay notification are similar to the PaymentDetailsResponse fields.
  • Adjustment
    This can be for a chargeback, reversal, or refund; check the reason_code to see which it is.
status The status of the payment. Possible values are:
  • CANCELED – The Preapproval agreement was cancelled
  • CREATED – The payment request was received; funds will be transferred once the payment is approved
  • COMPLETED – The payment was successful
  • INCOMPLETE – Some transfers succeeded and some failed for a parallel payment or, for a delayed chained payment, secondary receivers have not been paid
  • ERROR – The payment failed and all attempted transfers failed or all completed transfers were successfully reversed
  • REVERSALERROR – One or more transfers failed when attempting to reverse a payment
  • PROCESSING – The payment is in progress
  • PENDING – The payment is awaiting processing
sender_email Sender's email address.
action_type Whether the Pay API is used with or without the SetPaymentOptions and ExecutePayment API operations. Possible values are:
  • PAY – If you are not using the SetPaymentOptions and ExecutePayment API operations
  • CREATE – If you are using the SetPaymentOptions and ExecutePayment API operations
payment_request_date The date on which the payment request was initiated.
reverse_all_parallel_payments_on_error Whether the payment request specified to reverse parallel payments if an error occurs. Possible values are:
  • true – Each parallel payment is reversed if an error occurs
  • false – Only incomplete payments are reversed (default)
transaction[n].id The transaction ID, where [n] is a number from 0 to 5. For simple, single receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
transaction[n].status The transaction status, where [n] is a number from 0 to 5. For simple single-receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
Possible values are:
  • Completed
  • Pending
  • Refunded
transaction[n].id_for_sender The transaction ID for the sender, where [n] is a number from 0 to 5. For simple, single receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
transaction[n].status_for_sender_txn The transaction status, where [n] is a number from 0 to 5. For simple single-receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
Possible values are:
  • COMPLETED – The sender's transaction has completed
  • PENDING – The transaction is awaiting further processing
  • CREATED – The payment request was received; funds will be transferred once approval is received
  • PARTIALLY_REFUNDED – Transaction was partially refunded
  • DENIED – The transaction was rejected by the receiver
  • PROCESSING – The transaction is in progress
  • REVERSED – The payment was returned to the sender
  • REFUNDED – The payment was refunded
  • FAILED – The payment failed
transaction[n].refund_id The identification number for the refund
transaction[n].refund_amount The amount that was refunded.
transaction[n].refund_account_charged The email address of the debit account of the refund.
transaction[n].receiver The receiver's email address for the transaction
transaction[n].invoiceId The invoice number for this transaction
transaction[n].amount The payment amount of the transaction
transaction[n].is_primary_receiver Whether there is a primary receiver for this transaction, which indicates whether the transaction is a chained payment.
Possible values are:
  • true – There is a primary receiver (chained payment)
  • false – There is no primary receiver (simple or parallel payment)
return_url The URL to which the sender's browser is redirected after approving a payment on paypal.com. Use the pay key to identify the payment as follows: payKey=${payKey}.
cancel_url The URL to which the sender's browser is redirected if the sender cancels the approval for a payment on paypal.com. Use the pay key to identify the payment as follows: payKey=${payKey}.
ipn_notification_url The URL to which all IPN messages for this payment are sent.
pay_key The pay key that identifies this payment. This is a token that is assigned by the Pay API after a PayRequest message is received and can be used in other Adaptive Payments APIs as well as the cancelURL and returnURL to identify this payment. The pay key is valid for 3 hours.
memo A note associated with the payment.
fees_payer The payer of PayPal fees. Possible values are:
  • SENDER – Sender pays all fees (for personal, implicit simple/parallel payments; do not use for chained or unilateral payments)
  • PRIMARYRECEIVER – Primary receiver pays all fees (chained payments only)
  • EACHRECEIVER – Each receiver pays their own fee (default, personal and unilateral payments)
  • SECONDARYONLY – Secondary receivers pay all fees (use only for chained payments with one secondary receiver)
trackingId The tracking ID that was specified for this payment in the PaymentDetailsRequest message.
preapproval_key The preapproval key returned after a PreapprovalRequest, or the preapproval key that identifies the preapproval key sent with a PayRequest.
reason_code Whether this transaction is a chargeback, partial, or reversal. Possible values are:
  • Chargeback Settlement – Transaction is a chargeback
  • Admin reversal – Transaction was reversed by PayPal administrators
  • Refund – Transaction was partially or fully refunded

Preapproval Message Variables

PayPal generates an IPN message that contains information about a preapproval in response to the Adaptive Payments Preapproval API operation.

Variable

Description

transaction_type The type of transaction. For a preapproval, this variable returns Adaptive Payment Preapproval.
Note: If this variable is set to Adaptive Payment Pay or Adjustment, refer to the Pay Message Variable section.
preapproval_key The preapproval key returned after a PreapprovalRequest.
approved Whether the preapproval request was approved. Possible values are:
  • true – The preapproval was approved
  • false – The preapproval was denied
cancel_url The URL to which the sender's browser is redirected if the sender decides to cancel the preapproval as requested. Use the preapproval key to identify the payment as follows: preapprovalKey=${preapprovalKey}
current_number_of_payments The current number of payments made for this preapproval.
current_total_amount_of_all_payments The current total of payments made for this preapproval.
current_period_attempts The current number of attempts this period for this preapproval.
currencyCode The currency code. Possible values are:
  • Australian Dollar – AUD
  • Brazilian Real – BRL
    Note: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.
  • Canadian Dollar – CAD
  • Czech Koruna – CZK
  • Danish Krone – DKK
  • Euro – EUR
  • Hong Kong Dollar – HKD
  • Hungarian Forint – HUF
  • Israeli New Sheqel – ILS
  • Japanese Yen – JPY
  • Malaysian Ringgit – MYR
    Note: The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.
  • Mexican Peso – MXN
  • Norwegian Krone – NOK
  • New Zealand Dollar – NZD
  • Philippine Peso – PHP
  • Polish Zloty – PLN
  • Pound Sterling – GBP
  • Singapore Dollar – SGD
  • Swedish Krona – SEK
  • Swiss Franc – CHF
  • Taiwan New Dollar – TWD
  • Thai Baht – THB
  • Turkish Lira – TRY
    Note: The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts.
  • U.S. Dollar – USD
date_of_month The day of the month on which a monthly payment is to be made. A number between 1 and 31 indicates the day of the month. A value of 0 indicates that the payment can be made on any day.
day_of_week The day of the week that a weekly payment is to be made. Possible values are:
  • NO_DAY_SPECIFIED
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
starting_date First date for which the preapproval is valid.
ending_date Last date for which the preapproval is valid. Time is currently not supported.
max_total_amount_of_all_payments The preapproved maximum total amount of all payments.
max_amount_per_payment The preapproved maximum amount of all payments.
max_number_of_payments The maximum number of payments that is preapproved.
payment_period The payment period.
Possible values are:
  • NO_PERIOD_SPECIFIED
  • DAILY
  • WEEKLY
  • BIWEEKLY
  • SEMIMONTHLY
  • MONTHLY
  • ANNUALLY
pin_type Whether a personal identification number (PIN) is required. It is one of the following values:
  • NOT_REQUIRED – A PIN is not required
  • REQUIRED – A PIN is required
sender_email The sender's email address.

Adaptive Accounts IPN Messages

PayPal sends an IPN message whenever a PayPal account is created using the CreateAccount API operation.

Field

Description

notify_version Message's version number
first_name Account holder's first name
last_name Account holder's last name
verify_sign Encrypted string used to validate the authenticity of the transaction
charset Character set
account_key Account key returned by the CreateAccount API operation
confirmation_code Confirmation code
event_type The kind of event:
  • ACCOUNT_CONFIRMED indicates that the account holder has set a password and the account has been created.
  • LOGIN_CONFIRMED indicates that the account holder logged into the account.

Example IPN message in response to CreateAccount request

notify_version=UNVERSIONED&first_name=Someone&verify_sign=AI.LzRiNYreJbZLZ8BV5FbGKL8hSAupAtXf3haOHWI2NmcJ5C4VqdQrx&charset=windows-1252&last_name=Something&account_key=AA6N5043354R131103K&confirmation_code=15531193754629193930

Example IPN message in response to account holder setting the password

first_name=Someone&account_key=AA-6N5043354R131103K&notify_version=UNVERSIONED&charset=windows-1252&email_address=abawany-20110208-01%40paypal.com&event_type=%5BACCOUNT_CONFIRMED%5D&last_name=Something&verify_sign=AcIPKnsgPsoX2ONJgU17uAl9h-ZIAKJMRvhEULLvD9mOzH3WjdRNfEte
Note: This message indicates that the account setup is complete.

Example IPN message in response to account login

first_name=Someone&account_key=AA-6N5043354R131103K&notify_version=UNVERSIONED&charset=windows-1252&email_address=abawany-20110208-01%40paypal.com&event_type=%5BLOGIN_CONFIRMED%5D&last_name=Something&verify_sign=ANqF6tuR41eB.S.2I9dCskJuSSvrAI8Monbec4U2PZCnoKYffnv156mN

PDT-Specific Variables

PDT variables have the same names as IPN variables. Some variables, however, apply only to PDT.

Variable

Description

amt Amount of the transaction
cc Currency code
cm Custom message
sig

st Transaction status
tx Transaction ID/PDT token