Intelligent Links

For this Pay-By-Link option, you’re creating the link by adding query parameter to the link you give to your payers.

 

How does it work?

  1. You build the link with these two parts:

    1. Base URL (depends on the environment you want to use, see Base URL)

    2. Query String (depends on your individual settings and use case, see Query parameters)

    Example:

    https://gateway.flywire.com/v1/transfers?provider=FWU&payment_destination=Model%20University&amount=200000&sender_first_name=Peter&sender_last_name=Payer

  2. You give the link to your payer.

Base URL

There are two different versions of Intelligent Links:

  • IL-Gateway

  • IL-Payment

Which one should I use?

You can use either version, both will bring your payers to your PayEx portal. They offer slightly different functionality, so which one you should choose depends on your current use case. This documentation will help you decide which version you want to use for each link you generate, depending on the features you need.

 

IL-Gateway

Production 
https://gateway.flywire.com/v1/transfers
Demo 
https://gateway.demo.flywire.com/v1/transfers

 

IL-Payment

Production 
https://payment.flywire.com/pay/payment
Demo 
https://payment.demo.flywire.com/pay/payment

Query parameters

Query parameters define your settings for the payment. With those parameters, you direct payers to your unique PayEx portal and decide which fields will be pre-filled there. Each query parameter has a value that will either define settings (for example, your portal ID that directs your payer to your unique PayEx portal) or will pass data into a field of your PayEx portal (for example, the payment amount).

Portal (required)

These parameters are required to properly direct your payer to your unique PayEx portal.

Your logo in the upper left corner tells your payers that they are in your unique PayEx portal: 

Providing these query parameters is required.

 

Name Description Example
provider

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.

 provider=FWU
payment_destination

The unique subdomain for the portal. The subdomain has been provided to you by Flywire when your portal was set up.

You can look up the subdomain by checking your portal configuration.
 payment_destination=myuniversity

Payment amount or items

When you set up your portal with Flywire, you decided if you always want to get one total amount from a payer or if you want to differentiate between different items (for example, "housing" and "tuition") that each have their own amount. If you want to change this setting, please contact the Solutions team.

My portal uses one amount

Providing these query parameters is optional.

 

Name Description Example
amount

The payment amount in the billing currency.

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.

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.

 amount=10000
max_amount
This parameter can only be used for IL-Gateway links
(Base URL https://gateway.flywire.com/v1/transfers).

The max_amount parameter lets you set the maximum amount you're asking for, allowing your payer to change it to a smaller amount.

This is useful, for allowing partial payments or when the payer might have already partially paid via a different payment. For this reason, you set always set the max_amount to the same amount as the amount (or total amount of all items) - this gives your payer the option to pay less than the amount you are asking for.

If your portal uses items, the maximum amount applies to the sum of all items.

It depends on your portal settings if a payer is allowed to edit the amount you passed. Consider your portal settings before you pass amounts or define a maximum amount.

If you pre-filled the amount and the portal setting is that payers can edit the amount, your payer sees an editable field with the amount you passed. Your amount acts as a suggested amount, but the they can enter a different amount, higher or lower.

Your portal has general settings for minimal and maximal amounts for payments. The amount your payer enters must be within those settings, otherwise they will get an error.

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.

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.

If you use the max_amount parameter, the field is only editable to the maximum amount you passed.

The max_amount parameter lets you set the maximum amount you're asking for, allowing your payer to change it to a smaller amount.

This is useful, for allowing partial payments or when the payer might have already partially paid via a different payment. For this reason, you set always set the max_amount to the same amount as the amount (or total amount of all items) - this gives your payer the option to pay less than the amount you are asking for.

If your portal uses items, the maximum amount applies to the sum of all items.

Your payer will see a read-only field with the fixed amount you passed via the link.

 

This portal setting means you have to be careful when creating links.

If your portal doesn't allow payers to edit the amount field, using one total amount (not items), the following can result in a blockage for the payer because the amount will be 0 and not editable, which means the payer will not be able to go through the further steps in your PayEx portal:

  • Passing no amount (since the amount parameter is optional in the request body, the link will successfully be generated, but your payer will be blocked).

  • Passing only max_amount and no amount.

  • Passing an amount that is higher than the max_amount (since this amount contradicts the setting for maximum amount).

If your portal is using items, this does not apply. In all cases above, the amount fields for the items will be 0 but editable for the payer.

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.

 max_amount=10000
read_only (missing or bad snippet)

Use the field name(s) of the fields you want to make read only:

read_only=amount,student_id

You can pass multiple values as a comma-separated list with no spaces in between.

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example this means: read_only=amount%2Cstudend_id

My portal uses items

Providing these query parameters is optional.

 

Name Description Example

FOR IL-GATEWAY

items[item_internal_name]

FOR IL-PAYMENT

item_internal_name

The amount for this item in the billing currency,

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.

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.

FOR IL-GATEWAY

items[tuition]=200000

FOR IL-PAYMENT

tuition=200000

read_only
This parameter can only be used for IL-Payment links
(Base URL https://payment.flywire.com/pay/payment).

You can use the read_only parameter to make a field read-only. The following types of fields can be made read-only:

  • amount (either one amount or individual amounts for items)

  • dynamic fields

Use the field name(s) of the fields you want to make read only:

read_only=amount,student_id

You can pass multiple values as a comma-separated list with no spaces in between.

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example this means: read_only=amount%2Cstudend_id

Dynamic fields

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.

Guide for pre-filling dynamic fields

Pre-filling dynamic fields is optional. If you want to pre-fill them, you need to provide the internal_name of the field (you can check your portals settings to find the internal names of your dynamic fields.).

Dynamic fields can have different types, and it depends on the field type how you pre-fill them via query parameters.

  • Text
  • Dropdown
  • Single checkbox
  • Multiple checkboxes
Description How to pre-fill the field

A field to enter text. The field can have different formats:

Free text field

Phone number field

Country dropdown field

Date field
When you are checking your portal settings, this field type is called string - text/phone/country/date.

Field name:

Use the internal name (Id) of the field. You can check your portal settings to find the Id.

Values:

Free text

Pass the text as a string.

 student_id=ID123456

Phone number

The phone number of the payer (including the country code).

Use 00 in front of the country code, for example, "0044123456" for country code 44.

phone_number=0044123456789
Country

The ISO2 code of the country.

 country_residence=US
Date

Date in dd/mm/yyyy format, for example 01/01/2025.

 start_date=01/01/2025

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example this means: start_date=01%2F01%2F2025
Description How to pre-fill the field

A dropdown field with one possible option to pick.

When you are checking your portal settings, this field type is called string.

Field name:

Use the internal name (Id) of the field. You can check your portal settings to find the Id.

Values:

Pass the internal name (value, not the label of the value) as a string.

If you don't know the internal value for the labels in PayEx, contact the Solutions team.

You can only pass one value, since this is a dropdown.

Example:

student_status=full_time

Description How to pre-fill the field

A single checkbox so payers can check it for "yes" or uncheck it for "no"

When you are checking your portal settings, this field type is called boolean.

Field name:

Use the internal name (Id) of the field. You can check your portal settings to find the Id.

Values:

Pass either true (checkbox activated) or false (checkbox deactivated), since this is a boolean field.

Example:

residential_student=true

Description How to pre-fill the field

Multiple checkboxes so the payer can pick multiple values.

When you are checking your portal settings, this field type is called array.

Field name:

Use the internal name (Id) of the field. You can check your portal settings to find the Id.

Values:

Pass the internal name (value, not the label of the value) as a string.

If you don't know the internal value for the labels in PayEx, contact the Solutions team.

Example:

services_used=housing

You can pass multiple values as a comma-separated list with no spaces in between.

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example this means: services_used=housing%2Ctuition

Controlling if the payer can edit pre-filled fields

For IL-Payment:

When you pre-fill fields via the generated link, dynamic fields will still be editable. You can decide if you want to make them read-only for your payers with the read_only parameter.

Name Description Example
read_only
This parameter can only be used for IL-Payment links
(Base URL https://payment.flywire.com/pay/payment).

You can use the read_only parameter to make a field read-only. The following types of fields can be made read-only:

  • amount (either one amount or individual amounts for items)

  • dynamic fields

Use the field name(s) of the fields you want to make read only:

read_only=amount,student_id

You can pass multiple values as a comma-separated list with no spaces in between.

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example this means: read_only=amount%2Cstudend_id

 

For IL-Gateway:

When you pre-fill fields via a generated link, dynamic fields will be read-only for your payer.

This means:

  • For checkboxes, your payer won't be able to select more values or un-select the ones you selected.

  • If you pass invalid values (because of a typo or because the internal name of a value has been changed), the field will be empty and read-only for your payer. If the field is mandatory, this can mean that your payer can't complete the payment. Be careful with passing values that are prone to change.

Payer information

Payer information fields contain the details of the payer. The information necessary for Flywire to conduct compliance checks, such as Anti-Money-Laundering (AML). If the payer details are known to you, you can pre-fill the payer fields in your PayEx portal.
Providing these query parameters is optional.

 

Name Description Example

sender_email

The payer's email address.

[email protected]

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

sender_email=p-payer%40example.com

sender_first_name

The payer's first name.

If the payer is a company or organization, use the organization name as the first name.

 sender_first_name=Peter
sender_middle_name

The payer's middle name.

 sender_middle_name=James
sender_last_name

The last name (family name) of the payer.

If the payer is a company or organization, use the organization name as the last name.

 sender_last_name=Payer
sender_address1

The first line of the payer's address.

The residential address is required for legal reasons, which is why PO boxes are not permitted.

sender_address1=Main Street 14

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example:

sender_address1=Main%20Street%2014

sender_address2

The second line of the payer's address.

sender_address2=Apartment 2

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this example:

sender_address2=Apartment %202

sender_city

The payer's city.

 sender_city=London
sender_state

The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.

 sender_state=NY
sender_zip

The payer's zip code.

 sender_zip=12345
sender_phone

The phone number of the payer (including the country code).

Use 00 in front of the country code, for example, "0044123456" for country code 44.

sender_phone=00441234567

Payer redirection

You can display a button in your PayEx portal that redirects your payer somewhere, for example your website. This button is displayed on the final page of the payment creation process, to the right of the payment instructions.

Your portal might have default settings for the return button and its label. In that case, you don't need to provide a URL in order to display the button. But if there are no default settings and you don't provide a valid URL in the return_cta parameter, the button will not be displayed

Providing these query parameters is optional.

 

Name Description Example
return_cta

The URL payers are directed to when clicking the return button.

Maximal 500 characters.

Your portal might have default settings for the return button and its label. In that case, you don't need to provide a URL in order to display the button. But if there are no default settings and you don't provide a valid URL in the return_cta parameter, the button will not be displayed

return_cta=https://www.my-website.com

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this case:
return_cta=https%3A%2F%2Fwww.my-website.com
return_cta_name

The label of the return button. Maximum 500 characters.

If you don't specify a label for your button, the default label "Return to {portal name}" is used.

return_cta_name =Return to my website

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this case:
return_cta_name=Return%20to%20my%20website

Callback configuration

Flywire supports notifications via callbacks (also known as webhooks). These allow your system to receive real-time notifications about important events.

Payment status notifications are callbacks for payment key events, such as a payment status change.

Using callbacks for payments is optional, but has several benefits:

  • Callbacks can be used to facilitate reconciliation of Flywire payments to accounting systems, ERPs, etc.

  • Callbacks provide real-time updates for payment statuses, no manual checks in Dashboard needed.

  • Callbacks are especially useful for direct debit payments where the payment capture will take a few working days and may be subject to future failure.

  • You can use callbacks to trigger processes that start after the payment is completed.

Enabling callbacks

To enable callbacks, you need to provide a notification URL where Flywire will send HTTP requests. This can be done in two ways:

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set   = set

 

Static
URL		 Dynamic
URL		 Result
You won't receive notifications.
You'll receive notifications to your static URL.

For API integrations:

The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL.

For other integrations:

You'll receive callbacks to both URLs. This is called "dual callback URL".

A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.

You'll receive notifications to your dynamic URL

 

 

Providing these query parameters is optional.

 

Name Description Example
callback_url

The URL for receiving notifications.

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set   = set

 

Static
URL		 Dynamic
URL		 Result
You won't receive notifications.
You'll receive notifications to your static URL.

For API integrations:

The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL.

For other integrations:

You'll receive callbacks to both URLs. This is called "dual callback URL".

A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.

You'll receive notifications to your dynamic URL

 

callback_url=https://www.example.com

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).

In this case:
callback_url=https%3A%2F%2Fwww.example.com
callback_id

The external reference.

The external reference is used to match a notification to a particular payment. You can use any kind of identifier or reference from your own system you might need to identify the payment. The external reference is included in all status notifications for this payment (refer to Payment Status Notifications) to help you match the notification to the right payment using your own reference in addition to the Flywire-generated payment reference.

callback_id=my-callback-id

Keep in mind: Special characters must be URL-encoded for Pay-By-Link with query parameters (e.g., @ → %40 and , (comma) → %2C).
callback_version

The version of the callback. Possible values:

  • 2 (for version 2)

If you want to receive callbacks, you must provide the callback version and it must be version 2.

For details about callbacks see Payment Status Notifications.

 callback_version=2