Webhook Sample Payloads

This page contains representative JSON examples for webhook payloads whose shape has been verified.

Some webhook payloads include large nested objects. The examples below keep the important shape and common fields visible without showing every nullable field.

Each webhook has the same top-level envelope:

{
  "event": "PAYOR",
  "subtype": "CREATED",
  "payload": {}
}

The payload fields depend on the event and subtype.

---

TRANSACTION

Transaction webhooks notify your endpoint when transaction activity is emitted.

Payload Fields

Field	Type	Description
transaction_id	string	Unique transaction identifier.
transaction_type	string	Transaction type, such as DEBIT.
status	string	Current transaction status.
gross_amount	number	Total transaction amount in cents.
fees	number	Fee amount in cents.
net_amount	number	Net amount in cents.
currency	string	Transaction currency.
merchant_uid	string	Merchant identifier associated with the transaction.
transaction_date	string	Transaction timestamp.
metadata	string	JSON string of transaction metadata.
merchant	object	Merchant details included with the transaction.
payment_method	object	Payment method details included with the transaction.
invoice	object	Invoice details when the transaction is connected to an invoice.
recurring	object	Recurring payment details when the transaction is connected to a recurring payment.

TRANSACTION.CREATED

This example is abbreviated. Real transaction payloads may include additional nested fields and nullable values.

{
  "event": "TRANSACTION",
  "subtype": "CREATED",
  "payload": {
    "transaction_id": "ptl_txn_123",
    "transaction_type": "DEBIT",
    "status": "PENDING",
    "gross_amount": 102,
    "fees": 33,
    "net_amount": 69,
    "currency": "USD",
    "merchant_uid": "mer_123",
    "transaction_date": "2026-07-29T18:41:48.0Z",
    "metadata": "{\"pay_theory_reference\":\"field-trip\"}",
    "merchant": {
      "merchant_uid": "mer_123",
      "merchant_name": "Acme Store",
      "country_code": "USA"
    },
    "payment_method": {
      "payment_method_id": "ptl_pmt_123",
      "payment_type": "CARD",
      "card_brand": "MASTERCARD",
      "card_type": "DEBIT_CARD",
      "last_four": "6767",
      "payor": {
        "payor_id": "ptl_pay_123",
        "full_name": "Pat Theodore",
        "email": "pat@example.com"
      }
    }
  }
}

---

MERCHANT

Merchant webhooks notify your endpoint when a merchant record is created or updated. Hard deletes are not currently documented as webhook events.

Payload Fields

Field	Type	Description
merchant_uid	string	Unique merchant identifier.
merchant_name	string	Merchant display name.
is_system	boolean	Whether this is a system merchant.
country_code	string, optional	Merchant country code.
parent_merchant_uid	string, optional	Parent merchant identifier when nested.
ach_active	boolean, optional	Whether ACH payments are active.
card_active	boolean, optional	Whether card payments are active.
cash_active	boolean, optional	Whether cash payments are active.
submitted_onboarding	boolean, optional	Whether onboarding has been submitted.
settings	object, optional	Merchant profile, social, or contact settings.

MERCHANT.CREATED

{
  "event": "MERCHANT",
  "subtype": "CREATED",
  "payload": {
    "merchant_uid": "mer_123",
    "merchant_name": "Acme Store",
    "is_system": false,
    "country_code": "USA",
    "ach_active": true,
    "card_active": true,
    "cash_active": false,
    "submitted_onboarding": false
  }
}

MERCHANT.UPDATED

{
  "event": "MERCHANT",
  "subtype": "UPDATED",
  "payload": {
    "merchant_uid": "mer_123",
    "merchant_name": "Acme Store",
    "is_system": false,
    "country_code": "USA",
    "parent_merchant_uid": null,
    "ach_active": true,
    "card_active": true,
    "cash_active": false,
    "submitted_onboarding": true,
    "settings": {
      "contact_email": "ops@acme.com",
      "contact_phone": "+18005551212",
      "website": "https://paytheory.com"
    }
  }
}

---

PAYOR

Payor webhooks notify your endpoint when a payor record is created or updated.

Payload Fields

Field	Type	Description
payor_id	string	Unique payor identifier.
merchant_uid	string	Merchant identifier associated with the payor.
full_name	string, optional	Payor full name.
email	string, optional	Payor email address.
phone	string, optional	Payor phone number.
address_line1	string, optional	Primary street address.
address_line2	string, optional	Secondary street address.
city	string, optional	City.
region	string, optional	State or region.
postal_code	string, optional	Postal or ZIP code.
country	string, optional	Country code or name.

PAYOR.CREATED

{
  "event": "PAYOR",
  "subtype": "CREATED",
  "payload": {
    "payor_id": "payor_123",
    "merchant_uid": "mer_123",
    "full_name": "Pat Theodore",
    "email": "pat@example.com",
    "phone": "+18005550000",
    "address_line1": "123 Main St",
    "address_line2": "Suite 100",
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "USA"
  }
}

PAYMENT_METHOD

Payment method webhooks notify your endpoint when a payment method token record is created. Payment method updates use the same event family with the UPDATED subtype.

Payload Fields

Field	Type	Description
payment_method_id	string	Unique payment method identifier.
merchant_uid	string	Merchant identifier associated with the payment method.
payor_id	string, optional	Associated payor identifier.
payment_type	string, optional	Payment type or category.
card_brand	string, optional	Card brand for card payment methods.
card_type	string, optional	Card type, such as credit or debit.
exp_date	string, optional	Expiration date in the source format.
last_four	string, optional	Last four digits.
cvv_status	string, optional	CVV verification status.
bank_account_type	string, optional	Bank account type for ACH payment methods.
bank_code	string, optional	Bank routing number or bank code.
wallet_type	string, optional	Wallet provider or type.
barcode_id	string, optional	Barcode identifier for cash payment flows.
processor	string, optional	Upstream processor name.
processor_token	string, optional	Processor token or reference.
paytheory_encoded	string, optional	Encoded Pay Theory value or token.
issuing_country_code	string, optional	Issuing country code.
is_active	boolean, optional	Whether the payment method is active.
full_name	string, optional	Cardholder or account holder name.
address_line1	string, optional	Billing address line 1.
address_line2	string, optional	Billing address line 2.
city	string, optional	Billing city.
region	string, optional	Billing state or region.
postal_code	string, optional	Billing postal or ZIP code.
country	string, optional	Billing country.

PAYMENT_METHOD.CREATED

{
  "event": "PAYMENT_METHOD",
  "subtype": "CREATED",
  "payload": {
    "payment_method_id": "pmt_123",
    "merchant_uid": "mer_123",
    "payor_id": "payor_123",
    "payment_type": "CARD",
    "card_brand": "VISA",
    "card_type": "CREDIT",
    "exp_date": "12/29",
    "last_four": "4242",
    "cvv_status": "MATCH",
    "is_active": true,
    "full_name": "Pat Theodore",
    "address_line1": "123 Main St",
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "USA"
  }
}