2Checkout Webhook

2Checkout Webhook

2Checkout sends Instant Payment Notifications (IPN) for order and payment lifecycle events and License Change Notifications (LCN) for subscription lifecycle events. Both arrive as application/x-www-form-urlencoded POST bodies; storage normalizes flat fields and bracket arrays (for example IPN_PID[]) into JSON in export.json. Each POST is one stored delivery. Tools are read-only — query what already landed; do not assume every field is present on every delivery.

First moves

1. Latest report — default for “what order or subscription event arrived last”.
2. Inspect export.json — identify IPN vs LCN, then read status and reference fields.
3. Recent reports — compare REFNO, LICENSE_CODE, or MESSAGE_ID when debugging duplicates or missed events.
4. One report by id — after listing, when the user names a specific notification.

IPN vs LCN

• IPN (orders/payments) — look for REFNO, ORDERSTATUS, and MESSAGE_TYPE. Product lines use IPN_PID[], IPN_PNAME[], IPN_PCODE[], IPN_QTY[], IPN_PRICE[], IPN_TOTAL[], and IPN_TOTALGENERAL.
• LCN (subscriptions/licenses) — look for LICENSE_CODE, STATUS, and DISPATCH_REASON. Customer contact fields use FIRST_NAME, LAST_NAME, EMAIL (not the IPN billing FIRSTNAME/CUSTOMEREMAIL names).

The same ingest endpoint may receive both notification types.

IPN fields worth reading

Order identity and timing

• REFNO — 2Checkout order reference (primary dedupe key with MESSAGE_TYPE).
• REFNOEXT — merchant-controlled external order reference.
• ORDERNO — incremental order counter visible in the merchant account.
• SALEDATE, PAYMENTDATE, COMPLETE_DATE — placement, authorization, and completion timestamps (Y-m-d H:i:s).
• TEST_ORDER — 1 test, 0 live.

Status and event type

• ORDERSTATUS — lifecycle state such as PENDING, PAYMENT_AUTHORIZED, PAYMENT_RECEIVED, COMPLETE, REFUND, REVERSED, CANCELED, PURCHASE_PENDING.
• MESSAGE_TYPE — event that triggered the notification, such as APPROVED, AUTH, COMPLETE, REFUND, CHARGEBACK_OPEN, CHARGEBACK_CLOSED, CANCELED, PENDING, PROCESSING. On some payment methods (for example SEPA Direct Debit) MESSAGE_TYPE and ORDERSTATUS combinations differ from card flows — read both, do not infer one from the other.
• MESSAGE_ID — incremental sequence per message type; useful when the same order posts multiple events.

Payment and totals

• PAYMETHOD, PAYMETHOD_CODE — human label and code (for example CCVISAMC, PAYPAL, WIRE).
• CURRENCY, IPN_TOTALGENERAL, IPN_SHIPPING, IPN_COMMISSION.
• CARD_TYPE, CARD_LAST_DIGITS, CARD_EXPIRATION_DATE — present for card payments; empty otherwise.

Line items and subscriptions on the order

• IPN_PID[], IPN_PNAME[], IPN_PCODE[], IPN_SKU[] — product id, name, merchant code, SKU per line.
• IPN_QTY[], IPN_PRICE[], IPN_VAT[], IPN_TOTAL[] — quantity, unit price, tax, line total.
• IPN_LICENSE_REF[], IPN_LICENSE_TYPE[], IPN_LICENSE_EXP[], IPN_LICENSE_LIFETIME[] — subscription references on the order (REGULAR, RENEWAL, UPGRADE, TRIAL).
• IPN_DELIVEREDCODES[] — fulfillment codes when electronic delivery applies.

Customer and affiliate

• Billing: FIRSTNAME, LASTNAME, COMPANY, CUSTOMEREMAIL, ADDRESS1, CITY, STATE, ZIPCODE, COUNTRY, COUNTRY_CODE, PHONE.
• Delivery (gift/recipient): parallel *_D fields such as FIRSTNAME_D, EMAIL_D, ADDRESS1_D.
• IPADDRESS, IPCOUNTRY — shopper network origin.
• IPN_RESELLER_ID, IPN_RESELLER_NAME, IPN_RESELLER_COMMISSION — affiliate attribution when present.

Disputes and refunds

• CHARGEBACK_RESOLUTION — OPEN, WON, LOST, ACCEPTED, or NONE.
• CHARGEBACK_REASON_CODE — dispute reason when a chargeback exists.
• REFUND_REASON, REFUND_TYPE — TOTAL or PARTIAL on refund notifications; empty otherwise.

Other

• GIFT_ORDER — 1 when the purchase is a gift.
• EXTERNAL_CUSTOMER_REFERENCE, 2CHECKOUT_CUSTOMER_REFERENCE — merchant vs system customer ids.
• IPN_DATE — notification timestamp (YmdHis); distinct from order dates above.
• SIGNATURE_SHA2_256, SIGNATURE_SHA3_256 — validation digests included when enabled upstream.

LCN fields worth reading

Subscription identity and state

• LICENSE_CODE — primary subscription identifier.
• STATUS — ACTIVE, CANCELED, EXPIRED, PASTDUE, PAUSED, PENDING_ACTIVATION.
• DISPATCH_REASON — why the LCN fired, such as LICENCE_CHANGE, LICENCE_EXPIRATION, LICENCE_PASTDUE, LICENCE_CC_CHANGE, LICENCE_IMPORT, LICENCE_CPC_ACCEPTED, LICENCE_GP_CHANGE, LICENCE_PENDING_ACTIVATION, or scheduled cancellation codes.
• TEST — 1 test subscription, 0 live.

Dates and billing cycle

• START_DATE, PURCHASE_DATE, EXPIRATION_DATE — subscription start, initial purchase, and expiry (9999-12-31 23:59:59 for lifetime).
• DATE_UPDATED — last logged subscription change.
• NEXT_RENEWAL_DATE, NEXT_RENEWAL_PRICE, NEXT_RENEWAL_CURRENCY — upcoming renewal when present.
• BILLING_CYCLES, CONTRACT_CYCLES, CURRENT_BILLING_CYCLE, BILLING_CYCLES_LEFT — contract and renewal counters for configured subscriptions.
• RECURRING — 1 auto-renewing, 0 manual renewal required.
• LICENSE_TYPE — REGULAR or TRIAL; IS_TRIAL mirrors trial flag.
• LICENSE_LIFETIME — 1 evergreen, 0 term subscription.

Product and order links

• LICENSE_PRODUCT, LICENSE_PRODUCT_CODE, PSKU, PRODUCT_EXTERNAL_REFERENCE.
• ORIGINAL_ORDER_REFERENCE, LAST_ORDER_REFERENCE — tie back to IPN order refs.
• LCN_LICENSE_OPTIONS_TEXT[], LCN_LICENSE_OPTIONS_VALUE[], LCN_LICENSE_OPTIONS_PRICE[] — active pricing options; usage-scale groups may include consumed units (for example GBs: 100).

Customer and change metadata

• FIRST_NAME, LAST_NAME, EMAIL, COMPANY, ADDRESS, CITY, STATE, ZIP, COUNTRY.
• EXTERNAL_CUSTOMER_REFERENCE, AVANGATE_CUSTOMER_REFERENCE.
• CHANGED_BY — CUSTOMER, VENDOR, or SYSTEM.
• DISABLED — 1 disabled, 0 enabled.
• MESSAGE_ID — LCN sequence number.

Response shape

• export.json — normalized urlencoded fields; bracket keys become JSON arrays.
• source.captured_at — when the POST landed here (not the same as SALEDATE, IPN_DATE, or EXPIRATION_DATE).
• export.text — raw body fallback when JSON parsing is limited.

Operational order

1. Start with the latest report — do not guess a report id.
2. Determine IPN vs LCN from key fields before interpreting status.
3. For order questions, anchor on REFNO + MESSAGE_TYPE; for subscription questions, anchor on LICENSE_CODE + DISPATCH_REASON.
4. List recent reports only for history, duplicate suspicion, or compare-by-date asks.
5. Read ## This connection in the skill supplement for merchant-specific field enablement notes.

Gotchas

• Read-only — cannot acknowledge, refund, renew, or mutate 2Checkout state from here.
• Opt-in fields — merchants enable Response Tags upstream; missing keys are normal, not ingestion failure.
• Array indexing — line-item and license arrays share index positions (IPN_PID[0] aligns with IPN_PNAME[0], etc.).
• Duplicate POSTs — the same order may generate multiple IPNs (MESSAGE_TYPE advances); compare REFNO, MESSAGE_ID, and source.captured_at.
• IPN + LCN pairs — new purchases, renewals, and upgrades often trigger both; read the latest of each type when the user asks about “the order” vs “the subscription”.
• Test traffic — check TEST_ORDER (IPN) or TEST (LCN) before treating amounts or customer data as production.
• Empty — no stored reports means nothing has arrived yet.