Common Schemas

These JSON schemas are shared between the Payments API and the Insurance API. Schemas are identified by tags as defined in RFC 4151 — the full schema identifier is tag:flywire.com,2016:agents:api:schema:{name}.

Each entry pairs a human-readable layer (a field table and a representative example) with the verbatim JSON Schema advertised by the API.

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.

hypermedia

Every resource includes a links array. Links with an anchor property belong to a specific part of the representation (see Anchoring).

Field	Type	Description
rel	string (required)	Relation type (tag URI or IANA short name)
href	string, URI (required)	Target URL — opaque to your client
anchor	string, JSON Pointer (optional)	Points to a part of the current representation

{
  "links": [
    { "rel": "self", "href": "https://api-platform.demo.flywire.com/agents/v2/" },
    { "rel": "tag:flywire.com,2016:agents:api:relation:intermediated-payment", "href": "...", "anchor": "#/items/0" }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:hypermedia

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:hypermedia",
  "type": "object",
  "properties": {
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rel": { "type": "string" },
          "href": { "type": "string", "format": "uri-reference" },
          "anchor": { "type": "string", "format": "uri-reference" }
        },
        "required": ["rel", "href"]
      }
    }
  },
  "required": ["links"]
}

form

Resources that accept input return a form whose inputs property is a JSON Schema (draft 2020-12) describing the expected POST body. The schema is intended to be consumed dynamically: render labels from title, validation rules from minimum/maximum/pattern, dropdown options from oneOf, and so on.

{
  "inputs": {
    "type": "object",
    "properties": { "payment": { "type": "string" } },
    "required": ["payment"]
  },
  "links": [
    { "rel": "self", "href": "https://api-platform.demo.flywire.com/agents/v2/payment-intermediation-claim" }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:form

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:form",
  "type": "object",
  "properties": {
    "inputs": {
      "$ref": "https://json-schema.org/draft/2020-12/schema"
    }
  },
  "required": ["inputs"]
}

intermediation

Records who intermediated a resource and when. Used by intermediated payments and intermediated insurance applications.

Field	Type	Description
timestamp	timestamp	When the intermediation happened
agent.name	string	Name of the intermediating agency
client.name	string	Name of the client

{
  "timestamp": "2026-03-15T08:55:00Z",
  "agent": { "name": "Acme Agency" },
  "client": { "name": "Wei Zhang" }
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediation

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediation",
  "type": "object",
  "properties": {
    "timestamp": { "$ref": "tag:flywire.com,2016:agents:api:schema:timestamp" },
    "agent": {
      "type": "object",
      "properties": { "name": { "type": "string" } },
      "required": ["name"]
    },
    "client": {
      "type": "object",
      "properties": { "name": { "type": "string" } },
      "required": ["name"]
    }
  },
  "required": ["timestamp", "agent", "client"]
}

dynamic-data

Used wherever the API ships a payload alongside a JSON Schema describing it (for example, the information field on a payment or insurance application, or the setup.data.inputs of a payment experience). The schema is a full JSON Schema you can use to render labels, validation rules, or read-only flags in your UI.

{
  "value": { "student_id": "S-2026-001" },
  "schema": {
    "type": "object",
    "properties": {
      "student_id": { "type": "string", "title": "Student ID" }
    }
  }
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:dynamic-data

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:dynamic-data",
  "type": "object",
  "properties": {
    "value": { "type": "object" },
    "schema": { "$ref": "https://json-schema.org/draft/2020-12/schema" }
  },
  "required": ["value", "schema"]
}

amount

Represents a monetary value paired with its currency code.

Field	Type	Description
value	number	Monetary value
currency	iso-4217	ISO 4217 currency code

{ "value": 15000, "currency": "USD" }

JSON Schema — tag:flywire.com,2016:agents:api:schema:amount

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:amount",
  "type": "object",
  "properties": {
    "value": { "type": "number" },
    "currency": { "$ref": "tag:flywire.com,2016:agents:api:schema:iso-4217" }
  },
  "required": ["value", "currency"]
}

iso-4217

The set of valid ISO 4217 currency codes. Common examples include USD, EUR, GBP, AUD, NZD, JPY, CNY.

JSON Schema — tag:flywire.com,2016:agents:api:schema:iso-4217

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:iso-4217",
  "type": "string",
  "enum": [
    "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD",
    "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF",
    "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP",
    "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF",
    "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE",
    "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB",
    "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD",
    "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF",
    "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD",
    "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD",
    "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD",
    "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU",
    "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD",
    "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN",
    "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD",
    "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD",
    "SHP", "SLE", "SLL", "SOS", "SRD", "SSP", "STN", "SVC",
    "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY",
    "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI",
    "UYU", "UYW", "UZS", "VED", "VES", "VND", "VUV", "WST",
    "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD",
    "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA",
    "XXX", "YER", "ZAR", "ZMW", "ZWL"
  ]
}

iso-3166-1-alpha-2

The set of valid ISO 3166-1 alpha-2 country codes (e.g. US, GB, AU, NZ, CN). Used by payment-recipients and payment-experience to identify recipient countries.

JSON Schema — tag:flywire.com,2016:agents:api:schema:iso-3166-1-alpha-2

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:iso-3166-1-alpha-2",
  "type": "string",
  "enum": [
    "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU",
    "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ",
    "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "KY",
    "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CD", "CG", "CK", "CR", "CI", "HR",
    "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE",
    "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE",
    "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM",
    "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM",
    "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS",
    "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ",
    "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA",
    "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MK", "MP", "NO", "OM",
    "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE",
    "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA",
    "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES",
    "LK", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK",
    "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY",
    "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW"
  ]
}

timestamp

All timestamps are ISO 8601 date-time strings in UTC ("2026-03-20T14:30:00Z").

JSON Schema — tag:flywire.com,2016:agents:api:schema:timestamp

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:timestamp",
  "type": "string",
  "format": "date-time"
}