Payment Request Links

There are two ways to create Payment Request links: via query parameters and via API requests. This page is about creating Payment Requests via query parameters.The end result of creating the link will be a stateful link that you can give to a payer.

More info about the two options

To create links, you have two options:

1) Build the link with 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 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 the query parameters and values are identical, the same Payment ID will be generated.

2) Build the link with the Flywire API (see Payment Requests or Subscriptions).

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

More info about stateful links

	For a single payment, the link 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.
	For multiple installments, the link shows an overview about all installments in this request and lets the payer pay for them individually. Since the link is stateful, the overview gets updated whenever a payment is made.
	For subscriptions, the payer can save the payment method for all payments of this subscription. They also get an overview about past and upcoming payments of this subscription. Since the link is stateful, the overview gets updated whenever a payment is made.

More info about Payment Requests

A Payment Request is a way to ask your customer to make a payment, typically by sending them a link. Unlike links for standalone payments, links to a Payment Request are stateful, which means they retain the information if a payment has already been made.

Examples for what your payer sees when accessing Payment Request links

	For a single payment, the link 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.
	For multiple installments, the link shows an overview about all installments in this request and lets the payer pay for them individually. Since the link is stateful, the overview gets updated whenever a payment is made.
	For subscriptions, the payer can save the payment method for all payments of this subscription. They also get an overview about past and upcoming payments of this subscription. Since the link is stateful, the overview gets updated whenever a payment is made.

Payment Requests also serve as an umbrella sitting on top of one or multiple payments. In Dashboard, the Payment Request tab shows you all different kinds of Payment Requests:

• Payment Request for a Single Payment

• Payment Request for Multiple Installments

• Payment Request for Subscriptions

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

Creating a Payment Request link

You can create payment request 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/#/payment-request/quick-pay?code=FWB&clientId=XYZ123&amount=2000&firstName=John&lastName=Doe

Base URL

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

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

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.

• It depends on your settings which payer data and custom fields you need to provide.

  How to find out which fields are required for creating the Payment Request or subscription

  You can check the settings in Client 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.

Portal identification and authentication (required)

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
clientId	Your client ID is identical to the public reference of your company. What is a company and a public reference? 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.	required	clientId=ABC123

Payment amount (required)

Payer data

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

Which payer data fields are required?

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

How to find out which fields are required for creating the Payment Request or subscription

You can check the settings in Client 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.

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 your settings if a custom field is optional or required.

There are two layers of required fields:

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.

How to find out which fields are required for creating the Payment Request or subscription

You can check the settings in Client 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.

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. This means if a field is not required in Dashboard but is required for the portal, you have the option to not provide it when you create the Payment Request or subscription. But since it is required to create the payment, your payer has to fill out the field in the Checkout Experience form.

How to find out which fields are required for a portal

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)

Language options

Parameter	Description	Type	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. Supported languages and their values 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). What is 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. 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

Callbacks for Payment Requests

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 are different from payment status callbacks.

What does dynamic and static callback URL mean?

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 Pay-By-Link and Checkout , 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

= not set

= set

 

Static URL	Dynamic URL	Result
		You won't receive callbacks .
		You'll receive callbacks to your static URL. You'll also receive callbacks for payments that are part of Payment Requests.
		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.
		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 and URL encoding to enhance their security.

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 += '&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);

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