IPN parameters
Overview
Depending on your IPN settings, notifications contain all or a subset of the available parameters.
2Checkout sends IPN parameters exemplified in this article.
Parameter values for the Credit card flow: "ORDERSTATUS": "PAYMENT_RECEIVED" / "MESSAGE_TYPE": "APPROVED".
Parameter values for the SEPA Direct debit flow: "ORDERSTATUS": "PAYMENT_RECEIVED" / "MESSAGE_TYPE": "PROCESSING".
IPN Parameters
Parameter | Description | Type/Length | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
GIFT_ORDER |
Allows shoppers to gift the subscription/product acquired to the recipient specified using the delivery details during the purchase process. Possible values:
|
Integer/1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SALEDATE | Y-m-d H:i:s. The datetime stamp when shoppers place orders (e.g.: 2008-06-22 19:33:28) (e.g.: 2013-12-01 01:00:24) | String/19 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PAYMENTDATE | Y-m-d H:i:s. The datetime stamp when payment processors authorize a transaction for an order 2Checkout approved (e.g.: 2008-06-22 14:30:24) (e.g.: 2013-12-01 01:00:24) | String/19 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
COMPLETE_DATE | Y-m-d H:i:s. The datetime stamp when orders reach Complete status (2Checkout received payments and marked the order as fulfilled, if necessary). (e.g.: 2008-06-22 14:41:30) (e.g.: 2013-12-01 01:00:24) | String/19 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
REFNO | Unique, system-generated 2Checkout order reference. | Integer/9 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
REFNOEXT | The order reference code (max. 100 chars) you control. You can attach an external reference number to orders during the purchase process. | String/100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SHOPPER_REFERENCE_NUMBER | The internal reference number your customers assign to orders during the checkout process. Customers using Purchase Orders (POs) as the payment method during the ordering process have the option of setting identifiers for their orders to track and manage purchases in their own system. | String/255 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ORIGINAL_REFNOEXT |
Available for subscription renewals. Array of REFNOEXT (the external order reference - max. 100 chars) values set for the initial orders when the subscriptions were first acquired. |
String/100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ORDERNO | Order counter (numeric, incremental). Visible in your account in the Order search area. | Integer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ORDERSTATUS |
Current order status. Possible values are: • PENDING - Order placed, waiting bank authorization. • PAYMENT_AUTHORIZED – The bank authorized the payment. • SUSPECT – 2Checkout is reviewing the order having flagged it as a potential fraud attempt. Note: Not available by default. Contact 2Checkout directly to start receiving this order status. • INVALID – Invalid Billing/Delivery information. • COMPLETE – 2Checkout marked the order as complete. • REFUND – 2Checkout refunded the money paid back to the shopper. 2Checkout can only refund complete orders. • REVERSED – 2Checkout reversed a transaction and released the money back to the customer. 2Checkout can only reverse authorized orders that never reach the complete status. • PURCHASE_PENDING – Sent for orders placed using Purchase Orders after you approve the PO. 2Checkout is waiting for the customer to make the payment. • PAYMENT_RECEIVED – 2Checkout sends this notification when it received payment for orders with offline payment methods such as bank/wire transfer. • CANCELED - The 2Checkout system sends out notifications when:
• PENDING_APPROVAL - 2Checkout has yet to approve this order. |
String/22 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PAYMETHOD | Order payment method. | String/255 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PAYMETHOD_CODE |
Payment method code. Possible values:
|
String/250 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CARD_TYPE |
Shopper card type. When shoppers use multiple cards, 2Checkout includes the type of the last card used in the IPN - e.g. "Visa". Empty for non-card transactions. |
String/255 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CARD_LAST_DIGITS |
The last 4 digits of the shopper credit/debit card. When shoppers use multiple cards, 2Checkout includes the last four digits of the last card used in the IPN - e.g. "Visa". Empty for non-card transactions. |
String/4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CARD_EXPIRATION_DATE | MM/YY. Card expiration month and the year. | String/5 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FX_RATE | Value of the exchange rate locked when the order reaches the Complete status. Includes the 2Checkout markup. | Float Number/100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FX_MARKUP | 2Checkout exchange rate markup. | Float Number/100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PAYABLE_AMOUNT | Net profit in payout currency. | Float Number/100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PAYOUT_CURRENCY | Your account's default payout currency. | String/3 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SHIPPING_TRACKING_NO | The tracking number requested as optional information when the order was marked as shipped. | String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SHIPPING_COMMENTS | Additional information requested as optional when the order was marked as shipped. | String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SHIPPING_TRACKING_URL | The Tracking URL defined when creating a shipping method. | String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SHIPPING_METHOD_NAME | Name of the shipping method used during the order. | String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SHIPPING_STATUS |
Order shipment status. Possible values:
|
String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CHARGEBACK_RESOLUTION |
Chargeback status information. Possible values: · OPEN (chargeback is in progress) · WON (chargeback won by you) · LOST (chargeback won by the customer) · ACCEPTED (you agreed to repay the value of the order to the customer) · NONE (no chargeback initiated for the order) To manage chargeback notifications navigate to Control Panel Dashboard →Integrations → Webhooks and API, and click on the IPN settings tab. In the General IPN Settings section, under Triggers, make sure to check the boxes next to the following options: · chargeback open (2Checkout sends an IPN when shoppers open a chargeback dispute). · chargeback closed - (2Checkout sends an IPN when the parties involved resolve a chargeback dispute). Also, check the checkbox next to the CHARGEBACK_RESOLUTION parameter featured in the Response tags area. |
String/8 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CHARGEBACK_REASON_CODE |
Identifier for the chargeback dispute reason from the 2Checkout system. Empty for orders with no chargeback dispute initiated. Possible values:
|
String/24 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TEST_ORDER |
Possible values: • 1 - for test orders • 0 - for real orders |
Integer/1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GATEWAY_RESPONSE | Forwards the payment gateway response received as a part of the card authorization process. Contact 2Checkout directly if the GATEWAY_RESPONSE parameter is not available in the list under the Notification Details area on the IPN settings page. Log into your Control Panel account and access this link to download a list of all gateway responses. | String/255 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IPN_ORDER_ORIGIN |
Source of the order placed. Possible values:
|
String/17 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
REFUND_REASON |
Refund reason. Possible value can be one of the refund reasons defined in the platform:
If you have set your own refund reasons, the value corresponds to the reasons selected in the refund process from your customized reasons. Click here to learn how to customize your refund reasons. |
String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FRAUD_STATUS |
Possible values:
|
String/12 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
MESSAGE_ID | The number generated incrementally for each sequence of message type sent to a seller. | Integer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
MESSAGE_TYPE |
The name of the event triggering the notification.
|
String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
VENDOR_CODE | Unique merchant identifier generated by the 2Checkout system. | String | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PROPOSAL_ID | The unique identifier of the proposal generating the order. Can be found in Order additional information as text. | String |
CUSTOMER BILLING INFORMATION | Type/Length | |
---|---|---|
FIRSTNAME | Customer first name | String/40 |
LASTNAME | Customer last name | String/40 |
COMPANY | Company Name | String/40 |
REGISTRATIONNUMBER | Company registration number | String/50 |
FISCALCODE | Company VAT ID / Tax ID | String/50 |
CBANKNAME | Company bank name | String/40 |
CBANKACCOUNT | Company bank account | String/50 |
ADDRESS1 | Address | String/100 |
ADDRESS2 | More address information | String/100 |
CITY | City | String/30 |
STATE | State/County | String/30 |
ZIPCODE | Zip code | String/30 |
COUNTRY | Country | String/50 |
COUNTRY_CODE | Country code | String/2 |
PHONE | Phone number | String/40 |
FAX | Fax number | String/40 |
CUSTOMEREMAIL | Customer email address | String/40 |
CUSTOMER DELIVERY INFORMATION | Type/Length | |
---|---|---|
FIRSTNAME_D | First name | String/40 |
LASTNAME_D | Last name | String/40 |
COMPANY_D | Company name | String/50 |
ADDRESS1_D | Address | String/100 |
ADDRESS2_D | Extra address information | String/100 |
CITY_D | City | String/30 |
STATE_D | State/County | String/30 |
ZIPCODE_D | Zip code | String/20 |
COUNTRY_D | Country | String/50 |
COUNTRY_D_CODE | Country code | String/2 |
PHONE_D | Telephone number | String/40 |
EMAIL_D | Email address for delivery | String/80 |
IPADDRESS | Customer IP address | String/250 |
IPCOUNTRY | Country name, based on the user IP address | String/50 |
CUSTOM ORDER INFORMATION | Type/Length | |
---|---|---|
TIMEZONE_OFFSET | The time zone you selected or the default GMT+02:00 time zone of the 2Checkout system. | String/9 |
CURRENCY |
Currency used in order. Possible values: • USD Depending on your account settings, other currencies might be available. |
String/3 |
CUSTOM_PRICE |
Array of strings. Allows you to see how the custom price is calculated and is included in the IPN message you receive after an order. It contains the following variables:
Example :
|
String/255 |
LANGUAGE |
Payment interface language. Current possible values:
|
String/2
String/5 |
ORDERFLOW |
The type of ordering flow used for placing the order. Available values: • PURCHASE_ORDER (when customers use a Purchase Order). • REGULAR (default, with the exception of scenarios in which customers use POs). |
String/30 |
IPN_PID[] | Array of products identifiers, within current order, from 2Checkout system (unique, system-generated product reference codes). | Array of Integers |
IPN_PNAME[] | Array with products names. | Array of Strings |
IPN_PCODE[] | Array with the reference codes you configure and control for products. (seller reference) | Array of Strings/100 |
IPN_INFO[] | Array with extra information for each product within current order. | Array of Strings/100 |
IPN_QTY[] | Array with the number of units purchased. | Array of Integers/3 |
IPN_PRICE[] | Array with prices for each product (excluding tax), with dot as float separator. | Array of Float Numbers |
IPN_VAT[] | Array with the tax values for each product. | Array of Float Numbers |
IPN_VAT_RATE[] | Array with the tax rate as percentages for each product. | Array of Float Numbers/100 |
IPN_VER[] | Array with the version of each product. | Array of Strings/50 |
IPN_DISCOUNT[] | Array with discount values within a promotion, including taxes. | Array of Float Numbers |
IPN_PROMONAME[] | Array with names you configured for promotions. | Array of Strings/100 |
IPN_SKU[] | Array with product SKU codes. | Array of Strings/255 |
IPN_LICENSE_PROD[] | Array with unique, system-generated product references for which 2Checkout generates subscription for a purchase (either new subscriptions or renewals). | Array of Integers/11 |
IPN_LICENSE_TYPE[] |
Array with the type of subscription purchased for each product. Possible values: • REGULAR (new license) |
Array of Strings/7 |
IPN_LICENSE_REF[] | Array with unique, system-generated subscription references. You can use them to build renewal links. | Array of Strings/10 |
IPN_LICENSE_EXP[] | Array with subscription expiration dates. | Array of Strings/19 |
IPN_LICENSE_ADDITIONAL_INFO | Array with license additional information | Array of Strings |
IPN_DELIVEREDCODES[] | Array with codes delivered to customers when using 2Checkout Delivery. | Array of Strings/256 |
IPN_DOWNLOAD_LINK | Download link delivered to customers. | String/50 |
IPN_BUNDLE_DETAILS_1234_PID | Array with the unique identifiers of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Integers/11 |
IPN_BUNDLE_DETAILS_1234_PNAME | Array with the names of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Strings/155 |
IPN_BUNDLE_DETAILS_1234_PCODE | Array with the codes you control of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Strings/100 |
IPN_BUNDLE_DETAILS_1234_QTY | Array with the quantity of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Integers/3 |
IPN_BUNDLE_DETAILS_1234_SKU | Array with the SKUs of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Strings/255 |
IPN_BUNDLE_DETAILS_1234_PGROUP | Array with the group IDs of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Integers/11 |
IPN_BUNDLE_DETAILS_1234_PGROUP_NAME | Array with the names of the products included in the bundle, where 1234 represents the 2Checkout product ID. | Array of Strings/100 |
IPN_BUNDLE_DELIVEREDCODES_1234[] | Array with delivery information for each product included in the bundle. | Array of Strings/30 |
IPN_ORDER_COSTS[] | Array with DIS and Backup Media costs per each product in the order (in the order currency). | Array of Float Numbers |
IPN_PCOMMISSION[] | Affiliate product commission, using dot (.) as float separator. | Array of Float Numbers |
IPN_TOTAL[] | Partially total on order line (including taxes), using dot (.) as float separator. | Array of Float Numbers |
IPN_TOTALGENERAL | Total transacted sum, including shipping and VAT, using dot (.) as float separator, expressed in the same currency as the CURRENCY field. | Float Number |
IPN_PROMO_IDCODE[] | Promotion code automatically generated by adding a new promotion. | Array of Float Number |
IPN_PARTNER_MARGIN_PRODUCTS_PERCENT[] | Percentage configured as margin for partners. | Array of Float Number |
IPN_SHIPPING | Shipping costs, expressed in the same currency as the CURRENCY field, using dot (.) as float separator. | Float Number |
IPN_GLOBALDISCOUNT | Global order discount. It is an optional field that is sent only for values greater than 0. | Float Number |
IPN_COMMISSION | 2Checkout commission, using dot (.) as float separator. | Float Number |
IPN_CUSTOM_TEXT[] | Array with all the custom fields texts set per order. For example: "Do you agree with the return policy?". | Array of Strings |
IPN_CUSTOM_VALUE[] | Array with all client input corresponding for the text. For example: "Yes". | Array of Strings |
IPN_CUSTOM_1234_TEXT[] | Array with all the custom fields texts set per product, where1234 represents the product ID. | Array of Strings |
IPN_CUSTOM_1234_VALUE[] | Array with all client input corresponding for the text, where 1234 represents the product ID. | Array of Strings |
IPN_PRODUCT_OPTIONS_1234_TEXT[] |
Array with the names of all the price options, where 1234 represents the 2Checkout product ID. For usage scale pricing option groups, 2Checkout returns the name of the pricing options as well as the number of units of metered resources consumed by the customer. Format: 'PricingOptionsGroupName: NumberOfUnitsConsumed', for example 'GBs: 100'. |
Array of Strings/250 |
IPN_PRODUCT_OPTIONS_1234_VALUE[] |
Array with unique codes set up for the pricing option groups, where1234 represents the product ID. In the case of usage scale pricing options groups, 2Checkout return both the unique code of the group as well as the number of units of metered resources consumed by the customer. Format: 'UniqueCode: NumberOfUnitsConsumed', for example 'meteredGBs: 100'. |
Array of Strings/250 |
IPN_PRODUCT_OPTIONS_1234_OPTIONAL_VALUE[] |
Array with optional codes (unique for pricing option group), where 1234 represents the product ID. In the case of usage scale pricing options groups, 2Checkout returns both the unique code of the group as well as the number of units of metered resources consumed by the customer. Format: 'UniqueCode: NumberOfUnitsConsumed', for example 'meteredGBs: 100'. |
Array of Strings/250 |
IPN_PRODUCT_OPTIONS_1234_PRICE[] |
Array with all prices corresponding to each option (prices are in the order currency), where 1234 represents the product ID. In the case of usage scale pricing options groups, it will return the price of the metered resources consumed by the customer in the order currency. |
Array of Float Numbers |
IPN_PRODUCT_OPTIONS_1234_OPERATOR[] |
Array with all price operators corresponding to each price option, where 1234 represents the product ID • ADD |
Array of Strings/9 |
IPN_PRODUCT_OPTIONS_1234_USAGE[] |
Designed to differentiate usage pricing options groups from non-usage pricing options groups. Possible values: • PREPAID - for orders involving products with pricing options groups of the following type: Radio, Dropdown, Checkbox and Scale (but without a metered cost component (usage scale pricing)). |
String/8 |
IPN_REFERRER | The last URL accessed by the shopper before landing in the 2Checkout cart. | String/255 |
IPN_LINK_SOURCE | The link source for the sales. The SRC parameter used to track every sale point generator. | String/255 |
IPN_RESELLER_ID | Affiliate ID that referred the sale. | Integer/9 |
IPN_RESELLER_NAME | Affiliate name | String/50 |
IPN_RESELLER_URL | Affiliate website | String/100 |
IPN_RESELLER_COMMISSION | Affiliate total commission, using dot(.) as float separator. | Float Number |
IPN_LICENSE_LIFETIME[] |
Array indicating the products shoppers purchased opting for the lifetime/evergreen option. Possible values: • YES = lifetime subscription |
Array of Strings/3 |
IPN_PARTNER_CODE |
Possible values:
|
String/255 |
2CHECKOUT_CUSTOMER_REFERENCE | Default customer numerical (integer) IDs generated automatically by the 2Checkout system. Read more here. | Integer/11 |
EXTERNAL_CUSTOMER_REFERENCE | Unique customer alphanumeric (string) identifiers that you control. Read more here. | String/255 |
REFUND_TYPE |
This parameter, sent along with the notifications provided for orders placed in the 2Checkout system, offers additional info for refunds processed. REFUND_TYPE describes the type of the refund, total or partial. As such, the parameter can have two possible values:
REFUND_TYPE is empty for orders that are not refunds. |
String/7 |
IPN_PARTNER_MARGIN_PERCENT | Percentage configured as margin for partners. | Float Number |
IPN_PARTNER_MARGIN | Value deducted from the cost of orders, corresponding to the margin configured for partners. | Float Number |
IPN_EXTRA_MARGIN | Value deducted from the cost of the order corresponding to the extra margin offered to a partner for the purchase. | Float Number |
IPN_EXTRA_DISCOUNT | The value deducted from the cost of the order, corresponding to the extra discount offered to the partner for the purchase. | Float Number |
IPN_COUPON_DISCOUNT | The value of the discount deducted from the cost of the order, corresponding to the promotion coupon used by the partner for the purchase. | Float Number |
IPN_EXTERNAL_REFERENCE | Array with seller reference code for order products (seller reference). | Array of Strings |
IPN_PROMOCODE | Promotion codes for the above IPN_DISCOUNT. | Array of Float Numbers |
IPN_PGROUP | Product group ID. | Array of Strings |
IPN_PGROUP_NAME | Product group name. | Array of Strings |
IPN_LICENSE_START | Array with product subscription start dates. | Date/14 |
IPN_SHIPPING_TAX | Shipping tax expressed in the same currency as the CURRENCY field. | Number |
TAX_OFFICE | Tax office code (IPN_CODE_TAX_OFFICE) | String |
IPN_PROMOTION_CATEGORY[] |
Array with the category of the promotions you configured and are included in the order. Possible values:
|
Array of Strings |
VALIDATION INFORMATION | ||
IPN_DATE | IPN notification date in the YmdHis format. (ex: 20081117145935) (ex: 20131201010024) | Date/14 |
HASH |
Calculated HMAC_MD5 signature based on the sent IPN fields and the secret key. (Note: This parameter won't be used anymore for IPN validation as of 15th of August, 2024.) |
String/32 |
SIGNATURE_SHA2_256 | Calculated HMAC_SHA2_256 signature based on the sent IPN fields and the secret key. | String/64 |
SIGNATURE_SHA3_256 | Calculated HMAC_SHA3_256 signature based on the sent IPN fields and the secret key. | String/64 |
IPN_PURCHASE_ORDER_INFO | Order status and details for Purchase order acquisitions. | String |
IPN_ORIGINAL_LINK_SOURCE[] | Array of IPN_LINK_SOURCE (link source, the SRC parameter) values for the initial orders when the subscriptions were first acquired. Available for subscription renewals. | String |
CUSTOM_FIELDS | Additional order fields (dynamic variables). In your Merchant Control Panel, navigate to Setup - Ordering options - Additional order fields. | String |