Payment Requests

What is a Payment Request?

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

Payment Request Types

Payment Request for a Single Payment

A single payment for a specific amount that is part of a Payment Request. Giving the payment a due date is optional.

Unlike recurring payments, there are no follow-up payments and the payer's card or banking information is not stored in the Flywire vault.

Links for this kind of Payment Request:

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.

Options for creating the link:

Pay-By-Link

Flywire API

See Options for Creating Payment Request Links for more details.

Options for embedding via Checkout :

Embedding single Payment Requests is not possible.

More information

A Payment Request for a single payment generates a link to the Checkout Experience, but if you're using the Checkout integration, the Checkout Experience is already embedded in your website, so a link isn’t needed for single payments.

If you want to create a single payment embedded within your website, you can use Checkout for Standalone Payments instead.

Payment Request for Multiple Installments

A Payment Request with multiple installments allows you to collect future payments with variable amounts. You can decide if you want to have due dates for all installments to collect them on specific dates or if the installments have no specific due date.

Links for this kind of Payment Request:

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.

Options for creating the link:

Flywire API

See Options for Creating Payment Request Links for more details.

Embedding this Payment Request:

Scheduled payments allow you to collect future payments with variable amounts on specific dates. All payments that belong together are bundled into one Payment Request.

You can embed this type of Payment Request on your website via the Checkout integration. This lets your payer save their card or bank account to pay for scheduled payments or subscriptions.

Options for embedding via Checkout :

See Checkout for Scheduled Payments

Installments created via Checkout must have a due date, which is why they are called scheduled payments. If you want to create installments without a due date, you have to use the Flywire API.

Payment Request for Subscriptions

Subscription payments allow you to collect future payments with a fixed amount on regular intervals.For subscriptions, you cannot create or edit installments yourself - they are automatically generated by Flywire based on the rules that have been defined for the subscription.

In Dashboard, you can find subscriptions under "Payment Requests".

Subscription payments are a type of recurring payment.

Example:

"Store your card to pay 200 on the first of each month for one year."

Who handles future payment creation and emails to your payer?

Flywire will create the payments and send communications on your behalf at the appropriate times.

Links for subscriptions:

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.

Options for creating the link:

Flywire API

See Options for Creating Payment Request Links for more details.

Embedding subscriptions:

You can embed this type of Payment Request on your website via the Checkout integration. This lets your payer save their card or bank account to pay for scheduled payments or subscriptions.

Options for embedding via Checkout :

See Checkout for Subscriptions

Options for Creating Payment Request Links

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.

Managing Payment Requests

As long as the payment request is open (meaning at least one of the payments in it remains unpaid), you can make changes to it, for example add further installments or delete the whole request. You can also track the payment’s progress and status, and see its history, for example if and when the payer has opened the link.

Payment Requests can be managed either via Client Dashboard or the Flywire API:

Task	Via Client Dashboard	Via Flywire API
Get info about the Payment Request
Add/edit/delete installments
Delete Payment Request
Cancel Payment Request What is the difference between deleting and cancelling? Deleting a Payment Request or subscription permanently removes it from the system, which means: You can't view it in Dashboard anymore. You can't retrieve it via the API anymore. All future installments will cancelled. Your customer won't be able to make payments anymore. Deleting a Payment Request or subscription cannot be undone. Cancelling a Payment Request or a subscription means: It is permanently put in the CANCELLED status. All future installments will cancelled and payments will not be charged. Your customer will be notified about the cancellation via email and won't be able to make payments anymore. Cancelling a Payment Request or subscription cannot be undone. Unlike deleting, cancelling does not remove the Payment Request or subscription from the system, meaning you will still be able to view it in Dashboard and retrieve it via the API.
Map existing payment to the Payment Request
Send email reminders for upcoming payments
View a Payment Request's history

Checkout

The Checkout implementation allows you to embed the Checkout Experience into your own website.

With Checkout, your payers never leave your website:

With the click of a button on your website the Checkout Experience form opens for the payer.
In the form, the payer can choose their preferred payment method and complete the payment.
After the payment is completed and the form is closed, the payer either is returned to the original page or is redirected to a page you specified.

You can use Checkout for the following payment types:

Grand Horizons Travel Website

Luxury Trip Package

Experience the ultimate luxury getaway with our exclusive travel package. Enjoy a 7-day stay at a five-star resort, gourmet dining, private tours, and much more.

Price: 5.000,00 €

Pay with the button below.

How to embed the Checkout Experience via Checkout

This simplified html example shows you how to implement the Checkout Experience in your website:

Script

Add the script that opens the Checkout Experience to your page.

The script source is

https://checkout.flywire.com/flywire-payment.js

Button

Add a button (or other element or event) to trigger the Checkout Experience form.

Event Handler

Add an event handler that defines what happens after the button is clicked.

Configuration

Set your portal specific payment configuration options. See List of Configuration Parameters for all parameters.

Render

Render the Checkout Experience form with the specified configuration.

<!DOCTYPE html>
<html>
  <head>
    <!-- Include the flywire.js script -->
    <script src="https://checkout.flywire.com/flywire-payment.js"></script>
  </head>
  <body>
    <!-- Add a button element -->
    <button onclick="pay()">
      Make Payment
    </button>

    <script>
      // Add an event handler
      function pay() {
        var config = {
          // See sample configuration options
        };

        var modal = window.FlywirePayment.initiate(config);
        modal.render();
      }
    </script>
  </body>
</html>

Flywire API

The Flywire API allows you to integrate Flywire’s payment services into your own system. You can build a custom user interface while taking advantage of Flywire’s payment network, ensuring a smooth and secure payment experience.

Grand Horizons Travel Backoffice

This is just a demo user interface to visualise what you could build with the API - you can't perform any actions here.

Pay-By-Link

Pay-By-Link is the lightest and easiest integration. You simply generate a link for your payer that you can implement into emails and other places. After clicking the link, your payer will be directed to the Checkout Experience outside of your website and all fields you provided values for via the link (for example payer's name or the payment amount) are already pre-filled.

There are two types of Pay-By-Link integrations depending on your use case:

Payment Request Links

Here you build links for Payment Requests via query parameters.

What are Payment Requests?

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:

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

When should you use Payment Request Links?

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.

Important info for payment callbacks: Ensure your portal has a static callback URL in place when you are using Payment Request links.

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.

Dynamic Links

Here you build links for standalone payments via query parameters.

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.

When should you use Dynamic Links?

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

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.

From: [email protected]

To: Troy Traveler <[email protected]>

Subject: Your dream vacation

Grand Horizons Travel Experiences

Dear Troy Traveler,

We are excited to offer you an exclusive luxury travel package that promises an unforgettable experience. Enjoy a 7-day stay at a five-star resort, gourmet dining, private tours, and much more.

To secure your spot, please make a payment using the button below.

Sincerely,
The Grand Horizons Travel Team