Payments Schemas

Domain JSON schemas defined by the Payments API. Each entry pairs a human-readable layer (a field table and a representative example) with the verbatim JSON Schema advertised by the API. Schemas are identified by tags as defined in RFC 4151 — the full schema identifier is tag:flywire.com,2016:agents:api:schema:{name}.

Schemas shared with the Insurance API (hypermedia, form, intermediation, dynamic-data, amount, iso-4217, iso-3166-1-alpha-2, timestamp) live in Common Schemas.

TIP

The JSON Schema block is the canonical definition. The tables and examples are there to make the JSON Schema readable — when in doubt, the JSON Schema block wins.

intermediated-payments

The collection wrapper returned when following the intermediated-payments relation. It carries an items array whose elements conform to intermediated-payment-summary; navigation between pages happens through the first/prev/next/last links exposed by the item profile.

{
  "items": [
    {
      "reference": "FW-P-20260315-001",
      "recipient": { "name": "Demo University" },
      "status": { "name": "delivered" },
      "amount": { "value": 15000, "currency": "USD" },
      "intermediation": {
        "timestamp": "2026-03-15T08:55:00Z",
        "agent": { "name": "Acme Agency" },
        "client": { "name": "Wei Zhang" }
      }
    }
  ],
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "next", "href": "..." }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediated-payments

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediated-payments",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "tag:flywire.com,2016:agents:api:schema:intermediated-payment-summary"
      }
    }
  },
  "required": ["items"]
}

intermediated-payment-summary

A single row in the payments list. Status is exposed as a single-level status.name string drawn from the payment-status-name enum.

Field	Type	Description
reference	string	Unique payment identifier
recipient.name	string	Destination name
status.name	payment-status-name	Current payment status
amount	amount	Payment value and currency
intermediation	intermediation	Who intermediated the payment and when

{
  "reference": "FW-P-20260315-001",
  "recipient": { "name": "Demo University" },
  "status": { "name": "delivered" },
  "amount": { "value": 15000, "currency": "USD" },
  "intermediation": {
    "timestamp": "2026-03-15T08:55:00Z",
    "agent": { "name": "Acme Agency" },
    "client": { "name": "Wei Zhang" }
  }
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediated-payment-summary

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediated-payment-summary",
  "type": "object",
  "properties": {
    "reference": { "type": "string" },
    "recipient": {
      "type": "object",
      "properties": { "name": { "type": "string" } },
      "required": ["name"]
    },
    "status": {
      "type": "object",
      "properties": {
        "name": { "$ref": "tag:flywire.com,2016:agents:api:schema:payment-status-name" }
      },
      "required": ["name"]
    },
    "amount": { "$ref": "tag:flywire.com,2016:agents:api:schema:amount" },
    "intermediation": { "$ref": "tag:flywire.com,2016:agents:api:schema:intermediation" }
  },
  "required": ["reference", "recipient", "status", "amount", "intermediation"]
}

intermediated-payment

Full payment record with status history, amounts (original / converted plus the exchange rate), an information object describing destination-specific data, and the intermediation block. The detail view nests the current status under status.current and keeps the timeline of transitions in status.previous[].

Field	Type	Description
reference	string	Unique payment identifier
recipient.name	string	Destination name
status.current	{ name, timestamp }	Current status with the time it was reached
status.previous	array of { name, timestamp }	Prior status transitions
amount.original	amount	Value in the payer's currency
amount.converted	amount	Value in the recipient's currency
amount.rate	number	Exchange rate applied (payer → recipient)
information	dynamic-data	Destination-specific data with its schema
intermediation	intermediation	Intermediation details

Optional links: monitor (external tracking page), payment-receipt, payment-confirmation.

{
  "reference": "FW-P-20260315-001",
  "recipient": { "name": "Demo University" },
  "status": {
    "current": { "name": "delivered", "timestamp": "2026-03-16T12:00:00Z" },
    "previous": [
      { "name": "guaranteed", "timestamp": "2026-03-15T10:30:00Z" },
      { "name": "on_hold", "timestamp": "2026-03-15T09:30:00Z" },
      { "name": "verification", "timestamp": "2026-03-15T09:10:00Z" },
      { "name": "initiated", "timestamp": "2026-03-15T09:00:00Z" }
    ]
  },
  "amount": {
    "original": { "value": 15000, "currency": "USD" },
    "converted": { "value": 13200, "currency": "EUR" },
    "rate": 0.88
  },
  "information": {
    "value": { "student_id": "S-2026-001" },
    "schema": { "type": "object", "properties": { "student_id": { "type": "string" } } }
  },
  "intermediation": {
    "timestamp": "2026-03-15T08:55:00Z",
    "agent": { "name": "Acme Agency" },
    "client": { "name": "Wei Zhang" }
  },
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "monitor", "href": "https://tracking.example.com/FW-P-20260315-001" },
    { "rel": "tag:flywire.com,2016:agents:api:relation:payment-receipt", "href": "..." },
    { "rel": "tag:flywire.com,2016:agents:api:relation:payment-confirmation", "href": "..." }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediated-payment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediated-payment",
  "type": "object",
  "$defs": {
    "status": {
      "type": "object",
      "properties": {
        "name": { "$ref": "tag:flywire.com,2016:agents:api:schema:payment-status-name" },
        "timestamp": { "$ref": "tag:flywire.com,2016:agents:api:schema:timestamp" }
      },
      "required": ["name", "timestamp"]
    }
  },
  "properties": {
    "reference": { "type": "string" },
    "recipient": {
      "type": "object",
      "properties": { "name": { "type": "string" } },
      "required": ["name"]
    },
    "status": {
      "type": "object",
      "properties": {
        "current": { "$ref": "#/$defs/status" },
        "previous": {
          "type": "array",
          "items": { "$ref": "#/$defs/status" }
        }
      },
      "required": ["current", "previous"]
    },
    "amount": {
      "type": "object",
      "properties": {
        "original": { "$ref": "tag:flywire.com,2016:agents:api:schema:amount" },
        "converted": { "$ref": "tag:flywire.com,2016:agents:api:schema:amount" },
        "rate": { "type": "number" }
      },
      "required": ["original", "converted", "rate"]
    },
    "information": { "$ref": "tag:flywire.com,2016:agents:api:schema:dynamic-data" },
    "intermediation": { "$ref": "tag:flywire.com,2016:agents:api:schema:intermediation" }
  },
  "required": ["reference", "recipient", "status", "amount", "information", "intermediation"]
}

payment-recipients

The body of a payment-recipients response is an array whose items are either a fully-described destination ({ name, description, country }) or a group ({ name, description }). Groups can be drilled into by following an anchored payment-recipients link (see Anchoring).

[
  { "name": "Universities", "description": "Higher education institutions" },
  { "name": "Demo University", "description": "Tuition payments", "country": "US" }
]

The link envelope around this body comes from the hypermedia profile — for example, action links like standard-payment-experience are anchored to #/items/N to indicate which destination they apply to.

JSON Schema — tag:flywire.com,2016:agents:api:schema:payment-recipients

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:payment-recipients",
  "type": "array",
  "items": {
    "oneOf": [
      {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "country": { "$ref": "tag:flywire.com,2016:agents:api:schema:iso-3166-1-alpha-2" }
        },
        "required": ["name", "description", "country"]
      },
      {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" }
        },
        "required": ["name", "description"]
      }
    ]
  }
}

payment-experience

Returned once a payment experience exists. Carries:

• id — the stable identifier of the payment experience (a UUID). Present for persisted experiences and stable across requests, so you can store it to correlate the experience later — for example against the experienceId carried on payment status callbacks. Omitted for one-off experiences that are never persisted.
• status — current status plus the history of state transitions
• setup — the recipient information used to create the experience and the data.inputs that came from the user (when a setup form was involved)
• interactions[] — each entry records a timestamp at which the client interacted with the experience

When generated together with the hypermedia profile, the body advertises the IANA payment link (the shareable customer-facing URL).

{
  "id": "9f8c7b6a-5d4e-4c2b-9a09-8f7e6d5c4b3a",
  "status": {
    "current": { "name": "created", "timestamp": "2026-03-20T14:30:00Z" },
    "previous": []
  },
  "setup": {
    "recipient": {
      "name": "Demo University",
      "country": "US",
      "route": [
        { "name": "Tuition", "description": "Undergraduate tuition payments" }
      ]
    },
    "data": {
      "inputs": {
        "value": { "student_id": "S-2026-001" },
        "schema": { "type": "object", "properties": { "student_id": { "type": "string" } } }
      }
    }
  },
  "interactions": [],
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "payment", "href": "https://payment.demo.flywire.com/..." }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:payment-experience

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:payment-experience",
  "type": "object",
  "$defs": {
    "status": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "timestamp": { "$ref": "tag:flywire.com,2016:agents:api:schema:timestamp" }
      },
      "required": ["name", "timestamp"]
    }
  },
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "object",
      "properties": {
        "current": { "$ref": "#/$defs/status" },
        "previous": {
          "type": "array",
          "items": { "$ref": "#/$defs/status" }
        }
      },
      "required": ["current", "previous"]
    },
    "setup": {
      "type": "object",
      "properties": {
        "recipient": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "country": { "$ref": "tag:flywire.com,2016:agents:api:schema:iso-3166-1-alpha-2" },
            "route": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" }
                },
                "required": ["name", "description"]
              }
            }
          },
          "required": ["name", "country", "route"]
        },
        "data": {
          "type": "object",
          "properties": {
            "inputs": { "$ref": "tag:flywire.com,2016:agents:api:schema:dynamic-data" }
          },
          "required": ["inputs"]
        }
      }
    },
    "interactions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "timestamp": { "$ref": "tag:flywire.com,2016:agents:api:schema:timestamp" }
        },
        "required": ["timestamp"]
      }
    }
  },
  "required": ["status", "setup", "interactions"]
}

payment-status-name

The enum of valid status names for an intermediated payment. verification and on_hold are interim states that can appear between initiated and guaranteed.

Value	Stage
initiated	Payer has started the payment
verification	Awaiting verification checks
on_hold	Held pending operations review
guaranteed	Funds guaranteed by Flywire
delivered	Funds delivered to the recipient
cancelled	Payment cancelled
reversed	Payment reversed after completion

JSON Schema — tag:flywire.com,2016:agents:api:schema:payment-status-name

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:payment-status-name",
  "type": "string",
  "enum": [
    "initiated",
    "verification",
    "on_hold",
    "guaranteed",
    "delivered",
    "cancelled",
    "reversed"
  ]
}