Payment Request Links

This page is about creating Payment Requests via query parameters.

When you are using query parameters, you can only create links for a Payment Request with a single payment.

A Payment Request is a way to ask your customer to make a payment, typically by sending them a link. Payment Requests serve as an umbrella sitting on top of one or multiple payments.

Payments Requests can be edited after they are created, for example, you can add more payments to it (see Managing Payment Requests).

Payment Requests can be used for different purposes:

Want to create Payment Request links with more features?

For creating Payment Requests links with features like installments or subscriptions you need to use imageClient Dashboard or the imageFlywire API.

Want to manage Payment Requests after creating them?

For managing Payment Requests, for example changing or deleting them, you need to use imageClient Dashboard or the imageFlywire API .

Want to receive callbacks?

Make sure you read the Notes for Callbacks.

How it works

  1. You build a Payment Request by constructing them with these two parts:

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

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

    Example:

    https://app.flywire.com/#/payment-request/quick-pay?code=FWB&clientId=XYZ123&amount=2000&firstName=John&lastName=Doe

  2. You give this link to your payer, for example via email.

  3. The payer visits the link.

  4. Once the payer clicks on the "Make Payment" button, the query parameters are resolved into a Payment Request ID and a Payment Request is created in your system.

  5. Now that the Payment Request has been created, it will be visible to you in Dashboard and via the API.

Which type of Payment Request link do you want to create?

Unpaid:

Paid:

image

A stateful Payment Request link for single payment shows the amount to pay. Since the link is stateful, visiting the link again after the payment is made shows the information that the amount is already paid. This means you can use these types of links for unique links, for example links that you only want to use for a specific payer.

Good to know:

Stateful Payment Request links are ideal for highly customized links you want to send to a specific customer. For example, you can insert them into an invoice or an email template and they pre-fill the Checkout Experience form with all the payer info and the payment amount.

You can create stateful Payment Request links via Pay-By-Link or via an API request.

To create the links, you have two options:

1) Build the link with image Pay-By-Link using query parameters (see Payment Request Links).

  • When you are using query parameters, you can only create links for a Payment Request with a single payment.

  • When building stateful Payment Request links via query parameters, you must include a unique value, like a booking reference. This ensures that the system generates a unique Payment Request ID. If you use identical query parameters and values, they will always be resolved to the same Payment Request ID.

    This ID has been automatically generated when the Payment Request or subscription was created.

    This ID is publicly visible at the end of the Payment Request link, for example:

    https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

    Format:

    959c09e5-a27b-49e9-8f92-e9e13374cfdd

    32 hexadecimal characters grouped into 8-4-4-4-12

2) Build the link with the imageFlywire API (see Payment Requests).

  • With the API, you can create Payment Requests (with single payments or multiple installments, with or without a due date) and subscriptions.

  • You don't need a unique identifier value since the API will generate a unique ID independently of the parameter values.

  • Payment Request links created with the API are always stateful.

A stateless Payment Request link shows a form to enter payer details and then make a payment - even if a payment already has been made through this link. This means you can use these types of links to reuse them, for example using them on your website to always make a payment with a pre-set amount.

Good to know:

Stateless links need to be enabled for your portal before you can use them. Please reach out to your Flywire contactfor this.
Stateless links always create a Payment Request for a single payment.
Unlike stateful Payment Request links, stateless links don't require an amount to be provided, which means you can use them for completely "blank" links that don't pre-fill any fields.
Depending on your portal settings, it might be mandatory for the payer to store their used payment method for future payments. If this is the case for your portal, creating a Payment Request will create a new contact with the payer's details in Dashboard and the payment method will be saved for this contact.

Payment Request Link Generator

Important for stateful links

When building stateful Payment Request links via query parameters, you must include a unique value, like a booking reference. This ensures that the system generates a unique Payment Request ID. If you use identical query parameters and values, they will always be resolved to the same Payment Request ID.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

Choose which parameters you want to see on this page:

Base URL

Choose the base URL for your link type and environment:

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 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.
Portal identification and authentication

Providing the portal code and client ID is required. If you don't know them, please reach out to your Flywire contact.

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)

Your client ID is identical to the public reference of your company.

Your account with Flywire is called a company. Your company can have access to multiple portals (also called recipients).

The public reference (also called client ID) uniquely identifies this company in the Flywire system. It is a six-character code that can contain letters and numbers in the format ABC123.

Payment amount

Providing an amount it required for stateful Payment Request links.

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).

Payer data

Some payer data fields might be required for creating the link.

It depends on your Dashboard settings whether and which sender (payer) fields are required.

You can check the settings in imageClient Dashboard under "Settings - Payment Requests". If your user doesn't have the permissions to view this tab, you can create a new Payment Request in Dashboard and check which fields are marked as required.

Parameter Description 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.

 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.

 lastName=Doe
email

The payer's email address.

This parameter has a maximum length of 32 characters.

 [email protected]
address

The payer's address.

 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.

 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.

 state=MA
zip

The payer's zip code.

 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.

 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.

phone=+16173214567
Custom fields for the portal

Some custom fields might be required for creating the link.

It depends on your settings if a custom field is optional or required.

There are two layers of required fields:

1) Fields that are required due to settings in your Dashboard

If a field is set to required in Client Dashboard, you must provide it when you create the Payment Request or subscription. Optional fields can be left out.

You can check the settings in imageClient Dashboard under "Settings - Payment Requests". If your user doesn't have the permissions to view this tab, you can create a new Payment Request in Dashboard and check which fields are marked as required.

2) Fields that are required due to settings for the portal

If a field is required for the portal, it is required to create the payment.

If a field is not required due to Dashboard settings but is required for the portal, you can decide if you provide it or not when you create the Payment Request or subscription. If you don't provide it, your payer has to fill out the field in the Checkout Experience form, since it is required to create the payment.

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.

Check your portal configuration to see which custom fields exist for your 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.

Language options

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
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

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

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).

QR code settings
Your link and QR code

Payment Request Links Reference

Base URLs

For stateful links

Production 
https://app.flywire.com/#/payment-request/quick-pay
Demo 
https://app.demo.flywire.com/#/payment-request/quick-pay

For stateless links

Production 
https://app.flywire.com/#/payment-request/send
Demo 
https://app.demo.flywire.com/#/payment-request/send

List of parameters

All values must be URL encoded since they are used in query string parameters. To make reading the guide easier the example values have not been encoded. Omitting this step may generate broken links.

Important for stateful links

When building stateful Payment Request links via query parameters, you must include a unique value, like a booking reference. This ensures that the system generates a unique Payment Request ID. If you use identical query parameters and values, they will always be resolved to the same Payment Request ID.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

Portal identification and authentication (required)

Providing the portal code and client ID is required. If you don't know them, please reach out to your Flywire contact.

Parameter Description 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)

 code=FWB
clientId

Your client ID is identical to the public reference of your company.

Your account with Flywire is called a company. Your company can have access to multiple portals (also called recipients).

The public reference (also called client ID) uniquely identifies this company in the Flywire system. It is a six-character code that can contain letters and numbers in the format ABC123.

 clientId=ABC123

Payment amount (required for stateful links)

Providing an amount it required for stateful Payment Request links.

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

The amount is specified as a decimal (1000.25).

 amount=1234.56

Payer data

Some payer data fields might be required for creating the link.

It depends on your Dashboard settings whether and which sender (payer) fields are required.

You can check the settings in imageClient Dashboard under "Settings - Payment Requests". If your user doesn't have the permissions to view this tab, you can create a new Payment Request in Dashboard and check which fields are marked as required.

Parameter Description 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.

 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.

 lastName=Doe
email

The payer's email address.

This parameter has a maximum length of 32 characters.

 [email protected]
address

The payer's address.

 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.

 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.

 state=MA
zip

The payer's zip code.

 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.

 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.

phone=+16173214567

Custom fields for the portal

Some custom fields might be required for creating the link.

It depends on your settings if a custom field is optional or required.

There are two layers of required fields:

1) Fields that are required due to settings in your Dashboard

If a field is set to required in Client Dashboard, you must provide it when you create the Payment Request or subscription. Optional fields can be left out.

You can check the settings in imageClient Dashboard under "Settings - Payment Requests". If your user doesn't have the permissions to view this tab, you can create a new Payment Request in Dashboard and check which fields are marked as required.

2) Fields that are required due to settings for the portal

If a field is required for the portal, it is required to create the payment.

If a field is not required due to Dashboard settings but is required for the portal, you can decide if you provide it or not when you create the Payment Request or subscription. If you don't provide it, your payer has to fill out the field in the Checkout Experience form, since it is required to create the payment.

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.

Check your portal configuration to see which custom fields exist for your 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.

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

Language options

Parameter Description Example
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
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 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
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).

 filterCcy=fx

Notes for Callbacks

Callbacks for the Payment Request

Callbacks for Payment Requests are set up via Dashboard, see Callbacks for Payment Request Notifications.

Callbacks for payments that are part of a Payment Request

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 is different from payment status 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. You define the URL for the imageCheckout integration 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 is 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.

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 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 with URL Encoding

Note: Do not include the leading query string ?

3. Base64 Encoding

4. Final URL Construction

const baseUrl = 'https://app.flywire.com/#/payment-request/quick-pay';
// Note: Do not include the leading query string ?
let queryString = 'code=FWB';
queryString += '&clientId=ABC123';
queryString += '&amount=1234.56';
queryString += '&email=' + encodeURIComponent('[email protected]');
queryString += '&address=' + encodeURIComponent('123 Main St, Suite #100');

queryString = btoa(queryString);

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

After the payment is created

After the payer followed the payment request link and filled out the form, a payment is created.

The payment will be visible to you in your imageClient Dashboard , where you can manage it (for example add installments) and track the payment's history (for example checking if the payer has opened the link).