# IPN and PDT variables (/api/nvp-soap/ipn/IPNandPDTVariables)
> **Note:** **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:** **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 [#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_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 Website Payments Pro, Reference transactions, or Billing Agreements. |
| `mp_cancel` | Billing agreement canceled. |
| `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](/api/nvp-soap/paypal-payments-pro/integration-guide/#features). |
| `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 [#transaction-and-notification-related]
The following variables identify the merchant that receives a payment or notification and include 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:** **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. |
| `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 (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:** **Note:** The value of this variable is normalized to lowercase characters. |
| `receiver_id` | Unique account ID of the payment recipient. For example, 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. Value is: `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 [#buyer-information]
Buyer information identifies the payer by payer ID or email address. Extra 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. Value is:`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 [#payment-information]
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. |
| `discount` | The total discount to be applied to a shopping cart in the currency of `mc_currency`. |
| `echeck_time_processed` | The 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_rate` | Exchange rate used if a currency conversion occurred. |
| `fraud_management_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:`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 appends the number of the item. For example, `item_name1`, `item_name2`, and so on. 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. 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_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 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_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. For example, `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. For example, `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. For example, `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. For example, `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` | The PayPal-generated time and date stamp in the 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:** **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:** **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 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_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:** **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 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_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`: 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_eligibility` | The status of the seller's protection eligibility. Possible values: `Eligible`, `Ineligible`, `Partially Eligible—Unauth Only`, `PartiallyEligible`, `None`, `Active Fraud Control—Unauth Premium Eligible`. |
| `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. For example, `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` 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:** **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`. |
| `settlement_fee_amt` | The 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_currencycode` | Currency of `settlement_fee_amt`. |
| `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. For example, `item_name1`, `item_name2`). The `tax`*x* 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 [#auction]
The following variables contain information about an 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 format `HH:MM:SS Mmm DD, YYYY PDT`. Length: 28 characters. |
| `auction_multi_item` | The 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_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 [#mass-pay]
The following variables contain information about mass payments, including transaction status, transaction amounts, and 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 and time when the record set is processed in the format `HH:MM:SS Mmm DD, YYYY PDT`. 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`. \| Reason code \| Description \| \| --- \| --- \| \| `1001` \| Receiver's account is invalid \| \| `1002` \| Sender has insufficient funds \| \| `1003` \| User's country is not allowed \| \| `1004` \| User funding source is ineligible \| \| `1005` \| PENDING\_RECIPIENT\_NON\_HOLDING\_CURRENCY\_PAYMENT\_PREFERENCE(1005, "PENDING\_RECIPIENT\_NON\_HOLDING\_CURRENCY\_PAYMENT\_PREFERENCE", "This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout.") \| \| `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 \| \| `3501` \| Email address invalid; try again with a valid email ID \| \| `3535` \| Invalid currency \| \| `3547` \| Sender's address is located in a restricted State (e.g., California) \| \| `3558` \| Receiver's address is located in a restricted State (e.g., California) \| \| `3769` \| Market closed and transaction is between 2 different countries \| \| `4001` \| Internal error \| \| `4002` \| Internal error \| \| `8319` \| Zero amount \| \| `8330` \| Receiving limit exceeded \| \| `8331` \| Duplicate mass payment \| \| `9302` \| Transaction was declined \| \| `11711` \| Per-transaction sending limit exceeded \| \| `14159` \| Transaction currency cannot be received by the recipient \| \| `14550` \| Currency compliance \| \| `14761` \| The mass payment was declined because the secondary user sending the mass payment has not been verified \| \| `14763` \| Regulatory review - Pending \| \| `14764` \| Regulatory review - Blocked \| \| `14765` \| Receiver is unregistered \| \| `14766` \| Receiver is unconfirmed \| \| `14767` \| Receiver is a youth account \| \| `14800` \| POS cumulative sending limit exceeded \| | Reason code | Description | `1001` | Receiver's account is invalid | `1002` | Sender has insufficient funds | `1003` | User's country is not allowed | `1004` | User funding source is ineligible | `1005` | PENDING\_RECIPIENT\_NON\_HOLDING\_CURRENCY\_PAYMENT\_PREFERENCE(1005, "PENDING\_RECIPIENT\_NON\_HOLDING\_CURRENCY\_PAYMENT\_PREFERENCE", "This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout.") | `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 | `3501` | Email address invalid; try again with a valid email ID | `3535` | Invalid currency | `3547` | Sender's address is located in a restricted State (e.g., California) | `3558` | Receiver's address is located in a restricted State (e.g., California) | `3769` | Market closed and transaction is between 2 different countries | `4001` | Internal error | `4002` | Internal error | `8319` | Zero amount | `8330` | Receiving limit exceeded | `8331` | Duplicate mass payment | `9302` | Transaction was declined | `11711` | Per-transaction sending limit exceeded | `14159` | Transaction currency cannot be received by the recipient | `14550` | Currency compliance | `14761` | The mass payment was declined because the secondary user sending the mass payment has not been verified | `14763` | Regulatory review - Pending | `14764` | Regulatory review - Blocked | `14765` | Receiver is unregistered | `14766` | Receiver is unconfirmed | `14767` | Receiver is a youth account | `14800` | POS cumulative sending limit exceeded |
| Reason code | Description | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `1001` | Receiver's account is invalid | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `1002` | Sender has insufficient funds | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `1003` | User's country is not allowed | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `1004` | User funding source is ineligible | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `1005` | PENDING\_RECIPIENT\_NON\_HOLDING\_CURRENCY\_PAYMENT\_PREFERENCE(1005, "PENDING\_RECIPIENT\_NON\_HOLDING\_CURRENCY\_PAYMENT\_PREFERENCE", "This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout.") | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `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 | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `3501` | Email address invalid; try again with a valid email ID | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `3535` | Invalid currency | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `3547` | Sender's address is located in a restricted State (e.g., California) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `3558` | Receiver's address is located in a restricted State (e.g., California) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `3769` | Market closed and transaction is between 2 different countries | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `4001` | Internal error | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `4002` | Internal error | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `8319` | Zero amount | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `8330` | Receiving limit exceeded | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `8331` | Duplicate mass payment | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `9302` | Transaction was declined | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `11711` | Per-transaction sending limit exceeded | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14159` | Transaction currency cannot be received by the recipient | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14550` | Currency compliance | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14761` | The mass payment was declined because the secondary user sending the mass payment has not been verified | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14763` | Regulatory review - Pending | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14764` | Regulatory review - Blocked | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14765` | Receiver is unregistered | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14766` | Receiver is unconfirmed | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `14767` | Receiver is a youth account | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| `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 updates 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 [#recurring-payments]
The following variables identify the amounts and status associated with recurring transactions.
| 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 |
## Reference Transaction and Billing Agreements [#reference-transaction-and-billing-agreements]
Reference Transaction and Billing Agreements information identifies items about the transaction and billing agreement set by the merchant.
| 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. Possible values are `confirmed` and `unconfirmed`. |
| `address_street` | Customer's street address. Length: 200 characters. |
| `address_zip` | Zip code of customer's address. Length: 20 characters. |
| `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. Length: 127 characters. > **Note:** **Note:** The value of this variable is normalized to lowercase 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 |
| `discount` | The total discount to be applied to a shopping cart in the currency of `mc_currency`. |
| `first_name` | Customer's first name. Length: 64 characters. |
| `invoice` | Pass-through variable you can use to identify your invoice number for the 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. For example, `item_name1`, `item_name2`. 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. For example, `item_number1`, `item_number2`. Length: 127 characters. |
| `last_name` | Account 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_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_handling` | Total handling amount associated with the transaction. |
| `mc_shipping` | Total shipping amount associated with the transaction. |
| `memo` | Memo as entered by your customer in PayPal Website Payments Pro note field. Length: 255 characters. |
| `mp_currency` | The merchants primary currency. |
| `mp_custom` | Custom text passed by the merchant during `DoReferenceTransaction` call at creation. |
| `mp_cycle_start` | The month and day the agreement was created. |
| `mp_desc` | The agreement description set in `SetExpressCheckout` call. |
| `mp_id` | The encrypted billing agreement ID. |
| `mp_notification` | Sent to the merchant when an account is locked. All billing agreements for the account are canceled. |
| `mp_pay_type` | The accepted payment type. Possible values are `INSTANT`, `ANY`, and `ECHECK`. |
| `mp_status` | The agreement status. Possible values are `A` for an active agreement and `I` for an inactive agreement (equivalent to canceled). |
| `notify_version` | Message's version number. |
| `num_cart_items` | If this is a PayPal Shopping Cart transaction, number of items in cart. |
| `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. |
| `payer_status` | Whether the customer has a verified PayPal account. Possible values are `verified` or `unverified`. |
| `payment_date` | The PayPal-generated time and date stamp in the 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:** **Note:** This is a deprecated field. Use `mc_fee` instead. |
| `payment_type` | `echeck`: This payment was funded with an eCheck. `instant`: This payment was funded with PayPal balance, credit card, or Instant Transfer. |
| `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 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_eligibility` | The status of the seller's protection eligibility. Possible values: `Eligible`, `Ineligible`, `Partially Eligible—Unauth Only`, `PartiallyEligible`, `None`, `Active Fraud Control—Unauth Premium Eligible`. |
| `quantityx` | 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. For example, `quantity1`, `quantity2`). |
| `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. Length: 127 characters. > **Note:** **Note:** The value of this variable is normalized to lowercase characters. |
| `receiver_id` | Unique account ID of the payment recipient. For example, the merchant). This is the same as the recipient's referral ID. Length: 13 characters. |
| `residence_country` | ISO 3166 country code associated with the country of residence.
Length: 2 characters |
| `shipping_discount` | The discount amount for shipping charges in amount, not percentage. |
| `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. 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_subject` | A note or memo for the transaction. Applicable only after `notify_version >=2.6`. |
| `txn_id` | The merchant's original transaction identification number for the payment from the buyer, against which the case was registered. |
| `txn_type` | The type of transaction. Possible values are `merch_pmt`, `mp_cancel`, and `mp_signup`. |
| `verify_sign` | Encrypted string used to validate the authenticity of the transaction. |
## Subscription [#subscription]
Subscription information identifies the amounts and parameters associated with subscription transactions.
| Variable Name | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `amount3` | Amount 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_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. |
| `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 format `HH:MM:SS Mmm DD, YYYY PDT`. |
| `subscr_effective` | Date 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_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 |
### Summary of subscription variables [#summary-of-subscription-variables]
| Variable | Signup | Cancel | Modify | USD Payment | Multi-CurrencyPayment | Refund | 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 [#dispute-resolution]
The following variables identify the case ID and status of a dispute.
| Variable Name | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buyer_additional_information` | Notes the buyer entered into the Resolution Center. |
| `case_creation_date` | Date and time case was registered in the format `HH:MM:SS Mmm DD, YYYY PDT`. |
| `case_id` | Case identification number. > **Note:** **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:** **Note:** `bankreturn` is a deprecated value. |
| `reason_code` | Reason 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:** **Note:** `adjustment_reimburse` is a deprecated value.`billing`: Buyer claims that the received merchandise is unsatisfactory, defective, or damaged. > **Note:** **Note:** `billing` is a deprecated value. |
## Global shipping program message [#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.
| 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 [#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.
| Variable | Description |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transaction_type` | The 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. |
| `status` | The status of the payment. Value is:`CANCELED` — The [Preapproval](/archive/adaptive-payments/api/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_email` | Sender's email address. |
| `action_type` | Whether 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_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. Value is:`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. Value is:`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. 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_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. Value is:`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: `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: `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. 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). |
| `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. 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 [#preapproval-message]
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:** **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. Value is:`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: `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. |
| `currency_code` | The currency code. Value is:Australian Dollar — `AUD`.Brazilian Real — `BRL`. > **Note:** **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:** **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_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. Value is:`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 pre-approved maximum total amount of all payments. |
| `max_amount_per_payment` | The pre-approved maximum amount of all payments. |
| `max_number_of_payments` | The 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_type` | Whether a personal identification number (PIN) is required. Value is:`NOT_REQUIRED` — A PIN is not required.`REQUIRED` — A PIN is required. |
| `sender_email` | The sender's email address. |
## PDT-specific [#pdt-specific]
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. |