Payment Element
|
The payment element can process payments with different payment methods. How to control which payment method gets rendered The payment elements requires you to create a Checkout Session first. The type of Checkout Session you create determines which payment method gets rendered. For example, creating a Checkout Session for "card tokenization" renders the "card tokenization" payment element.
|
|
|
For Cards
-
Tokenization -
Tokenization & pay
-
New mandate
-
Pre-Authorization
|
The payer sees a form that collects the payer and card information. With Smart Rendering, the appearance of the element and the displayed fields may vary based on your customizations. 
|
Card tokenization (save card) This form collects the payer and card details. The data is then saved as a payment method token and mandate ID for future payments. No payment is being made with this form, which is why it doesn't show a payment amount. Customization Options
Checkout Session Settings
|
Fields
The payer information fields can be pre-filled when creating a Checkout Session.
Info about pre-filling fields
-
Pre-filled fields will remain editable for the payer to make corrections if needed.
-
Pre-filling fields is optional. If no parameters are provided, the fields will be empty for the payer to complete.
Best practice
Before pre-filling the payer fields, consider your use case and who the actual payer will be. The UI forms collect the card holder or bank account owner information. There can be cases when this person is different from the payer in your system.
For example, if you are a school and your system stores information about a student, you consider the student as the “payer”. But the person who actually pays could be the student’s parent. In this case, it would not make sense to pre-fill the fields with the student’s information, since the card holder is a different person. On the other hand, the payer can always edit the fields in the UI form, which means even if you are pre-filling the fields with the wrong details the payer can always correct them.
In order to create the best payment experience for your payers, consider which information you store in your system and how useful it is for them when fields are already filled out.
First name
Parameter to pre-fill this field: payor.first_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Max. 256 characters.
Last name
Parameter to pre-fill this field: payor.last_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Parameter to pre-fill this field: payor.email
Validation Rules
The field accepts Latin characters from A-Z and 0-9 and the + (plus) sign.
Max. 256 characters.
City
Parameter to pre-fill this field: payor.city
Validation Rules
The field only accepts Latin characters from A-Z and 0-9. The city needs to contain at least a vowel and have more than one character. For example, NY won’t be accepted and must be corrected to New York.
Max. 256 characters.
Country
Parameter to pre-fill this field: payor.country
Validation Rules
When you're pre-filling the field:
The country of the payer in ISO 3166-1 Alpha-2 country code format.
State
Parameter to pre-fill this field: payor.state
Validation Rules
When you're pre-filling the field:
The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.
Address
Parameter to pre-fill this field: payor.address
Validation Rules
The field only accepts Latin characters from A-Z and 0-9 and the , (comma) sign.
The address can’t be a PO box. If the word “box” is detected in this field, it will show an error message.
Post code
Parameter to pre-fill this field: payor.zip
Validation Rules
If the country is “United States” the field only accepts exactly 5 digits, for any other country it accepts a maximum of 10 digits or characters.
Phone number
Parameter to pre-fill this field: payor.phone
Validation Rules
The field doesn’t accept spaces or hyphens.
Max. 15 digits.
Note for pre-filling the phone number
To fill out the country code field of the phone number, you need to put 00 in front of it. For example, "0044123456" will be turned into "44" in the country code field and "123456" in the phone number field. If you don't use 00 the country code field will be left empty and only the phone number field will be populated.
Card Number
The field only accepts valid card numbers.
Expiry Date (MM/YY)
The expiry date (can’t be in the past).
CVV
The CVV of the card.
Terms and conditions
Mandatory and/or optional checkboxes the payer has to tick before they can send the form. The checkboxes and their content depend on the payment method and other factors.
Action Button
Action button that sends the form.
|
The payer sees a form that collects the payer and card information. After the payer confirmed the form, the payment is created. With Smart Rendering, the appearance of the element and the displayed fields may vary based on your customizations. 
|
Card tokenization and pay (save card and make payment) This form collects the payer and card details, and immediately makes the first payment. The data is then saved as a payment method token and mandate ID for future payments Customization Options
Checkout Session Settings
|
Fields
The payer information fields can be pre-filled when creating a Checkout Session.
Info about pre-filling fields
-
Pre-filled fields will remain editable for the payer to make corrections if needed.
-
Pre-filling fields is optional. If no parameters are provided, the fields will be empty for the payer to complete.
Best practice
Before pre-filling the payer fields, consider your use case and who the actual payer will be. The UI forms collect the card holder or bank account owner information. There can be cases when this person is different from the payer in your system.
For example, if you are a school and your system stores information about a student, you consider the student as the “payer”. But the person who actually pays could be the student’s parent. In this case, it would not make sense to pre-fill the fields with the student’s information, since the card holder is a different person. On the other hand, the payer can always edit the fields in the UI form, which means even if you are pre-filling the fields with the wrong details the payer can always correct them.
In order to create the best payment experience for your payers, consider which information you store in your system and how useful it is for them when fields are already filled out.
First name
Parameter to pre-fill this field: payor.first_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Max. 256 characters.
Last name
Parameter to pre-fill this field: payor.last_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Parameter to pre-fill this field: payor.email
Validation Rules
The field accepts Latin characters from A-Z and 0-9 and the + (plus) sign.
Max. 256 characters.
City
Parameter to pre-fill this field: payor.city
Validation Rules
The field only accepts Latin characters from A-Z and 0-9. The city needs to contain at least a vowel and have more than one character. For example, NY won’t be accepted and must be corrected to New York.
Max. 256 characters.
Country
Parameter to pre-fill this field: payor.country
Validation Rules
When you're pre-filling the field:
The country of the payer in ISO 3166-1 Alpha-2 country code format.
State
Parameter to pre-fill this field: payor.state
Validation Rules
When you're pre-filling the field:
The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.
Address
Parameter to pre-fill this field: payor.address
Validation Rules
The field only accepts Latin characters from A-Z and 0-9 and the , (comma) sign.
The address can’t be a PO box. If the word “box” is detected in this field, it will show an error message.
Post code
Parameter to pre-fill this field: payor.zip
Validation Rules
If the country is “United States” the field only accepts exactly 5 digits, for any other country it accepts a maximum of 10 digits or characters.
Phone number
Parameter to pre-fill this field: payor.phone
Validation Rules
The field doesn’t accept spaces or hyphens.
Max. 15 digits.
Note for pre-filling the phone number
To fill out the country code field of the phone number, you need to put 00 in front of it. For example, "0044123456" will be turned into "44" in the country code field and "123456" in the phone number field. If you don't use 00 the country code field will be left empty and only the phone number field will be populated.
Card Number
The field only accepts valid card numbers.
Expiry Date (MM/YY)
The expiry date (can’t be in the past).
CVV
The CVV of the card.
Amount
The amount your payer pays in their currency and the amount you receive in your currency. If your payer pays in a different currency, they get a breakdown about how the exchange rate is calculated.
Terms and conditions
Mandatory and/or optional checkboxes the payer has to tick before they can send the form. The checkboxes and their content depend on the payment method and other factors.
Action Button
Action button that sends the form.
|
The payer sees a form where they can enter only the CVV number. All other fields are read-only
|
Card new mandate (use existing card for different plan) This form allows the payer to confirm their card's CVV to create a new mandate ID for recurring payments. It uses a saved card (which already has a payment method token) for a different plan (which requires a new mandate). The payer simply re-enters the CVV to prove consent for the new mandate. Customization Options
Checkout Session Settings
|
Fields
First name
The payer's first name (read-only)
Last name
The payer's last name (read-only)
Card details
The card details (read-only)
CVV
The CVV of the card.
Charging information
Information for the payer.
Action Button
Action button that sends the form.
|
The payer sees a form that collects the payer and card information. After the payer confirmed the form, the payment is created. With Smart Rendering, the appearance of the element and the displayed fields may vary based on your customizations.
|
Pre-Authorization Payment This form collects the payer and card details. The funds are being reserved on the card and you can capture them later. Customization Options
|
Fields
The payer information fields can be pre-filled when creating a Checkout Session.
Info about pre-filling fields
-
Pre-filled fields will remain editable for the payer to make corrections if needed.
-
Pre-filling fields is optional. If no parameters are provided, the fields will be empty for the payer to complete.
Best practice
Before pre-filling the payer fields, consider your use case and who the actual payer will be. The UI forms collect the card holder or bank account owner information. There can be cases when this person is different from the payer in your system.
For example, if you are a school and your system stores information about a student, you consider the student as the “payer”. But the person who actually pays could be the student’s parent. In this case, it would not make sense to pre-fill the fields with the student’s information, since the card holder is a different person. On the other hand, the payer can always edit the fields in the UI form, which means even if you are pre-filling the fields with the wrong details the payer can always correct them.
In order to create the best payment experience for your payers, consider which information you store in your system and how useful it is for them when fields are already filled out.
First name
Parameter to pre-fill this field: payor.first_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Max. 256 characters.
Last name
Parameter to pre-fill this field: payor.last_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Parameter to pre-fill this field: payor.email
Validation Rules
The field accepts Latin characters from A-Z and 0-9 and the + (plus) sign.
Max. 256 characters.
City
Parameter to pre-fill this field: payor.city
Validation Rules
The field only accepts Latin characters from A-Z and 0-9. The city needs to contain at least a vowel and have more than one character. For example, NY won’t be accepted and must be corrected to New York.
Max. 256 characters.
Country
Parameter to pre-fill this field: payor.country
Validation Rules
When you're pre-filling the field:
The country of the payer in ISO 3166-1 Alpha-2 country code format.
State
Parameter to pre-fill this field: payor.state
Validation Rules
When you're pre-filling the field:
The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.
Address
Parameter to pre-fill this field: payor.address
Validation Rules
The field only accepts Latin characters from A-Z and 0-9 and the , (comma) sign.
The address can’t be a PO box. If the word “box” is detected in this field, it will show an error message.
Post code
Parameter to pre-fill this field: payor.zip
Validation Rules
If the country is “United States” the field only accepts exactly 5 digits, for any other country it accepts a maximum of 10 digits or characters.
Phone number
Parameter to pre-fill this field: payor.phone
Validation Rules
The field doesn’t accept spaces or hyphens.
Max. 15 digits.
Note for pre-filling the phone number
To fill out the country code field of the phone number, you need to put 00 in front of it. For example, "0044123456" will be turned into "44" in the country code field and "123456" in the phone number field. If you don't use 00 the country code field will be left empty and only the phone number field will be populated.
Card Number
The field only accepts valid card numbers.
Expiry Date (MM/YY)
The expiry date (can’t be in the past).
CVV
The CVV of the card.
Amount
The amount your payer pays in their currency and the amount you receive in your currency. If your payer pays in a different currency, they get a breakdown about how the exchange rate is calculated.
Terms and conditions
Mandatory and/or optional checkboxes the payer has to tick before they can send the form. The checkboxes and their content depend on the payment method and other factors.
Action Button
Action button that sends the form.
For Direct Debit
-
Tokenization -
Tokenization & pay
Your payer sees the SEPA form where they can enter their payer and bank account information. 
After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info. 
Your payer sees the BACS form where they can enter their payer and bank account information. 
After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info. 
Your payer sees the ACH form where they can enter their payer and bank account information. 
After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info. 
Your payer sees the EFT Canada form where they can enter their payer information. 
After entering their information, your payer will be redirected to Plaid. The third-party implementation will lead your payer through the steps to connect to their bank account. 
After your payer successfully connected to their bank account, they will be redirected to the EFT Canada direct debit Form. 
Back at the EFT Canada direct debit form, your payer can either edit their payer info, connect to a different bank account or confirm the information. 
|
Direct debit tokenization (save bank account) This form collects the payer and bank account details. The data is then saved as a payment method token and mandate ID for future payments. No payment is being made with this form, which is why it doesn't show a payment amount. Which direct debit schemes are supported?
Supported direct debit schemes
Customization Options
Checkout Session Settings
|
Fields
The payer information fields can be pre-filled when creating a Checkout Session.
Info about pre-filling fields
-
Pre-filled fields will remain editable for the payer to make corrections if needed.
-
Pre-filling fields is optional. If no parameters are provided, the fields will be empty for the payer to complete.
Best practice
Before pre-filling the payer fields, consider your use case and who the actual payer will be. The UI forms collect the card holder or bank account owner information. There can be cases when this person is different from the payer in your system.
For example, if you are a school and your system stores information about a student, you consider the student as the “payer”. But the person who actually pays could be the student’s parent. In this case, it would not make sense to pre-fill the fields with the student’s information, since the card holder is a different person. On the other hand, the payer can always edit the fields in the UI form, which means even if you are pre-filling the fields with the wrong details the payer can always correct them.
In order to create the best payment experience for your payers, consider which information you store in your system and how useful it is for them when fields are already filled out.
First name
Parameter to pre-fill this field: payor.first_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Max. 256 characters.
Last name
Parameter to pre-fill this field: payor.last_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Parameter to pre-fill this field: payor.email
Validation Rules
The field accepts Latin characters from A-Z and 0-9 and the + (plus) sign.
Max. 256 characters.
City
Parameter to pre-fill this field: payor.city
Validation Rules
The field only accepts Latin characters from A-Z and 0-9. The city needs to contain at least a vowel and have more than one character. For example, NY won’t be accepted and must be corrected to New York.
Max. 256 characters.
Country
Parameter to pre-fill this field: payor.country
Validation Rules
When you're pre-filling the field:
The country of the payer in ISO 3166-1 Alpha-2 country code format.
State
Parameter to pre-fill this field: payor.state
Validation Rules
When you're pre-filling the field:
The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.
Address
Parameter to pre-fill this field: payor.address
Validation Rules
The field only accepts Latin characters from A-Z and 0-9 and the , (comma) sign.
The address can’t be a PO box. If the word “box” is detected in this field, it will show an error message.
Post code
Parameter to pre-fill this field: payor.zip
Validation Rules
If the country is “United States” the field only accepts exactly 5 digits, for any other country it accepts a maximum of 10 digits or characters.
Phone number
Parameter to pre-fill this field: payor.phone
Validation Rules
The field doesn’t accept spaces or hyphens.
Max. 15 digits.
Note for pre-filling the phone number
To fill out the country code field of the phone number, you need to put 00 in front of it. For example, "0044123456" will be turned into "44" in the country code field and "123456" in the phone number field. If you don't use 00 the country code field will be left empty and only the phone number field will be populated.
IBAN
Only shown for for SEPA.
Validation Rules
The IBAN is validated against the country field, for example when the country is Spain the IBAN has to start with ES.
The field doesn't accept special or non-Latin characters.
BIC code
Only shown for SEPA when a NON-EEA country is selected.
What are NON-EEA countries?
NON-EEA stands for "Non European Economic Area". NON-EEA countries are:
-
Andorra
-
Monaco
-
San Marino
-
Switzerland
-
United Kingdom
-
Vatican City state
Validation Rules
The BIC code must be exactly 8 or 11 characters long.
The field doesn't accept special or non-Latin characters.
Routing number
Only shown for for ACH.
Account number
Only shown for ACH.
Account type
Only shown for ACH.
Either checking or savings account.
Account number
Only shown for for BACS.
Sort code
Only shown for BACS.
Validation Rules
Sort code in the format 00-00-00 (including the dashes).
Terms and conditions
Mandatory and/or optional checkboxes the payer has to tick before they can send the form. The checkboxes and their content depend on the payment method and other factors.
Action Button
Action button that sends the form.
|
Your payer sees the SEPA form where they can enter their payer and bank account information.
After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info.
|
Direct debit tokenization and pay (save bank account and make payment) This form collects the payer and bank account details, and immediately makes the first payment. The data is then saved as a payment method token and mandate ID for future payments. Supported direct debit schemes:
Customization Options
Checkout Session Settings
|
Fields
The payer information fields can be pre-filled when creating a Checkout Session.
Info about pre-filling fields
-
Pre-filled fields will remain editable for the payer to make corrections if needed.
-
Pre-filling fields is optional. If no parameters are provided, the fields will be empty for the payer to complete.
Best practice
Before pre-filling the payer fields, consider your use case and who the actual payer will be. The UI forms collect the card holder or bank account owner information. There can be cases when this person is different from the payer in your system.
For example, if you are a school and your system stores information about a student, you consider the student as the “payer”. But the person who actually pays could be the student’s parent. In this case, it would not make sense to pre-fill the fields with the student’s information, since the card holder is a different person. On the other hand, the payer can always edit the fields in the UI form, which means even if you are pre-filling the fields with the wrong details the payer can always correct them.
In order to create the best payment experience for your payers, consider which information you store in your system and how useful it is for them when fields are already filled out.
First name
Parameter to pre-fill this field: payor.first_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Max. 256 characters.
Last name
Parameter to pre-fill this field: payor.last_name
Validation Rules
The field only accepts Latin characters from A-Z and 0-9.
Parameter to pre-fill this field: payor.email
Validation Rules
The field accepts Latin characters from A-Z and 0-9 and the + (plus) sign.
Max. 256 characters.
City
Parameter to pre-fill this field: payor.city
Validation Rules
The field only accepts Latin characters from A-Z and 0-9. The city needs to contain at least a vowel and have more than one character. For example, NY won’t be accepted and must be corrected to New York.
Max. 256 characters.
Country
Parameter to pre-fill this field: payor.country
Validation Rules
When you're pre-filling the field:
The country of the payer in ISO 3166-1 Alpha-2 country code format.
State
Parameter to pre-fill this field: payor.state
Validation Rules
When you're pre-filling the field:
The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.
Address
Parameter to pre-fill this field: payor.address
Validation Rules
The field only accepts Latin characters from A-Z and 0-9 and the , (comma) sign.
The address can’t be a PO box. If the word “box” is detected in this field, it will show an error message.
Post code
Parameter to pre-fill this field: payor.zip
Validation Rules
If the country is “United States” the field only accepts exactly 5 digits, for any other country it accepts a maximum of 10 digits or characters.
Phone number
Parameter to pre-fill this field: payor.phone
Validation Rules
The field doesn’t accept spaces or hyphens.
Max. 15 digits.
Note for pre-filling the phone number
To fill out the country code field of the phone number, you need to put 00 in front of it. For example, "0044123456" will be turned into "44" in the country code field and "123456" in the phone number field. If you don't use 00 the country code field will be left empty and only the phone number field will be populated.
IBAN
Only shown for for SEPA.
Validation Rules
The IBAN is validated against the country field, for example when the country is Spain the IBAN has to start with ES.
The field doesn't accept special or non-Latin characters.
BIC code
Only shown for SEPA when a NON-EEA country is selected.
What are NON-EEA countries?
NON-EEA stands for "Non European Economic Area". NON-EEA countries are:
-
Andorra
-
Monaco
-
San Marino
-
Switzerland
-
United Kingdom
-
Vatican City state
Validation Rules
The BIC code must be exactly 8 or 11 characters long.
The field doesn't accept special or non-Latin characters.
Amount
The amount your payer pays in their currency and the amount you receive in your currency. If your payer pays in a different currency, they get a breakdown about how the exchange rate is calculated.
Terms and conditions
Mandatory and/or optional checkboxes the payer has to tick before they can send the form. The checkboxes and their content depend on the payment method and other factors.
Action Button
Action button that sends the form.
Implementing the Payment Element
Example page
SDK script
Add the Flywire SDK script in the header of your page:
Production:
https://artifacts.flywire.com/sdk/js/v0/main.js
Sandbox:
https://artifacts.flywire.com/sdk/js/v0/sandbox.main.js
Container
Only if you embed the element within a container. Define a container where the element will be rendered.
Configuration script
Initialize the Flywire SDK with your frontend key
You receive the frontend key together with your other credentials when you register for the Flywire API.
Define the appearance of the element
See Element appearance.
Create and configure the element
Load the type of the payment element via the session ID.
How do you want to display the elements?
Which fields do you want to display?
Event listeners
Define what happens after the element is closed, see Event listeners for a detailed example.
Mount
See Mounting the element.
<!DOCTYPE html>
<head>
<script src="https://artifacts.flywire.com/sdk/js/v0/sandbox.main.js"></script>
</head>
<body>
<div id="my-container-id"></div>
<script type="module" crossorigin="anonymous" async type="text/javascript">
(async () => {
var sdk = await window.FlywireSDK(
"your-frontend-key-here" // Replace with your actual frontend key
);
var elements = await sdk.elements({
appearance: {
fonts: [
{
url: "https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700&display=swap",
fontFamily: "Roboto",
},
],
variables: { primaryColor: "#5a81f0" },
},
locale: "en",
});
var element = await elements.create("payment", {
sessionId: "your-session-id-here", // Replace with your actual session ID
displayMode: "container",
fields: {
first_name: { hidden: false },
last_name: { hidden: false },
country: { hidden: true },
address: { hidden: true },
city: { hidden: true },
phone: { hidden: false },
email: { hidden: false },
state: { hidden: false },
zip: { hidden: false },
},
});
element.onEvent("success", handleSuccess); // Handle success event
element.onEvent("error", handleError); // Handle error event
element.mount("my-container-id"); // Mount the element to the container
})();
</script>
</body>
</html>Fonts
Here you can customize the font of the element:
url string (url)
Provide a URL pointing to a Google Font or a URL from the same origin as your website.
For security reasons, only same-origin URLs and Google Font URLs are allowed.
fontFamily string
Specify the font family name as you would in a CSS stylesheet. This replaces the default font-family used in the element’s CSS.
Ensure the font family name matches the one defined in the URL.
Variables
primaryColor
Here you can customize the primary color of the element. Provide the hex value of the color you want to use.
UI components that are affected by the primary color
|
Radio buttons |
|
|
Links |
|
|
Action button |
|
Locale
Defines in which language the element is shown.
If you don't provide the locale, the default is English.
Available languages
| Language | Value for locale |
|---|---|
| English | en |
| Spanish | es-ES |
| Chinese | zh-CN |
| Korean | ko |
| Portuguese | pt-PT |
| Japanese | ja |
| French | fr-FR |
| Bahasa Indonesia | id |
| Arabic | ar |
| Vietnamese | vi |
| Italian | it-IT |
| German | de-DE |
var elements = await sdk.elements({
appearance: {
fonts: [
{
url: "https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700&display=swap",
fontFamily: "Roboto",
},
],
variables: { primaryColor: "#5a81f0" },
},
locale: "en",
});Session ID
When you are creating a payment element, the session ID is needed to determine which payment element gets rendered.
To get the session ID, you need to create a Checkout Session. The type of Checkout Session you create determines the type of payment element, for example creating a Checkout Session for "card tokenization" renders the "card tokenization" payment element.
Display Mode
There are two different display modes:
-
container: To embed the element in a container in your website.
-
full-screen: To display the element in a pop-up (a modal that covers the full-screen with a background)
If you don't provide this value, the default is full-screen.
Fields
Here you can hide fields from being displayed in the element with the hidden parameter:
-
true: field will be hidden
-
false: field will be shown (default)
Not providing a field means the field will be shown.
All payer fields are mandatory for completing the payment. This means for hidden fields you must provide a valid value when you create the Checkout Session. If you don't provide a value or it is invalid, the field will be shown, even if it is set to hidden. This ensures that missing values don't block you from displaying the element.
Possible fields:
-
first_name
-
last_name
-
country
-
address
-
city
-
phone
-
email
-
state
-
zip
var element = await elements.create("payment", {
sessionId: "your-session-id-here", // Replace with your actual session ID
displayMode: "container",
fields: {
first_name: { hidden: false },
last_name: { hidden: false },
country: { hidden: true },
address: { hidden: true },
city: { hidden: true },
phone: { hidden: false },
email: { hidden: false },
state: { hidden: false },
zip: { hidden: false },
},
});There are two key events you need to set up event listeners for:
Success Event (success)
This event is triggered when the element was sent successfully.
Optionally: Display a custom success message to your payer.
Mandatory: Send the postMessage data to your backend. The postMessage contains the confirm URL you need to confirm the Checkout Session, see The postMessage of the Event Listener.
A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.
Error Event (error)
This event is triggered when there was an error or when the payer closed the element.
Optionally: Display a custom error message to your payer.
Mandatory: Send the error message to your backend for troubleshooting.
// Success event handler
element.onEvent("success", (sessionResult) => {
// Custom success message for your payer
const customSuccessMessage = "Your payment was successful.";
// Send the session result to the backend
fetch('/your-backend-endpoint', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(sessionResult),
});
// Show the custom success message to the payer
alert(customSuccessMessage);
});
// Error event handler
element.onEvent("error", (error) => {
// Custom error message for your payer
const customErrorMessage = "Something went wrong. Please try again.";
// Send the error details to the backend
fetch('/your-backend-endpoint', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(error),
});
// Show the custom error message to the payer
alert(customErrorMessage);
});- Full-screen
- Container
Mounting as a pop-up in a full-screen overlay
For mounting the element as a full-screen pop-up , the displayMode must be set to full-screen. Don't specify a container ID, simply use the mount function.
element.mount(); // Mount the element as a pop-up in a full screen overlay Mounting in a container
When you are mounting the element in a container, you need to state a container ID here and ensure to include a container with the same ID on your website .
If you provided a valid container ID and the element still gets rendered as a pop-up, check your displayMode settings. It must be set to container, not full-screen.
element.mount("my-container-id"); // Mount the element to the containerExample page
CSS
Add CSS to adjust the layout of the form in the iframe.
iframe
Source
You’ll get the hostedFormUrl from the response after you created a Checkout Session.
See Example for getting the hostedFormUrl for an example of where to find the url.
Dimensions
Give the iframe a fixed height and width to avoid it filling up the whole screen.
Recommended dimensions
| Form | Type | Height | Width |
| Card | tokenization |
823 |
660 |
| tokenization and pay | 1010 | 660 | |
| new mandate | 320 | 660 | |
| Direct Debit | SEPA tokenization | 835 | 660 |
| SEPA tokenization and pay | 968 | 660 | |
| BACS tokenization | 928 | 660 | |
| EFT Canada tokenization | 928 | 660 | |
| ACH tokenization | 928 | 660 |
Event listener
Implement an event listener in the parent window to receive the postMessages after the form is completed.
See Example for a postMessage of the event listener for an example.
<!DOCTYPE html>
<head>
<style>
.my-iframe {
padding: 18px;
margin: 32px 0px;
background: #FFFFFF;
}
</style>
</head>
<body>
<!-- iframe to display the Flywire form -->
<iframe
src="{hostedFormUrl}"
id="flywireform"
title="Flywire Payment Form"
class="my-iframe"
height="928"
width="660">
</iframe>
<script>
window.addEventListener("message", (event) => {
// IMPORTANT: Verify the origin of the data to ensure it is from Flywire
// The use of indexOf ensures that the origin ends with ".flywire.com"
if (event.origin.indexOf(".flywire.com")) {
// If the message was sent from Flywire:
// Extract the data from the event
const result = event.data;
if (result.source !== 'checkout_session') {
return;
}
// Check if the session was successful and confirm_url is present:
if (result.success && result.confirm_url) {
// The session was successful and the confirm_url has been returned
const confirm_url = result.confirm_url;
console.log(result);
// Use the confirm_url to confirm the Checkout Session
console.log("Confirm URL:", confirm_url.url);
} else {
// Handle failure accordingly
console.error("Session unsuccessful or confirm_url missing.");
}
}
});
</script>
</body>
</html>Example for getting the hostedFormUrl
This is a response after creating a Checkout Session that contains the url you need to provide under src="{hostedFormUrl}":
id string
The Checkout Session ID.
This is the session ID you need if you are using Flywire Elements with Smart Rendering or Checkout as Javascript with API.
What is Smart Rendering?
Smart Rendering means you render Flywire Elements on your website with the help of the Flywire SDK script.
Extensive customization
-
Select which payer fields to display.
-
Customize the appearance, such as fonts and colors.
-
Choose the language.
Responsive layout
Optimized responsive layout for desktop and mobile devices.
Easy event handling
Simply define what should happen in case of success or errors - no need to filter individual postMessages.
expires_in_seconds integer
The time before the Checkout Session expires in seconds.
hosted_form object
Only relevant when you render the form via iframe. More info:
-
iframe rendering for Flywire Elements
-
iframe rendering for Checkout
url string (url)
The hosted-form-URL. This is the URL your iframe displays.
method string
The method (GET).
warnings array
source string
The field where the error occurred.
For a description of all fields and their valid values form see:
-
Payment Element if you are using Flywire Elements
-
Checkout Experience if you are using Checkout
errors array
You can decide which information from the response you want to filter out in your backend before passing the URL to your frontend.
text string
The error text.
error type string
The error type.
{
"id": "494d2e9d-c0c9-407c-9094-5b3b2a02c00f",
"expires_in_seconds": 1800,
"hosted_form": {
"url": "https://payment-checkout-dev-apache.flywire.cc/v1/form?session_id=494d2e9d-c0c9-407c-9094-5b3b2a02c00f",
"method": "GET"
},
"warnings": []
}Example for a postMessage of the event listener
After your payer sent the form, the event listener will return a successful postMessage.
A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.
The postMessage contains the following information:
confirm_url object
Contains the confirm URL. The confirm URL is the full url for the request to confirm the session, already resolved with the correct session ID.
method string The method (POST).
url string (url) The confirm URL. The confirm URL is the full url for the request to confirm the session, already resolved with the correct session ID.
payor object
The email address your payer entered in the UI Form. You need to use this email address to send mandatory emails to your payer, see
One Off Payments: Emails to Your Payer (only if you opted for sending emails yourself)
source string This parameter helps you filter the PostMessages to only return the result of the Checkout Session. This is only necessary when you render via iframe (see Implementing the Payment Element for Elements and Implementing the Checkout Experience for Checkout).
success booleanIndicates if the Checkout Session was successful.
true: Checkout Session successful
false: Checkout Session failed
You can use this parameter to filter the PostMessages to only return successful ones. This is only necessary when you render via iframe (see Implementing the Payment Element for Elements and Implementing the Checkout Experience for Checkout).
{
confirm_url: {
method: "POST",
url: "https://api-platform.flywire.com/payments/v1/checkout/sessions/494d2e9d-c0c9-407c-9094-5b3b2a02c00f/confirm",
},
payor: {
email: "[email protected]"
},
source: "checkout_session",
success: true
}