Webhooks - Paysight Documentation

Configuration

Clients can configure individual webhook URLs per event type at Paysight Account Settings

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.

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

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

[
    {
      "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": 830,
      "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
    }
]

Field Descriptions for Transaction Events

gateway

string

NMI/Payon/EmerchantPay etc

transactionId

string

Paysight’s unique identifier for the transaction (also referred to as messageId)

orderId

number

The unique order refrerence to which the transaction relates. This will match the orderId returned in the original widget/card submit response

sent

string

Timestamp in GMT when transaction was initiated

string

User Email address

sandbox

boolean

Indicates if transaction was simulated (sandbox=true) or real (sandbox=false)

applicationId

number

Paysight’s unique identifier of the transaction type

status

string

Status of the transaction

statusId

number

Paysight’s unique identifier of the status of the transaction

success

boolean

Indicates if the billing event was successful (fully captured funds or successful refund etc)

completed

string

Timestamp in GMT when transaction was finalized

currency

string

Transaction currency (e.g ‘USD’)

amount

number

Transaction amount (e.g 9.99)

mid

string

Merchant Account Identifier

descriptor

string

Merchant Account Descriptor

customerId

number

Paysight Customer Id

authCode

string

Gateway Authorization code

gatewayTransactionId

string

Gateway Transaction Id

firstName

string

Customer First Name

lastName

string

Customer Last Name

bin

string

Card Bin (first 6 digits)

last4

string

Card Last 4 digits

refunded

boolean

Indicates if Transaction has been refunded

refundable

boolean

Indicates if Transaction is refundable

hasAlert

boolean

Indicates if Transaction has a related Charegack alert

chargedBack

boolean

Indicates if Transaction was charged back

application

string

Paysight Transaction Type

applicationId2

number

Paysight Transaction Type 2 (classifies transactions in a similar way to above with some specific differences. Speak to support team for more info)

application2

string

Identifier for above. Speak to support team for more info)

shopId

number

Shopify Store Id (if applicable)

storeName

string

Shopify Store Name (if applicable)

storeDomain

string

Shopify Store Domain (if applicable)

storeRootDomain

string

Shopify Store Root Domain (if applicable)

merchantAccountId

number

Paysight Identifier for Merchant Account

midName

string

MID Name/Title/Description

companyId

number

Merchant Account Company Identifier

company

string

Merchant Account Company

parentCompanyId

number

Paysight Tenant Identifier (ClientId)

subscriptionId

number

Paysight Subscription Identifier

subscription

string

Paysight Subscription Name

refundSourceId

number

Identifier for Refund Source (if applicable)

alertTypeId

number

Identifier for Alert Type (if applicable)

alertSourceId

number

Identifier for Alert Source (if applicable)

submitOrderId

number

Unique identifier of Card Submit event

alertSource

string

Chargeback Mitigation Provider (e.g Kount)

alertType

string

Chargeback Alert Type, e.g RDR, Ethoca, CDRN

refundSource

string

Source of Refund (if applicable) e.g Alert Related, Customer Service etc

binCountry

string

Country Code associated with issuing Bin

ipCountry

string

Country code associated with user IP address (from original session)

campaignId

number

Paysight unique identifier for Client’s campaign

campaign

string

Client’s campaign

affiliateId

number

Paysight unique identifier for Client’s traffic source/affiliate

affiliate

string

Client’s traffic source/affilia

productId

number

Paysight unique identifier for Product, which is the entry point and determines how a user should be handled

product

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

paymentNumber

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

attempt

number

attempt=1 is the first natural attempt. attempt=2 is the first retry. attempt=3 is the 2nd retry etc.

originalTransactionId

string

For refunds, chargebacks and chargeback alerts this is the reference to related transaction

New Subscription / Cancelled Subscription

[
    {
        "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"
    }
]

Field Descriptions for Subscription Events

parentCompanyId

number

Paysight Tenant Identifier (ClientId)

companyId

number

Identifier for Merchant Account Company

company

string

Merchant Account Company

mid

string

Merchant Account Identifier

descriptor

string

MID Descriptor

subscriberId

number

Unique identifier for the customer’s specific subscription

customerId

number

Unique identifier for the customer

subDate

string (ISO 8601)

Timestamp in GMT when the user was subscribed

unsubDate

string (ISO 8601)

Timestamp in GMT when the user unsubscribed/cancelled

orderId

number

The unique order refrerence to which the transaction relates. This will match the orderId returned in the original widget/card submit response

active

boolean

True if the user has not yet cancelled or been unsubscribed

unsubscribeOrderId

number

Unique identifier for the unsubscribe event (null if user has not yet unsubscribed)

string

Customer Email

subscriptionId

number

Unique identifier for the Subscription (service) on Paysight

subscription

string

Name of the Subscription (service) on Paysight

productId

number

Paysight unique identifier for Product, which is the entry point and determines how a user should be handled

product

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

frozen

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)

crossSale

boolean

Indicates if user was added to the subscription as a cross sale (from another subscription)

unsubscribeSource

string

Indicates how the user was unsubscribed. Values are:

ChargebackAlert
CustomerService

Chargeback Alert

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

[
    {
        // TBD
    }
]

Still in progress, stay tuned for more updates.

Chargeback

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

[
    {
        // TBD
    }
]

Still in progress, stay tuned for more updates.

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.

Getting Started

​Configuration

​Available Event Types

​Delivery & Performance

​Payload Structure

​New Transaction / Updated Transaction

​Field Descriptions for Transaction Events

​New Subscription / Cancelled Subscription

​Field Descriptions for Subscription Events

​Chargeback Alert

​Chargeback

​Best Practices

Configuration

Available Event Types

Delivery & Performance

Payload Structure

New Transaction / Updated Transaction

Field Descriptions for Transaction Events

New Subscription / Cancelled Subscription

Field Descriptions for Subscription Events

Chargeback Alert

Chargeback

Best Practices