Subscriptions Overview

Subscriptions define which events trigger notifications to your webhook destinations. Each subscription type corresponds to a category of events in the PayNetWorx platform.

List Subscription Types

Returns the available subscription types.

Request

GET /v1/subscriptions

Response

{
  "urls": [
    "/v1/subscriptions/merchant_ach_funding_item",
    "/v1/subscriptions/merchant_card_funding_group",
    "/v1/subscriptions/merchant_card_funding_item",
    "/v1/subscriptions/transaction"
  ]
}

Available Subscription Types

Subscription Type	Path	Description
Transaction	/v1/subscriptions/transaction	Real-time notifications for payment transactions (authorizations, captures, refunds, voids)
Merchant ACH Funding Item	/v1/subscriptions/merchant_ach_funding_item	Individual ACH transaction funding details
Merchant Card Funding Group	/v1/subscriptions/merchant_card_funding_group	Card funding batch summaries with aggregated totals
Merchant Card Funding Item	/v1/subscriptions/merchant_card_funding_item	Individual card transaction funding details

Common Subscription Operations

All subscription types support the same set of operations:

Operation	Method	Path
List subscriptions	GET	/v1/subscriptions/{type}
Create subscription	POST	/v1/subscriptions/{type}
Get subscription	GET	/v1/subscriptions/{type}/{id}
Update subscription	PUT	/v1/subscriptions/{type}/{id}
Delete subscription	DELETE	/v1/subscriptions/{type}/{id}
List destinations	GET	/v1/subscriptions/{type}/{id}/destinations
Add destination	POST	/v1/subscriptions/{type}/{id}/destinations
Remove destination	DELETE	/v1/subscriptions/{type}/{id}/destinations/{destination}
Send test event	POST	/v1/subscriptions/{type}/{id}/test

Subscription Arguments

Each subscription type accepts filtering arguments that determine which events trigger notifications. All subscriptions require:

Argument	Type	Required	Description
entity_ksuid	string	Yes	Your 27-character merchant identifier
roll_up	boolean	No	When true, includes events for child merchants in the hierarchy

Additional type-specific filters (amount ranges, transaction types, statuses) are documented on each subscription type's page.

Subscription Workflow

1. Create a Subscription

Create a subscription for the event type you want to receive. Include your merchant identifier and any filtering arguments:

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/transaction" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Transaction Subscription",
    "description": "Receive all transaction events",
    "arguments": {
      "entity_ksuid": "YOUR_MERCHANT_KSUID_27_CHARS",
      "roll_up": false
    }
  }'

2. Link Destinations

Connect one or more webhook destinations to receive events:

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

3. Test Your Integration

Send a test event to verify your webhook receives and processes notifications correctly:

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

4. Receive Events

Once linked, confirmed webhook destinations will receive events matching the subscription type and filter criteria.

Common Query Parameters

All list endpoints support pagination:

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

Error Responses

All subscription endpoints may return these error responses:

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