Transactions Webhook

Trigger Events

Action	Trigger
`INSERT`	A new transaction is created. Skipped for historical/imported transactions.
`MODIFY`	A transaction's status changes or its change details are updated. Other field changes are ignored.
`REMOVE`	A transaction is deleted.

Headers

Header	Description
`Content-Type`	`application/json`
`X-Valmar-Webhook`	HMAC-SHA512 hex-encoded signature of the request body. Only present if an HMAC secret is configured.

Payload Schema

{
  "category": "transactions",       // Always "transactions"
  "action": "INSERT | MODIFY | REMOVE",
  "data": {
    // --- Core Fields ---
    "company": "string",             // Company name
    "uuid": "string",               // Transaction UUID
    "numericId": 0,                  // Numeric transaction ID
    "method": "string",             // ACH, RCC, RTP, P2C, CRD
    "type": "string",               // DEBIT or CREDIT
    "amount": 0,                     // Amount in cents (e.g. 1000 = $10.00)
    "status": "string",             // Current transaction status
    "standardEntryClassCode": "string | null", // SEC code (e.g. WEB, PPD, CCD)
    "createdAt": "ISO 8601",        // Transaction creation timestamp
    "externalUniqueId": "string | null",
    "description": "string | null",
    "memo": "string | null",
    "externalCustomerId": "string | null",
    "failureReason": "string | null",

    // --- Detail Objects (null when not applicable) ---
    "paymentDetails": { ... },
    "batchDetails": { ... },
    "settlementDetails": { ... },
    "returnDetails": { ... },
    "holdDetails": { ... },
    "changeDetails": { ... },
    "voidDetails": { ... },
    "rejectDetails": { ... },
    "authorizationDetails": { ... },
    "captureDetails": { ... }
  }
}

`paymentDetails`

Present on all transactions. Contains counterparty payment information.

Field	Type	Description
`name`	`string`	Counterparty name
`accountType`	`string`	`checking` or `savings`
`routingNumber`	`string\|null`	ABA routing number (ACH/RCC)
`panFirstSix`	`string\|null`	First 6 digits of card PAN (CRD only)
`panLastFour`	`string\|null`	Last 4 digits of card PAN (CRD only)
`expirationDate`	`string\|null`	Card expiration date (CRD only)
`billingAddress`	`string\|null`	Cardholder billing address (CRD only)
`billingPostalCode`	`string\|null`	Billing postal code (CRD only)
`billingCity`	`string\|null`	Billing city (CRD only)
`billingState`	`string\|null`	Billing state (CRD only)
`bankDetails`	`object\|null`	Bank information from ABA lookup (see below)

`bankDetails`

Field	Type	Description
`name`	`string\|null`	Bank name
`address`	`string\|null`	Bank address
`city`	`string\|null`	Bank city
`state`	`string\|null`	Bank state
`zip`	`string\|null`	Bank ZIP code
`zipExt`	`string\|null`	ZIP extension
`areaCode`	`string\|null`	Phone area code
`phonePrefix`	`string\|null`	Phone prefix
`phoneSuffix`	`string\|null`	Phone suffix
`servicingFRBNumber`	`string\|null`	Servicing Federal Reserve number

`batchDetails`

Present when the transaction has been batched for processing.

Field	Type	Description
`batchUuid`	`string\|null`	Batch UUID
`batchNumericId`	`string\|null`	Batch numeric ID
`batchedAt`	`string\|null`	ISO 8601 batch timestamp

`settlementDetails`

Present when the transaction has settlement information.

Field	Type	Description
`settlementUuid`	`string\|null`	Settlement UUID
`settlementNumericId`	`string\|null`	Settlement numeric ID
`expectedToSettleAt`	`string\|null`	Expected settlement date
`settlementProcessedAt`	`string\|null`	ISO 8601 actual settlement timestamp
`lateReturnSettlementUuid`	`string\|null`	Late return settlement UUID
`lateReturnSettlementNumericId`	`string\|null`	Late return settlement numeric ID
`lateReturnSettlementProcessedAt`	`string\|null`	ISO 8601 late return settlement timestamp

`returnDetails`

Present when the transaction has been returned.

Field	Type	Description
`returnCode`	`string\|null`	Return reason code (e.g. R01, R02)
`returnReason`	`string\|null`	Human-readable return reason
`returnNumericId`	`string\|null`	Return numeric ID
`returnUuid`	`string\|null`	Return UUID
`returnedAt`	`string\|null`	ISO 8601 return timestamp
`lateReturnedAt`	`string\|null`	ISO 8601 late return timestamp

`holdDetails`

Present when the transaction is on hold.

Field	Type	Description
`holdReason`	`string\|null`	Reason for hold
`holdCode`	`string\|null`	Hold code (e.g. H01, H02)
`releasedAt`	`string\|null`	ISO 8601 hold release timestamp

`changeDetails`

Present when a NOC (Notification of Change) has been received.

Field	Type	Description
`changeCode`	`string\|null`	Change code (e.g. C01, C02)
`changeReason`	`string\|null`	Human-readable change reason
`changedAt`	`string\|null`	ISO 8601 change timestamp
`oldValues`	`object\|null`	Previous field values
`newValues`	`object\|null`	Updated field values
`filterUuid`	`string\|null`	Associated filter UUID

`voidDetails`

Present when the transaction has been voided.

Field	Type	Description
`voidedAt`	`string\|null`	ISO 8601 void timestamp

`rejectDetails`

Present when the transaction has been rejected.

Field	Type	Description
`rejectReason`	`string\|null`	Reason for rejection
`rejectedAt`	`string\|null`	ISO 8601 rejection timestamp
`restoredAt`	`string\|null`	ISO 8601 restoration timestamp

`authorizationDetails`

Present for card (CRD) transactions after authorization.

Field	Type	Description
`authorizationCode`	`string\|null`	Authorization code from processor
`authorizedAt`	`string\|null`	ISO 8601 authorization timestamp
`expiresAt`	`string\|null`	ISO 8601 authorization expiry
`capturedAt`	`string\|null`	ISO 8601 capture timestamp
`avsCode`	`string\|null`	AVS response code
`avsDescription`	`string\|null`	AVS response description
`avsMatch`	`boolean\|null`	Whether AVS matched
`cvvCode`	`string\|null`	CVV response code
`cvvDescription`	`string\|null`	CVV response description
`cvvMatch`	`boolean\|null`	Whether CVV matched
`responseCode`	`string\|null`	Processor response code
`responseMessage`	`string\|null`	Processor response message
`approvalCode`	`string\|null`	Approval code from processor

`captureDetails`

Present for card (CRD) transactions after capture/settlement.

Field	Type	Description
`capturedAt`	`string\|null`	ISO 8601 capture timestamp
`saleAt`	`string\|null`	ISO 8601 sale timestamp
`batchNumber`	`string\|null`	Processor batch number
`responseCode`	`string\|null`	Capture response code

Example Payloads

New ACH Transaction (INSERT)

{
  "category": "transactions",
  "action": "INSERT",
  "data": {
    "company": "Acme Corp",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "numericId": 100542,
    "method": "ACH",
    "type": "DEBIT",
    "amount": 15000,
    "status": "pending",
    "standardEntryClassCode": "WEB",
    "createdAt": "2026-03-25T14:30:00Z",
    "externalUniqueId": "inv-2026-0042",
    "description": "Monthly subscription",
    "memo": null,
    "externalCustomerId": "cust-8821",
    "failureReason": null,
    "paymentDetails": {
      "name": "John Doe",
      "accountType": "checking",
      "routingNumber": "021000021",
      "panFirstSix": null,
      "panLastFour": null,
      "expirationDate": null,
      "billingAddress": null,
      "billingPostalCode": null,
      "billingCity": null,
      "billingState": null,
      "bankDetails": {
        "name": "JPMorgan Chase",
        "address": "270 Park Avenue",
        "city": "New York",
        "state": "NY",
        "zip": "10017",
        "zipExt": null,
        "areaCode": "212",
        "phonePrefix": "270",
        "phoneSuffix": "6000",
        "servicingFRBNumber": "021001208"
      }
    },
    "batchDetails": null,
    "settlementDetails": null,
    "returnDetails": null,
    "holdDetails": null,
    "changeDetails": null,
    "voidDetails": null,
    "rejectDetails": null,
    "authorizationDetails": null,
    "captureDetails": null
  }
}

Transaction Settled (MODIFY)

{
  "category": "transactions",
  "action": "MODIFY",
  "data": {
    "company": "Acme Corp",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "numericId": 100542,
    "method": "ACH",
    "type": "DEBIT",
    "amount": 15000,
    "status": "settled",
    "standardEntryClassCode": "WEB",
    "createdAt": "2026-03-25T14:30:00Z",
    "externalUniqueId": "inv-2026-0042",
    "description": "Monthly subscription",
    "memo": null,
    "externalCustomerId": "cust-8821",
    "failureReason": null,
    "paymentDetails": {
      "name": "John Doe",
      "accountType": "checking",
      "routingNumber": "021000021",
      "panFirstSix": null,
      "panLastFour": null,
      "expirationDate": null,
      "billingAddress": null,
      "billingPostalCode": null,
      "billingCity": null,
      "billingState": null,
      "bankDetails": null
    },
    "batchDetails": {
      "batchUuid": "b1c2d3e4-f5a6-7890-bcde-fa1234567890",
      "batchNumericId": "5023",
      "batchedAt": "2026-03-25T18:00:00Z"
    },
    "settlementDetails": {
      "settlementUuid": "s1t2u3v4-w5x6-7890-cdef-ab1234567890",
      "settlementNumericId": "3010",
      "expectedToSettleAt": "2026-03-27",
      "settlementProcessedAt": "2026-03-27T12:00:00Z",
      "lateReturnSettlementUuid": null,
      "lateReturnSettlementNumericId": null,
      "lateReturnSettlementProcessedAt": null
    },
    "returnDetails": null,
    "holdDetails": null,
    "changeDetails": null,
    "voidDetails": null,
    "rejectDetails": null,
    "authorizationDetails": null,
    "captureDetails": null
  }
}

Transaction Returned (MODIFY)

{
  "category": "transactions",
  "action": "MODIFY",
  "data": {
    "company": "Acme Corp",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "numericId": 100542,
    "method": "ACH",
    "type": "DEBIT",
    "amount": 15000,
    "status": "returned",
    "standardEntryClassCode": "WEB",
    "createdAt": "2026-03-25T14:30:00Z",
    "externalUniqueId": "inv-2026-0042",
    "description": "Monthly subscription",
    "memo": null,
    "externalCustomerId": "cust-8821",
    "failureReason": "NSF - Not Sufficient Funds",
    "paymentDetails": {
      "name": "John Doe",
      "accountType": "checking",
      "routingNumber": "021000021",
      "panFirstSix": null,
      "panLastFour": null,
      "expirationDate": null,
      "billingAddress": null,
      "billingPostalCode": null,
      "billingCity": null,
      "billingState": null,
      "bankDetails": null
    },
    "batchDetails": {
      "batchUuid": "b1c2d3e4-f5a6-7890-bcde-fa1234567890",
      "batchNumericId": "5023",
      "batchedAt": "2026-03-25T18:00:00Z"
    },
    "settlementDetails": {
      "settlementUuid": "s1t2u3v4-w5x6-7890-cdef-ab1234567890",
      "settlementNumericId": "3010",
      "expectedToSettleAt": "2026-03-27",
      "settlementProcessedAt": "2026-03-27T12:00:00Z",
      "lateReturnSettlementUuid": null,
      "lateReturnSettlementNumericId": null,
      "lateReturnSettlementProcessedAt": null
    },
    "returnDetails": {
      "returnCode": "R01",
      "returnReason": "Insufficient Funds",
      "returnNumericId": "7001",
      "returnUuid": "r1e2t3u4-r5n6-7890-defg-bc1234567890",
      "returnedAt": "2026-03-28T09:15:00Z",
      "lateReturnedAt": null
    },
    "holdDetails": null,
    "changeDetails": null,
    "voidDetails": null,
    "rejectDetails": null,
    "authorizationDetails": null,
    "captureDetails": null
  }
}

Card Authorization (INSERT)

{
  "category": "transactions",
  "action": "INSERT",
  "data": {
    "company": "Acme Corp",
    "uuid": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
    "numericId": 100601,
    "method": "CRD",
    "type": "DEBIT",
    "amount": 4999,
    "status": "authorized",
    "standardEntryClassCode": null,
    "createdAt": "2026-03-25T16:45:00Z",
    "externalUniqueId": "order-9930",
    "description": "Online purchase",
    "memo": null,
    "externalCustomerId": "cust-5540",
    "failureReason": null,
    "paymentDetails": {
      "name": "Jane Smith",
      "accountType": "checking",
      "routingNumber": null,
      "panFirstSix": "411111",
      "panLastFour": "1111",
      "expirationDate": "12/27",
      "billingAddress": "123 Main St",
      "billingPostalCode": "90210",
      "billingCity": "Beverly Hills",
      "billingState": "CA",
      "bankDetails": null
    },
    "batchDetails": null,
    "settlementDetails": null,
    "returnDetails": null,
    "holdDetails": null,
    "changeDetails": null,
    "voidDetails": null,
    "rejectDetails": null,
    "authorizationDetails": {
      "authorizationCode": "AUTH01",
      "authorizedAt": "2026-03-25T16:45:01Z",
      "expiresAt": "2026-04-01T16:45:01Z",
      "capturedAt": null,
      "avsCode": "Y",
      "avsDescription": "Street address and 5-digit ZIP match",
      "avsMatch": true,
      "cvvCode": "M",
      "cvvDescription": "CVV matches",
      "cvvMatch": true,
      "responseCode": "00",
      "responseMessage": "Approved",
      "approvalCode": "093821"
    },
    "captureDetails": null
  }
}