Dynamic Links

Dynamic links create standalone payments.

A standalone payment is a one-time payment for a specific amount. Standalone payments are not part of a Payment Request or a recurring payment plan.

 

image

Links for standalone payments (called "dynamic links") are stateless, meaning they don’t track if the payment has already been made.

  • Dynamic links are ideal for unspecific links that you want to re-use, for example a payment link on your website that always fills the Checkout Experience form with the same amount, but doesn't pre-fill any information about the payer since you don't know who will be clicking the link.

  • While you can also send dynamic links to a specific customer, they are not ideal since those links will ask the customer to pay each time they click on the link. This could result in duplicate payments (meaning the payer creates multiple payments in the Flywire system), even though Flywire has measures in place to try to prevent this.

  • Dynamic links allow you to provide a dynamic URL for receiving callbacks for the payment. If you don't provide a dynamic URL, the fixed URL of the portal will be used (if there is one).

    There are two different URLs for receiving callbacks:

    Static URL

    A static callback URL is a fixed URL defined in your portal. All payments for this portal will send callbacks to this URL.

    The static callback URL has been defined when your portal was set up. If you don't use a static callback URL yet and want to start using it, please reach out to your Flywire contact.

    Dynamic URL

    A dynamic callback URL is a URL that you define when you create the payment. Since this URL can be different for every payment you create, it is called dynamic.

    For image Pay-By-Link and imageCheckout , you define the URL via the callbackUrl parameter.

    If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

    You cannot provide a dynamic callback URL for payments that are part of a Payment Request. To receive callbacks about those payments, you have to use the static URL. Alternatively, you can use callback notifications for Payment Request status updates, but note that the content of those callbacks are different from payment status callbacks.

    How defining static and dynamic URLs affect callbacks

    image = not set   image = set

     

    Static
    URL    		 Dynamic
    URL    		 Result
    image image You won't receive callbacks .
    image image

    You'll receive callbacks to your static URL.

    You'll also receive callbacks for payments that are part of Payment Requests.
    image image

    You'll receive callbacks to both URLs.

    You'll also receive callbacks for payments that are part of Payment Requests, but only to the static URL.
    image image

    You'll receive callbacks to your dynamic URL

    You will not receive callbacks for payments that are part of Payment Requests since there is no static URL.

You can create dynamic links by constructing them 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 string parameters)

Example:

https://app.flywire.com/solutions/quick-pay/?code=FWB&amount=2000&firstName=John&lastName=Doe

Base URL

Production 
https://app.flywire.com/solutions/quick-pay/
Demo

Instead of having separate URLs for production and demo, the environment is determined by the query string parameter env.

By default the production environment will be used if no env parameter is supplied within the URL.

Query string parameters

All parameters are added as query string key value pairs.

Things to keep in mind:

  • All query string parameter values should be URL encoded. To make reading the guide easier the example values have not been encoded. Omitting this step may generate broken links.

Environment

Parameter Description Type Example
env

You can add the env parameter to point to the desired environment. Possible values:

  • demo

  • prod (Default)

By default the production environment will be used if no env parameter is supplied within the URL.

 optional env=demo

Portal identification (required)

If you don't know your portal code, please reach out to your Flywire contact.

 

Parameter Description Type Example
code

The portal code for this portal (also called recipient).

The portal code identifies the portal. The portal code has been assigned by Flywire when the portal has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

 required code=FWB

Payment amount (required)

Parameter Description Type 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 portal's configuration and is defined when the portal is set up by Flywire.

The amount is specified as a decimal (1000.25).

 required amount=1234.56

Payer data

You can pass payer data to pre-populate the fields in the Checkout Experience form.

 

Parameter Description Type Example
firstName

The payer's first name.

This parameter has a maximum length of 256 characters.

This parameter cannot contain Chinese (Han), Japanese (Katakana or Hiragana), or Korean (Hangul) characters.

 recommended firstName=John
lastName

The last name (family name) of the payer.

This parameter has a maximum length of 256 characters.

This parameter cannot contain Chinese (Han), Japanese (Katakana or Hiragana), or Korean (Hangul) characters.

 recommended lastName=Doe
email

The payer's email address.

This parameter has a maximum length of 32 characters.

 recommended [email protected]
address

The payer's address.

 optional address=21 Jump St
city

The payer's city.

This parameter has a maximum length of 256 characters.

This parameter cannot contain Chinese (Han), Japanese (Katakana or Hiragana), or Korean (Hangul) characters.

 optional city=Boston
state

The state of the payer.

Format:

Only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.

This parameter has a maximum length of 256 characters.

This parameter cannot contain Chinese (Han), Japanese (Katakana or Hiragana), or Korean (Hangul) characters.

 optional state=MA
zip

The payer's zip code.

 optional zip=02111
country

The country of the payer.

Format:

Two-letter format (ISO 3166-1 alpha-2), for example US for USA or GB for the United Kingdom.

 optional country=US
phone

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

Use + in front of the country code, for example, "+44123456" for country code 44.

optional phone=+16173214567

Custom fields for the portal

Custom fields are fields that are specific to your portal.

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.

Which fields are required?

It depends on the recipient which fields are optional or required. If a field is required, you must provide it here. Optional fields can be left out.

You have two options:

Checking via the API

You can check which fields are required for a recipient (portal) with this request (replace {recipientId} with the recipient ID):

GET/payments/v1/recipients/{recipientId}

Required fields have the required parameter set to true. For more info see Getting Details about a Recipient.

Checking online

You can check which fields are required by checking your portal configuration.

Example for common custom fields:

(Note that the custom fields for your portal might be different, these are just examples)

Parameter Description Example
booking_reference Unique booking identifier booking_reference=REF-1234
invoice_number Unique invoice identifier invoice_number=INV-1234

Read-Only fields

You can set payer information and custom fields for the portal to read-only in the Checkout Experience form.

Parameter Description Type Example
readOnly

Provide fields as a comma separated list to make them un-editable.

 optional readOnly=email,booking_reference

Display Options

Parameter Description Type Example
title You can add a title to the payment page to add some additional context to your payer as to what the payment is for, or just as a welcome message. optional title=Please make your payment.
subTitle You can add a sub-title to the payment page to add some additional context to your payer as to what the payment is for, or just as a welcome message. optional subTitle=We look forward to seeing you soon!
locale

Enables you to set the language of the payment page.

If not provided, the payment page defaults to the browser's language (if supported). While browser-based adaptation is recommended, you can set a fixed language using this parameter.

Language Value for locale
English en
Spanish es
Chinese zh
Korean ko
Portuguese pt
Japanese ja
French fr
Bahasa Indonesia id
Vietnamese vi
optional locale=es

Filtering payment options

By default, Flywire displays all payment options for a portal. In some cases, you might want to restrict the available payment options, for example if you want to accept only bank transfers for payments over a certain amount or only show card payments a certain time before a booking.

You can use two filters to restrict payment options:

  • Restrict to specific types of payments

  • Restrict to specific currencies

 

Parameter Description Type Example
filterType

Payment method type filters.

Each filter you add means show this option. Each filter you leave out means hide this option.

For example, credit_card ,online means: Show card payment options and online alternative pay options, but no bank transfer options.

If you don't provide any filters, all payment method types will be displayed in the Checkout Experience.

bank_transfer Bank transfer option - payer receives instructions how to transfer the money to Flywire
credit_card Card payment options - credit or debit cards
online Alternative online payment options - e.g. PayPal
direct_debit Direct debit option - funds are automatically withdrawn from the payer’s bank account
moto_payment MOTO (Mail Order / Telephone Order) payment – payments entered manually by a Flywire agent
optional filterType=online,credit_card
filterCcy

Payment currency filters. The filters restrict payment options based on currencies:

local

Show only payment options in the payer's local currency (e.g., only GBP for a payer in the UK).
foreign

Show only payment options not in the payers local currency (e.g., everything but GBP options for a payer in the UK).
fx

Only show payment options that are a different currency to the billing currency (e.g., everything but GBP if your billing currency is GBP).

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

Only show payment options that are in the same currency as the billing currency (e.g., only GBP if your billing currency is GBP).

Be careful with combining those filters. Your payer might end up not being able to pay if you restrict the options too much. As a best practice, use either local/ foreign (when you want the options to depend on the payer's country) or fx / nonFX (when you want the options to depend on your billing currency).

 optional filterCcy=fx

Split Payments

A split payment allows you to divide a payment between multiple portals.

This means if your customer makes a payment, a portion of that amount can be sent to your partners, with the remaining balance going to you. This ensures that different parties receive their share of a payment in one simple transaction.

You can define multiple partner recipients for one payment and set specific amounts for each partner.

Each recipient must have a portal code from Flywire to receive their portion.

Parameter Description Type Example
payoutCode

The portal code of the partner who receives a portion of the payment.

The portal code identifies the portal. The portal code has been assigned by Flywire when the portal has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

 optional* payoutCode=FWB
payoutAmount

The amount of the portion for the partner.

Must not exceed the payment amount.

 optional* payoutAmount=123.45

*Using split payments is optional, but if you use them both the payoutCode and payoutAmount parameters are required.

Callback Notifications

Payment status notifications are callbacks for payment key events, such as a payment status change. They enable you to track a payment while it makes its way through the payment workflow. Whenever a status change event occurs, for example when the payment status changes from Initiated to Processed, you'll get a notification to the URL you provided.

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

A static callback URL is a fixed URL defined in your portal. All payments for this portal will send callbacks to this URL.

The static callback URL has been defined when your portal was set up. If you don't use a static callback URL yet and want to start using it, please reach out to your Flywire contact.

Dynamic URL

A dynamic callback URL is a URL that you define when you create the payment. Since this URL can be different for every payment you create, it is called dynamic.

For image Pay-By-Link and imageCheckout , you define the URL via the callbackUrl parameter.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

You cannot provide a dynamic callback URL for payments that are part of a Payment Request. To receive callbacks about those payments, you have to use the static URL. Alternatively, you can use callback notifications for Payment Request status updates, but note that the content of those callbacks are different from payment status callbacks.

How defining static and dynamic URLs affect callbacks

image = not set   image = set

 

Static
URL		 Dynamic
URL		 Result
image image You won't receive callbacks .
image image

You'll receive callbacks to your static URL.

You'll also receive callbacks for payments that are part of Payment Requests.
image image

You'll receive callbacks to both URLs.

You'll also receive callbacks for payments that are part of Payment Requests, but only to the static URL.
image image

You'll receive callbacks to your dynamic URL

You will not receive callbacks for payments that are part of Payment Requests since there is no static URL.

 

If you are using callbacks, it is highly recommended to use Anti-Tampering for the URL.

Parameter Description Type Example
callbackUrl

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

A static callback URL is a fixed URL defined in your portal. All payments for this portal will send callbacks to this URL.

The static callback URL has been defined when your portal was set up. If you don't use a static callback URL yet and want to start using it, please reach out to your Flywire contact.

Dynamic URL

A dynamic callback URL is a URL that you define when you create the payment. Since this URL can be different for every payment you create, it is called dynamic.

For image Pay-By-Link and imageCheckout , you define the URL via the callbackUrl parameter.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

You cannot provide a dynamic callback URL for payments that are part of a Payment Request. To receive callbacks about those payments, you have to use the static URL. Alternatively, you can use callback notifications for Payment Request status updates, but note that the content of those callbacks are different from payment status callbacks.

How defining static and dynamic URLs affect callbacks

image = not set   image = set

 

Static
URL		 Dynamic
URL		 Result
image image You won't receive callbacks .
image image

You'll receive callbacks to your static URL.

You'll also receive callbacks for payments that are part of Payment Requests.
image image

You'll receive callbacks to both URLs.

You'll also receive callbacks for payments that are part of Payment Requests, but only to the static URL.
image image

You'll receive callbacks to your dynamic URL

You will not receive callbacks for payments that are part of Payment Requests since there is no static URL.

 

If you are using the Checkout or Pay-By-Link integration:

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

 optional* callbackUrl=https://api.your-domain.com/flywire-notifications
callbackId

The external reference.

The external reference helps you to identify a payment, since the Flywire-generated payment reference might not be the way you typically identify payments. With the external reference, you can enter your own identifier, such as an ID or invoice number.

The external reference is included in all status notifications to help you map a payment to a callback notification. (see Payment Status Notifications)

If you are using the Checkout or Pay-By-Link integration:

The external reference is called "callback ID" here. You'll find the callbackId in the external_reference parameter of the callback.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

 optional* callbackId=REF1234
callbackVersion

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.

 optional callbackVersion=2

*Using callbacks is optional, but if you want to use them the parameters are interdependent. If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.Technically, setting the callback version is optional. But since the default is 1, clients have to set it to 2 manually to receive the only version we talk about and we want them to receive.

Redirection

You can redirect payers to your website or any page of your choice after a successful payment. For failed payments, the payer will automatically be given the option to try again.

Parameter Description Type Example
returnUrl

The return URL serves two purposes:

  1. It specifies where the payer will be redirected after the payment is created and the Checkout Experience form closes. Example: http://www.developers.flywire.com

  2. Query parameters with payment information are automatically added to the return URL.

    While the payer is redirected to the return URL, Flywire attaches query string parameters containing payment information to the set URL. This way, your website can receive and process the payment information without requiring additional API calls.

    It depends on the type of payment which parameters are returned, see Parameters returned via returnUrl or onCompleteCallback handler.

 optional returnUrl=https://httpbin.org/get

Anti-Tampering

When query parameters are used as plain text in URLs, they can be easily understood and potentially tampered with. To safeguard against this, you can encrypt the links with Base64 and URL encoding to enhance their security.

While this anti-tampering method does not fully prevent customers from decoding and editing the URL, it does effectively discourage casual users from viewing and altering the values within the URL.

1. Base URL

2. Query String Construction

Note: Do not include the leading query string ?

3. Base64 Encoding

4. URL Encoding

5. Final URL Construction

const baseUrl = 'https://app.flywire.com/solutions/quick-pay';
// Note: Do not include the leading query string ?
let queryString = 'code=FWB';
queryString += '&amount=1234.56';
queryString += '&callbackUrl=' + encodeURIComponent('https://api.your-domain.com/flywire-notifications');
queryString += '&callbackId=' + encodeURIComponent('REF1234');

queryString = btoa(queryString);
queryString = encodeURIComponent(queryString);

const finalUrl = baseUrl + '?' + queryString;
console.log(finalUrl);