Merchant Card Funding Group Subscriptions

Receive notifications for card funding batch summaries, providing aggregated totals for groups of card transactions settled together.

Subscription Arguments

When creating a merchant card funding group 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 funding groups for child merchants in the hierarchy. Default: false
merchant_account_number_last_four	string	Filter by last 4 digits of account number (exactly 4 characters)
merchant_bank_number	string	Filter by bank routing number
net_transaction_total_amount_min	integer	Minimum net total amount (in minor units)
net_transaction_total_amount_max	integer	Maximum net total amount (in minor units)

---

Webhook Payload

When a card funding group 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 (merchant_card_funding_group)
timestamp	string	When the notification was generated
attempts	array	Delivery attempt history
data	array	Array of card funding group event objects

Event Fields

Field	Type	Description
funding_group_id	string	Unique identifier for the funding group
acquiring_bank_id	string	Acquiring bank identifier
merchant_id	string	Merchant identifier
merchant_dba_name	string	Merchant DBA (doing business as) name
transaction_count	string	Number of transactions in this group
transaction_total_amount	string	Total transaction amount in currency units
tip_total_amount	string	Total tips in currency units
surcharge_total_amount	string	Total surcharges in currency units
reserve_total_amount	string	Total reserves in currency units
debit_discount_rate_fee_total_amount	string	Total debit discount rate fees
flat_rate_fee_total_amount	string	Total flat rate fees
discount_rate_fee_total_amount	string	Total discount rate fees
authorization_fee_total_amount	string	Total authorization fees
grouped_fee_total_amount	string	Total grouped fees
withheld_total_amount	string	Total withheld amount
net_transaction_total_amount	string	Net total amount after all fees
currency_code	string	ISO 4217 currency code
currency_exponent	string	Decimal places for currency
merchant_bank_number	string	Merchant bank routing number
merchant_account_number_last_four	string	Last 4 digits of merchant account

Example Payload

{
  "id": "a905a6b0-4bca-4a62-89aa-447ea5ae4882",
  "type": "merchant_card_funding_group",
  "timestamp": "2024-01-15 14:28:29.598 -0800",
  "attempts": [],
  "data": [
    {
      "funding_group_id": "cf22cc8d-ee6d-4996-aa86-b9c092599054",
      "acquiring_bank_id": "38JJwFxz9LDBQl8tq04OnFlwi58",
      "merchant_id": "38JJwFFnZAwgL6tY2wlTYQtS019",
      "merchant_dba_name": "Example Merchant",
      "transaction_count": "1",
      "transaction_total_amount": "52.76",
      "tip_total_amount": "0.00",
      "surcharge_total_amount": "0.00",
      "reserve_total_amount": "2.64",
      "debit_discount_rate_fee_total_amount": "0.00",
      "flat_rate_fee_total_amount": "0.00",
      "discount_rate_fee_total_amount": "0.00",
      "authorization_fee_total_amount": "0.00",
      "grouped_fee_total_amount": "0.00",
      "withheld_total_amount": "2.64",
      "net_transaction_total_amount": "50.12",
      "currency_code": "840",
      "currency_exponent": "2",
      "merchant_bank_number": "123456789",
      "merchant_account_number_last_four": "9999"
    }
  ]
}

---

API Operations

List Subscriptions

Retrieve a paginated list of merchant card funding group subscriptions.

curl -X GET "https://api.notifications.paynetworx.cloud/v1/subscriptions/merchant_card_funding_group?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 merchant card funding group subscription with filtering arguments.

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/merchant_card_funding_group" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Large Settlement Batches",
    "description": "Notifications for settlement batches over $10,000",
    "arguments": {
      "entity_ksuid": "2MER123CHANT456KSUID789ABC",
      "net_transaction_total_amount_min": 1000000,
      "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.

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

---

Update Subscription

Update an existing subscription.

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

---

Delete Subscription

Delete a subscription. This also removes all destination mappings.

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

---

List Subscription Destinations

List webhook destinations linked to this subscription.

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

---

Add Destination to Subscription

Link a webhook destination to receive events from this subscription.

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/merchant_card_funding_group/{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.

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

---

Send Test Event

Send a test notification to verify your webhook integration.

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/merchant_card_funding_group/{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 card funding group payload to all linked webhook destinations. 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