Disbursements

List of endpoints

Description Endpoint

Getting a List of all Disbursements

GET/payments/v1/disbursements

Getting Details about a Disbursement

GET/payments/v1/disbursements/{disbursementId}

Getting the Reconciliation Files for a Disbursement

GET/payments/v1/disbursements/{disbursementId}/files

Getting a List of all Refunds within a Disbursement

GET/payments/v1/disbursements/{disbursementId}/refunds

Getting a List of all Payouts within a Disbursement

GET/payments/v1/disbursements/{disbursementId}/payouts

Getting a List of all Adjustments within a Disbursement

GET/payments/v1/disbursements/{disbursementId}/adjustments

About Disbursements

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

Requirements for using the Disbursements Resource

You need permission to use the /disbursements endpoints. Please contact the Solutions team if you want to use them.

Disbursement calculation formula

The total disbursement amount represents the final financial settlement delivered to you for a given processing period.

The total amount of the disbursement is calculated as follows:

Total Disbursement Amount = Payouts + Credited Adjustments − Refunds − Debited Adjustments

Formula components

  • Payouts: the total of all payout amounts bundled into the disbursement.

  • Credited adjustments: financial adjustments that increase the overall disbursement amount (where entry_type is credit).

  • Debited adjustments: financial adjustments that reduce the overall disbursement amount (where entry_type is debit).

  • Refunds: refund amounts deducted from the overall disbursement amount.

Formula components and API mapping

While the root /disbursements endpoint provides high-level summary counts, you can retrieve the itemized line items for a specific disbursement using the following endpoints:

Getting a List of all Disbursements

This endpoint returns a paginated list of all delivered disbursements.

The information returned in this list provides an overview of your delivered disbursements. It allows you to view disbursement totals, track fund delivery dates, inspect the composition of each disbursement (including payment, refund, and adjustment counts), and isolate specific disbursement cycles using date-range filters to match Flywire's deposits against your bank ledger.

Due to security scoping, this endpoint only returns records associated with recipients that your API key has access to.

Request

Parameters for the Request Body

No request body needed.

Optional Query Parameters for Filtering

You can filter the list of results by the following parameters:

You can filter the list by one or more (max. 10) specific recipients to only get results for those recipients back. If you provide more than one value, divide them by commas (",").

You need to use the recipient ID of the recipient as a value.

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

If you omit this parameter, results are returned for all recipients you are authorized to access.

If you specify a recipient ID that you are not authorized to access, or more than 10 IDs, the request fails with a validation error.

This parameter filters results to a single specific date, used as both the start and end of the date range. It is a shorthand alternative to specifying delivered_from and delivered_to with the same value.

Constraints

You cannot use this parameter together with delivered_from or delivered_to, doing so returns a validation error.

Recommended format

Express the date using the format YYYY-MM-DD.

This parameter specifies the start of the date range within which you want to search. You may optionally also provide the end of the date range using the parameter delivered_to. If you omit it, the end date defaults to the current date.

This filter returns all results from the specified start date to the end date, inclusive. This means that results occurring on both the start date and the end date, as well as any dates in between, are included in the filtered results.

Constraints

You cannot use this parameter together with delivered_at, doing so returns a validation error.

Recommended format

Express the date using the format YYYY-MM-DD.

This parameter specifies the end of the date range within which you want to search. You may optionally also provide the start of the date range using the parameter delivered_from. If you omit it, the API returns all historical records up to this specified end date, effectively applying no lower limit.

This filter returns all results from the specified start date to the end date, inclusive. This means that results occurring on both the start date and the end date, as well as any dates in between, are included in the filtered results.

Constraints

You cannot use this parameter together with delivered_at, doing so returns a validation error.

Recommended format

Express the date using the format YYYY-MM-DD.

Optional Query Parameters for Pagination

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

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

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

Possible values: min 1, max 100

GET/payments/v1/disbursements 

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

Response

Pagination Parameters

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

The total number of pages available.

The current page of the results.

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

disbursements array

Only payments that are in status delivered have a disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

The ID of the recipient that received the disbursement.

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

The status of this disbursement.

Possible values:

  • delivered

The date and time at which the disbursement was delivered to the recipient.

Timestamps use ISO 8601 format with UTC (YYYY-MM-DDTHH:MM:SSZ, e.g., 2025-03-31T13:21:27Z).

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

    Example: 2024-09-20T14:30:00Z = 2:30 PM in UTC.

  • +hh:mm or -hh:mm → Offset from UTC.

    Example: 2024-09-20T14:30:00+02:00 = 2:30 PM in a time zone 2 hours ahead of UTC (e.g., Central European Summer Time).

The total number of unique, originating payments represented by the payouts in this disbursement.

This summary counter allows you to verify the total number of originating payments without needing to fetch the detailed payouts list.

The total number of refunds deducted from this disbursement.

This summary counter allows you to quickly check if any refunds occurred without fetching the full list

You can retrieve an itemized breakdown of the refunds within a disbursement using the endpoint, Getting a List of all Refunds within a Disbursement.

A disbursement only contains refunds if you are using netting as a refund method

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

The total number of adjustments (both debits and credits) applied directly to this disbursement.

This summary counter allows you to quickly check if any adjustments occurred without fetching the full list.

You can retrieve an itemized breakdown of these adjustments within a disbursement using the endpoint, Getting a List of all Adjustments within a Disbursement.

The net monetary total of the disbursement, representing the combined value of all payouts minus refunds and adjustments.

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 payout currency of the disbursement in ISO 4217 format.

The payout currency is the currency you receive from Flywire in a disbursement. In most cases, this is the same currency as your billing currency, but in some edge cases this might be a different currency depending on the settings for the recipient.

A masked string representing the destination bank account where Flywire deposited the disbursement.

This field exposes the last 4 digits of the bank account number.

{
  "total_entries": 2,
  "total_pages": 1,
  "page": 1,
  "per_page": 10,
  "disbursements": [
    {
      "disbursement_id": "FWU2026-07-13",
      "recipient_id": "FWU",
      "status": "delivered",
      "delivered_at": "2026-07-13T17:11:39Z",
      "number_of_payments": 82,
      "number_of_refunds": 0,
      "number_of_adjustments": 0,
      "amount": 6000000,
      "currency": "EUR",
      "bank_account_number": "XXX5677"
    },
    {
      "disbursement_id": "FWU2026-06-13",
      "recipient_id": "FWU",
      "status": "delivered",
      "delivered_at": "2026-06-13T17:22:22Z",
      "number_of_payments": 37,
      "number_of_refunds": 0,
      "number_of_adjustments": 0,
      "amount": 1000000,
      "currency": "USD",
      "bank_account_number": "XXX5677"
    }
  ]
}

Getting Details about a Disbursement

This endpoint returns the details of a specific disbursement.

The information returned provides an overview of a delivered disbursement. It allows you to view the disbursement's total amount, track its exact fund delivery date, and inspect its composition (including payment, refund, and adjustment counts) to match a specific Flywire deposit against your bank ledger.

Due to security scoping, this endpoint only returns records associated with recipients that your API key has access to.

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {disbursementId} in the endpoint with the disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

You have various options to look up the disbursement ID.

Flywire API > Disbursements resource:

  • Call the endpoint Getting a List of all Disbursements to retrieve a list of all your disbursements.

  • Each object in the response represents an individual disbursement, with the disbursement's unique identifier being represented in the disbursement_id field.

Flywire API > Payments resource:

  • Call the endpoint Getting Details about a Payment.

  • Once a payment has progressed to the top-level status of delivered, this endpoint returns details of the payouts associated with the payment. The unique identifier of the disbursement to which the payout belongs is returned within the payouts.disbursement_id parameter.

Callbacks:

  • The Delivered payment callback returns the disbursement ID for payments that have progressed to a top-level status of delivered. Refer to Payment Status Notifications.

GET/payments/v1/disbursements/{disbursementId} 

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

Response

  • image 200 OK
  • image 404 Error

Only payments that are in status delivered have a disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

The ID of the recipient that received the disbursement.

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

The status of this disbursement.

Possible values:

  • delivered

The date and time at which the disbursement was delivered to the recipient.

Timestamps use ISO 8601 format with UTC (YYYY-MM-DDTHH:MM:SSZ, e.g., 2025-03-31T13:21:27Z).

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

    Example: 2024-09-20T14:30:00Z = 2:30 PM in UTC.

  • +hh:mm or -hh:mm → Offset from UTC.

    Example: 2024-09-20T14:30:00+02:00 = 2:30 PM in a time zone 2 hours ahead of UTC (e.g., Central European Summer Time).

The total number of unique, originating payments represented by the payouts in this disbursement.

This summary counter allows you to verify the total number of originating payments without needing to fetch the detailed payouts list.

The total number of refunds deducted from this disbursement.

This summary counter allows you to quickly check if any refunds occurred without fetching the full list

You can retrieve an itemized breakdown of the refunds within a disbursement using the endpoint, Getting a List of all Refunds within a Disbursement.

A disbursement only contains refunds if you are using netting as a refund method

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

The total number of adjustments (both debits and credits) applied directly to this disbursement.

This summary counter allows you to quickly check if any adjustments occurred without fetching the full list.

You can retrieve an itemized breakdown of these adjustments within a disbursement using the endpoint, Getting a List of all Adjustments within a Disbursement.

The net monetary total of the disbursement, representing the combined value of all payouts minus refunds and adjustments.

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 payout currency of the disbursement in ISO 4217 format.

The payout currency is the currency you receive from Flywire in a disbursement. In most cases, this is the same currency as your billing currency, but in some edge cases this might be a different currency depending on the settings for the recipient.

A masked string representing the destination bank account where Flywire deposited the disbursement.

This field exposes the last 4 digits of the bank account number.

{
    "disbursement_id": "FWU2026-06-13",
    "recipient_id": "FWU",
    "status": "delivered",
    "delivered_at": "2026-06-13T17:22:22Z",
    "number_of_payments": 37,
    "number_of_refunds": 0,
    "number_of_adjustments": 0,
    "amount": 1000000,
    "currency": "USD",
    "bank_account_number": "XXX5677"
}

404 Error - resource not found

When does this happen?

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.

In this case, an invalid disbursementId was provided in the path.

What should you do?

Verify that the URI is correct and the resource exists.

{
  "type": "https://developers.flywire.com",
  "title": "Not Found",
  "status": "404",
  "detail": "Invalid Disbursement ID. The disbursement ID provided does not exist in our records. Please verify the ID and try again."
}

Getting the Reconciliation Files for a Disbursement

Retrieves a list of pre-signed download URLs for the settlement files associated with a specific disbursement.

Due to security scoping, this endpoint only returns records associated with recipients that your API key has access to.

Available files depend on configuration

The types of files and the content within each file depend on the recipient (also called portal) configuration.

Download links are temporary

The download links returned in the response are temporary pre-signed URLs.

They expire automatically after the duration specified in the URL's X-Amz-Expires query parameter.

Do not store these URLs long-term; request fresh links as needed.

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {disbursementId} in the endpoint with the disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

You have various options to look up the disbursement ID.

Flywire API > Disbursements resource:

  • Call the endpoint Getting a List of all Disbursements to retrieve a list of all your disbursements.

  • Each object in the response represents an individual disbursement, with the disbursement's unique identifier being represented in the disbursement_id field.

Flywire API > Payments resource:

  • Call the endpoint Getting Details about a Payment.

  • Once a payment has progressed to the top-level status of delivered, this endpoint returns details of the payouts associated with the payment. The unique identifier of the disbursement to which the payout belongs is returned within the payouts.disbursement_id parameter.

Callbacks:

  • The Delivered payment callback returns the disbursement ID for payments that have progressed to a top-level status of delivered. Refer to Payment Status Notifications.

GET/payments/v1/disbursements/{disbursementId}/files 

curl https://base-url-placeholder/disbursements/FWU2026-06-13/files
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

  • image 200 OK
  • image 404 Error

Returns an array of objects, with each object representing a settlement file within this disbursement. Each object contains a direct, pre-signed AWS S3 download link, along with the settlement file's name and type.

Supported file extensions include .csv, .txt, and .dat.

The file name and extension of the file.

Supported file extensions include .csv, .txt, and .dat.

A temporary, pre-signed URL used to download the file.

This URL expires after the period specified in the X-Amz-Expires query parameter and should not be stored long-term.

[
    {
        "name": "FWU2026-06-13.txt",
        "url": "https://s3.amazonaws.com/example-bucket/sample_recipient/FWU2026-06-13.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLEKEY%2F20260722%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260722T100400Z&X-Amz-Expires=30000&X-Amz-SignedHeaders=host&X-Amz-Signature=EXAMPLE_SIGNATURE_HASH"
    }
]

404 Error - resource not found

When does this happen?

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.

In this case, an invalid disbursementId was provided in the path.

What should you do?

Verify that the URI is correct and the resource exists.

{
  "type": "https://developers.flywire.com",
  "title": "Not Found",
  "status": "404",
  "detail": "Invalid Disbursement ID. The disbursement ID provided does not exist in our records. Please verify the ID and try again."
}

Getting a List of all Refunds within a Disbursement

This endpoint returns a paginated list of all individual refunds deducted from this specific disbursement.

The information in this array provides an itemized breakdown of the refunds processed within the a disbursement. It allows you to view individual refund amounts and currencies, as well as identify the originating payment IDs connected to each refund for end-to-end tracking and reconciliation.

Due to security scoping, this endpoint only returns records associated with recipients that your API key has access to.

A disbursement only contains refunds if you are using netting as a refund method

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {disbursementId} in the endpoint with the disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

You have various options to look up the disbursement ID.

Flywire API > Disbursements resource:

  • Call the endpoint Getting a List of all Disbursements to retrieve a list of all your disbursements.

  • Each object in the response represents an individual disbursement, with the disbursement's unique identifier being represented in the disbursement_id field.

Flywire API > Payments resource:

  • Call the endpoint Getting Details about a Payment.

  • Once a payment has progressed to the top-level status of delivered, this endpoint returns details of the payouts associated with the payment. The unique identifier of the disbursement to which the payout belongs is returned within the payouts.disbursement_id parameter.

Callbacks:

  • The Delivered payment callback returns the disbursement ID for payments that have progressed to a top-level status of delivered. Refer to Payment Status Notifications.

Optional Query Parameters for Pagination

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

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

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

Possible values: min 1, max 100

GET/payments/v1/disbursements/{disbursementId}/refunds 

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

Response

  • image 200 OK
  • image 404 Error

Pagination Parameters

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

The total number of pages available.

The current page of the results.

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

refunds array

An array of objects containing information about the individual refunds within the disbursement.

The refund ID.

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

Format:

Either:RABC1AB23CD4

R 3-letter portal/recipient ID 8 hexadecimals

Or: R1ABC1D1AB23CD4

R number 5-alphanum portal/recipient ID 8 hexadecimals

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

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

  2. Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.

    The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.

    The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.

    You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.

  3. When the cut-off time for recipient A is reached, Flywire either processes the bundle or requires your approval first, based on the recipient's settings.

    All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:

    Type of approval approval_type (setting for the recipient)

    Manual approval

    Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).

    		 manual

    Automatic approval

    Flywire processes refund bundles automatically after the cut-off time.

    		 automatic

     

     

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

     

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

  4. Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.

Refund Bundle Essentials: What You Should Know

  • A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.

  • Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.

  • A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

payment object

Object containing information about the original payment for which the refund was created.

The payment reference.

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

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 payout currency. This is the amount Flywire will take from the recipient to refund it back to the payer.

The payout currency is the currency you receive from Flywire in a disbursement. In most cases, this is the same currency as your billing currency, but in some edge cases this might be a different currency depending on the settings for the recipient.

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. This corresponds to the recipient's payout currency.

The payout currency is the currency you receive from Flywire in a disbursement. In most cases, this is the same currency as your billing currency, but in some edge cases this might be a different currency depending on the settings for the recipient.

Format:

Three-letter ISO 4217 currency code, for example EUR. 

{
  "total_entries": 2,
  "total_pages": 1,
  "page": 1,
  "per_page": 10,
  "refunds": [
    {
        "refund_id": "RFWU1CB69313",
        "payment": {
            "id": "FWU787203662",
            "external_reference": "67893"
        },
        "amount": 654334,
        "currency": "GBP"
    },
    {
        "refund_id": "RFWU03D114FE",
        "payment": {
            "id": "FWU718097777",
            "external_reference": null
        },
        "amount": 50000,
        "currency": "GBP"
    }
  ]
}

404 Error - resource not found

When does this happen?

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.

In this case, an invalid disbursementId was provided in the path.

What should you do?

Verify that the URI is correct and the resource exists.

{
  "type": "https://developers.flywire.com",
  "title": "Not Found",
  "status": "404",
  "detail": "Invalid Disbursement ID. The disbursement ID provided does not exist in our records. Please verify the ID and try again."
}

Getting a List of all Payouts within a Disbursement

This endpoint returns a paginated list of all individual payouts bundled inside this specific disbursement.

The information in this array provides a breakdown of how a disbursement's total amount is distributed across multiple payouts. It allows you to view the individual payout amounts and identify the originating payment IDs connected to each payout for end-to-end tracking.

Due to security scoping, the array only displays the payout objects for recipients that your API key has access to.

A payout represents the final movement of collected funds to a specific destination. While a payment captures the inbound collection of money from a payer, a payout tracks the outbound distribution of those funds.

Individual payouts are ultimately bundled together into a container called a disbursement, which represents the actual funds transfer sent from Flywire to your bank.

When multiple payout objects share the same payment_id, it indicates a split payout scenario.

A split payout occurs when a single initial payment has been distributed to multiple recipients (e.g., splitting a single transaction to separate the core service cost from auxiliary fees).

Each object within the array represents an individual payout, and specifies:

  • The originating ID (payment_id) of the payment that spawned this payout.

  • The target recipient (recipient_id) that will receive the funds.

  • The final amount and currency (amount, currency) delivered to that recipient.

  • Tracking metrics, including the unique payout reference, and the current status of the payout.

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {disbursementId} in the endpoint with the disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

You have various options to look up the disbursement ID.

Flywire API > Disbursements resource:

  • Call the endpoint Getting a List of all Disbursements to retrieve a list of all your disbursements.

  • Each object in the response represents an individual disbursement, with the disbursement's unique identifier being represented in the disbursement_id field.

Flywire API > Payments resource:

  • Call the endpoint Getting Details about a Payment.

  • Once a payment has progressed to the top-level status of delivered, this endpoint returns details of the payouts associated with the payment. The unique identifier of the disbursement to which the payout belongs is returned within the payouts.disbursement_id parameter.

Callbacks:

  • The Delivered payment callback returns the disbursement ID for payments that have progressed to a top-level status of delivered. Refer to Payment Status Notifications.

Optional Query Parameters for Pagination

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

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

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

Possible values: min 1, max 100

GET/payments/v1/disbursements/{disbursementId}/payouts 

curl https://base-url-placeholder/disbursements/FWU2025-12-31/payouts
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

  • image 200 OK
  • image 404 Error

Pagination Parameters

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

The total number of pages available.

The current page of the results.

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

payouts array

Contains an array of objects representing individual payouts.

This array contains granular tracking details for each individual payout, including unique payout references, the unique reference of the payment that the payout is connected to, and payout-specific status values.

The ID of the recipient that receives the payout.

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

The ID that identifies the payout.

Format:

Either: PABC123456789

P 3-letter portal/recipient ID 9 numbers

Or: P1ABC1D12AB5C78

P number 5-alphanum portal/recipient ID 8 alphanums

The status of this specific payout.

This field reflects the status of the individual payout, rather than the status of the parent disbursement that the payout belongs to.

Possible values:

  • delivered: the funds have been successfully delivered to you (as part of a disbursement) but Flywire has not yet sent a delivery notification.

  • notified: Flywire has sent you a notification that delivery has been completed. This is the payout's final status, with no further status transitions possible.

The unique identifier of the originating inbound payment from which this payout was allocated.

Use this ID to cross-reference payout details against the primary payments resource.

The payment reference.

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

The value of this specific payout allocation, expressed in subunits of the payouts.currency.

The amount is specified in the smallest unit of the currency, called subunits. For example, in USD, the subunit is cents, and 100 cents equal 1 USD. So, an amount of 12025 (cents) is equivalent to 120.25 USD.

Note that the subunit-to-unit ratio varies by currency, it is not always 100. See Currencies for the subunits of each currency.

The payout currency in ISO 4217 format.

The payout currency is the currency you receive from Flywire in a disbursement. In most cases, this is the same currency as your billing currency, but in some edge cases this might be a different currency depending on the settings for the recipient.

{
  "total_entries": 2,
  "total_pages": 1,
  "page": 1,
  "per_page": 10,
  "payouts": [
    {
      "recipient_id": "FWU",
      "reference": "PFWU744586810",
      "status": "notified",
      "payment_id": "FWU744586810",
      "currency": "GBP",
      "amount": 20000
    },
    {
      "recipient_id": "FWU",
      "reference": "PFWU744586922",
      "status": "notified",
      "payment_id": "FWU744586712",
      "currency": "GBP",
      "amount": 37000
    }
  ]
}

404 Error - resource not found

When does this happen?

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.

In this case, an invalid disbursementId was provided in the path.

What should you do?

Verify that the URI is correct and the resource exists.

{
  "type": "https://developers.flywire.com",
  "title": "Not Found",
  "status": "404",
  "detail": "Invalid Disbursement ID. The disbursement ID provided does not exist in our records. Please verify the ID and try again."
}

Getting a List of all Adjustments within a Disbursement

This endpoint returns a paginated list of all individual adjustments applied to a specific disbursement.

You typically only need to call this endpoint if the parent disbursement indicates that adjustments exist (number_of_adjustments > 0).

The response provides an itemized breakdown of each adjustment's amount, category, entry type (credited or debited), and originating entity reference for end-to-end reconciliation.

Due to security scoping, this endpoint only returns records associated with recipients that your API key has access to.

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {disbursementId} in the endpoint with the disbursement ID.

The disbursement ID identifies a disbursement.

Format: 

Either: ABC2025-12-17

3-letter portal/recipient ID disbursement date YYYY-MM-DD

Or: ABC1D2025-12-17

5-alphanum portal/recipient ID disbursement date YYYY-MM-DD

A disbursement is a consolidated financial settlement transferred from Flywire to your bank account. These transfers occur on a regular schedule.

Rather than transferring individual transactions separately, a disbursement acts as a single container that bundles together payouts, along with any applicable refunds or balance modifications, into one total settlement amount.

Note if you are using refunds:

Disbursements can also contain refunds if you are using the refund collection method netting.

Netting refers to a method used to simplify transactions. By offsetting the value of multiple payments between you and Flywire into a single net amount, it reduces the number of individual transactions.

Simplified example: You have to pay Flywire $200 because you have to refund money to your payers. At the same time, Flywire has to pay you $500 because you have new payments incoming. Instead of exchanging $200 and $500 separately, netting combines these amounts and you'll receive only $300 from Flywire while Flywire takes no money from you.

Essentials about using netting as a refund collection method

  • Refunds will only be processed when Flywire has received enough funds from new payments to offset them against the pending refunds.

  • This means if the original recipient doesn't have a constant stream of new incoming payments, it can take a while before refunds are processed.

  • This refund collection method is not available by default, you need to set it up together with Flywire. Please contact the Solutions team if you want to use this method.

You have various options to look up the disbursement ID.

Flywire API > Disbursements resource:

  • Call the endpoint Getting a List of all Disbursements to retrieve a list of all your disbursements.

  • Each object in the response represents an individual disbursement, with the disbursement's unique identifier being represented in the disbursement_id field.

Flywire API > Payments resource:

  • Call the endpoint Getting Details about a Payment.

  • Once a payment has progressed to the top-level status of delivered, this endpoint returns details of the payouts associated with the payment. The unique identifier of the disbursement to which the payout belongs is returned within the payouts.disbursement_id parameter.

Callbacks:

  • The Delivered payment callback returns the disbursement ID for payments that have progressed to a top-level status of delivered. Refer to Payment Status Notifications.

Optional Query Parameters for Pagination

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

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

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

Possible values: min 1, max 100

GET/payments/v1/disbursements/{disbursementId}/adjustments 

curl https://base-url-placeholder/disbursements/FWU2025-12-31/adjustments
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

  • image 200 OK
  • image 404 Error

Pagination Parameters

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

The total number of pages available.

The current page of the results.

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

adjustments array

Contains an array of objects representing individual adjustments applied to the disbursement.

Unique reference identifier for the adjustment.

Format:

ADJ260612052533CMGDE

ADJ 12-digit timestamp 5 alphanumeric characters

The timestamp component of the identifier uses the pattern YY-MM-DD-HH-MM-SS.

The classification category for the adjustment.

Examples include surcharge and service.

New categories may be introduced in the future to support additional adjustment types. Integrations should be designed to handle unknown category values gracefully.

The adjustment amount.

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 code for the adjustment amount.

Format:

Three-letter ISO 4217 currency code, for example EUR.

Indicates whether the adjustment amount was credited to or debited from the overall disbursement.

The type of Flywire record linked to this adjustment (for example, payment or refund). This value indicates which API resource you should query for additional details.

Conditionally populated depending on the adjustment.category. Can return null.

The unique Flywire identifier for the record specified in the entity field.

Use this ID to query the corresponding API resource for additional details.

Conditionally populated depending on the adjustment.category. Can return null.

{
  "total_entries": 1,
  "total_pages": 1,
  "page": 1,
  "per_page": 10,
  "adjustments": [
    {
      "reference": "ADJ260612052533CMGDE",
      "category": "surcharge",
      "amount": 60000,
      "currency": "USD",
      "entry_type": "credit",
      "entity": "payment",
      "entity_reference": "FWU928923284"
    }
  ]
}

404 Error - resource not found

When does this happen?

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.

In this case, an invalid disbursementId was provided in the path.

What should you do?

Verify that the URI is correct and the resource exists.

{
  "type": "https://developers.flywire.com",
  "title": "Not Found",
  "status": "404",
  "detail": "Invalid Disbursement ID. The disbursement ID provided does not exist in our records. Please verify the ID and try again."
}