A refund is a way to return funds back to your payer via Flywire. You can define if you want to return the full amount (full refund) or just part of the amount (partial refund) of the original payment.
Refund Essentials: What You Should Know
A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
Each refund is connected to one payment, it is not possible to create one "shared" refund for multiple payments.
A payment can only have one active refund at a time. When the refund is done (in status finished) you can create a new refund for the payment.
The refunded amount, whether it's one full refund or several partial refunds added together, can't be more than the initial payment amount.
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.
Requirements for using Refunds
There are two sides to requirements for using refunds:
Requirements on the client side
You as a client need to have the permission to work with refunds. Please contact the Solutions team for this.
Requirements on the recipient side
A recipient must have the following settings in place to be able to use refunds:
The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.
The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.
You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.
The recipient must have defined if refunds need to be approved or not.
All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:
Type of approval
approval_type setting for the recipient
Manual approval
Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).
manual
Automatic approval
Flywire processes refund bundles automatically after the cut-off time.
automatic
To add or change the settings for refund approvals of a recipient please contact the Solutions team.
How does the Refund Process work?
The refund process works like this:
Flywire collects the funds from the recipient of the original payment.
There are three ways for how Flywire can collect the money for the refund from the original recipient of the payment. Which method is being used depends on what the original recipient of the payment agreed on with Flywire.
Bank transfer
If bank transfer is used as a refund collection method, Flywire will request the original recipient of the payment to transfer the money for the refund to Flywire.
Netting
Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.
Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.
Essentials about using netting as a refund collection method
Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.
This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.
This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.
Direct debit
If direct debit is used a refund collection method, the original recipient of the payment allows Flywire to collect the money for refunds from their bank account automatically.
Essentials about using direct debit as a refund collection method
This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.
Flywire returns the money to the payer of the original payment,
Flywire returns the refund amount to the original payer using the original payment method.
For bank transfer, Flywire will send emails to the payer that informs them about the steps Flywire needs them to do for being able to receive the money. You still have to send the other mandatory emails, see Refunds: Emails You Need To Send.
Walkthrough: Creating Refunds
The following steps are necessary to create refunds with the Flywire API:
To be able to use the Flywire API, you need to be registered, and all requests to the Flywire API need to be authenticated, see Flywire API Basics
If you are just getting started and only have Sandbox credentials, you need to use the Sandbox environment. All request examples let you switch between the production and sandbox base URL.
You need to know the payment reference of the payment you want to create a refund for.
GET/payments
If you don't know the payment reference of the payment, you can use the this endpoint to find it. More about the endpoint: Getting a List of all Payments
You can use this endpoint to display a list of all payments in a UI.
Which payments will be returned in the list?
The list will contain all payments that have been created by you as a client with your API credentials via the Flywire API .
Don't use the list of payments as a source of truth regarding the payment status. If you want to get immediate updates about a payment's status, use notifications (see Payment Status Notifications).
There can be a latency in fetching this information. Under normal conditions, it takes only minutes to get the latest status of a payment or to show a newly created payment, but it can take much longer depending on technical circumstances.
Example for displaying a list of payments
Each parameter can be used as a column (for example payment reference or status). You can decide which parameters you want to display to help you identify a payment before you get more detailed information about it (see Getting Details about a Payment). Check the response to see which parameters of the payments are returned in the list.
Parameters for the Request Body
No request body needed.
Optional Query Parameters for Filtering
You can filter the list of results by the following parameters:
You can filter the list by one or more (max. 10) specific recipients to only get payments for those recipients back. If you use more than one recipient, divide them by commas (",").
You need to use the recipient ID of the recipient as a value.
The recipient ID is the unique three-letter ID that identifies the recipient, for example FWU for Flywire University. The recipient ID has been assigned by Flywire when the recipient has been set up.
You can filter the list by the status of a payment to only get payments back that are currently in that status. You can only filter by one status at a time.
In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:
A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.
Recipient ID followed by a string of characters, for example FWU744586810.
With the payment reference, the payment can be tracked during its journey 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.
When the payment reference is assigned, two things happen:
The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).
The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.
A Pre-Authorization Payment temporary reserves the payment amount on a debit or credit card. The purpose of a pre-authorization is to verify that the cardholder has sufficient credit available to cover a transaction and to temporarily set aside that amount until you capture the funds.
Pre-Authorization Payments are only available for same-currency payments, not for FX payments.
Example for a Pre-Authorization Payment:
A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.
Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.
During the Stay: The guest orders room service for $50.
Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.
The payment has been authorized and is now in the holding period.
How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.
When you cancel a Pre-Authorization Payment the blocked amount immediately returns back to the cardholder's credit.
Processed
processed
The payment status goes from initiated to processed when Flywire has the confirmation that the funds have been received or captured via one of these ways:
Bank transfer: funds have been received in a Flywire bank account.
Card payments: funds have been captured in payer’s card.
Direct debit: instructions to capture the funds are in progress and correct.
After a payment is processed by you, you should notify your payer that their payment was processed to avoid duplicate payments.
Guaranteed
guaranteed
The status changes to guaranteed when funds are received by Flywire and all the necessary validations for that payment method and corridor are successful (since Flywire performs a security check on every payment once the funds have been received).
At this point, you are guaranteed that Flywire will send you the funds.
Delivered
delivered
The status changes from guaranteed to delivered when Flywire sent you the funds in your daily batch disbursement. Payments are updated to delivered at a set time each day.
The status delivered is the end stage, the status of a delivered payment can't change.
Failed
failed
The status failed can only occur for card or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure.
Cancelled
cancelled
The payment status cancelled means that the payment has been cancelled and will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.
Payers can cancel a payment in two different ways:
You can give your payers the option to cancel a payment themselves if you implement this function in your UI.
Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire.
Payers can contact Flywire and ask for a payment to be cancelled.
cancelled_by_user
Flywire
There can be different reasons why Flywire cancels a payment:
Verification not passed
The payment didn’t pass Flywire validations. If funds were captured, an automatic refund will be created and funds will be returned directly to the source of funds.
rejected
Duplicate payment
The payer created 2 payments by mistake, and Flywire closed one of them after identifying the duplicate issue.
duplicated
You or the payer contacted Flywire to cancel the payment.
cancelled_by_user
Automatic cancellation - Payment expired
When a payment expires it will automatically be cancelled. Expiring means the payment reached the expiration date without Flywire receiving the funds.
A payment expires automatically after a while if no funds are received by Flywire:
Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.
Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.
For API integration:
Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt.
For other integrations:
Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.
The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.
expired
Direct debit payment failed
When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.
Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.
A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
unpaid
Reversed
reversed
This status has different meaning depending on the context:
This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.
This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.
A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
Then Flywire will start a recovery process and the payment status will change from delivered to reversed.
Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.
You can use this filter to search for values in any of the fields of a recipient.
To narrow down the list of results, you must use this filter in combination with at least one recipient filter. You can use more than one, but maximum ten recipients.
Do not use this filter in automated queries. This filter is intended to be used on demand, not as an automatic query to keep dashboards updated. If you're sending too many requests within a certain time you can be cut off from using the Flywire API, see Rate Limits.
Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.
Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).
Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.
A refund is a way to return funds back to your payer via Flywire. You can define if you want to return the full amount (full refund) or just part of the amount (partial refund) of the original payment.
Refund Essentials: What You Should Know
A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
Each refund is connected to one payment, it is not possible to create one "shared" refund for multiple payments.
A payment can only have one active refund at a time. When the refund is done (in status finished) you can create a new refund for the payment.
The refunded amount, whether it's one full refund or several partial refunds added together, can't be more than the initial payment amount.
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.
You received the payment reference after you created the Pre-Authorization Payment, see Checkout for Pre-Authorization Payments - After Payment Completion.
A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
The amount of the refund in the billing currency. This is the amount Flywire will take from the recipient to refund it back to the payer.
The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.
The external reference is used to match a notification to a particular refund. You can use any kind of identifier or reference from your own system you might need to identify the refunds. Since this parameter will be included in the status notifications about this refund, it will help you to answer the question "For which refund did I get this notification?" Max size of 50 characters.
The refund is automatically added to a refund bundle. You can keep adding refunds for other payments for the same recipient to the bundle until the cut-off time for the recipient is reached.
Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.
The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.
You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.
When the cut-off time for recipient A is reached, Flywire either processes the bundle or requires your approval first, based on the recipient's settings.
All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:
Type of approval
approval_type setting for the recipient
Manual approval
Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).
manual
Automatic approval
Flywire processes refund bundles automatically after the cut-off time.
automatic
To add or change the settings for refund approvals of a recipient please contact the Solutions team.
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.
The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.
The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.
You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.
After the cut-off time has passed, the refund bundle either gets processed by Flywire or - if refunds for this recipient need approval - you need to approve the refund bundle first via
All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:
Type of approval
approval_type setting for the recipient
Manual approval
Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).
manual
Automatic approval
Flywire processes refund bundles automatically after the cut-off time.
automatic
To add or change the settings for refund approvals of a recipient please contact the Solutions team.
Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.
The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.
You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.
When the cut-off time for recipient A is reached, Flywire either processes the bundle or requires your approval first, based on the recipient's settings.
All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:
Type of approval
approval_type setting for the recipient
Manual approval
Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).
manual
Automatic approval
Flywire processes refund bundles automatically after the cut-off time.
automatic
To add or change the settings for refund approvals of a recipient please contact the Solutions team.
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.
A refund is a way to return funds back to your payer via Flywire. You can define if you want to return the full amount (full refund) or just part of the amount (partial refund) of the original payment.
Refund Essentials: What You Should Know
A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
Each refund is connected to one payment, it is not possible to create one "shared" refund for multiple payments.
A payment can only have one active refund at a time. When the refund is done (in status finished) you can create a new refund for the payment.
The refunded amount, whether it's one full refund or several partial refunds added together, can't be more than the initial payment amount.
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.
Refund bundles
Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.
The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.
You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.
When the cut-off time for recipient A is reached, Flywire either processes the bundle or requires your approval first, based on the recipient's settings.
All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:
Type of approval
approval_type setting for the recipient
Manual approval
Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).
manual
Automatic approval
Flywire processes refund bundles automatically after the cut-off time.
automatic
To add or change the settings for refund approvals of a recipient please contact the Solutions team.
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.
POST/refund_bundles/{bundleID}/approve
curl https://base-url-placeholder/refund_bundles/BUDRW12345678/approve
-X POST
-H "Content-Type: application/json"
-H "X-Authentication-Key: {api_key}"
The refund bundle is now being processed by Flywire.
GET/refunds
You can get an overview about all refunds you created via this endpoint, see Refunds.
If you provided a notifications URL, you'll also receive callbacks for each status change, see Refund Status Notifications.
The Flywire API allows you to integrate Flywire’s payment services into your own system. This keeps everything within your own interface while taking advantage of Flywire’s payment network and ensuring a smooth and secure payment experience.
More info
initiated
Flywire API