Refund Status Notifications
Refund Status Notifications enable you to track refunds and refund bundles while they make their way through the refund process. Whenever a status change event occurs, for example when the refund status changes from initiated to received, you'll get a notification to the URL you provided.
There are two different kinds of notifications for refunds:
-
Notifications for single refunds
More info about single 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.
-
-
Notifications for refund bundles
More info about refund bundles
Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
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.
-
How do I get started?
-
For testing notifications: See Flywire API Sandbox
-
For your production environment: See How to set up Refund Status Notifications.
Refund Statuses and Notifications
For Single Refunds
The following statuses trigger a notification for a refund:
Status/Notification | Description |
---|---|
|
You have created a refund. |
![]() |
Flywire has received your money for the refund. |
![]() |
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. |
![]() |
When you cancel a refund, Flywire will not process the refund. Cancelling a Refund Essentials - What You Should Know:
|
![]() |
After Flywire received the money from you, Flywire returned the money back to you instead of returning it to your payer. This could happen for example when Flywire was unable to transfer the money to the 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. |
For Refund Bundles
A refund bundle can have the following statuses and notifications:
Status | Notification | Description | |||||
---|---|---|---|---|---|---|---|
pending
|
![]() |
The refund bundle has been successfully created. |
|||||
![]() |
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. ![]() 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. ![]() 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 |
![]() |
The refund bundle has been approved, either manually by you or automatically by Flywire. |
|||||
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. ![]() 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.
|
|||||
received |
![]() |
Flywire has received your money for the refund bundle. |
Content of Refund Status Notifications
For Single Refunds
-
Initiated
-
Received
-
Finished
-
Returned
-
Cancelled

Type of the event (status change).
Possible event types
initiated
cancelled
received
finished

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refunds
data object

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

The current status of the refund.

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. ![]()
|
||||||||||||||||
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:
|
||||||||||||||||
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.
|

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "initiated",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refunds",
"data": {
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"bundle_id": "BUDR0AEA9E47",
"status": "initiated",
"amount": "4800",
"currency": "EUR"
}
}

Type of the event (status change).
Possible event types
initiated
cancelled
received
finished

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refunds
data object

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

The current status of the refund.

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. ![]()
|
||||||||||||||||
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:
|
||||||||||||||||
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.
|

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "received",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refunds",
"data": {
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"bundle_id": "BUDR0AEA9E47",
"status": "received",
"amount": "4800",
"currency": "EUR"
}

Type of the event (status change).
Possible event types
initiated
cancelled
received
finished

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refunds
data object

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

The current status of the refund.

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. ![]()
|
||||||||||||||||
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:
|
||||||||||||||||
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.
|

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "finished",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refunds",
"data": {
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"bundle_id": "BUDR0AEA9E47",
"status": "finished",
"amount": "4800",
"currency": "EUR"
}
}

Type of the event (status change).
Possible event types
initiated
cancelled
received
finished

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refunds
data object

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

The current status of the refund.

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. ![]()
|
||||||||||||||||
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:
|
||||||||||||||||
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.
|

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "returned",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refunds",
"data": {
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"bundle_id": "BUDR0AEA9E47",
"status": "returned",
"amount": "4800",
"currency": "EUR"
}
}

Type of the event (status change).
Possible event types
initiated
cancelled
received
finished

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refunds
data object

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

The current status of the refund.

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. ![]()
|
||||||||||||||||
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:
|
||||||||||||||||
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.
|

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "cancelled",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refunds",
"data": {
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"bundle_id": null,
"status": "cancelled",
"amount": "4800",
"currency": "EUR"
}
}
For Refund Bundles
-
Pending
-
Pending - Marked for Approval
-
Approved
-
Debited
-
Received

Type of the event (status change).
Possible event types:
pending
marked_for_approval
approved
debited
received

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refund_bundles
data object

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
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.

Internal Flywire reference to identify the bundle.

The external reference for refund bundles is always null
since refund bundles get created automatically when you are creating a refund. You can define the external reference for a refund, but not for a bundle.

Status of the refund bundle.

A refund bundle can have the following statuses and notifications:
Status | Notification | Description | |||||
---|---|---|---|---|---|---|---|
pending
|
![]() |
The refund bundle has been successfully created. |
|||||
![]() |
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. ![]() 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. ![]() 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 |
![]() |
The refund bundle has been approved, either manually by you or automatically by Flywire. |
|||||
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. ![]() 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.
|
|||||
received |
![]() |
Flywire has received your money for the refund bundle. |

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
requests array
This array contains the refunds that are part of the bundle. Each refund contains the following parameters:

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "pending",
"event_date": "2024-01-26T13:15:29Z",
"event_resource": "refund_bundles",
"data": {
"bundle_id": "BUDRF62DEF4A",
"api_reference": null,
"external_reference": null,
"status": "pending",
"amount": "120000",
"currency": "USD",
"requests": [
{
"refund_id": "RRUC8277E659",
"payment_id": "RUC203100127",
"external_reference": "abcdef",
"amount": "120000",
"currency": "USD"
}
]
}
}

Type of the event (status change).
Possible event types:
pending
marked_for_approval
approved
debited
received

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refund_bundles
data object

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
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.

Internal Flywire reference to identify the bundle.

The external reference for refund bundles is always null
since refund bundles get created automatically when you are creating a refund. You can define the external reference for a refund, but not for a bundle.

Status of the refund bundle.

A refund bundle can have the following statuses and notifications:
Status | Notification | Description | |||||
---|---|---|---|---|---|---|---|
pending
|
![]() |
The refund bundle has been successfully created. |
|||||
![]() |
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. ![]() 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. ![]() 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 |
![]() |
The refund bundle has been approved, either manually by you or automatically by Flywire. |
|||||
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. ![]() 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.
|
|||||
received |
![]() |
Flywire has received your money for the refund bundle. |

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "marked_for_approval",
"event_date": "2024-01-26T13:17:00Z",
"event_resource": "refund_bundles",
"data": {
"bundle_id": "BUDRF62DEF4A",
"api_reference": null,
"external_reference": null,
"status": "pending",
"amount": "120000",
"currency": "USD"
}
}

Type of the event (status change).
Possible event types:
pending
marked_for_approval
approved
debited
received

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refund_bundles
data object

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
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.

Internal Flywire reference to identify the bundle.

The external reference for refund bundles is always null
since refund bundles get created automatically when you are creating a refund. You can define the external reference for a refund, but not for a bundle.

Status of the refund bundle.

A refund bundle can have the following statuses and notifications:
Status | Notification | Description | |||||
---|---|---|---|---|---|---|---|
pending
|
![]() |
The refund bundle has been successfully created. |
|||||
![]() |
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. ![]() 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. ![]() 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 |
![]() |
The refund bundle has been approved, either manually by you or automatically by Flywire. |
|||||
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. ![]() 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.
|
|||||
received |
![]() |
Flywire has received your money for the refund bundle. |

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
requests array
This array contains the refunds that are part of the bundle. Each refund contains the following parameters:

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "approved",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refund_bundles",
"data": {
"bundle_id": "BUDR0AEA9E47",
"api_reference": "ABCD123",
"external_reference": "a-reference-bundle",
"status": "approved",
"amount": "4800",
"currency": "EUR",
"requests": [
{
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"amount": "1000",
"currency": "EUR"
},
{
"refund_id": "RPTUE0D68649",
"payment_id": "PTU146224730",
"external_reference": "a-reference-1",
"amount": "3800",
"currency": "EUR"
},
]
}
}

Type of the event (status change).
Possible event types:
pending
marked_for_approval
approved
debited
received

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refund_bundles
data object

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
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.

Internal Flywire reference to identify the bundle.

The external reference for refund bundles is always null
since refund bundles get created automatically when you are creating a refund. You can define the external reference for a refund, but not for a bundle.

Status of the refund bundle.

A refund bundle can have the following statuses and notifications:
Status | Notification | Description | |||||
---|---|---|---|---|---|---|---|
pending
|
![]() |
The refund bundle has been successfully created. |
|||||
![]() |
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. ![]() 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. ![]() 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 |
![]() |
The refund bundle has been approved, either manually by you or automatically by Flywire. |
|||||
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. ![]() 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.
|
|||||
received |
![]() |
Flywire has received your money for the refund bundle. |

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
requests array
This array contains the refunds that are part of the bundle. Each refund contains the following parameters:

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "debited",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refund_bundles",
"data": {
"bundle_id": "BUDR0AEA9E47",
"api_reference": "ABCD123",
"external_reference": "a-reference-bundle",
"status": "debited",
"amount": "4800",
"currency": "EUR",
"requests": [
{
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"amount": "1000",
"currency": "EUR"
},
{
"refund_id": "RPTUE0D68649",
"payment_id": "PTU146224730",
"external_reference": "a-reference-1",
"amount": "3800",
"currency": "EUR"
},
]
}
}

Type of the event (status change).
Possible event types:
pending
marked_for_approval
approved
debited
received

The time when the event (status change) occurred. Expressed in UTC time, ISO 8601 format, for example 2023-10-06T18:12:22Z

The resource that has generated the notification. Possible value:
-
refund_bundles
data object

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

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.
The refund bundle cycle
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
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.

Internal Flywire reference to identify the bundle.

The external reference for refund bundles is always null
since refund bundles get created automatically when you are creating a refund. You can define the external reference for a refund, but not for a bundle.

Status of the refund bundle.

A refund bundle can have the following statuses and notifications:
Status | Notification | Description | |||||
---|---|---|---|---|---|---|---|
pending
|
![]() |
The refund bundle has been successfully created. |
|||||
![]() |
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. ![]() 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. ![]() 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 |
![]() |
The refund bundle has been approved, either manually by you or automatically by Flywire. |
|||||
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. ![]() 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.
|
|||||
received |
![]() |
Flywire has received your money for the refund bundle. |

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
requests array
This array contains the refunds that are part of the bundle. Each refund contains the following parameters:

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

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
-
Creating a refund for recipient A automatically generates a refund bundle for recipient A.
-
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.
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. -
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.
-
Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.
Refund Bundle Essentials: What You Should Know
-
A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.
-
Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
-
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

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

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.

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
The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.
Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

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

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the
{
"event_type": "received",
"event_date": "2021-05-20T11:24:45Z",
"event_resource": "refund_bundles",
"data": {
"bundle_id": "BUDR0AEA9E47",
"api_reference": "ABCD123",
"external_reference": "a-reference-bundle",
"status": "received",
"amount": "4800",
"currency": "EUR",
"requests": [
{
"refund_id": "RPTUE0D63641",
"payment_id": "PTU146221637",
"external_reference": "a-reference",
"amount": "1000",
"currency": "EUR"
},
{
"refund_id": "RPTUE0D68649",
"payment_id": "PTU146224730",
"external_reference": "a-reference-1",
"amount": "3800",
"currency": "EUR"
},
]
}
}
How to set up Refund Status Notifications
When you are creating a refund (see Creating a Refund for a Payment) the following parameters influence the refund status notifications:
Parameter | Description |
---|---|
notifications_url string |
You receive notifications about the refund status via callbacks (see Refund Status Notifications) via the notifications URL.
|
external_reference string |
The external reference. The external reference is used to match a notification to a particular refund. You can use any kind of identifier or reference from your own system you might need to identify the refunds. Since this parameter will be included in the status notifications about this refund, it will help you to answer the question "For which refund did I get this notification?" Max size of 50 characters. See Refund Status Notifications for more details. |
Validating Refund Status Notifications
Validating notifications is optional, as it’s on your server side, but for security reasons it is recommended to validate all notifications.
How to validate a notification
To validate a notification, check its X-Flywire-Digest header. This value is generated by Flywire using your Shared Secret to encrypt the notification body. To verify the notification, generate the digest using the same method and compare it to the X-Flywire-Digest value in the header. If they match, the notification is legitimate and hasn't been tampered with.
-
Retrieve the raw HTTP body of the notification you received.
Make sure you use the raw HTTP body of the notification. You must generate the X-Flywire-Digest value using the exact payload you received in the notification. If you change the body in any way the values won't match later.
-
Encrypt the received notification twice:
1) Encrypt the raw HTTP body of the received notification with your Shared Secret using the SHA-256 algorithm.
2) Take the result and encrypt it in Base64.
The examples show you how to do this in different programming languages. In each example, exchange the shared_key with your Shared Secret and message_body with the raw HTTP body of the notification.
What is my Shared Secret?
The Shared Secret is a string of characters used for security validations.
For API integration:
Your Shared Secret is used to validate notifications. You receive your Shared Secret together with your API credentials via a secure email after you registered your application.
For other integrations:
Your Shared Secret is used to validate notifications and authenticate requests. You receive your Shared Secret from the Flywire Solutions team after your portal has been set up (please contact the Solutions team in case you don't have your Shared Secret). Note that each portal might have a different shared secret. If you have access to multiple portals, make sure you use the correct shared secret for each portal.
- Ruby
- .NET
- JavaScript
digest = OpenSSL::Digest.new('sha256') encrypted_payload = OpenSSL::HMAC.digest(digest, shared_secret, notification_body) Base64.encode64(encrypted_payload).strip # Step 1: Define the hashing algorithm to use for the HMAC. # This initializes the SHA-256 hashing mechanism. hash_algorithm = OpenSSL::Digest.new('sha256') # Step 2: Compute the HMAC in binary format. # This uses the shared secret and the message body to produce the HMAC signature. hmac_binary = OpenSSL::HMAC.digest(hash_algorithm, shared_secret, message_body) # Step 3: Encode the HMAC in Base64 for use in the X-Flywire-Digest header. x_flywire_digest = Base64.encode64(hmac_binary).strip
public static string Digest(string shared_secret, string message_body) { // Step 1: Initialize the HMACSHA256 object with the shared secret. // This sets up the hashing algorithm (SHA-256) and the secret key for HMAC. using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(shared_secret))) { // Step 2: Convert the message body into a byte array. // The message body is the message payload you want to hash var bytes = Encoding.UTF8.GetBytes(message_body); // Step 3: Compute the HMAC hash of the message body. // This generates the HMAC using the shared secret and the message body. var hashedBytes = hmacsha256.ComputeHash(bytes); // Step 4: Convert the hashed byte array into a Base64 string. return Convert.ToBase64String(hashedBytes); } }
const crypto = require('crypto'); function createDigest(shared_secret, message_body) { // Step 1: Initialize the HMAC with the SHA-256 algorithm and the shared secret. const hmac = crypto.createHmac('sha256', shared_secret); // Step 2: Update the HMAC with the message body. // The message body is the message payload you want to hash hmac.update(message_body); // Step 3: Get the HMAC digest and encode it in Base64. const digestHeader = hmac.digest('base64'); return digestHeader; // The `digestHeader` is the X-Flywire-Digest header. }
-
Compare your Base64 string to the value in the X-Flywire-Digest parameter of the notification you received.
If the values match, the notification came from Flywire and hasn't been changed by a third party.
If the values don't match, you shouldn't trust the notification.