Merchant Card Funding Item Subscriptions

Receive notifications for individual card transaction funding details, providing visibility into each card transaction as it is settled.

Subscription Arguments

When creating a merchant card funding item 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 items for child merchants in the hierarchy. Default: `false`
`transaction_event_type`	string	Filter by transaction event type
`transaction_movement_type`	string	Filter by movement type: `SALE`, `CREDIT`, or `DEBIT`
`card_scheme_type`	string	Filter by card scheme (see values below)
`transaction_amount_min`	integer	Minimum transaction amount (in minor units)
`transaction_amount_max`	integer	Maximum transaction amount (in minor units)
`net_transaction_amount_min`	integer	Minimum net transaction amount (in minor units)
`net_transaction_amount_max`	integer	Maximum net transaction amount (in minor units)

Card Scheme Types

Valid values for the card_scheme_type argument:

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

Webhook Payload

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

Event Fields

Field	Type	Description
`funding_item_id`	string	Unique identifier for the funding item
`funding_group_id`	string	Parent funding group identifier
`acquiring_bank_id`	string	Acquiring bank identifier
`merchant_id`	string	Merchant identifier
`transaction_event_id`	string	Related transaction event identifier
`transaction_datetime`	string	When the transaction occurred
`merchant_dba_name`	string	Merchant DBA (doing business as) name
`transaction_id`	string	Transaction identifier
`original_transaction_event_id`	string	Original transaction event ID (for refunds/voids), empty string if not applicable
`transaction_event_type`	string	Type of transaction event (e.g., `Authorization Capture`)
`transaction_movement_type`	string	Movement type: `SALE`, `CREDIT`, or `DEBIT`
`transaction_amount`	string	Transaction amount in currency units
`tip_amount`	string	Tip amount in currency units
`surcharge_amount`	string	Surcharge amount in currency units
`reserve_amount`	string	Reserve amount in currency units
`debit_discount_rate_fee_amount`	string	Debit discount rate fee
`flat_rate_fee_amount`	string	Flat rate fee
`discount_rate_fee_amount`	string	Discount rate fee
`authorization_fee_amount`	string	Authorization fee
`grouped_fee_amount`	string	Grouped fee amount
`withheld_amount`	string	Withheld amount
`net_transaction_amount`	string	Net transaction amount after all fees
`currency_code`	string	ISO 4217 currency code
`currency_exponent`	string	Decimal places for currency
`processing_code`	string	Processing code
`card_scheme_type`	string	Card network (VISA, MASTERCARD, etc.)
`card_last_four`	string	Last 4 digits of card number
`device_id`	string	Device/terminal identifier
`device_name`	string	Device/terminal name

Example Payload

json

{
  "id": "e21cae65-d4bc-4f1f-ba97-65906ba8ca0e",
  "type": "merchant_card_funding_item",
  "timestamp": "2024-01-15 14:28:30.949 -0800",
  "attempts": [],
  "data": [
    {
      "funding_item_id": "e45f5eaf-5116-4679-a65c-f9308dd2fa70",
      "funding_group_id": "cf22cc8d-ee6d-4996-aa86-b9c092599054",
      "acquiring_bank_id": "38JJwDIF8YFpxHq6s2PVphUulaN",
      "merchant_id": "38JJwEHffyVTPWhh73BIB6NMCyW",
      "transaction_event_id": "38JJwGpK2pp0Kgh6RAZLNT02PxG",
      "transaction_datetime": "2024-01-15 14:24:17.000",
      "merchant_dba_name": "Example Merchant",
      "transaction_id": "38JJwFPYTnJTdTNoBzPRWCvAxDP",
      "original_transaction_event_id": "",
      "transaction_event_type": "Authorization Capture",
      "transaction_movement_type": "SALE",
      "transaction_amount": "52.76",
      "tip_amount": "0.00",
      "surcharge_amount": "0.00",
      "reserve_amount": "2.64",
      "debit_discount_rate_fee_amount": "0.00",
      "flat_rate_fee_amount": "0.00",
      "discount_rate_fee_amount": "0.00",
      "authorization_fee_amount": "0.00",
      "grouped_fee_amount": "0.00",
      "withheld_amount": "2.64",
      "net_transaction_amount": "50.12",
      "currency_code": "840",
      "currency_exponent": "2",
      "processing_code": "00",
      "card_scheme_type": "VISA",
      "card_last_four": "0123",
      "device_id": "38JJwCxzJIrU2k3njaWXY1co3QK",
      "device_name": "Ecommerce"
    }
  ]
}

API Operations

List Subscriptions

Retrieve a paginated list of merchant card funding item subscriptions.

bash

curl -X GET "https://api.notifications.paynetworx.cloud/v1/subscriptions/merchant_card_funding_item?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 item subscription with filtering arguments.

bash

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/merchant_card_funding_item" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Visa Transactions Only",
    "description": "Notifications for Visa card transactions",
    "arguments": {
      "entity_ksuid": "2MER123CHANT456KSUID789ABC",
      "card_scheme_type": "VISA",
      "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/merchant_card_funding_item/{id}" \
  -H "Authorization: YOUR_API_TOKEN"

Update Subscription

Update an existing subscription.

bash

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

Delete Subscription

Delete a subscription. This also removes all destination mappings.

bash

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

Merchant Card Funding Item Subscriptions ​

Subscription Arguments ​

Required Arguments ​

Optional Filter Arguments ​

Card Scheme Types ​

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 ​

Merchant Card Funding Item Subscriptions

Subscription Arguments

Required Arguments

Optional Filter Arguments

Card Scheme Types

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