2Checkout Webhook MCP Server

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.