Merchant: Residual Report Published
Receive and interpret merchant.residuals.published notifications.
Incoming notification
merchant.residuals.published is an incoming POST to your registered callback, not an endpoint that your application calls. This event is triggered when merchant residuals reports are published. POST <your registered callback URL> Content-Type: application/json Signature: <HMAC-SHA256 of the raw request body>
Verify before processing
Use the Sign-Up subscription secret to compute HMAC-SHA256 over the original request bytes and compare it with the Signature header. Do not use the gateway Webhook-Signature nonce format for this API family. Persist the event before acknowledging it and make downstream handlers safe for repeated delivery. Sign-Up verification and delivery
Payload fields
Required flags are scoped to the containing object. The complete schema below preserves enums, nullable types and constraints. Field Required Type Constraints Meaning event_id Not marked required string maxLength: 36 — event_type Not marked required allOf / reference — — event_body Not marked required object — — event_body.month Required in parent integer — — event_body.year Required in parent integer — — event_body.processor_id Required in parent integer — — event_body.processor_name Required in parent string maxLength: 255 —
Payload contract
{ "type": "object", "properties": { "event_id": { "type": "string", "maxLength": 36, "example": "38cf9efa-8aec-4a4e-98e2-6bb2411fdc60" }, "event_type": { "allOf": [ { "$ref": "#/components/schemas/event-types" }, { "example": "merchant.residuals.published" } ] }, "event_body": { "type": "object", "required": [ "month", "year", "processor_id", "processor_name" ], "properties": { "month": { "type": "integer", "example": 3 }, "year": { "type": "integer", "example": 2024 }, "processor_id": { "type": "integer", "example": 123 }, "processor_name": { "type": "string", "maxLength": 255, "example": "TSYS" } } } } } true
Example payload
Source example values are fixtures; do not treat its IDs as account credentials or real account state. { "event_id": "38cf9efa-8aec-4a4e-98e2-6bb2411fdc60", "event_type": "merchant.residuals.published", "event_body": { "month": 3, "year": 2024, "processor_id": 123, "processor_name": "TSYS" } }
Referenced schema definitions
{ "components": { "schemas": { "event-types": { "type": "string", "enum": [ "application.updated.data.requested", "application.approved", "application.declined", "application.cancelled", "application.merchant.closed", "application.merchant.boarded", "merchant.chargeback.added", "merchant.deposit.new", "merchant.first-batch", "merchant.processing.start", "merchant.processing.stop", "merchant.residuals.published", "merchant.retrieval.added", "merchant.statement.new" ], "example": "application.merchant.boarded" } } } } true