IPN and PDT variables

APILegacyLast updated: December 12th 2023, @ 7:31:44 am


Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

PayPal returns variables for the following message types:

  • Instant Payment Notification (IPN)
  • Payment Data Transfer (PDT)

IPN and PDT variable names are case-sensitive. Most constant values are lowercase. The constant values for payment_status have an initial capital letter.

Note: Values posted by IPN are URL-encoded. For example, the URL https://example.com is encoded as http%3A//example.com

IPN transaction types

Back-end or administrative processes can 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_typeDescription
Credit card chargeback if the case_type variable contains chargeback.
adjustmentA dispute has been resolved and closed.
cartPayment received for multiple items; source is Express Checkout or the PayPal Shopping Cart.
express_checkoutPayment received for a single item; source is Express Checkout.
masspayPayment sent using Mass Pay.
merch_pmtMonthly subscription paid for Website Payments Pro, Reference transactions, or Billing Agreements.
mp_cancelBilling agreement canceled.
new_caseA new dispute was filed.
payoutA payout related to a global shipping transaction was completed.
pro_hostedPayment received; source is Website Payments Pro Hosted Solution.
recurring_paymentRecurring payment received.
recurring_payment_expiredRecurring payment expired.
recurring_payment_failedRecurring 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_cancelRecurring payment profile canceled.
recurring_payment_profile_createdRecurring payment profile created.
recurring_payment_skippedRecurring payment skipped; it will be retried up to 3 times, 5 days apart.
recurring_payment_suspendedRecurring 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_paymentRecurring 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_moneyPayment received; source is the Send Money tab on the PayPal website.
subscr_cancelSubscription canceled.
subscr_eotSubscription expired.
subscr_failedSubscription payment failed.
subscr_modifySubscription modified.
subscr_paymentSubscription payment received.
subscr_signupSubscription started.
virtual_terminalPayment received; source is Virtual Terminal.
web_acceptPayment received; source is any of the following:
  • A Direct Credit Card (Pro) transaction.
  • A Buy Now, Donation, or Smart Logo for eBay auctions button.

The following variables identify the merchant that receives a payment or notification and include transaction-specific information.

Variable NameDescription
businessEmail 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.
charsetCharacter set.
customCustom value as passed by you, the merchant. These are pass-through variables that are never presented to your customer. Length: 255 characters.
ipn_track_idInternal; only for use by MTS.
notify_versionMessage's version number.
parent_txn_idIn 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_idUnique ID generated during guest checkout (payment by credit card without logging in).
receiver_emailPrimary email address of the payment recipient (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. Length: 127 characters.
Note: The value of this variable is normalized to lowercase characters.
receiver_idUnique account ID of the payment recipient. For example, the merchant). This is the same as the recipient's referral ID. Length: 13 characters.
resendWhether this IPN message was resent (equals true); otherwise, this is the original message.
residence_countryISO 3166 country code associated with the country of residence. Length: 2 characters.
test_ipnWhether the message is a test message. Value is: 1 — the message is directed to the sandbox.
txn_idThe merchant's original transaction identification number for the payment from the buyer, against which the case was registered.
txn_typeThe kind of transaction for which the IPN message was sent.
verify_signEncrypted string used to validate the authenticity of the transaction.

Buyer information

Buyer information identifies the payer by payer ID or email address. Extra contact or shipping information may be provided.

Variable NameDescription
address_countryCountry of customer's address. Length: 64 characters.
address_cityCity of customer's address. Length: 40 characters.
address_country_codeISO 3166 country code associated with customer's address. Length: 2 characters.
address_nameName used with address (included when the customer provides a Gift Address). Length: 128 characters.
address_stateState of customer's address. Length: 40 characters.
address_statusWhether the customer provided a confirmed address. Value is:
  • confirmed — Customer provided a confirmed address.
  • unconfirmed — Customer provided an unconfirmed address.
address_streetCustomer's street address. Length: 200 characters.
address_zipZip code of customer's address. Length: 20 characters.
contact_phoneCustomer's telephone number. Length: 20 characters.
first_nameCustomer's first name. Length: 64 characters.
last_nameCustomer's last name. Length: 64 characters.
payer_business_nameCustomer's company name, if customer is a business. Length: 127 characters.
payer_emailCustomer's primary email address. Use this email to provide any credits. Length: 127 characters.
payer_idUnique customer ID. Length: 13 characters.

Payment information

Payment information identifies the amount and status of a payment transaction, including fees.

Variable NameDescription
auth_amountAuthorization amount.
auth_expAuthorization expiration date and time in the following format: HH:MM:SS DD Mmm YY, YYYY PST Length: 28 characters.
auth_idAuthorization identification number. Length: 19 characters.
auth_statusStatus of authorization.
discountThe total discount to be applied to a shopping cart in the currency of mc_currency.
echeck_time_processedThe time an eCheck was processed; for example, when the status changes to Success or Completed. The format is: hh:mm:ss MM DD, YYYY ZONE. For example, 04:55:30 May 26, 2011 PDT.
exchange_rateExchange rate used if a currency conversion occurred.
fraud_management_pending_filters_xOne 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:
  • 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
invoicePass-through variable you can use to identify your Invoice Number for this purchase. If omitted, no variable is passed back. Length: 127 characters.
item_namexItem 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 appends the number of the item. For example, item_name1, item_name2, and so on. Length: 127 characters.
item_numberxPass-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. For example, item_number1, item_number2, and so on. Length: 127 characters.
mc_currency
  • For payment IPN notifications, this is the currency of the payment.
  • For non-payment subscription IPN notifications. For example, 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. For example, txn_type = subscr_payment).
mc_feeTransaction 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_grossFull 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_xThe amount of shopping cart detail item prior to discount. The amount is in the currency of mc_currency, where x is the shopping cart detail item number. The value of mc_gross_x is mc_gross minus discount.
mc_handlingTotal handling amount associated with the transaction.
mc_shippingTotal shipping amount associated with the transaction.
mc_shippingxThis 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.
memoMemo as entered by your customer in PayPal Website Payments note field. Length: 255 characters.
num_cart_itemsIf this is a PayPal Shopping Cart transaction, number of items in cart.
option_name1Option 1 name as requested by you. PayPal appends the number of the item where x represents the number of the shopping cart detail item. For example, option_name1, option_name2). Length: 64 characters.
option_name2Option 2 name as requested by you. PayPal appends the number of the item where x represents the number of the shopping cart detail item. For example, option_name2, option_name2). Length: 64 characters.
option_selection1Option 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. For example, option_selection1, option_selection2). Length: 200 characters.
option_selection2Option 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. For example, option_selection1, option_selection2). Length: 200 characters.
payer_statusWhether the customer has a verified PayPal account.
  • verified — Customer has a verified PayPal account.
  • unverified — Customer has an unverified PayPal account.
payment_dateThe PayPal-generated time and date stamp in the format HH:MM:SS Mmm DD, YYYY PDT. Length: 28 characters.
payment_feeUSD 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_xIf 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_grossFull USD amount of the customer's payment, before transaction fee is subtracted. Will be empty for non-USD payments. This is a deprecated 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_xIf 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_statusThe 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 through 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 reason_code element.
  • Processed: A payment has been accepted.
  • Voided: This authorization has been voided.
payment_typeecheck: This payment was funded with an eCheck. instant: This payment was funded with PayPal balance, credit card, or instant transfer.
pending_reasonThis variable is set only if payment_status is Pending:
  • address: Your Payment Receiving Preferences are set so that if a customer does not include a confirmed shipping address, you must manually accept or deny the payment. 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.
  • delayed_disbursement: The transaction has been approved and is currently awaiting funding from the bank. This typically takes less than 48 hrs.
  • 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 profile'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_eligibilityThe status of the seller's protection eligibility. Possible values: Eligible, Ineligible, Partially Eligible—Unauth Only, PartiallyEligible, None, Active Fraud Control—Unauth Premium Eligible.
quantityQuantity 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. For example, quantity1, quantity2).
reason_codeThis 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` stands 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_settleRemaining amount that can be captured with Authorization and Capture.
settle_amountAmount 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_currencyCurrency of settle_amount.
settlement_fee_amtThe transaction fee associated with the payment in the settlement currency. Applicable only for use cases where the PayPal fee is charged in the settlement currency.
settlement_fee_currencycodeCurrency of settlement_fee_amt.
shippingShipping charges associated with this transaction. Format: unsigned, no currency symbol, two decimal places.
shipping_methodThe 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.
taxAmount of tax charged on payment. PayPal appends the number of the item. For example, 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_entityAuthorization and Capture transaction entity.

Auction

The following variables contain information about an auction.

Variable NameDescription
auction_buyer_idThe customer's auction ID. Length: 64 characters.
auction_closing_dateThe auction's close date in the format HH:MM:SS Mmm DD, YYYY PDT. Length: 28 characters.
auction_multi_itemThe number of items purchased in multi-item auction payments. It enables 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_auctionThis 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

The following variables contain information about mass payments, including transaction status, transaction amounts, and fees.

Variable NameDescription
masspay_txn_id_xFor 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_xFor Mass Payments, the currency of the amount and fee, where x is the record number the mass pay item.
mc_fee_xFor Mass Payments, the transaction fee associated with the payment, where x is the record number the mass pay item.
mc_gross_xThe gross amount for the amount, where x is the record number the mass pay item.
mc_handlingxThe 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_dateFor Mass Payments, the first IPN is the date and time when the record set is processed in the format HH:MM:SS Mmm DD, YYYY PDT. Length: 28 characters.
payment_statusCompleted: 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_xThis variable is set only if status = Failed.`partial:partials/docs/mass-pay-reason-codes.en-XC`
receiver_email_xFor 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_xFor 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 updates within 72 hours.
  • Blocked: This payment was blocked due to a violation of government regulations.
unique_id_xFor 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

The following variables identify the amounts and status associated with recurring transactions.

VariablesProfile created messageRecurring payment message
Basic Information
businessX
receiver_emailXX
receiver_idX
Transaction Information
payment_statusX
payment_typeX
payment_dateX
txn_idX
initial_payment_statusX
initial_payment_txn_idX
txn_typerecurring_payment_profile_createdrecurring_payment
Currency and Exchange
mc_grossX
mc_feeX
mc_currencyX
payment_grossX
currency_codeXX
payment_feeX
Buyer Information
first_nameXX
last_nameXX
address_nameX
address_streetX
address_cityX
address_stateX
address_zipX
address_countryX
payer_emailXX
payer_idXX
payer_statusXX
residence_countryXX
address_country_codeX
address_statusX
Recurring Payment
recurring_payment_idXX
rp_invoice_idXX
product_nameXX
product_typeXX
period_typeXX
payment_cycleXX
outstanding_balanceXX
amount_per_cycleXX
initial_payment_amountXX
profile_statusXX
amountXX
time_createdXX
next_payment_dateXX
Other Information
notify_versionXX
charsetXX

Reference Transaction and Billing Agreements

Reference Transaction and Billing Agreements information identifies items about the transaction and billing agreement set by the merchant.

Variable NameDescription
address_countryCountry of customer's address. Length: 64 characters.
address_cityCity of customer's address. Length: 40 characters.
address_country_codeISO 3166 country code associated with customer's address. Length: 2 characters.
address_nameName used with address (included when the customer provides a Gift Address). Length: 128 characters.
address_stateState of customer's address. Length: 40 characters.
address_statusWhether the customer provided a confirmed address. Possible values are confirmed and unconfirmed.
address_streetCustomer's street address. Length: 200 characters.
address_zipZip code of customer's address. Length: 20 characters.
businessEmail 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. Length: 127 characters.
Note: The value of this variable is normalized to lowercase characters.
charsetCharacter set.
customCustom value as passed by you, the merchant. These are pass-through variables that are never presented to your customer. Length: 255 characters
discountThe total discount to be applied to a shopping cart in the currency of mc_currency.
first_nameCustomer's first name. Length: 64 characters.
invoicePass-through variable you can use to identify your invoice number for the purchase. If omitted, no variable is passed back. Length: 127 characters.
item_namexItem 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. For example, item_name1, item_name2. Length: 127 characters.
item_numberxPass-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. For example, item_number1, item_number2. Length: 127 characters.
last_nameAccount holder's last name.
mc_currency
  • For payment IPN notifications, this is the currency of the payment.
  • For non-payment subscription IPN notifications. For example,, 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. For example, txn_type = subscr_payment.
mc_feeTransaction 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_grossFull 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_handlingTotal handling amount associated with the transaction.
mc_shippingTotal shipping amount associated with the transaction.
memoMemo as entered by your customer in PayPal Website Payments Pro note field. Length: 255 characters.
mp_currencyThe merchants primary currency.
mp_customCustom text passed by the merchant during DoReferenceTransaction call at creation.
mp_cycle_startThe month and day the agreement was created.
mp_descThe agreement description set in SetExpressCheckout call.
mp_idThe encrypted billing agreement ID.
mp_notificationSent to the merchant when an account is locked. All billing agreements for the account are canceled.
mp_pay_typeThe accepted payment type. Possible values are INSTANT, ANY, and ECHECK.
mp_statusThe agreement status. Possible values are A for an active agreement and I for an inactive agreement (equivalent to canceled).
notify_versionMessage's version number.
num_cart_itemsIf this is a PayPal Shopping Cart transaction, number of items in cart.
payer_emailCustomer's primary email address. Use this email to provide any credits. Length: 127 characters.
payer_idUnique customer ID. Length: 13 characters.
payer_statusWhether the customer has a verified PayPal account. Possible values are verified or unverified.
payment_dateThe PayPal-generated time and date stamp in the format HH:MM:SS Mmm DD, YYYY PDT. Length: 28 characters.
payment_feeUSD 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_typeecheck: This payment was funded with an eCheck. instant: This payment was funded with PayPal balance, credit card, or Instant Transfer.
payment_grossFull USD amount of the customer's payment, before transaction fee is subtracted. Will be empty for non-USD payments. This is a deprecated 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.
protection_eligibilityThe status of the seller's protection eligibility. Possible values: Eligible, Ineligible, Partially Eligible—Unauth Only, PartiallyEligible, None, Active Fraud Control—Unauth Premium Eligible.
quantityxQuantity 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. For example, quantity1, quantity2).
receiver_emailPrimary 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. Length: 127 characters.
Note: The value of this variable is normalized to lowercase characters.
receiver_idUnique account ID of the payment recipient. For example, the merchant). This is the same as the recipient's referral ID. Length: 13 characters.
residence_countryISO 3166 country code associated with the country of residence.
Length: 2 characters
shipping_discountThe discount amount for shipping charges in amount, not percentage.
shipping_methodThe 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.
taxAmount of tax charged on payment. PayPal appends the number of the item. For example, 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_subjectA note or memo for the transaction. Applicable only after notify_version >=2.6.
txn_idThe merchant's original transaction identification number for the payment from the buyer, against which the case was registered.
txn_typeThe type of transaction. Possible values are merch_pmt, mp_cancel, and mp_signup.
verify_signEncrypted string used to validate the authenticity of the transaction.

Subscription

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

Variable NameDescription
amount1(Optional) Amount of payment for trial period 1 for USD payments; otherwise blank.
amount2(Optional) Amount of payment for trial period 2 for USD payments; otherwise blank.
amount3Amount of payment for regular subscription period for USD payments; otherwise blank.
mc_amount1(Optional) Amount of payment for trial period 1, regardless of currency.
mc_amount2(Optional) Amount of payment for trial period 2, regardless of currency.
mc_amount3Amount 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.
period3Regular subscription interval in days, weeks, months, or years.
reattemptIndicates whether reattempts should occur upon payment failures. 1 is yes, blank is no.
recurringIndicates whether regular rate recurs. 1 is yes, blank is no.
retry_atDate PayPal will retry a failed subscription payment.
subscr_dateStart date or cancellation date depending on whether transaction is subscr_signup or subscr_cancel. Time/Date stamp generated by PayPal in the format HH:MM:SS Mmm DD, YYYY PDT.
subscr_effectiveDate when the subscription modification will be effective (only for txn_type = subscr_modify). Time/Date stamp generated by PayPal in the format HH:MM:SS Mmm DD, YYYY PDT
subscr_idID 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

Summary of subscription variables

VariableSignupCancelModifyUSD PaymentMulti-CurrencyPaymentRefundFailedEOT
Basic Information
businessXXXXXXX
receiver_emailXXXXXXX
receiver_idXX
item_nameXXXXXXX
item_numberXXXXXXX
Advanced and Custom Information
invoiceXXXXXXX
customXXXXXXX
option_name1XXXXXXX
option_selection1XXXXXXX
option_name2XXXXXXX
option_selection2XXXXXXX

Transaction Information

payment_statusXXX
pending_reasonXX
reason_codeXX
payment_dateXX
txn_idXX
parent_txn_idXX
txn_typesubscr_
signup
subscr_
cancel
subscr_
modify
subscr_paymentsubscr_
failed
subscr_eot
Currency and Exchange information
mc_grossXX
mc_feeXX
mc_currencyXXXXXXX
settle_amountXX
exchange_rateXX
payment_grossXXX
payment_feeX
Buyer Information
first_nameXXXXXXX
last_nameXXXXXXX
payer_business_nameXXXXXX
address_nameXXXXXX
address_streetXXXXXX
address_cityXXXXXX
address_stateXXXXXX
address_zipXXXXXX
address_
country
XXXXXX
payer_emailXXXXXXX
payer_idXXXXXXX
payer_statusXXXXXXX
payment_typeXX
Subscription Information
subscr_dateXXX
subscr_
effective
X
period1XXX
period2XXX
period3XXX
amount1XXX
amount2XXX
amount3XXX
mc_amount1XXX
mc_amount2XXX
mc_amount3XXX
recurringXXX
reattemptXXX
retry_atX
recur_timesXXX
usernameXXXXXXX
passwordXXXXXXX
subscr_idXXXXXXX

Dispute resolution

The following variables identify the case ID and status of a dispute.

Variable NameDescription
buyer_additional_informationNotes the buyer entered into the Resolution Center.
case_creation_dateDate and time case was registered in the format HH:MM:SS Mmm DD, YYYY PDT.
case_idCase identification number.
Important: Multiple formats are accepted for the case_id variable. PayPal is enhancing the dispute management system to provide more details regarding dispute IPNs. The time to transition to the new format varies depending on your integration.
  • Original Formats: PP-nnn-nnn-nnn-nnn where n is any numeric character and PP-D-xxxx where xxxx is an integer, and the D indicates a dispute.
  • New Format: PP-R-XXX-NNNNNN where R is the resolution, XXX is randomly generated letters, and N is a unique numeric sequence. Example: PP-R-BFV-90020010.
Make sure that your IPN integration can accept and process both formats. As a best practice, you are encouraged to integrate flexibly so that any future changes to IPN value parameters can be made without the need for integration change.
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.
  • bankreturn: An ACH return was initiated from the buyer's bank, and the money was removed from the seller's PayPal account.
    Note: bankreturn is a deprecated value.
reason_codeReason for the case. Values for case_type set to complaint or dispute:
  • 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
  • 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.
  • adjustment_reimburse: A case that has been resolved and closed requires a reimbursement.
    Note: adjustment_reimburse is a deprecated value.
  • billing: Buyer claims that the received merchandise is unsatisfactory, defective, or damaged.
    Note: billing is a deprecated value.

Global shipping program message

PayPal generates an IPN message for transactions related to eBay's Global Shipping Program. These messages relate to the third party logistics (3PL) domestic fulfillment center address where merchants should ship merchandise for buyers.

VariableDescription
fulfillment_address_countryCountry of fulfillment center address. Length: 64 characters.
fulfillment_address_cityCity of fulfillment center address. Length: 40 characters.
fulfillment_address_country_codeISO 3166 country code associated with fulfillment center address. Length: 2 characters.
fulfillment_address_nameName used with fulfillment center address. Length: 128 characters.
fulfillment_address_stateState of fulfillment center address. Length: 40 characters.
fulfillment_address_streetStreet of fulfillment center address. Length: 200 characters.
fulfillment_address_zipZip code of fulfillment center address. Length: 20 characters.

Pay message

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.

VariableDescription
transaction_typeThe type of transaction. Value is:
  • 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.
statusThe status of the payment. Value is:
  • CANCELED — The Preapproval agreement was cancelled.m
  • 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_emailSender's email address.
action_typeWhether the Pay API is used with or without the SetPaymentOptions and ExecutePayment API operations. Value is:
  • 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_dateThe date on which the payment request was initiated.
reverse_all_parallel_payments_on_errorWhether the payment request specified to reverse parallel payments if an error occurs. Value is:
  • true — Each parallel payment is reversed if an error occurs.
  • false — Only incomplete payments are reversed (default).
transaction[n].idThe 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].statusThe 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. Value is:

  • Completed.
  • Pending.
  • Refunded.
transaction[n].id_for_senderThe 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_txnThe 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. Value is:
  • 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_idThe identification number for the refund.
transaction[n].refund_amountThe amount that was refunded.
transaction[n].refund_account_chargedThe email address of the debit account of the refund.
transaction[n].receiverThe receiver's email address for the transaction.
transaction[n].invoiceIdThe invoice number for this transaction.
transaction[n].amountThe payment amount of the transaction.
transaction[n].is_primary_receiverWhether there is a primary receiver for this transaction, which indicates whether the transaction is a chained payment. Value is:
  • true — There is a primary receiver (chained payment).
  • false — There is no primary receiver (simple or parallel payment).
return_urlThe URL to which the sender's browser is redirected after approving a payment on paypal.com. Use the pay key to identify the payment: `payKey=$payKey`.
cancel_urlThe 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: `payKey=$payKey`.
ipn_notification_urlThe URL to which all IPN messages for this payment are sent.
pay_keyThe 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.
memoA note associated with the payment.
fees_payerThe payer of PayPal fees. Value is:
  • 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).
trackingIdThe tracking ID that was specified for this payment in the PaymentDetailsRequest message.
preapproval_keyThe preapproval key returned after a PreapprovalRequest, or the preapproval key that identifies the preapproval key sent with a PayRequest.
reason_codeWhether this transaction is a chargeback, partial, or reversal. Value is:
  • Chargeback Settlement — Transaction is a chargeback.
  • Admin reversal — Transaction was reversed by PayPal administrators.
  • Refund — Transaction was partially or fully refunded.

Preapproval message

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

VariableDescription
transaction_typeThe 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_keyThe preapproval key returned after a PreapprovalRequest.
approvedWhether the preapproval request was approved. Value is:
  • true — The preapproval was approved.
  • false — The preapproval was denied.
cancel_urlThe 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: preapprovalKey=`$preapprovalKey`.
current_number_of_paymentsThe current number of payments made for this preapproval.
current_total_amount_of_all_paymentsThe current total of payments made for this preapproval.
current_period_attemptsThe current number of attempts this period for this preapproval.
currency_codeThe currency code. Value is:
  • Australian Dollar — AUD.
  • Brazilian Real — BRL.
    Note: This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only. If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate. The currency conversion rate includes PayPal's applicable spread or fee.
  • Canadian Dollar — CAD.
  • Czech Koruna — CZK.
  • Danish Krone — DKK.
  • Euro — EUR.
  • Hong Kong Dollar — HKD.
  • Hungarian Forint — HUF.
  • Israeli New Shekel — 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.
  • U.S. Dollar — USD.
date_of_monthThe 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_weekThe day of the week that a weekly payment is to be made. Value is:
  • NO_DAY_SPECIFIED.
  • SUNDAY.
  • MONDAY.
  • TUESDAY.
  • WEDNESDAY.
  • THURSDAY.
  • FRIDAY.
  • SATURDAY.
starting_dateFirst date for which the preapproval is valid.
ending_dateLast date for which the preapproval is valid. Time is currently not supported.
max_total_amount_of_all_paymentsThe pre-approved maximum total amount of all payments.
max_amount_per_paymentThe pre-approved maximum amount of all payments.
max_number_of_paymentsThe maximum number of payments that is pre-approved.
payment_period The payment period. Value is:
  • NO_PERIOD_SPECIFIED.
  • DAILY.
  • WEEKLY.
  • BIWEEKLY.
  • SEMIMONTHLY.
  • MONTHLY.
  • ANNUALLY.
pin_typeWhether a personal identification number (PIN) is required. Value is:
  • NOT_REQUIRED — A PIN is not required.
  • REQUIRED — A PIN is required.
sender_emailThe sender's email address.

PDT-specific

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

VariableDescription
amtAmount of the transaction.
ccCurrency code.
cmCustom message.
sig
stTransaction status.
txTransaction ID/PDT token.