Checkout for 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.

If you want to create a single payment as part of a Payment Requests you need to use either the Dashboard, Payment Request Links or the Flywire API.

Sample Configurations for Payments

  • Minimum Configuration
  • Partial or Full Payer Info
  • Full Payer Info
  • Callbacks Configuration
  • Typical Configuration

The following parameters must be specified as a minimum to successfully render the Checkout Experience form.

In the form, the payer enters their payer data and - if your portal uses custom fields - the custom field information.

Basic Settings

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

Specifies the portal (also called recipient) that will receive the payment.

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

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)

If you are using the demo environment, your portal code might be different from the one you are using in production.

Payment Settings

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

Validation Settings

Flywire recommends that you always implement an onInvalidInput handler to report any error messages to your payers. For details see Checkout for Standalone Payments.

Form Settings

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

Specifying which pages will be shown:

The default for both parameters is false, which means omitting the parameters means the pages will not be displayed. If you are not submitting the full information yourself or want the payer to verify it, you have to set the parameters to true.

Specifies if the payer information page will be shown.

Possible values:

  • true

  • false (Default)

Specifies if the custom information for the recipient page will be shown.

Possible values:

  • true

  • false (Default)

After-Payment Settings

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.

var config = {
  // Set the target environment (demo, prod)
  env: "demo",

  // Set your unique code (may differ between demo and prod)
  recipientCode: "Your Portal Code",

  // Set the amount of the payment to be processed
  amount: 1234.56,

  // Recommended (not required) validation error handler
  onInvalidInput: function(errors) {
    errors.forEach(function(error) {
      alert(error.msg);
    });
  },

  // Display payer and custom field input boxes
  requestPayerInfo: true,
  requestRecipientInfo: true,

  // Set the return URL where payers are redirected to on completion
  returnUrl: "https://httpbin.org/get",
};

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

This sample configuration will render a Checkout Experience form that can handle partial and complete pre-filling of information:

  • If the information has only partially pre-filled by you, the page will be displayed.

  • If the information has been fully provided by you, the page will be skipped.

Once the payment is complete the onCompleteCallback handler will be called and the checkout closed rather than the window being redirected.

 

Basic Settings

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

Specifies the portal (also called recipient) that will receive the payment.

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

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)

If you are using the demo environment, your portal code might be different from the one you are using in production.

Payment Settings

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

Validation Settings

Flywire recommends that you always implement an onInvalidInput handler to report any error messages to your payers. For details see Checkout for Standalone Payments.

Form Settings

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

Specifying which pages will be shown:

The default for both parameters is false, which means omitting the parameters means the pages will not be displayed. If you are not submitting the full information yourself or want the payer to verify it, you have to set the parameters to true.

Specifies if the payer information page will be shown.

Possible values:

  • true

  • false (Default)

Specifies if the custom information for the recipient page will be shown.

Possible values:

  • true

  • false (Default)

Skipping completed pages:

To avoid making payers clicking through unnecessary pages in the Checkout Experience form, this setting will automatically skip input pages if all the required information for the page has been supplied. If there is information missing, the page will be displayed.

This setting is useful if you are unsure whether either the payer details or custom field values you supply will be complete or partial.

Possible values:

  • true (Hide pages that have been completely pre-filled)

  • false (Default - display pages even if they haven been completely pre-filled)

    There is also the option to skip only a certain step. Simply set the name of the page as the value:

  • requestPayerInfo (Hide only payer information page if it has been completely pre-filled)

  • requestRecipientInfo (Hide only custom information for the recipient page if it has been completely pre-filled)

Pre-filling Payer and Recipient Information

Payer Information

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

The payer's address.

The payer's city.

The payer's state.

The payer's zip code.

Example: SW1A

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

Recipient Information

recipientFields object

A recipient (portal) can have various custom fields. You define those fields when you set up your portal together with Flywire.

Custom fields can be mandatory or optional. All mandatory fields need to be filled out in order to create a payment.

You need an invoice number and a booking reference for your payments. Your portal has the following fields:

recipientFields: {
	invoice_number: "Invoice-12345",
	booking_reference: "REF1234"
},
The custom fields vary by portal - please check your specific portal configuration to view your available fields.

When you are pre-filling custom fields and want to leave some fields empty, you can either pass them and set their value to null or you can just omit the field.

This:

recipientFields: {
	invoice_number: "Invoice-12345",
	booking_reference: null
},

is the same as this:

recipientFields: {
	invoice_number: "Invoice-12345"
},

After-Payment Settings

onCompleteCallback object

A JavaScript callback function that is executed once the payment is completed and the modal has closed.

The payer stays on the original page. You specify an onCompleteCallback function in the Checkout configuration that handles the parameters containing payment information. The parameters are returned as a JSON args object to the callback handler.

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

var config = {
env: "demo",
recipientCode: "Your Portal Code",
amount: 1234.56,

  onInvalidInput: function(errors) {
    errors.forEach(function(error) {
      alert(error.msg);
    });
  },

  // Display the payer and custom information input boxes
  // skipping either page if all the information has been passed in.
  // NB. You can see this behavior by completing the address, city and
  // country parameters in the next block.
  requestPayerInfo: true,
  requestRecipientInfo: true,
  skipCompletedSteps: true,

  // Pass in partial payer information (missing parameters can
  // alternatively be omitted rather than included with empty or
  // null values)
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  phone: "+44 1234 567 890",
  address: "",
  city: "",
  state: "",
  zip: "",
  country: null,

  // Pass in partial custom field information (missing parameters can
  // alternatively be omitted rather than included with empty or null
  // values)
  recipientFields: {
    booking_reference: "REF1234",
    additional_information: null,
  },

  // The callback function that is called once the payment is complete
  onCompleteCallback: function(args) {
    alert(args);
  },
};

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

This sample configuration will render a Checkout Experience form that hides both pages since you are providing all the information.

It is important to provide an onInvalidInput handler in this instance to ensure any validation errors are reported back to the payer.

In addition a nonce parameter can be set that is included in the generation of the sig parameter included in the returnUrl (and in the args supplied to the onCompleteCallback handler). Flywire recommends that you set this to a value that uniquely identifies an entity in your platform that this payment relates to - e.g. the same value as booking_reference in the sample below.

Basic Settings

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

Specifies the portal (also called recipient) that will receive the payment.

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

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)

If you are using the demo environment, your portal code might be different from the one you are using in production.

Payment Settings

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

Validation Settings

Flywire recommends that you always implement an onInvalidInput handler to report any error messages to your payers. For details see Checkout for Standalone Payments.

Form Settings

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

Specifying which pages will be shown:

The default for both parameters is false, which means omitting the parameters means the pages will not be displayed. If you are not submitting the full information yourself or want the payer to verify it, you have to set the parameters to true.

Specifies if the payer information page will be shown.

Possible values:

  • true

  • false (Default)

Specifies if the custom information for the recipient page will be shown.

Possible values:

  • true

  • false (Default)

Pre-filling Payer and Recipient Information

Payer Information

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

The payer's address.

The payer's city.

The payer's state.

The payer's zip code.

Example: SW1A

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

Recipient Information

recipientFields object

A recipient (portal) can have various custom fields. You define those fields when you set up your portal together with Flywire.

Custom fields can be mandatory or optional. All mandatory fields need to be filled out in order to create a payment.

You need an invoice number and a booking reference for your payments. Your portal has the following fields:

recipientFields: {
	invoice_number: "Invoice-12345",
	booking_reference: "REF1234"
},
The custom fields vary by portal - please check your specific portal configuration to view your available fields.

When you are pre-filling custom fields and want to leave some fields empty, you can either pass them and set their value to null or you can just omit the field.

This:

recipientFields: {
	invoice_number: "Invoice-12345",
	booking_reference: null
},

is the same as this:

recipientFields: {
	invoice_number: "Invoice-12345"
},

After-Payment Settings

A nonce (short for "number used once") is a unique value to ensure the security and integrity. Provide a value that uniquely identifies an entity in your platform that this payment relates to, for example a payment reference from your system e.g. REF1234.

The nonce parameter will be included in the generation of the sig parameter that is passed to the returnUrl or the onCompleteCallback handler (depending on which one you use, see List of Configuration Parameters - After-Payment Settings for details).

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.

var config = {
  env: "demo",
  recipientCode: "Your Portal Code",
  amount: 1234.56,

  // Highly recommended for this configuration
  onInvalidInput: function(errors) {
    errors.forEach(function(error) {
      alert(error.msg);
    });
  },

  // Hide the information input boxes
  requestPayerInfo: false,
  requestRecipientInfo: false,

  // Pass in complete payer information
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  phone: "+44 1234 567 890",
  address: "10, Downing St.",
  city: "London",
  state: "",
  zip: "SW1A",
  country: "GB",

  // Pass in complete custom field information
  recipientFields: {
    booking_reference: "REF1234",
    additional_information: "This is a sample",
  },

  // Supply a nonce to be included in the signature generation
  nonce: "REF1234",

  returnUrl: "https://httpbin.org/get",
};

This sample configuration renders the Checkout Experience form with settings for receiving callbacks for the payment.

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.

 

Requirements for using callbacks

You must supply the following parameters for receiving callbacks:

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.

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.

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.

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.

 

Basic Settings

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

Specifies the portal (also called recipient) that will receive the payment.

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

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)

If you are using the demo environment, your portal code might be different from the one you are using in production.

Payment Settings

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

Validation Settings

Flywire recommends that you always implement an onInvalidInput handler to report any error messages to your payers. For details see Checkout for Standalone Payments.

Form Settings

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

Specifying which pages will be shown:

The default for both parameters is false, which means omitting the parameters means the pages will not be displayed. If you are not submitting the full information yourself or want the payer to verify it, you have to set the parameters to true.

Specifies if the payer information page will be shown.

Possible values:

  • true

  • false (Default)

Specifies if the custom information for the recipient page will be shown.

Possible values:

  • true

  • false (Default)

After-Payment Settings

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.

Callback Settings

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.

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.

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.

var config = {
  env: "demo",
  recipientCode: "Your Portal Code",
  amount: 1234.56,

  onInvalidInput: function(errors) {
    errors.forEach(function(error) {
      alert(error.msg);
    });
  },

  requestPayerInfo: true,
  requestRecipientInfo: true,

  returnUrl: "https://httpbin.org/get",

  // Enable payment status notification callbacks
  callbackId: "REF1234",
  callbackUrl: "https://api.yourdomain.com/flywire-notifications",
  callbackVersion: "2"
};

This configuration shows typical parameters with the following features:

  • setting some fields to read only so that the payer can see them but not edit their content

  • a custom sort order for payment options

  • setting up callback notifications

  • secure, verifiable signature generation

 

Basic Settings

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

Specifies the portal (also called recipient) that will receive the payment.

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

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)

If you are using the demo environment, your portal code might be different from the one you are using in production.

Payment Settings

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

paymentOptionsConfig object

Contains optional configurations for the payment options displayed in the Checkout form.

sort array

Flywire makes every effort to display the payment option to payers in the most appropriate order based on payer behavior. You may prefer to change this order to better suit your and your payers needs. You can define the order in which payment options are shown to your payer based on payment currency, payment price (amount), and payment method (type).

The order in which currency , amount , and type are set in the sort array affects the final sort order.

Defines which currency is shown first. Possible values:

  • local (The payers local currency)

  • foreign (Not the payers local currency)

Example: To show the local currency payment options first:

currency: ["local", "foreign"]

Defines in which order of price the payment options are shown. Possible values:

  • asc - (ascending amount order - show cheapest first)

  • desc - (descending amount order- show most expensive first)

Example: To show the cheapest payment options first:

amount: "asc"

Defines in which order of payment method the payment options are shown. Possible values:

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

Example: To show prefer bank transfer over cards and online methods:

type: ["bank_transfer", "credit_card", "online"]

Validation Settings

Flywire recommends that you always implement an onInvalidInput handler to report any error messages to your payers. For details see Checkout for Standalone Payments.

Form Settings

There are two input pages for collecting information that are displayed to the payer in the Checkout Experience form before they choose their preferred payment method:

  • Payer information

  • Custom information for the recipient

Specifying which pages will be shown:

The default for both parameters is false, which means omitting the parameters means the pages will not be displayed. If you are not submitting the full information yourself or want the payer to verify it, you have to set the parameters to true.

Specifies if the payer information page will be shown.

Possible values:

  • true

  • false (Default)

Specifies if the custom information for the recipient page will be shown.

Possible values:

  • true

  • false (Default)

Skipping completed pages:

To avoid making payers clicking through unnecessary pages in the Checkout Experience form, this setting will automatically skip input pages if all the required information for the page has been supplied. If there is information missing, the page will be displayed.

This setting is useful if you are unsure whether either the payer details or custom field values you supply will be complete or partial.

Possible values:

  • true (Hide pages that have been completely pre-filled)

  • false (Default - display pages even if they haven been completely pre-filled)

    There is also the option to skip only a certain step. Simply set the name of the page as the value:

  • requestPayerInfo (Hide only payer information page if it has been completely pre-filled)

  • requestRecipientInfo (Hide only custom information for the recipient page if it has been completely pre-filled)

Pre-filling Payer and Recipient Information

Payer Information

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

The payer's address.

The payer's city.

The payer's state.

The payer's zip code.

Example: SW1A

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

Recipient Information

readonlyFields array (string)

You can set any of the input fields (for both the payer information and the custom fields) to read only with the readonlyFields array. This way you can ensure that the payer can't overwrite your pre-filled field values.

  • If you do not use this parameter, all fields will be editable.

  • If you use this parameter, any field passed here will be read-only. Any field not passed will still be editable.

recipientFields object

A recipient (portal) can have various custom fields. You define those fields when you set up your portal together with Flywire.

Custom fields can be mandatory or optional. All mandatory fields need to be filled out in order to create a payment.

You need an invoice number and a booking reference for your payments. Your portal has the following fields:

recipientFields: {
	invoice_number: "Invoice-12345",
	booking_reference: "REF1234"
},
The custom fields vary by portal - please check your specific portal configuration to view your available fields.

When you are pre-filling custom fields and want to leave some fields empty, you can either pass them and set their value to null or you can just omit the field.

This:

recipientFields: {
	invoice_number: "Invoice-12345",
	booking_reference: null
},

is the same as this:

recipientFields: {
	invoice_number: "Invoice-12345"
},

After-Payment Settings

A nonce (short for "number used once") is a unique value to ensure the security and integrity. Provide a value that uniquely identifies an entity in your platform that this payment relates to, for example a payment reference from your system e.g. REF1234.

The nonce parameter will be included in the generation of the sig parameter that is passed to the returnUrl or the onCompleteCallback handler (depending on which one you use, see List of Configuration Parameters - After-Payment Settings for details).

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.

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.

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.

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.

var config = {
  env: "demo",
  recipientCode: "Your Portal Code",
  amount: 1234.56,
							
  // Show the cheapest local payment option first but prefer bank transfers
  // over cards and online methods if they are the same price
  paymentOptionsConfig: {
    sort: [
      { currency: ["local", "foreign"] },
      { amount: "asc" },
      { type: ["bank_transfer", "credit_card", "online"] },
    ],							
  },
							
  onInvalidInput: function(errors) {
    errors.forEach(function(error) {
      alert(error.msg);
    });
  },

  requestPayerInfo: true,
  requestRecipientInfo: true,
  skipCompletedSteps: true,


  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  phone: "+44 1234 567 890",
  address: "10, Downing St.",
  city: "London",
  state: "",
  zip: "SW1A",
  country: "GB",

  // Set any custom fields to read-only to prevent payers changing values
  // (in this configuration 'additional_information' will be editable)
  readonlyFields: ["booking_reference", "client_id"],							
							
  recipientFields: {
    booking_reference: "REF1234",
    client_id: "CLI1234",
    additional_information: null,
  },

  nonce: "REF1234",
  returnUrl: "https://httpbin.org/get",

  callbackId: "REF1234",
  callbackUrl: "https://api.yourdomain.com/flywire-notifications",
  callbackVersion: "2",
};

After Payment Completion

Once a the payer has successfully entered their details and the Checkout Experience form is closed, you receive information about the payment either via the returnUrl or the onCompleteCallback handler.

The after-payment settings define how information is sent back to your website.

The payment flow for the Checkout integration is:

  1. Customer enters information.

    Your customer opens the Checkout Experience form on your website and enters their payment details.

  2. Information is sent back to your website.

    After the payment is completed, the Checkout Experience window automatically closes after a few seconds.

    This triggers the Checkout integration to send back the payment status and details to your website. This can be done in two different ways:

    You can either use the returnUrl parameter or the onCompleteCallback parameter, never both.

    For security reasons, the token is only returned via onCompleteCallback handler. The returnUrl does not return the token.

    This means that when you are tokenizing, you must only use the onCompleteCallback handler.

    returnUrl :

    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.

    onCompleteCallback:

    The payer stays on the original page. You specify an onCompleteCallback function in the Checkout configuration that handles the parameters containing payment information. The parameters are returned as a JSON args object to the callback handler.

    • Immediate Handling

      Since the data is passed directly to your callback, you can handle the payment confirmation on the same page without a redirect.

    • Dynamic Updates

      You can dynamically update the page (e.g., show a success message) without leaving the current view, providing a smoother user experience.

    • Flexibility

      You can implement custom logic directly in the callback, such as updating the UI or logging information for analytics.

  3. You use the information for your own systems and the customer.

    You can use the returned parameters to update your backend, display information to your payer, or for your internal logging and processing of payments.

Example for response via returnUrl:

(Click to see the return URL in JSON formatting. For a detailed description of the parameters see the response via onCompleteCallback handler below.)

http://httpbin.org/get?reference=FLY123567890&status=success&amount=1234.56&payment_method=online&_=REF1234&sig=abcdefgh

Example for response via onCompleteCallback handler:

The status of the attempted charge. Note that this charge status doesn't mean that funds have successfully been transferred. It gives you information about the communication between Flywire and the external system (for example, the bank or card provider):

Possible values:

success The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

error

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

active
Only for scheduled payments and subscriptions.

The scheduled payment(s) or subscription has successfully been created and is now active.

pending
Always returned for bank transfer payments and never returned for online payments.

The payment creation was successful, but since the payer has to make a bank transfer manually, Flywire doesn't know if and when this will happen.

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

Possible values are:

  • bank_transfer

  • online

The due date of the bank transfer.

The payment reference.

The payment reference is an ID generated by Flywire to identify a payment.

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

With the payment reference, the payment can be tracked through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

A nonce (short for "number used once") is a unique value to ensure the security and integrity. Provide a value that uniquely identifies an entity in your platform that this payment relates to, for example a payment reference from your system e.g. REF1234.

The nonce parameter will be included in the generation of the sig parameter that is passed to the returnUrl or the onCompleteCallback handler (depending on which one you use, see List of Configuration Parameters - After-Payment Settings for details).

The sig is a cryptographic signature generated by Flywire that verifies that the data has not been altered during transmission. The sig is returned via returnUrl or the onCompleteCallback handler (depending on which one you are using). You can use it to verify the other parameters in the response, see Signature Verification.

{
    status: "success",   
    amount: "1234.56",
    paymentMethod: "bank_transfer",
	bankTransferDueDate: "2024-05-27T14:54:57Z"
	reference: "FLY1234567890",
    _: "REF1234",
    sig: "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
}