Notifications API - Getting Started

Welcome to the PayNetWorx Notifications API documentation. This API enables you to receive real-time notifications about payment events via webhooks.

Overview

The Notifications API provides a webhook-based notification system that allows you to:

• Destinations: Configure webhook endpoints where notifications are delivered
• Subscriptions: Define which event types trigger notifications to your destinations
• Events: Query notification history and resend failed notifications

Key Concepts

Destinations

A destination is a webhook endpoint that receives notification payloads. Each destination has:

• A unique ID (UUID)
• An HTTP endpoint URL where events are sent
• Optional custom headers for authentication
• A confirmation status (webhooks must be confirmed before receiving live events)

Subscriptions

Subscriptions define what events you want to receive. Available subscription types:

Type	Description
Transaction	Notifications for payment transaction events (auth, capture, refund, void)
Merchant ACH Funding Item	Individual ACH transaction funding details
Merchant Card Funding Group	Card funding batch/group summaries
Merchant Card Funding Item	Individual card transaction funding details

Each subscription can be linked to multiple destinations.

Events

Events represent the actual notifications sent to your destinations. Event types include:

Event Type	Description
CONFIRM	Webhook confirmation request
STARTED	Notification processing started
SENT	Notification sent to destination
DELIVERED	Notification successfully delivered
FAILED	Notification delivery failed
CONFIRMED	Webhook destination confirmed

Quick Start

Step 1: Create a Webhook Destination

First, create a destination where notifications will be sent:

curl -X POST "https://api.notifications.paynetworx.cloud/v1/destinations/webhook" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "description": "Production webhook endpoint",
    "http_endpoint_url": "https://example.com/webhook",
    "method": "POST"
  }'

Step 2: Confirm Your Webhook

When you create a webhook, a confirmation event is sent to your endpoint. Your endpoint must respond with a 2xx status code to confirm it can receive events. You can also manually trigger confirmation:

curl -X POST "https://api.notifications.paynetworx.cloud/v1/destinations/webhook/{id}/confirm" \
  -H "Authorization: YOUR_API_TOKEN"

Step 3: Create a Subscription

Create a subscription for the events you want to receive. The entity_ksuid is your merchant identifier:

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

Step 4: Link Destination to Subscription

Connect your webhook destination to the subscription:

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": "your-webhook-destination-id"
  }'

Step 5: Test Your Webhook

Before waiting for live events, send a test notification to verify your integration:

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

This sends a sample payload to all linked destinations, allowing you to verify your webhook handler works correctly.

Step 6: Verify Webhook Signatures

All webhook notifications are signed using Ed25519 signatures. Use the JWKS endpoint to retrieve the public keys for verification:

curl -X GET "https://api.notifications.paynetworx.cloud/.well-known/jwks.json"

See the Signature Verification guide for implementation details.

API Base URLs

Environment	Base URL
Production	https://api.notifications.paynetworx.cloud
QA	https://api.notifications-qa.paynetworx.ninja

All API endpoints in this documentation use the production URL. Replace with the QA URL for testing.

For the complete API specification, see the OpenAPI Documentation.

Authentication

The Notifications API uses the same authentication mechanism as other PayNetWorx APIs. Include your API credentials in request headers.

Next Steps

• Webhooks - Learn how to manage webhook destinations
• Subscriptions Overview - Explore all subscription types and filtering options
• Event History - Query and resend notifications
• Signature Verification - Secure your webhook endpoints with Ed25519 signature verification