Payment Status Updated

Sent when a payment is recorded or its status changes. Use it to keep your own systems in sync with the lifecycle of payments you intermediate — without polling the API.

This page describes the data payload only. It is wrapped in the standard callback envelope (id, occurredOn, data) and delivered with the headers described in the Callbacks Overview.

• Event type: payment.status.updated
• Content-Type: application/vnd.flywire.payment.status.updated+json;version=1.0

data

Field	Type	Description
payment	string	Payment identifier. Required.
status	string	Current payment status. Required.
reference	string (UUID)	Reference of what the payment originated from — the payment request ID when it comes from a payment request, or the payment initialization ID when it comes from an API initialization. Omitted otherwise.
experienceId	string (UUID)	Identifier of the payment experience the payment originates from — matches the experienceId exposed by the API. Present only when the payment is linked to a payment experience.
subjectId	number	Identifier of the subject (contact) associated with the payment, when available. Optional.

reference and experienceId are mutually exclusive

A payment status update carries at most one of these, depending on how the payment originated:

• reference — present when the payment comes from a payment request (the payment request ID) or an API initialization (the payment initialization ID).
• experienceId — present when the payment originates from a payment experience.

They never appear together, and neither is present for payments from other origins.

Correlating with a payment experience

When present, experienceId matches the id of a payment-experience you created earlier. Store that id when you set up the experience so you can tie incoming status updates back to it.

Examples

A payment originating from a payment experience carries experienceId:

{
  "id": "9f1c8d7e-2a3b-4c5d-8e6f-0a1b2c3d4e5f",
  "occurredOn": "2026-03-15T08:55:00Z",
  "data": {
    "payment": "ABK123456",
    "status": "DELIVERED",
    "experienceId": "7c2e4d1a-5b6f-4c8d-9e0a-1b2c3d4e5f60",
    "subjectId": 42
  }
}

A payment originating from a payment request or an API initialization carries reference instead (here, a payment request ID):

{
  "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
  "occurredOn": "2026-03-15T09:10:00Z",
  "data": {
    "payment": "ABK123457",
    "status": "DELIVERED",
    "reference": "3b6c1f2a-9d4e-4a7b-8c1d-2e3f4a5b6c7d",
    "subjectId": 42
  }
}

JSON Schema — flywire.agents.payment.status.updated.1-0

{
  "$id": "https://agents.flywire.com/api/schemas/flywire.agents.payment.status.updated.1-0.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Payment status updated object.",
  "type": "object",
  "required": ["id", "occurredOn", "data"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Event id."
    },
    "occurredOn": {
      "description": "ISO-8601 event date/timestamp.",
      "type": "string",
      "format": "date-time"
    },
    "data": {
      "type": "object",
      "required": ["payment", "status"],
      "properties": {
        "payment": {
          "type": "string",
          "description": "Payment ID."
        },
        "reference": {
          "type": "string",
          "description": "Payment reference."
        },
        "status": {
          "type": "string",
          "description": "Payment status."
        },
        "experienceId": {
          "type": "string",
          "format": "uuid",
          "description": "Id of the payment experience the payment originates from (matches the `experienceId` exposed by api v2). Omitted when the payment is not linked to a payment experience."
        }
      }
    }
  }
}

TIP

subjectId is delivered in the callback payload when available, but is not part of the published JSON Schema above. Treat it as an optional, informational field.