Who this is for

This is intended for customers and partners who:

Subscribe to MassPay webhooks.
And/or use value date information to drive downstream processes such as -reconciliation, customer communications, expected delivery messaging, or release planning.

Overview

A payment may be created with a value date that is achievable at that moment, but later becomes unachievable due to factors such as:

local cut-off times.
weekends and holidays.
corridor/payment method constraints, or .
the payment spending longer than expected in operational workflow steps.

To avoid stale or inaccurate date information, MassPay can re-check and update relevant dates during the payment lifecycle and notify subscribers when a change occurs.

What dates can change

Depending on the scenario, MassPay may update one or more of the following:

Value Date: the intended date the payment is credited/settled (as applicable to the method/corridor).
Best Achievable Value Date (BAVD): the earliest achievable value date based on rules and timing.
Release Date: the date MassPay plans to release the payment for onward processing.
Not all fields always change together.

When you will receive a webhook

If you subscribe to the event, MassPay may send payment.valueDateChanged when it detects that stored date values have changed as a result of:

Recalculation after creation (for example, updated rule outputs based on the latest context).
Ongoing lifecycle checks while a payment is still in-flight.
Final validation before release to ensure the planned dates remain achievable.
If there is no meaningful change, no event is sent.

Webhook: payment.valueDateChanged

Event purpose

This event tells you that the payment’s previously known date information may now be out of date and provides both the previous and new values so you can update your systems without polling.

Example payload

{
  "id": "bf8d970a-7abe-43cf-bac5-71e89ff92502",
  "eventType": "payment.valueDateChanged",
  "createdOnUTC": "2026-03-23T13:13:28Z",
  "summary": "Value Date has been changed.",
  "resource": {
    "PaymentId": "zDJEjb7zJm0uERFrUmOaV23Ef2ePJplb",
    "PartnerReference": "Partner",
    "PaymentReference": "Payment",
    "CustomerId": "MP_CPL3-2",
    "BatchId": "dRDR0jnqtJzDka3Jme5hsQDkyAkUyreZ",
    "PreviousValueDate": "2026-03-24T00:00:00",
    "PreviousBestAchievableValueDate": "2026-03-17T00:00:00",
    "PreviousReleaseDate": "2026-03-17T00:00:00",
    "NewValueDate": "2026-03-24T00:00:00",
    "NewBestAchievableValueDate": "2026-03-17T00:00:00",
    "NewReleaseDate": "2026-03-23T00:00:00",
    "ChangedOnUtc": "2026-03-23T13:10:18Z",
    "PaymentStatus": "SanctionCleared",
    "CurrencyCode": "USD",
    "DestinationCountryCode": "CO",
    "PaymentMethod": "Wire"
  }
}

Note: Timestamp formats are UTC. Date-time values may be returned at midnight (T00:00:00) depending on how the underlying date is represented for that field.

Field definitions

Field	Description	Required
`id`	Unique identifier for the webhook event instance.	Yes
`eventType`	Event name. For this webhook the value is `payment.valueDateChanged`.	Yes
`createdOnUTC`	UTC timestamp when the webhook event was created.	Yes
`summary`	Human-readable summary of the event.	Yes
`resource.PaymentId`	MassPay payment identifier.	Yes
`resource.PartnerReference`	Partner-side reference if available.	No
`resource.PaymentReference`	Payment reference if available.	No
`resource.CustomerId`	MassPay customer identifier.	Yes
`resource.BatchId`	Associated batch identifier.	Yes
`resource.PreviousValueDate`	Previously stored payment value date.	No
`resource.PreviousBestAchievableValueDate`	Previously stored BAVD.	No
`resource.PreviousReleaseDate`	Previously stored release date.	No
`resource.NewValueDate`	New payment value date after recalculation or adjustment.	No
`resource.NewBestAchievableValueDate`	New BAVD after recalculation.	No
`resource.NewReleaseDate`	New release date after recalculation.	No
`resource.ChangedOnUtc`	UTC timestamp when the underlying value date change occurred.	Yes
`resource.PaymentStatus`	Payment status at the time of the change, e.g. `SanctionCleared`.	Yes
`resource.CurrencyCode`	Payment currency.	Yes
`resource.DestinationCountryCode`	Beneficiary destination country code where available.	No
`resource.PaymentMethod`	Payment method, e.g. `Wire`.	Yes

Delivery and processing guidance`

Idempotency and retries

Webhooks should be treated as at-least-once delivery.
Use id to support idempotent processing (ignore duplicates).

Ordering

Events can arrive out of order relative to other event types (for example, status updates).
Use timestamps such as createdOnUTC and resource.ChangedOnUtc if you need to sequence updates.

Partial changes

Do not assume NewValueDate, NewBestAchievableValueDate, and NewReleaseDate always change together.
Update only the fields present and relevant to your business logic.

Nullable “previous” fields

In some scenarios, previous values may be missing (null/omitted), particularly if the earlier lifecycle stage did not populate all fields. Your consumer should handle this gracefully.

Frequently asked questions

**Does this event mean the payment status has changed? **

No. This event is specifically about date changes. The payment may remain in the same status.

Should I treat the new dates as authoritative?

Yes—if you consume these fields, treat this event as the signal that prior stored values in your system may now be stale.

What if my policy requires rejection rather than adjusting dates?

If a payment is rejected due to policy or validation rules, it will follow the standard rejection/notification behaviour. This event is focused on communicating date updates.