Recipients

List of endpoints

About Recipients

What are recipients?

Where do recipients come from?

Recipients have been set up during your onboarding process as a client. You need to contact Flywire to set up new recipients.

Localization

Recipients can be localized.

Getting a List of all available Recipients

Request

The list of recipients contains all the recipients that are available to you as a client. You can display this list in your UI, for example as a drop down, so that the person creating the payment in your system can choose one of the recipients.

Parameters for the Request Body

No request body is needed.

Optional Query Parameters for Pagination

This endpoint supports pagination. If you are not providing any pagination parameters, the response is returned with default pagination settings.

Pagination parameters are added as query parameters with the request in the format

{endpoint_path}?page=2&per_page=10

Default setting

The default setting is:

• page=1 (start on page 1)

• per_page=10 (display 10 entries per page)

page integerquery parameter

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

per_page integer query parameter

Enables you to define how many results will be included per page.

Possible values: min 1, max 100

GET /recipients

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/recipients?page=1&per_page=100
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

Parameters for pagination

total_entries integer

The total number of items in the full result list, not just of the current page.

total_pages integer

The total number of pages available.

page integer

The current page of the results.

per_page integer

The maximum number of results to return at one time (on one page).

Recipients array

id string

The recipient ID (also called portal code).

The recipient ID is the unique three-letter ID that identifies the recipient, for example FWU for Flywire University. The recipient ID has been assigned by Flywire when the recipient has been set up.

external_code string

The external code for the recipient (if there is one).

The external code of a recipient is optional, it can contain an identifier for the recipient that is different from the Flywire recipient ID. One example for an external code is the "Federal School Code (FSC)", which is a list of codes that identify different schools within the US.

name string

The name of the recipient.

country string

The ISO Alpha-2 country code representing the country where the recipient is located. This two-letter country code should conform to the ISO 3166-1 Alpha-2 standard. For example, "US" for the United States, "GB" for the United Kingdom.

state string

The state where the recipient is located.

{
    "total_entries": 350,
    "total_pages": 4,
    "page": 1,
    "per_page": 100,
    "recipients": [
    {
      "id": "AAE",
      "external_code": "E00210",
      "name": "International American University", 
      "country": "US",
      "state": "MA"
    },
    {
      "id": "FWU",
      "external_code": "E00212",
      "name": "Flywire University",
      "country": "US",
      "state": "IN"
    },
    // The array continues with similar objects for each recipient
  ]
}

Getting Details about a Recipient

Request

This endpoint returns all the information about one recipient.

Parameters for the Request Body

No request body is needed.

How to Resolve the Path Placeholders of the Endpoint

Replace the {recipientId} of the endpoint with the actual recipient ID.

What is the recipient ID?

The recipient ID is the unique three-letter ID that identifies the recipient, for example FWU for Flywire University. The recipient ID has been assigned by Flywire when the recipient has been set up.

Where do I find the recipient ID? 

You can use this request to get a list of all recipients that are available to you as a client and what their recipient ID is:

GET /recipients

For details see Getting a List of all available Recipients.

GET/recipients/{recipientId}

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/recipients/FWU
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

id string

The recipient ID (also called portal code).

The recipient ID is the unique three-letter ID that identifies the recipient, for example FWU for Flywire University. The recipient ID has been assigned by Flywire when the recipient has been set up.

external_code string

The external code for the recipient (if there is one).

The external code of a recipient is optional, it can contain an identifier for the recipient that is different from the Flywire recipient ID. One example for an external code is the "Federal School Code (FSC)", which is a list of codes that identify different schools within the US.

name string

The name of the recipient.

email string

The email associated with the recipient.

website string

The website of the recipient.

logo_url string

The URL that contains the logo of the recipient.

Tips for displaying logos

If you want to display the recipient's logo in your own UI knowing the Flywire logo standards can be helpful to you. Flywire asks clients to provide logos as a vector (PDF or SVG) with a max size of 1MB and the following dimensions:

Type	max-width	max-height
Desktop	240px	88px
Mobile	200px	88px

Tips:

• If a logo is square-shaped or vertical-shaped, adjust it to the max height.

• If a logo is horizontal-shaped, adjust it to the max width.

address string

The first address line of the recipient.

address2 string

The second address line of the recipient.

city string

The city where the recipient is located.

state string

The state where the recipient is located.

zip string

The zip code where the recipient is located.

country string

The ISO Alpha-2 country code representing the country where the recipient is located. This two-letter country code should conform to the ISO 3166-1 Alpha-2 standard. For example, "US" for the United States, "GB" for the United Kingdom.

currency string

The billing currency in ISO 4217 format.

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.

List of available currencies

Currency ISO 4217 code	Currency Full Name	Subunit to Unit
AED	United Arab Emirates Dirhams	100
AFN	Afghan afghanis	100
AMD	Armenian drams	100
ANG	Netherlands Antillean guilders	100
AOA	Angolan kwanzas	100
ARS	Argentine pesos	100
AUD	Australian Dollars	100
AWG	Aruban florin	100
AZN	Azerbaijani Manat	100
BAM	Bosnia and Herzegovina convertible marks	100
BBD	Barbadian dollars	100
BDT	Bangladeshi takas	100
BGN	Bulgarian Levs	100
BHD	Bahraini Dinars	1,000
BIF	Burundian franc	100
BMD	Bermudian Dollars	100
BND	Brunei dollar	100
BOB	Bolivian Bolivianos	100
BRL	Brazilian Reals	100
BSD	Bahamian Dollars	100
BTN	Bhutanese ngultrum	100
BWP	Botswana pula	100
BZD	Belize dollars	100
CAD	Canadian Dollars	100
CDF	Congolese francs	100
CHF	Swiss Francs	100
CLP	Chilean pesos	1
CNH	Chinese Yuan (Offshore) Renminbi	100
CNY	Chinese Yuan Renminbi	100
COP	Colombian pesos	100
CRC	Costa Rican colones	100
CVE	Cape Verdean escudos	100
CZK	Czech Korunas	100
DJF	Djiboutian francs	100
DKK	Danish Kroner	100
DOP	Dominican pesos	100
DZD	Algerian dinars	100
EGP	Egyptian pounds	100
ERN	Eritrean Nakfas	100
ETB	Ethiopian Birrs	100
EUR	Euros	100
FJD	Fijian Dollars	100
FKP	Falkland Islands pounds	100
GBP	British Pounds	100
GEL	Georgian lari	100
GHS	Ghana cedis	100
GIP	Gibraltar Pounds	100
GMD	Gambian dalasis	100
GNF	Guinean francs	100
GTQ	Guatemalan Quetzals	100
GYD	Guyanaese Dollars	100
HKD	Hong Kong Dollars	100
HNL	Honduran lempiras	100
HRK	Croatian Kunas	100
HTG	Haitian gourdes	100
HUF	Hungarian Forints	100
IDR	Indonesian Rupiahs	100
ILS	Israeli New Sheqels	100
INR	Indian Rupees	100
ISK	Icelandic krónur	100
JMD	Jamaican dollars	100
JOD	Jordanian Dinars	100
JPY	Japanese Yen	1
KES	Kenyan Shillings	100
KGS	Kyrgyzstani Som	100
KHR	Cambodian Riels	100
KMF	Comorian francs	100
KRW	South Korean Won	100
KWD	Kuwaiti Dinars	1,000
KYD	Cayman Island Dollars	100
KZT	Kazakhstani tenge	100
LAK	Lao kip	100
LBP	Lebanese Pounds	100
LKR	Sri Lankan rupees	100
LRD	Liberian dollars	100
LSL	Lesotho maloti	100
LYD	Libyan Dinars	1,000
MAD	Moroccan Dirhams	100
MDL	Moldovan lei	100
MGA	Malagasy ariary	5
MKD	Macedonian denari	100
MMK	Myanmar kyat	100
MNT	Mongolian tugriks	100
MOP	Macau Patacas	100
MUR	Mauritian Rupees	100
MVR	Maldivian Rufiyaas	100
MWK	Malawian kwachas	100
MXN	Mexican Pesos	100
MYR	Malaysian Ringgits	100
MZN	Mozambican meticais	100
NAD	Namibian Dollars	100
NGN	Nigerian Naira	100
NIO	Nicaraguan córdobas	100
NOK	Norwegian Kroner	100
NPR	Nepalese rupees	100
NZD	New Zealand Dollars	100
OMR	Omani Rials	1,000
PAB	Panamanian Balboas	100
PEN	Peruvian Nuevo Sols	100
PGK	Papua New Guinean kina	100
PHP	Philippine Pisos	100
PKR	Pakistani rupees	100
PLN	Polish złoties	100
PYG	Paraguayan guaranies	100
QAR	Qatari Riyals	100
RON	Romanian Leus	100
RSD	Serbian Dinars	100
RWF	Rwandan francs	100
SAR	Saudi Riyals	100
SBD	Solomon Islands dollars	100
SCR	Seychellois rupees	100
SEK	Swedish Kronor	100
SGD	Singapore Dollars	100
SHP	Saint Helena pounds	100
SLL	Sierra Leonean leones	100
SOS	Somali shillings	100
SRD	Surinamese dollars	100
STD	São Tomé and Príncipe dobras	100
SZL	Swazi Lilangenis	100
THB	Thai Bahts	100
TJS	Tajikistani somoni	100
TND	Tunisian Dinars	1,000
TOP	Tongan paʻanga	100
TRY	Turkish Liras	100
TTD	Trinidad and Tobago Dollars	100
TWD	New Taiwan Dollars	100
TZS	Tanzanian shillings	100
UAH	Ukrainian Hryvnia	100
UGX	Ugandan shillings	100
USD	United States Dollars	100
UYU	Uruguayan pesos	100
UZS	Uzbekistan So'm	100
VND	Vietnamese Dong	10
VUV	Vanuatu vatu	1
WST	Samoan tālā	100
XAF	CFA francs	100
XCD	East Caribbean dollars	100
XOF	West African CFA francs	100
XPF	French Pacific Francs	100
YER	Yemeni Rials	100
ZAR	South African Rands	100
ZMW	Zambian kwacha	100

fields array

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

The parameters of the fields depend on the type of field.

id string

Identifier of the field.

type string

The type of the field affects how the field is filled out and how the field is displayed in the PayEx portal.

Information about how fields and messages are displayed in a Flywire PayEx portal is not relevant when you are using the Flywire API since you are not using a PayEx portal for payments.

format string

The format used to represent this field:

• country

• date

• phone

• text

A field with the country format expects SO2 country codes as values.

required boolean

Indicates if the field is required (true) or optional (false) when creating the payment. If true you must provide this field when creating a payment.

pattern string

RegEx pattern that will be used to validate the provided value when it is passed in field value in the payment.

pattern_message string

Validation message that you can display in your PayEx portal when an error related to the validation of this field appears. This is a helpful hint for your payer to help them fill out the field correctly. For example "Your student ID needs to start with an F followed by 8 digits".

Information about how fields and messages are displayed in a Flywire PayEx portal is not relevant when you are using the Flywire API since you are not using a PayEx portal for payments.

value string or array

The value depends on the type of the field.

view_options object

The view options contain additional information about how to display this field in your PayEx portal.

Information about how fields and messages are displayed in a Flywire PayEx portal is not relevant when you are using the Flywire API since you are not using a PayEx portal for payments.

section_identifier string

Fields are usually organized in sections. This property indicates the section where the field belongs.

section_name string

The section name where the field belongs. It can be rendered as a section title when rendering the view.

section_description string

The description of the section. It can be used as a subtitle of the section when rendering the view.

label string

The label of the field. The label value will be returned in the language set in the locale parameter when you were retrieving the recipient details. If you didn't specify a locale, the default is English.

See Localization for more information about configuring the locale parameter.

help string

Help text related to the field. It can be displayed as part of the UI next to the field.

hint string

Text hint to explain how to fill in that field.

placeholder string

Placeholder to use inside the field.

position integer

Relative position for order of the fields.

hidden boolean

You can hide fields from being displayed when they are not meant to be filled out by the payer. You can use this for fields that are required, but are pre-populated by you.

• true - field is hidden

• false - field is displayed

items array

An item is something that your payer can pay for (for example: tuition fees, housing, etc.). When you create a payment, you display the items to your payer and they can choose for which items they want to pay. How many items there are depends on the recipient's configuration.

The Flywire API expects every recipient to have at least one item. If no item(s) were specified when the recipient was set up, the Flywire API interprets that as one item which has the id "default".

id string

Identifier of the item.

The Flywire API expects every recipient to have at least one item. If no item(s) were specified when the recipient was set up, the Flywire API interprets that as one item which has the id "default".

currency string

ISO 4217 of the currency associated with this item.

The currency is pulled from the currency parameter of the recipient, which means it is always identical to the recipient's currency. You can't define a different currency for individual items.

label string

User friendly description of the item.

settings object

amount_limits object

Contains the payment amount limits.

The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire.

If you didn't customize the settings, the default limits are:

• Minimum: 5000 = 50.00 USD

• Maximum: 15000000 = 150000.00 USD

When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items.

What happens when a payment is not within the defined settings?

When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned.

minimum_amount integer

The minimum amount

The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.

Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

maximum_amount integer

The maximum amount

The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.

Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

refund_bundle_cut_off object

The cut-off time and approval settings are only relevant when you are using refunds. For details about those settings see Refunds: Cut-off time and Approval.

periodicity string

The scheduled interval for the cut-off time.

The possible interval values depend on your agreement with Flywire. For example, the value could be daily or weekly.

The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.

The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.

You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.

approval_type string

All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:

Type of approval	approval_type setting for the recipient
Manual approval Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).	manual
Automatic approval Flywire processes refund bundles automatically after the cut-off time.	automatic

 

 

To add or change the settings for refund approvals of a recipient please contact the Solutions team.

next_cutoff_time date

The date and time when the next cut-off will happen in ISO 8601 format expressed as UTC, for example 2023-12-22T09:47:06.090Z.

{
  "id": "TQQ",
  "external_code": "",
  "name": "TechDoc University",
  "email": "",
  "website": "",
  "logo_url": "https://cloud.TechDoc_University_Logo1695717629",
  "address": "London Street",
  "address2": "",
  "city": "London",
  "state": "London",
  "zip": "",
  "country": "GB",
  "currency": "GBP",
  "fields": [
    {
      "id": "services_used",
      "type": "array",
      "format": "",
      "required": false,
      "pattern": null,
      "pattern_message": null,
      "value": [
        {
          "label": "Housing",
          "value": "housing"
        },
        {
          "label": "Tuition & Fees (including room & meal plan)",
          "value": "tuition"
        },
        {
          "label": "Orientation",
          "value": "orientation"
        }
      ],
      "view_options": {
        "section_identifier": "student_information",
        "section_name": "Student Information",
        "section_description": "Please provide us the following details",
        "label": "Services Used",
        "help": null,
        "hint": null,
        "placeholder": null,
        "position": 2,
        "hidden": false
      }
    }
  ],
  "items": [
    {
      "id": "default",
      "currency": "GBP",
      "label": "Amount"
    }
  ],
  "settings": {
    "amount_limits": {
      "minimum_amount": 3668,
      "maximum_amount": 11004758
    }
  },
"refund_bundle_cut_off": {
    "periodicity": "weekly",
    "approval_type": "manual",
    "next_cutoff_time": "2023-12-22T09:47:06.090Z"
	}
}

Key Elements of Recipient Data

Items

Settings

The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire.

If you didn't customize the settings, the default limits are:

• Minimum: 5000 = 50.00 USD

• Maximum: 15000000 = 150000.00 USD

When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items.

What happens when a payment is not within the defined settings?

When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned.

Fields

Field Types

"fields": [
      {
      "id": "student_status",
      "type": "string",
      "format": "",
      "required": false,
      "pattern": null,
      "pattern_message": null,
       "value": [
	    {
           "label": "Full-time",
           "value": "full_time"
        }, 
	    {
           "label": "Part-Time",
           "value": "part_time"
        },
	    {
           "label": "Online-Campus",
           "value": "online_campus"
        }
	   ],
       "internal_alias": null,
       "view_options": {
           "section_identifier": "student_information",
           "section_name": "Student Information",
           "section_description": "Please provide us the following details",
           "label": "Student Status",
           "help": null,
           "hint": null,
           "placeholder": null,
           "position": 1,
           "hidden": false
       }
   }
 ],

"fields": [
      {
      "id": "student_id",
      "type": "string",
      "format": "text",
      "required": true,
      "pattern": "^[f|F]\d{8}$",
      "pattern_message": "The ID begins with "F" followed by 8 digits",
      "value": "",
      "view_options": {
        "section_identifier": "student_information",
        "section_name": "Student Information",
        "section_description": "Please provide us the following details",
        "label": "Student ID",
        "help": null,
        "hint": null,
        "placeholder": null,
        "position": 4,
        "hidden": false
      }
   ],

"fields": [
    {
      "id": "residential_student",
      "type": "boolean",
      "format": "",
      "required": false,
      "pattern": null,
      "pattern_message": null,
      "value": "",
      "view_options": {
        "section_identifier": "student_information",
        "section_name": "Student Information",
        "section_description": "Please provide us the following details",
        "label": "Are you a residential student?",
        "help": null,
        "hint": null,
        "placeholder": null,
        "position": 3,
        "hidden": false
      }
    }
  ],

"fields": [
    {
      "id": "services_used",
      "type": "array",
      "format": "",
      "required": false,
      "pattern": null,
      "pattern_message": null,
      "value": [
        {
          "label": "Housing",
          "value": "housing"
        },
        {
          "label": "Tuition & Fees (including room & meal plan)",
          "value": "tuition"
        },
        {
          "label": "Orientation",
          "value": "orientation"
        }
      ],
      "view_options": {
        "section_identifier": "student_information",
        "section_name": "Student Information",
        "section_description": "Please provide us the following details",
        "label": "Services Used",
        "help": null,
        "hint": null,
        "placeholder": null,
        "position": 2,
        "hidden": false
      }
    }
  ],

Refunds: Cut-off time and Approval

A recipient must have the following settings in place to be able to use refunds:

• The recipient must have a cut-off time defined.

  More info

  The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.

  The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.

  You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.

• The recipient must have defined if refunds need to be approved or not.

  More info

  All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:

  Type of approval	approval_type setting for the recipient
  Manual approval Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).	manual
  Automatic approval Flywire processes refund bundles automatically after the cut-off time.	automatic

   

   

  To add or change the settings for refund approvals of a recipient please contact the Solutions team.