> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysight.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Paysight provides a webhook-based integration for clients to receive near real-time batched notifications for billing and subscription events.

## Configuration

Clients can configure individual webhook URLs per event type at [Paysight Account Settings](https://app.paysight.io/settings/account)

## Available Event Types

| Event Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **New Transaction**        | Triggered when a new billing event occurs (authorize, sale, refund, chargeback, or alert).                                                                                                                                                                                                                                                                                                                             |
| **Updated Transaction**    | Triggered when an existing authorized transaction is captured or cancelled.  The `status`, `statusId` and `completed` fields will be updated. Please note: You will not receive an updated transaction for transactions that are refunded / charged back. You will receive these in the New Transaction event webhook as they are a separate transaction but can be linked back to the original tranaction (see above) |
| **New Subscription**       | Triggered when a new customer subscription is created.                                                                                                                                                                                                                                                                                                                                                                 |
| **Cancelled Subscription** | Triggered when a subscription is cancelled.                                                                                                                                                                                                                                                                                                                                                                            |
| **Chargeback Alert**       | Raw unmatched chargeback alerts from mitigation provider.                                                                                                                                                                                                                                                                                                                                                              |
| **Chargeback**             | Raw unmatched chargeback records reported against the client.                                                                                                                                                                                                                                                                                                                                                          |

<Note>
  For **New Transaction** event type, the important properties are:

  * `transactionId`
  * `orderId`
  * `originalTransactionId` - if the transaction is a Refund, Chargeback Alert or Chargeback then the OriginalTranactionId will be provided which references the tranaction that was refunded/charged back
    These transactions can be identfied via the applicationId property listed below and will have a negative `amount` value:
    * Refund - `applicationId` = 200
    * Chargeback - `applicationId` = 201
    * Chargeback Alert - `applicationId` = 202
</Note>

## Delivery & Performance

* **HTTP Method**: Webhooks are delivered via `HTTP POST` to the configured URLs.
* **Batch Delivery**: Webhooks are sent as arrays of event objects.
* **Response Time**: Your server must respond with HTTP 200 OK within 2 seconds.
* **No Inline Processing**: Please queue events for asynchronous processing.

## Payload Structure

### New Transaction / Updated Transaction

<Info>
  Session correlation fields for transaction webhooks:

  * `paysightSession`: Paysight-generated session identifier
  * `partnerSession`: your external session/click/visit identifier from Card Submit `partnerSession`
  * Widget integrations: Widget `sessionId` is sent to Card Submit as `partnerSession`
</Info>

```json theme={null}
[
    {
      "gateway": "NMI",
      "transactionId": "90a0bbed-752a-4445-8112-b44de14a865c",
      "orderId": 193777233,
      "sent": "2025-06-18T16:01:04",
      "email": "johnsmith@hotmail.com",
      "sandbox": false,
      "applicationId": 6,
      "status": "None",
      "statusId": 0,
      "success": false,
      "completed": "2025-06-18T16:01:04",
      "currency": "USD",
      "amount": 0,
      "mid": "56220000192222",
      "descriptor": "genericthing.com",
      "customerId": 39306678,
      "authCode": "",
      "gatewayTransactionId": "",
      "firstName": "John",
      "lastName": "Smith",
      "bin": "468831",
      "last4": "9471",
      "refunded": false,
      "refundable": false,
      "hasAlert": false,
      "chargedBack": false,
      "application": "Sub Start",
      "applicationId2": 216,
      "application2": "Opt In",
      "shopId": 0,
      "storeName": "",
      "storeDomain": "",
      "storeRootDomain": "",
      "merchantAccountId": 831,
      "midName": "US - Generic Merchant - CBCal",
      "companyId": 182,
      "company": "Acme Limited",
      "parentCompanyId": 981,
      "subscriptionId": 8402,
      "subscription": "Acme Subscription",
      "refundSourceId": 0,
      "alertTypeId": 0,
      "alertSourceId": 0,
      "submitOrderId": 193777261,
      "alertSource": "Unassigned",
      "alertType": "Unassigned",
      "refundSource": "Unassigned",
      "binCountry": "US",
      "ipCountry": "US",
      "campaignId": 0,
      "campaign": "None/Unassigned",
      "affiliateId": 0,
      "affiliate": "None",
      "productId": 8469,
      "product": "Acme Main Landing Page",
      "paymentNumber": 0,
      "attempt": 1,
      "originalTransactionId": null,
      "containsSalesStrategy": false,
      "networkTokenized": false,
      "chargebackFee": 0,
      "cardBrandId": 1,
      "cardBrand": "Visa",
      "eci": "02",
      "paysightSession":"202602231518583780223233",
      "partnerSession":"fds9Pam2fj-291",
      "applePay": true,
      "googlePay": false
    }
]
```

#### Field Descriptions for Transaction Events

<ParamField query="gateway" type="string">
  NMI/Payon/EmerchantPay etc
</ParamField>

<ParamField query="transactionId" type="string">
  Paysight’s unique identifier for the transaction (also referred to as messageId)
</ParamField>

<ParamField query="orderId" type="number">
  The unique order refrerence to which the transaction relates. This will match the orderId returned in the original widget/card submit response
</ParamField>

<ParamField query="sent" type="string">
  Timestamp in GMT when transaction was initiated
</ParamField>

<ParamField query="email" type="string">
  User Email address
</ParamField>

<ParamField query="sandbox" type="boolean">
  Indicates if transaction was simulated (sandbox=true) or real (sandbox=false)
</ParamField>

<ParamField query="applicationId" type="number">
  Paysight’s unique identifier of the transaction type
</ParamField>

<ParamField query="status" type="string">
  Status of the transaction
</ParamField>

<ParamField query="statusId" type="number">
  Paysight’s unique identifier of the status of the transaction
</ParamField>

<ParamField query="success" type="boolean">
  Indicates if the billing event was successful (fully captured funds or successful refund etc)
</ParamField>

<ParamField query="completed" type="string">
  Timestamp in GMT when transaction was finalized
</ParamField>

<ParamField query="currency" type="string">
  Transaction currency (e.g ‘USD’)
</ParamField>

<ParamField query="amount" type="number">
  Transaction amount (e.g 9.99)
</ParamField>

<ParamField query="mid" type="string">
  Merchant Account Identifier
</ParamField>

<ParamField query="descriptor" type="string">
  Merchant Account Descriptor
</ParamField>

<ParamField query="customerId" type="number">
  Paysight Customer Id
</ParamField>

<ParamField query="authCode" type="string">
  Gateway Authorization code
</ParamField>

<ParamField query="gatewayTransactionId" type="string">
  Gateway Transaction Id
</ParamField>

<ParamField query="firstName" type="string">
  Customer First Name
</ParamField>

<ParamField query="lastName" type="string">
  Customer Last Name
</ParamField>

<ParamField query="bin" type="string">
  Card Bin (first 6 digits)
</ParamField>

<ParamField query="last4" type="string">
  Card Last 4 digits
</ParamField>

<ParamField query="refunded" type="boolean">
  Indicates if Transaction has been refunded
</ParamField>

<ParamField query="refundable" type="boolean">
  Indicates if Transaction is refundable
</ParamField>

<ParamField query="hasAlert" type="boolean">
  Indicates if Transaction has a related Charegack alert
</ParamField>

<ParamField query="chargedBack" type="boolean">
  Indicates if Transaction was charged back
</ParamField>

<ParamField query="application" type="string">
  Paysight Transaction Type
</ParamField>

<ParamField query="applicationId2" type="number">
  Paysight Transaction Type 2 (classifies transactions in a similar way to above with some specific differences. Speak to support team for more info)
</ParamField>

<ParamField query="application2" type="string">
  Identifier for above. Speak to support team for more info)
</ParamField>

<ParamField query="shopId" type="number">
  Shopify Store Id (if applicable)
</ParamField>

<ParamField query="storeName" type="string">
  Shopify Store Name (if applicable)
</ParamField>

<ParamField query="storeDomain" type="string">
  Shopify Store Domain (if applicable)
</ParamField>

<ParamField query="storeRootDomain" type="string">
  Shopify Store Root Domain (if applicable)
</ParamField>

<ParamField query="merchantAccountId" type="number">
  Paysight Identifier for Merchant Account
</ParamField>

<ParamField query="midName" type="string">
  MID Name/Title/Description
</ParamField>

<ParamField query="companyId" type="number">
  Merchant Account Company Identifier
</ParamField>

<ParamField query="company" type="string">
  Merchant Account Company
</ParamField>

<ParamField query="parentCompanyId" type="number">
  Paysight Tenant Identifier (ClientId)
</ParamField>

<ParamField query="subscriptionId" type="number">
  Paysight Subscription Identifier
</ParamField>

<ParamField query="subscription" type="string">
  Paysight Subscription Name
</ParamField>

<ParamField query="refundSourceId" type="number">
  Identifier for Refund Source (if applicable)
</ParamField>

<ParamField query="alertTypeId" type="number">
  Identifier for Alert Type (if applicable)
</ParamField>

<ParamField query="alertSourceId" type="number">
  Identifier for Alert Source (if applicable)
</ParamField>

<ParamField query="submitOrderId" type="number">
  Unique identifier of Card Submit event
</ParamField>

<ParamField query="alertSource" type="string">
  Chargeback Mitigation Provider (e.g Kount)
</ParamField>

<ParamField query="alertType" type="string">
  Chargeback Alert Type, e.g RDR, Ethoca, CDRN
</ParamField>

<ParamField query="refundSource" type="string">
  Source of Refund (if applicable) e.g Alert Related, Customer Service etc
</ParamField>

<ParamField query="binCountry" type="string">
  Country Code associated with issuing Bin
</ParamField>

<ParamField query="ipCountry" type="string">
  Country code associated with user IP address (from original session)
</ParamField>

<ParamField query="campaignId" type="number">
  Paysight unique identifier for Client’s campaign
</ParamField>

<ParamField query="campaign" type="string">
  Client’s campaign
</ParamField>

<ParamField query="affiliateId" type="number">
  Paysight unique identifier for Client’s traffic source/affiliate
</ParamField>

<ParamField query="affiliate" type="string">
  Client’s traffic source/affilia
</ParamField>

<ParamField query="productId" type="number">
  Paysight unique identifier for Product, which is the entry point and determines how a user should be handled
</ParamField>

<ParamField query="product" type="string">
  The Product contains the settings that determine how a user is handled/charged when they interact with Paysight via the Payment Widget / Card Submit API
</ParamField>

<ParamField query="paymentNumber" type="number">
  Paysight Billing Cycle. Indicates the number of payments that the user has made on the applicable subscription. e.g 4 = User has made 3 previous payments before this one
</ParamField>

<ParamField query="attempt" type="number">
  attempt=1 is the first natural attempt. attempt=2 is the first retry. attempt=3 is the 2nd retry etc.
</ParamField>

<ParamField query="originalTransactionId" type="string">
  For refunds, chargebacks and chargeback alerts this is the reference to related transaction
</ParamField>

<ParamField query="containsSalesStrategy" type="boolean">
  Indicates if the eCom related order contained an upsell
</ParamField>

<ParamField query="networkTokenized" type="boolean">
  Indicates if the transactions was network tokenized
</ParamField>

<ParamField query="chargebackFee" type="number">
  Fee associated with Chargeback, if the transaction is a chargeback
</ParamField>

<ParamField query="cardBrandId" type="number">
  1=Visa,2=Mastercard,3=Discover,4=Amex,5=Chase,6=JCB
</ParamField>

<ParamField query="cardBrand" type="string">
  Card Brand e.g Visa
</ParamField>

<ParamField query="eci" type="string">
  For transactions with 3D Secure, the Electronic Commerce Indicator value. 02 and 05 are fully authenticated and there should be liability shift. 01 and 06 are attempted.
</ParamField>

<ParamField query="paysightSession" type="string">
  Unique identifier for the Paysight session associated with the transaction. This represents the session created and managed within Paysight during the user’s interaction (e.g. payment widget session).
</ParamField>

<ParamField query="partnerSession" type="string">
  Optional partner-provided session identifier. This can be used to correlate the transaction with the client’s own session, tracking, or analytics systems.
</ParamField>

<ParamField query="applePay" type="boolean">
  Indicates whether the transaction was processed using Apple Pay.
</ParamField>

<ParamField query="googlePay" type="boolean">
  Indicates whether the transaction was processed using Google Pay.
</ParamField>

### New Subscription / Cancelled Subscription

```json theme={null}
[
    {
        "parentCompanyId": 106,
        "companyId": 125,
        "company": "Acme Corp Inc",
        "mid": "502231321321",
        "descriptor": "FitnessForAll.com",
        "subscriberId": 521254582,
        "customerId": 5898542245,
        "subDate": "2025-05-23T01:16:23",
        "unsubDate": "2025-06-19T10:24:53",
        "orderId": 85422140,
        "active": false,
        "unsubscribeOrderId": 0,
        "email": "jack@whitestripes.com",
        "subscriptionId": 8402,
        "subscription": "Generic Fitness Subscription",
        "productId": 8469,
        "product": "Fitness Landing Page 1",
        "frozen": false,
        "crossSale": false,
        "unsubscribeSource": "ChargebackAlert",
        "submitOrderId": 85422140
    }
]
```

#### Field Descriptions for Subscription Events

<ParamField query="parentCompanyId" type="number">
  Paysight Tenant Identifier (ClientId)
</ParamField>

<ParamField query="companyId" type="number">
  Identifier for Merchant Account Company
</ParamField>

<ParamField query="company" type="string">
  Merchant Account Company
</ParamField>

<ParamField query="mid" type="string">
  Merchant Account Identifier
</ParamField>

<ParamField query="descriptor" type="string">
  MID Descriptor
</ParamField>

<ParamField query="subscriberId" type="number">
  Unique identifier for the customer’s specific subscription
</ParamField>

<ParamField query="customerId" type="number">
  Unique identifier for the customer
</ParamField>

<ParamField query="subDate" type="string (ISO 8601)">
  Timestamp in GMT when the user was subscribed
</ParamField>

<ParamField query="unsubDate" type="string (ISO 8601)">
  Timestamp in GMT when the user unsubscribed/cancelled
</ParamField>

<ParamField query="orderId" type="number">
  The unique order refrerence to which the transaction relates. This will match the orderId returned in the original widget/card submit response
</ParamField>

<ParamField query="active" type="boolean">
  True if the user has not yet cancelled or been unsubscribed
</ParamField>

<ParamField query="unsubscribeOrderId" type="number">
  Unique identifier for the unsubscribe event (null if user has not yet unsubscribed)
</ParamField>

<ParamField query="email" type="string">
  Customer Email
</ParamField>

<ParamField query="subscriptionId" type="number">
  Unique identifier for the Subscription (service) on Paysight
</ParamField>

<ParamField query="subscription" type="string">
  Name of the Subscription (service) on Paysight
</ParamField>

<ParamField query="productId" type="number">
  Paysight unique identifier for Product, which is the entry point and determines how a user should be handled
</ParamField>

<ParamField query="product" type="string">
  The Product contains the settings that determine how a user is handled/charged when they interact with Paysight via the Payment Widget / Card Submit API
</ParamField>

<ParamField query="frozen" type="boolean">
  True if Paysight is no longer attempting to bill the customer (this will happen after retry strategies have been exhausted or specifc hard declines)
</ParamField>

<ParamField query="crossSale" type="boolean">
  Indicates if user was added to the subscription as a cross sale (from another subscription)
</ParamField>

<ParamField query="unsubscribeSource" type="string">
  Indicates how the user was unsubscribed.
  Values are:

  * `ChargebackAlert`
  * `CustomerService`
</ParamField>

<ParamField query="submitOrderId" type="number">
  Unique identifier of Card Submit event
</ParamField>

## Chargeback Alert

The Chargeback Alert event webhook will provide a uniform feed of all chargeback alerts. This is still under development

```json theme={null}
[
    {
        // TBD
    }
]
```

<Warning>Still in progress, stay tuned for more updates.</Warning>

## Chargeback

The Chargeback event webhook will provide a uniform feed of all chargeback alerts. This is still under development

```json theme={null}
[
    {
        // TBD
    }
]
```

<Warning>Still in progress, stay tuned for more updates.</Warning>

## Best Practices

* Always respond with `HTTP 200 OK` within 2 seconds.
* Do not process payloads inline—queue them for background processing.
* Log webhook events and delivery statuses.