Refunds

List of endpoints

About Refunds

What is a refund?

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.

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

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 recipient must have a cut-off time defined.

  More info

  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.

  More info

  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:

1. Flywire collects the funds from the recipient of the original payment.

   How does Flywire collect the funds?

   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.

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

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

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

2. Flywire returns the money to the payer of the original payment,

   How does Flywire return the money?

   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.

How do I receive notifications for refunds?

You receive notifications about the refund status via callbacks (see Refund Status Notifications) via the notifications URL.

• For refunds you can provide a notifications URL that is different from the notifications URL of the payment.

  • If you don't provide a URL, the notifications URL of the original payment is being used.

  • If the original payment had no notifications URL, no notifications will be sent.

• For refund bundles, the notifications URL of the first refund that created the bundle is being used as the notifications URL for the whole bundle.

Getting a list of all your refunds

Request

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:

payment_id stringquery parameter

You can use the payment reference of a payment to only return refunds for this specific payment.

What is the payment reference?

The payment reference identifies a payment.

The format for a payment reference is:

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.

status stringquery parameter

You can filter the list by the status of a refund to only get refunds that are currently in that status. You can only filter by one status at a time.

Example:

GET/refunds

?status=initiated

Possible values

A refund can have the following statuses:

Status	Description
initiated	You have created a refund.
failed	There was a problem trying to create the refund. Reasons for a failed refund Error Reason Description not_found The payment that the refund is supposed to be created for can't be found. already_refund The payment that the refund is supposed to be created for already has a refund in progress. 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. status The payment that the refund is supposed to be created for is in a status that doesn't allow a refund to be created. A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses). amount_ over_ remaining_ balance The amount of the refund is bigger than the remaining payment balance. minimum_ threshold The amount of the refund is less than the minimum amount configured for the recipient. What is the minimum amount configured for a recipient? The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire. If you didn't customize the settings, the default limits are: Minimum: 5000 = 50.00 USD Maximum: 15000000 = 150000.00 USD When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items. What happens when a payment is not within the defined settings? When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned. currency Currency mismatch. multiple The payment that the refund is supposed to be created for is already fully refunded.
received	Flywire has received your money for the refund.
cancelled	When you cancel a refund, Flywire will not process the refund. Cancelling a Refund Essentials - What You Should Know: You can only cancel a refund that is in status initiated, meaning that Flywire has not taken the first step for processing the refund and no money has been moved yet. You can cancel a refund before and after the cut-off time of a recipient. You can't cancel a refund bundle.
finished	Flywire has transferred the money back to your payer. If a refund moves back from finished to received, it means Flywire couldn't transfer the money because the payer's bank rejected it. You don't need to take any action. Flywire will keep trying and notify you if the issue continues.
returned	After Flywire received the money from you, Flywire returned the money back to you instead of returning it to your payer. In the rare case that a refund moves back from returned to received, it means that Flywire couldn't transfer the money back to you. Flywire will contact you if that happens.

recipients stringquery parameter

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.

What is the recipient ID?

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.

created_at date query parameter

You can filter the list for a specific date or time span by using the status name plus _at, _from, or _to. Use the format YYYY-MM-DD for the values:

created_at	To return only results for a specific date. {endpoint-path}?created_at=2024-01-09
created_from	To return only results starting from a specific date. {endpoint-path}?created_from=2024-01-09
created_to	To return only results before a specific date. {endpoint-path}?created_to=2024-01-09
created_from together with created_to	To return only results between a specific time span. {endpoint-path}?created_from=2024-01-01&created_to=2024-01-09

bundle_id stringquery parameter

You can filter the list by refund bundle ID. Only one refund bundle ID can be used at a time.

What is the refund bundle ID?

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Where do I find the refund bundle ID?

The refund bundle ID is returned to you in the response after you created a refund, see Creating a Refund for a Payment.

For existing refund bundles, you can see the refund bundle ID by getting the list of refund bundles via

GET/refund_bundles

, see Getting a list of all your refund bundles.

Optional Query Parameters for Pagination

This endpoint supports pagination. If you are not providing any pagination parameters, the response is returned with default pagination settings.

Pagination parameters are added as query parameters with the request in the format

{endpoint_path}?page=2&per_page=10

Default setting

The default setting is:

• page=1 (start on page 1)

• per_page=10 (display 10 entries per page)

page integerquery parameter

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

per_page integer query parameter

Enables you to define how many results will be included per page.

Possible values: min 1, max 100

GET/refunds

Production - https://api-platform.flywire.com/payments/v1/ Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/refunds
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

Pagination Parameters

total_entries integer

The total number of items in the full result list, not just of the current page.

total_pages integer

The total number of pages available.

page integer

The current page of the results.

per_page integer

The maximum number of results to return at one time (on one page).

refunds array

refund_id string

The refund ID.

The refund ID is a unique reference generated by Flywire to identify a refund. It is generated for each refund after a refund has been created.

Format: R + recipient ID + 8 characters

Example: RPTUABCDE123

The refund ID identifies a single refund within a refund bundle. The single refund starts with an R and the refund bundle it is part of starts with a BUDR.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

payment_id string

The payment reference.

What is the payment reference?

The payment reference identifies a payment.

The format for a payment reference is:

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.

bundle_id string

The refund bundle ID.

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

recipient_id string

The recipient ID.

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.

created_at date

The time and date the refund was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

amount integer

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.

currency string

The currency in which Flywire takes the funds back from the recipient (same as the recipient's billing currency) in ISO 4217 format.

What is the billing currency?

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.

status string

The current status of the refund.

Possible refund statuses

A refund can have the following statuses:

Status	Description
initiated	You have created a refund.
failed	There was a problem trying to create the refund. Reasons for a failed refund Error Reason Description not_found The payment that the refund is supposed to be created for can't be found. already_refund The payment that the refund is supposed to be created for already has a refund in progress. 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. status The payment that the refund is supposed to be created for is in a status that doesn't allow a refund to be created. A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses). amount_ over_ remaining_ balance The amount of the refund is bigger than the remaining payment balance. minimum_ threshold The amount of the refund is less than the minimum amount configured for the recipient. What is the minimum amount configured for a recipient? The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire. If you didn't customize the settings, the default limits are: Minimum: 5000 = 50.00 USD Maximum: 15000000 = 150000.00 USD When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items. What happens when a payment is not within the defined settings? When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned. currency Currency mismatch. multiple The payment that the refund is supposed to be created for is already fully refunded.
received	Flywire has received your money for the refund.
cancelled	When you cancel a refund, Flywire will not process the refund. Cancelling a Refund Essentials - What You Should Know: You can only cancel a refund that is in status initiated, meaning that Flywire has not taken the first step for processing the refund and no money has been moved yet. You can cancel a refund before and after the cut-off time of a recipient. You can't cancel a refund bundle.
finished	Flywire has transferred the money back to your payer. If a refund moves back from finished to received, it means Flywire couldn't transfer the money because the payer's bank rejected it. You don't need to take any action. Flywire will keep trying and notify you if the issue continues.
returned	After Flywire received the money from you, Flywire returned the money back to you instead of returning it to your payer. In the rare case that a refund moves back from returned to received, it means that Flywire couldn't transfer the money back to you. Flywire will contact you if that happens.

external_reference string

This is the external reference you provided via the external_reference parameter when you created the refund. The external reference is used to match a notification to a particular refund, usually an identifier or reference from your own system.

{
    "total_entries": 42,
    "total_pages": 5,
    "page": 1,
    "per_page": 10,
    "refunds": [
        {
            "refund_id": "RRUC247B58FE",
            "payment_id": "RUC990764382",
            "bundle_id": "BUDR123456HG",
            "recipient_id": "ARA",
            "created_at": "2023-12-04T14:07:01Z",
            "amount": 10000,
            "currency": "USD",
            "status": "pending",
            "external_reference": "a-reference"
        }
    ]
}

Getting details about a refund

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {refundID} in the endpoint with the actual refund ID.

What is the refund ID?

The refund ID is a unique reference generated by Flywire to identify a refund. It is generated for each refund after a refund has been created.

Format: R + recipient ID + 8 characters

Example: RPTUABCDE123

The refund ID identifies a single refund within a refund bundle. The single refund starts with an R and the refund bundle it is part of starts with a BUDR.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Where do I find the refund ID?

The refund ID is returned to you in the response after you created a refund, see Creating a Refund for a Payment.

For existing refunds, you can see the refund ID by getting the list of refunds via this request:

GET/refunds

See Getting a list of all your refunds for details.

GET/refunds/{refundID}

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/refunds/RFLW12345678
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

refund_id string

The refund ID.

The refund ID is a unique reference generated by Flywire to identify a refund. It is generated for each refund after a refund has been created.

Format: R + recipient ID + 8 characters

Example: RPTUABCDE123

The refund ID identifies a single refund within a refund bundle. The single refund starts with an R and the refund bundle it is part of starts with a BUDR.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

payment_id string

The payment reference.

What is the payment reference?

The payment reference identifies a payment.

The format for a payment reference is:

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.

bundle_id string

The refund bundle ID.

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

created_at date

The time and date the refund was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

status string

The current status of the refund.

Possible refund statuses

A refund can have the following statuses:

Status	Description
initiated	You have created a refund.
failed	There was a problem trying to create the refund. Reasons for a failed refund Error Reason Description not_found The payment that the refund is supposed to be created for can't be found. already_refund The payment that the refund is supposed to be created for already has a refund in progress. 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. status The payment that the refund is supposed to be created for is in a status that doesn't allow a refund to be created. A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses). amount_ over_ remaining_ balance The amount of the refund is bigger than the remaining payment balance. minimum_ threshold The amount of the refund is less than the minimum amount configured for the recipient. What is the minimum amount configured for a recipient? The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire. If you didn't customize the settings, the default limits are: Minimum: 5000 = 50.00 USD Maximum: 15000000 = 150000.00 USD When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items. What happens when a payment is not within the defined settings? When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned. currency Currency mismatch. multiple The payment that the refund is supposed to be created for is already fully refunded.
received	Flywire has received your money for the refund.
cancelled	When you cancel a refund, Flywire will not process the refund. Cancelling a Refund Essentials - What You Should Know: You can only cancel a refund that is in status initiated, meaning that Flywire has not taken the first step for processing the refund and no money has been moved yet. You can cancel a refund before and after the cut-off time of a recipient. You can't cancel a refund bundle.
finished	Flywire has transferred the money back to your payer. If a refund moves back from finished to received, it means Flywire couldn't transfer the money because the payer's bank rejected it. You don't need to take any action. Flywire will keep trying and notify you if the issue continues.
returned	After Flywire received the money from you, Flywire returned the money back to you instead of returning it to your payer. In the rare case that a refund moves back from returned to received, it means that Flywire couldn't transfer the money back to you. Flywire will contact you if that happens.

status_transitions object

The status transitions provide you with a log for if and when a refund was cancelled.

See Refund Status Notifications for details about the status.

cancelled_at date

If the refund has been cancelled: The time and date the refund was cancelled.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

amount integer

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.

currency string

The currency in which Flywire takes the funds back from the recipient (same as the recipient's billing currency) in ISO 4217 format.

What is the billing currency?

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.

amount_to integer

The amount of the refund in the payer currency. This is what your payer will receive in their own currency.

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.

currency_to string

The payer currency for the refund (meaning the currency that the payer paid and will receive their refund in) in ISO 4217 format.

recipient_id string

The recipient ID.

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.

payer object

The payer information is not automatically included. Returning payer information is disabled by default and needs to be enabled by Flywire.

Please contact the Solutions team if you require payer information to be returned.

first_name string

The payer's first name.

last_name string

The payer's last name.

middle_name string

The payer's middle name.

address1 string

The payer's first line of address.

address2 string

The payer's second line of address.

city string

The payer's city.

zip string

The payer's zip code.

country string

The ISO2 code of the payer country (the country the money was sent from).

state string

The payer's state.

phone string

The payer's phone number.

email string

The payer's email address.

external_reference string

This is the external reference you provided via the external_reference parameter when you created the refund. The external reference is used to match a notification to a particular refund, usually an identifier or reference from your own system.

{
	"refund_id": "RFLW123456789",
	"payment_id": "FLW990764382",
	"bundle_id": "BUDR123456HG",
	"created_at": "2024-01-02T08:43:38Z",
	"status": "cancelled",
	"status_transitions": {
		"cancelled_at": "2024-01-03T15:40:50Z"
	},
	"amount": 12000,
	"currency": "USD",
	"amount_to": 10000,
	"currency_to": "EUR",
	"recipient_id": "FLW",
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    },
	"external_reference": "My reference"
}

Getting a list of all your refund bundles

Request

You can use this endpoint to display a list of refund bundles in your UI, for example:

• To get an overview of all refund bundles created by you.

• If you're using approvals: To get an overview of refund bundles that are waiting for approval.

Each parameter can be used as a column. You can decide which parameters you want to display to help you identify a refund before you get more detailed information about it (see Getting details about a refund bundle). Check the response to see which parameters of refund bundles are returned.

Which refund bundles are returned in the list?

You can see refund bundles that contain payments you have access to. Which payments you have access to depends on your individual client settings you have agreed on with Flywire.

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:

status stringquery parameter

You can filter the list by the status of a refund bundle to only get refund bundles that are currently in that status. You can only filter by one status at a time.

Possible values

A refund bundle can have the following statuses and notifications:

Status	Notification	Description
pending	pending	The refund bundle has been successfully created.
	marked for approval	Only for refund bundles that require manual approval. The cut-off time for the refund bundle has been reached and the bundle is now ready for approval. What are manual and automatic approvals? 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. What is the cut-off time? 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.
approved	approved	The refund bundle has been approved, either manually by you or automatically by Flywire.
debited	debited	Flywire has requested the money for the refund from the original recipient through direct debit. This status only occurs when Flywire collects the funds via direct debit from the original recipient of the payment. More about how Flywire collects money for refunds 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.
received	received	Flywire has received your money for the refund bundle.

created_at date query parameter

You can filter the list for a specific date or time span by using the status name plus _at, _from, or _to. Use the format YYYY-MM-DD for the values:

created_at	To return only results for a specific date. {endpoint-path}?created_at=2024-01-09
created_from	To return only results starting from a specific date. {endpoint-path}?created_from=2024-01-09
created_to	To return only results before a specific date. {endpoint-path}?created_to=2024-01-09
created_from together with created_to	To return only results between a specific time span. {endpoint-path}?created_from=2024-01-01&created_to=2024-01-09

recipients stringquery parameter

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.

What is the recipient ID?

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.

marked_for_approval stringquery parameter

This filter cannot be used in combination with the status filter, since only refund bundles in status pending can be marked for approval. All other filters can be used in combination with this filter.

You can filter the list to include only refund bundles that are marked for approval.

Possible values:

• true

• false

Example:

GET/refund_bundles

?marked_for_approval=true

What does "marked for approval" mean?

Indicates if the refund bundle is waiting for approval.

This parameter is only relevant for refund bundles that require manual approval:

• Before the cut-off time is reached, the value is false.

• After the cut-off time is reached, this value switches to true (meaning the bundle is waiting for manual approval).

• After the manual approval is given, the value switches back to false.

For bundles that are approved automatically the value is always false.

What is the cut-off time?

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.

Details about manual and automatic approvals

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.

Optional Query Parameters for Pagination

This endpoint supports pagination. If you are not providing any pagination parameters, the response is returned with default pagination settings.

Pagination parameters are added as query parameters with the request in the format

{endpoint_path}?page=2&per_page=10

Default setting

The default setting is:

• page=1 (start on page 1)

• per_page=10 (display 10 entries per page)

page integerquery parameter

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

per_page integer query parameter

Enables you to define how many results will be included per page.

Possible values: min 1, max 100

GET/refund_bundles

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/refund_bundles
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

Pagination Parameters

total_entries integer

The total number of items in the full result list, not just of the current page.

total_pages integer

The total number of pages available.

page integer

The current page of the results.

per_page integer

The maximum number of results to return at one time (on one page).

refund_bundles array

id string

The refund bundle ID.

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

recipient_id string

The recipient ID.

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.

status string

Status of the refund bundle.

Possible refund bundle statuses

A refund bundle can have the following statuses and notifications:

Status	Notification	Description
pending	pending	The refund bundle has been successfully created.
	marked for approval	Only for refund bundles that require manual approval. The cut-off time for the refund bundle has been reached and the bundle is now ready for approval. What are manual and automatic approvals? 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. What is the cut-off time? 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.
approved	approved	The refund bundle has been approved, either manually by you or automatically by Flywire.
debited	debited	Flywire has requested the money for the refund from the original recipient through direct debit. This status only occurs when Flywire collects the funds via direct debit from the original recipient of the payment. More about how Flywire collects money for refunds 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.
received	received	Flywire has received your money for the refund bundle.

amount integer

The total amount of the refund bundle, which is the sum of all refund amounts in the bundle. The currency for this amount is the billing currency of the recipient.

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.

currency string

The currency in which Flywire takes the funds back from the recipient (same as the recipient's billing currency) in ISO 4217 format.

What is the billing currency?

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.

created_at date

The time and date the refund bundle was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

marked_for_approval boolean

Indicates if the refund bundle is waiting for approval.

This parameter is only relevant for refund bundles that require manual approval:

• Before the cut-off time is reached, the value is false.

• After the cut-off time is reached, this value switches to true (meaning the bundle is waiting for manual approval).

• After the manual approval is given, the value switches back to false.

For bundles that are approved automatically the value is always false.

What is the cut-off time?

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.

Details about manual and automatic approvals

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.

{
  "total_entries": 2,
  "total_pages": 1,
  "page": 1,
  "per_page": 10,
  "refund_bundles": [
    {
      "id": "BUDREB8E4538",
      "recipient_id": "EBS",
      "status": "pending",
      "amount": 115000,
      "currency": "GBP",
      "created_at": "2022-07-21T17:27:54Z",
      "marked_for_approval": true
    },
    {
      "id": "BUDREF477410",
      "recipient_id": "EBS",
      "status": "approved",
      "amount": 10000,
      "currency": "GBP",
      "created_at": "2022-03-23T14:27:56Z",
      "marked_for_approval": false
    }
  ]
}

Getting details about a refund bundle

Request

You can use this endpoint to display the details about a refund bundle in a UI. For example, if you are using approvals, you can see if and when a bundle has been approved. Check the response to see which parameters of the refund bundles are returned.

Are you looking for an overview of all refunds in a bundle?

To find all refunds in a bundle, get the list of refunds and filter it with the query parameter bundle_id.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {bundleID} in the endpoint with the actual refund bundle ID.

What is the refund bundle ID?

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Where do I find the refund bundle ID?

The refund bundle ID is returned to you in the response after you created a refund, see Creating a Refund for a Payment.

For existing refund bundles, you can see the refund bundle ID by getting the list of refund bundles via

GET/refund_bundles

, see Getting a list of all your refund bundles.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

GET/refund_bundles/{bundleID}

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/refund_bundles/BUDRW12345678
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

bundle_id string

The refund bundle ID.

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

recipient_id string

The recipient ID.

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.

status string

Status of the refund bundle.

Possible refund bundle statuses

A refund bundle can have the following statuses and notifications:

Status	Notification	Description
pending	pending	The refund bundle has been successfully created.
	marked for approval	Only for refund bundles that require manual approval. The cut-off time for the refund bundle has been reached and the bundle is now ready for approval. What are manual and automatic approvals? 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. What is the cut-off time? 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.
approved	approved	The refund bundle has been approved, either manually by you or automatically by Flywire.
debited	debited	Flywire has requested the money for the refund from the original recipient through direct debit. This status only occurs when Flywire collects the funds via direct debit from the original recipient of the payment. More about how Flywire collects money for refunds 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.
received	received	Flywire has received your money for the refund bundle.

marked_for_approval boolean

Indicates if the refund bundle is waiting for approval.

This parameter is only relevant for refund bundles that require manual approval:

• Before the cut-off time is reached, the value is false.

• After the cut-off time is reached, this value switches to true (meaning the bundle is waiting for manual approval).

• After the manual approval is given, the value switches back to false.

For bundles that are approved automatically the value is always false.

What is the cut-off time?

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.

Details about manual and automatic approvals

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.

created_at date

The time and date the refund bundle was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

approved_at date

The date and time the refund bundle has been approved, either manually or automatically.

Details about manual and automatic approvals

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.

notifications_url string (url)

The notifications URL.

You receive notifications about the refund status via callbacks (see Refund Status Notifications) via the notifications URL.

• For refunds you can provide a notifications URL that is different from the notifications URL of the payment.

  • If you don't provide a URL, the notifications URL of the original payment is being used.

  • If the original payment had no notifications URL, no notifications will be sent.

• For refund bundles, the notifications URL of the first refund that created the bundle is being used as the notifications URL for the whole bundle.

amount integer

The total amount of the refund bundle, which is the sum of all refund amounts in the bundle. The currency for this amount is the billing currency of the recipient.

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.

currency string

The currency in which Flywire takes the funds back from the recipient (same as the recipient's billing currency) in ISO 4217 format.

What is the billing currency?

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.

reception object

The reception of funds is a special term for refunds and refers to how and when Flywire collects money from the original recipient of the payment in order to return it to the payer.

Ways for Flywire to collect the money from the original recipient

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.

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

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

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

date date

The date when Flywire took the funds from the recipient.

bank_reference string

The bank reference for the bank account from which Flywire collected the funds.

If netting was used to collect the funds, the value is null.

What is 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.

account_number string

The account for the bank account from which Flywire collected the funds.

If netting was used to collect the funds, the value is null.

What is 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.

amount integer

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.

currency string

The currency in which Flywire takes the funds back from the recipient (same as the recipient's billing currency) in ISO 4217 format.

What is the billing currency?

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the recipient's configuration and is defined when the recipient is set up by Flywire.

{
  "bundle_id": "BUUI123456789",
  "recipient_id": "ARA",
  "status": "approved",
  "marked_for_approval": "false",
  "created_at": "2017-12-06 17:41:27 UTC",
  "approved_at": "2017-12-06 17:41:27 UTC",
  "notifications_url": "my-notifications-url",
  "amount": 12000,
  "currency": "USD",
  "reception": {
    "date": "2019-01-11",
    "bank_reference": null,
    "account_number": null,
    "amount": 12000,
    "currency": "USD"
  }
}

Approving a refund bundle

Request

This endpoint lets you approve a refund bundle.

What are approvals for refund bundles?

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:

To add or change the settings for refund approvals of a recipient please contact the Solutions team.

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {bundleID} in the endpoint with the actual refund bundle ID.

What is the refund bundle ID?

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Where do I find the refund bundle ID?

The refund bundle ID is returned to you in the response after you created a refund, see Creating a Refund for a Payment.

For existing refund bundles, you can see the refund bundle ID by getting the list of refund bundles via

GET/refund_bundles

, see Getting a list of all your refund bundles.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/refund_bundles/BUDRW12345678/approve
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

id string

The refund bundle ID.

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

status string

Returned as "approved" for successfully approved bundles.

"id": "BUUI123456789", 
"status": "approved"

Cancelling a refund

Request

When you cancel a refund, Flywire will not process the refund.

Cancelling a Refund Essentials - What You Should Know:

• You can only cancel a refund that is in status initiated, meaning that Flywire has not taken the first step for processing the refund and no money has been moved yet.

• You can cancel a refund before and after the cut-off time of a recipient.

• You can't cancel a refund bundle.

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {refundID} in the endpoint with the actual refund ID.

What is the refund ID?

The refund ID is a unique reference generated by Flywire to identify a refund. It is generated for each refund after a refund has been created.

Format: R + recipient ID + 8 characters

Example: RPTUABCDE123

The refund ID identifies a single refund within a refund bundle. The single refund starts with an R and the refund bundle it is part of starts with a BUDR.

What is the difference between a refund and a refund bundle?

Refunds

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

1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

   More details about the cut-off time

   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.

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

   More details about approvals

   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.

    

   For details about how to approve a refund bundle see see Approving a refund bundle.

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

Where do I find the refund ID?

The refund ID is returned to you in the response after you created a refund, see Creating a Refund for a Payment.

For existing refunds, you can see the refund ID by getting the list of refunds via this request:

GET/refunds

See Getting a list of all your refunds for details.

POST/refunds/{refundID}/cancel

Production - https://api-platform.flywire.com/payments/v1/Sandbox - https://api-platform-sandbox.flywire.com/payments/v1/

curl https://base-url-placeholder/refunds/RFLW23456432/cancel
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

204 NO CONTENT