Transaction Subscriptions

Receive real-time notifications for payment transaction events including authorizations, captures, refunds, voids, and ACH transactions.

Subscription Arguments

When creating a transaction subscription, you can specify filtering arguments to receive only the events you need.

Required Arguments

Argument	Type	Description
`entity_ksuid`	string	Required. Your 27-character merchant identifier

Optional Filter Arguments

Argument	Type	Description
`roll_up`	boolean	When `true`, includes transactions for child merchants in the hierarchy. Default: `false`
`status`	string	Filter by transaction status. Values: `Tran approved`, `Tran denied`, `Tran approved no response`, `Tran denied no response`
`amount_greater_than`	string	Only include transactions with amounts greater than this value
`amount_less_than`	string	Only include transactions with amounts less than this value
`type`	string	Filter by transaction type (see values below)
`currency_code`	string	Filter by 3-digit currency code (e.g., `840` for USD)
`card_scheme`	string	Filter by card network (see values below)
`response_code`	string	Filter by specific response code
`initiation_type`	string	Filter by initiation type: `ecommerce` or `telephone`
`was_voided`	boolean	When `true`, only include voided transactions
`was_refunded`	boolean	When `true`, only include refunded transactions
`was_captured`	boolean	When `true`, only include captured transactions
`was_reversed`	boolean	When `true`, only include reversed transactions
`has_error`	boolean	When `true`, only include transactions with errors

Transaction Types

Valid values for the type argument:

Authorization
Capture
Refund
Void
ACH Credit
ACH Debit
Authorization Capture
Standalone Refund
Balance Inquiry
Partial Reversal
Authorization Reversal
Withdrawal
Account Verification
Payment Credit
ACH Void

Card Schemes

Valid values for the card_scheme argument:

VISA
MASTERCARD
AMERICAN EXPRESS
DISCOVER
JCB
DINERS CLUB INTERNATIONAL
CHINA UNION PAY
DEBIT

Webhook Payload

When a transaction event matches your subscription criteria, your webhook receives a JSON payload with a wrapper containing metadata and a data array of events.

Wrapper Fields

Field	Type	Description
`id`	UUID	Unique identifier for this notification
`type`	string	Subscription type (`transactions`)
`timestamp`	string	When the notification was generated
`attempts`	array	Delivery attempt history
`data`	array	Array of transaction event objects

Event Fields

Field	Type	Description
`tran_ksuid`	string	Unique transaction identifier
`tran_event_ksuid`	string	Unique transaction event identifier
`entity_ksuid`	string	Merchant identifier
`request_ksuid`	string	Original request identifier
`gateway_type_ksuid`	string	Gateway type identifier
`date`	string	Transaction datetime with timezone
`type`	string	Transaction type
`status`	string	Transaction status
`cannonical_id`	string	Composite identifier in format `{type}:{status}`
`card`	string	Last 4 digits of card number
`card_scheme`	string	Card network (VISA, MASTERCARD, etc.)
`payment_method`	string	Payment method used
`transaction_amount`	number	Transaction amount in currency units
`fee_amount`	number	Fee amount
`tip_amount`	number	Tip amount
`tax_amount`	number	Tax amount
`ach_processing_amount`	number	ACH processing amount
`currency_code`	string	ISO 4217 currency code
`currency_name`	string	Currency name
`currency_exponent`	number	Decimal places for currency
`auth_code`	string	Authorization code
`response_code`	string	Response code
`response_text`	string	Response description
`avs_check`	string	AVS check result
`device_name`	string	Terminal/device name
`device_notes`	string	Device notes
`merchant_data`	object	Merchant-specific custom data
`possible_descriptor_values`	object	Statement descriptor values by card scheme
`request_json`	string	Original API request as JSON string
`response_json`	string	API response as JSON string
`was_voided`	boolean	Whether transaction was voided
`was_refunded`	boolean	Whether transaction was refunded
`was_captured`	boolean	Whether transaction was captured
`was_reversed`	boolean	Whether transaction was reversed
`load_ts`	string	Record load timestamp
`tran_event_load_ts`	string	Transaction event load timestamp
`tran_event_authorization_load_ts`	string	Authorization event load timestamp
`tran_event_authorization_detail_load_ts`	string	Authorization detail load timestamp

Example Payload

json

{
  "id": "0a5373fd-af38-4a43-b76e-a254ad0f3b0a",
  "type": "transactions",
  "timestamp": "2024-01-15 10:30:00.545 -0800",
  "attempts": [],
  "data": [
    {
      "tran_ksuid": "38JJwHd8U9DJHGg3QqInArVqL9b",
      "tran_event_ksuid": "38JJwB5ErCxrbv9OgntMqlYcBRp",
      "entity_ksuid": "38JJwFgEKU8xJjpJKmbMwvhD3qF",
      "request_ksuid": "38JJwHhsBGxzl1knke5PEyj2QLN",
      "gateway_type_ksuid": "38JJwGyceey6vvIUVSvWme2uCRR",
      "date": "2024-01-15 10:30:00.000 -0800",
      "type": "Authorization Capture",
      "status": "Tran approved",
      "cannonical_id": "Authorization Capture:Tran approved",
      "card": "4242",
      "card_scheme": "VISA",
      "payment_method": "Card",
      "transaction_amount": 150.00,
      "fee_amount": 0,
      "tip_amount": 0,
      "tax_amount": 0,
      "ach_processing_amount": 0,
      "currency_code": "840",
      "currency_name": "US Dollar",
      "currency_exponent": 2,
      "auth_code": "123456",
      "response_code": "00",
      "response_text": "Approval and completed successfully",
      "avs_check": "Y",
      "device_name": "ECommerce Device",
      "device_notes": "Merchant Name : ECommerce Device",
      "merchant_data": {
        "CustomerID": "cust_123456",
        "OrderNumber": "order_789012"
      },
      "possible_descriptor_values": {
        "VISA": "MERCHANT NAME"
      },
      "request_json": "{\"Amount\":{\"Total\":150.00,\"Currency\":\"USD\"},\"PaymentMethod\":{\"Card\":{...},\"Token\":{\"TokenID\":\"...\"}},\"TransactionEntry\":{...},\"Detail\":{...}}",
      "response_json": "{\"TransactionID\":\"...\",\"EventID\":\"...\",\"RequestID\":\"...\",\"AuthCode\":\"123456\",\"ResponseCode\":\"00\",\"ResponseText\":\"Approval and completed successfully\",\"Approved\":true,...}",
      "was_voided": false,
      "was_refunded": false,
      "was_captured": false,
      "was_reversed": false,
      "load_ts": "2024-01-15 10:30:15.000 -0800",
      "tran_event_load_ts": "2024-01-15 10:30:15.000 -0800",
      "tran_event_authorization_load_ts": "2024-01-15 10:30:15.000 -0800",
      "tran_event_authorization_detail_load_ts": "2024-01-15 10:30:15.000 -0800"
    }
  ]
}

INFO

The request_json and response_json fields contain the full API request and response as JSON strings. They are truncated in this example for brevity.

API Operations

List Subscriptions

Retrieve a paginated list of transaction subscriptions.

bash

curl -X GET "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction?limit=10&offset=0" \
  -H "Authorization: YOUR_API_TOKEN"

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	10	Maximum number of results (0-1000)
`offset`	integer	0	Number of results to skip

Create Subscription

Create a new transaction subscription with filtering arguments.

bash

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Value Transactions",
    "description": "Notifications for transactions over $100",
    "arguments": {
      "entity_ksuid": "2MER123CHANT456KSUID789ABC",
      "amount_greater_than": "10000",
      "roll_up": false
    }
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name for the subscription (1-64 characters)
`description`	string	No	Description (1-256 characters)
`arguments`	object	Yes	Filter arguments (see above)

Get Subscription

Retrieve details of a specific subscription.

bash

curl -X GET "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}" \
  -H "Authorization: YOUR_API_TOKEN"

Update Subscription

Update an existing subscription.

bash

curl -X PUT "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description",
    "arguments": {
      "entity_ksuid": "2MER123CHANT456KSUID789ABC",
      "status": "Tran approved"
    }
  }'

Delete Subscription

Delete a subscription. This also removes all destination mappings.

bash

curl -X DELETE "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}" \
  -H "Authorization: YOUR_API_TOKEN"

List Subscription Destinations

List webhook destinations linked to this subscription.

bash

curl -X GET "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}/destinations" \
  -H "Authorization: YOUR_API_TOKEN"

Add Destination to Subscription

Link a webhook destination to receive events from this subscription.

bash

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}/destinations" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "9603F4B2-1874-42FE-A2BC-F7B45C45A9D6"
  }'

Remove Destination from Subscription

Unlink a webhook destination from this subscription.

bash

curl -X DELETE "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}/destinations/{destination_id}" \
  -H "Authorization: YOUR_API_TOKEN"

Send Test Event

Send a test notification to verify your webhook integration.

bash

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction/{id}/test" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Query Parameters

Parameter	Type	Default	Description
`dry_run`	boolean	`false`	When `true`, returns the payload that would be sent without actually delivering it

Request Body (Optional)

Field	Type	Description
`overrides`	object	Optional field overrides for the test payload

This sends a sample transaction payload to all linked webhook destinations, allowing you to verify your integration before receiving live events. Use dry_run=true to preview the payload without sending.

Error Responses

Status	Description
400	Bad Request - Invalid input parameters
403	Forbidden - Insufficient permissions
500	Internal Server Error

Transaction Subscriptions ​

Subscription Arguments ​

Required Arguments ​

Optional Filter Arguments ​

Transaction Types ​

Card Schemes ​

Webhook Payload ​

Wrapper Fields ​

Event Fields ​

Example Payload ​

API Operations ​

List Subscriptions ​

Query Parameters ​

Create Subscription ​

Request Body ​

Get Subscription ​

Update Subscription ​

Delete Subscription ​

List Subscription Destinations ​

Add Destination to Subscription ​

Remove Destination from Subscription ​

Send Test Event ​

Query Parameters ​

Request Body (Optional) ​

Error Responses ​

Transaction Subscriptions

Subscription Arguments

Required Arguments

Optional Filter Arguments

Transaction Types

Card Schemes

Webhook Payload

Wrapper Fields

Event Fields

Example Payload

API Operations

List Subscriptions

Query Parameters

Create Subscription

Request Body

Get Subscription

Update Subscription

Delete Subscription

List Subscription Destinations

Add Destination to Subscription

Remove Destination from Subscription

Send Test Event

Query Parameters

Request Body (Optional)

Error Responses