Payments

List of endpoints

Description	Endpoint
Creating a Payment within a Self-Managed Recurring Plan	POST/payments/charge
Capturing the Funds for a Pre-Authorization Payment	POST/payments/{paymentID}/captures
Adjusting the Amount for a Pre-Authorization Payment	POST/payments/{paymentID}/authorization_adjustments
Marking a Payment as processed	POST/payments/{paymentID}/process
Cancelling a Payment	POST/payments/{paymentID}/cancel
Getting a List of all Payments	GET/payments
Getting Details about a Payment	GET/payments/{paymentID}
Creating a Refund for a Payment	POST/payments/{paymentID}/refunds

What is a Payment?

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:

A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.
What is the payment reference?
The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

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

The payment reference is also important in other situations, for example:
- When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.
- The payment reference helps Flywire to identify the payment if you or your payer needs support.
When the payment reference is assigned, two things happen:
- The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).
- The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

Creating a Payment within a Self-Managed Recurring Plan

Request

This endpoint is only for creating follow-up payments of a self-managed plan (see Use Case: Self-Managed Recurring Payments).

Why?

This endpoint creates a recurring payment within a self-managed plan. This is a manual step since Flywire doesn't know your payment schedule, meaning you have to ensure that recurring payments are created on time. If you want recurring payments to get created automatically, you can use Flywire-Managed Plans.

What do I need to use this endpoint?

You need a payment method token and mandate ID to create the payment:

The payment method token lets you create the payment with known payer and payment information.

The payer and payment information has been gathered via a UI form and stored in the payment_method object. This information is used for the future payments. The payer information is passed via the payment_method_token when you charge a payment.

Where do I find the payment method token?

The payment method token is returned to you in the response after you confirmed a Checkout Session.

You can also find all payment method tokens for a payer (identified by their payor_id) with this request:

GET/payors/{payorId}/payment_methods

For details see Getting a List of all stored Payment Methods for a Payer.
It is mandatory to include the mandate ID when charging the payment.

Why is it mandatory?

For some card payments, this is mandatory to be compliant with policies. For example the mandate ID serves as the "Visa Transaction ID", which is mandatory since October 31st, 2022 (not providing the Visa Transaction ID could result in soft declines and fees for non-compliance). Other payment processors may require a similar ID for consent verification in the future.

Flywire generates mandate IDs for both cards and bank accounts to ensure future readiness.

Where do I find the mandate ID?

You can find all mandate IDs for a payment method token with this request:

GET/payors/{payorId}/payment_methods/{token}

For details see Getting the Mandate IDs for a Payment Method Token.

Important information for payments within a self-managed plan

Mandatory emails

Self-managed recurring payments require you to send mandatory emails to your payer. For details refer to Recurring Payments: Emails to Your Payer.

Charging direct debit payments

For direct debit payments (SEPA and BACS), the payer must be informed about the upcoming charge. To ensure this, charging a direct debit payment will trigger an email to inform the payer, and the actual charge will automatically be delayed for 3 business days.

The email is sent by Flywire (for SEPA) or Finastra (for BACS), see List of Emails for Recurring Payments for Cards and Direct Debit.
After charging a direct debit payment it can take up to 10 business days before the funds appear in your bank account (3 days of charge delay plus up to 7 days of collecting and processing the charge).

Parameters for the Request Body

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

mandate_id string

Provide the mandate ID for this payment.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

More info about the mandate PDF

The mandate PDF is the mandate fully written out "on paper" (but paperless as a PDF). The PDF will be delivered to your payer by email.

There are different types of PDFs depending on the direct debit scheme for the payments:

SEPA mandate

The SEPA mandate is a PDF with the written out SEPA contract. A SEPA mandate has a specific format and strictly defined content. It is part of the SEPA payment system, and you cannot charge a bank account without having a SEPA mandate.

The file name for the PDF with the SEPA mandate contains the date the SEPA mandate was created and the mandate ID that was generated by Flywire.

BACS mandate

The BACS mandate is a PDF with the written out contract including the Direct Debit Guarantee for BACS. A BACS mandate has a specific format and strictly defined content. It is part of the BACS payment system, and you cannot charge a bank account without having a BACS mandate.

payment_method_token string

Provide the payment method token for this payment.

recipient object

fields array

It depends on the recipient which fields are optional or required. If a field is required, you must provide it here. Optional fields can be left out.

items array

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

POST/payments/charge

curl https://base-url-placeholder/payments/charge
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
    "charge_intent": {
        "mode": "subscription"
    },
    "mandate_id": "MCHUV20220526UAUTYQ8W",
    "payment_method_token": "e1278a8863eaef9b7a7c",
    "payor_id": "payor_CCC",
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 5000,
        }
    ],
    "metadata": {
       "Internal-ID": "12345",
       "Int-Comment": "A comment about this payment"
    },
    "notifications_url": "http://a-callback-url.com/callback",
    "external_reference": "a-reference"
}

Response

There are three possible outcomes:

The payment was created and successfully charged.

The payment was created but the charging was not successful.

There was an error and the payment was not created.

Payment created and charged
Charge failed
404 Error
422 Error
500 Error

If you provided a notifications URL for the payment, you’ll start receiving notifications that let you track the payment’s progress (refer to Payment Status Notifications).

payment_reference string

The payment reference.

charge_info object

charge_result object

status string

The status of the attempted charge. Note that this charge status doesn't mean that funds have successfully been transferred. It gives you information about the communication between Flywire and the external system (for example, the bank or card provider):

Possible values:

success

The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

failed

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

unknown

The communication with the external system was not successful. Flywire can't determine if the charge process finished correctly.

If this happens, check the payment callbacks (see Payment Status Notifications). If you have received a processed or guaranteed status, the payment has been charged successfully and no further action is required.

If after ten minutes you only received the initiated status callback, cancel the payment and create a new payment. Don't try to charge the original payment again while it is still in initiated, you might end up with a duplicated charge.

{
    "payment_reference": "TQQ921794790",
    "charge_info": {
        "amount": 70000,
        "currency": "EUR"
    },
    "charge_result": {
        "status": "success"
    }
}

If the payment was successfully created but could not be charged, the response contains the payment_reference and information why the charging failed.

At the moment, it is not possible to try to charge the same payment again. You need to create a new payment to try a new charge.

When does charging fail?

A failed charge means that the third-party (for example card issuer or bank) refused the charge. This can happen for example when the card was rejected (expired card, insufficient funds etc.) or the bank account number is invalid.

payment_reference string

The payment reference.

charge_info object

charge_result object

status string

Possible values:

success

The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

failed

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

unknown

The communication with the external system was not successful. Flywire can't determine if the charge process finished correctly.

errors object

message string

The reason why the payment failed that you can share with your payers. You can display this reason to your payer to help them figuring out what went wrong and possibly solve the problem.

There are different reasons depending on what the issue is.

Examples for failed payment reasons returned by the API

Issue	Reason returned by the API
Configuration or connectivity issues	Your transaction has not been successful, please try again. If the error persists select a different payment method or contact our customer support team.
Issues related with bank or card details, like invalid data or refused by the bank	Your transaction has been declined by your bank. Please try inserting correct, valid card/bank account details to complete the payment or contact your bank to resolve the issue.
Not enough balance or over amount limit	Your transaction has been declined by your bank. Please try increasing the available balance of your account, use a different card/bank account or contact your bank for further assistance.

{
  "payment_reference": "UUI754118889",
  "charge_info": {
    "amount": 5000,
    "currency": "EUR"
  },
  "charge_result": {
    "status": "failed",
    "errors": [
      {
        "type": 006,
        "message": "Your transaction has been declined by your bank.
        Please try inserting correct, valid card/bank account 
        details to complete the payment or contact your bank 
        to resolve the issue."
      }
    ]
  }
}

Creating the Payment failed - Resource not found

The payment has not been created.

404 Error

When does this happen?

The payment method token (payment_method_token) or payer ID payor_id is not correct.

What should you do?

Check if you used the correct payment method token and payer ID.
Check if you used the same payor_id for charging the payment you used for creating the Checkout Session.

{
    "type": "https://developers.flywire.com",
    "title": "Not Found",
    "status": 404,
    "detail": "The provided payment_method_token 88b669e924fc46e41fe3 is not valid 
    or it's not associated to the provided payor_id i_23456789"
}

Creating the Payment failed - Missing or invalid parameter

The payment has not been created.

422 Error

When does this happen?

Your request was either missing a parameter or a parameter contained an invalid value.

What should you do?

The error response will tell you which parameter is affected. It could be the parameter itself or the value for the parameter.

If there's a missing parameter, check your request if you misspelled the parameter or left it out.
If there's an invalid value, check the validation rules for the value. You'll find descriptions of parameters and their allowed values for each request in this documentation.

{
    "type": "https://developers.flywire.com",
    "title": "Unprocessable entity",
    "status": 422,
    "detail": "Invalid parameters",
    "errors": [
        {
            "source": "/",
            "param": "payor_id",
            "type": "missing_param",
            "message": "is missing"
        }
    ]
}

Creating the Payment failed - Internal Server Error

The payment has not been created.

500 - Internal Server Error

Communication with the API failed.

When does this happen?

The server is unavailable or an unexpected condition was encountered. This can have various reasons, for example:

Authentication issues
API being unavailable
Server time out (the request took longer than 8 secs)
Network issues
Rate limits exceeded

What should you do?

Check the following and then try again:

Authentication
- Ensure that you are using the right API key and it is correctly implemented in the request.
Flywire API Status
- Check the status of the Flywire API: https://status.flywire.com
Rate Limits
- Ensure you haven't exceeded the rate limits, see Rate Limits.
Network Connectivity
- Confirm that your server has a stable internet connection, and no firewall or network issues blocking the connection to the API.

{
  "type": "https://developers.flywire.com",
  "status": "500",
  "title": "Internal Server Error"
}

Capturing the Funds for a Pre-Authorization Payment

Request

When you capture a Pre-Authorization Payment the card is being charged and Flywire starts processing the payment.

Mandatory emails

There are mandatory emails you need to send to your payer when charging Pre-Authorization Payments, for details see Pre-Authorization Payments: Emails to Your Payer.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

Parameters for the Request Body

You can capture the exact blocked amount or less, but not more.

POST/payments/{paymentID}/captures

curl https://base-url-placeholder/payments/UUI754118889/captures
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '
  
{
    "amount": 60000
}

Response

Successful capture
422 Error

payment_reference string

The payment reference.

charge_info object

charge_result object

status string

Possible values:

success

The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

failed

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

unknown

The communication with the external system was not successful. Flywire can't determine if the charge process finished correctly.

{
    "payment_reference": "TQQ921794790",
    "charge_info": {
        "amount": 70000,
        "currency": "EUR"
    },
    "charge_result": {
        "status": "success"
    }
}

Capturing the Pre-Authorization Payment failed - Amount higher than authorized

422 Error

When does this happen?

The amount you tried to capture was higher than the authorized amount.

What should you do?

If you want to capture a higher amount than authorized, you need to adjust the amount before capturing it.

{
	"type": "https://developers.flywire.com",
	"title": "Unprocessable entity",
	"status": 422,
	"detail": "Invalid parameters",
	"errors": null
				}

Adjusting the Amount for a Pre-Authorization Payment

Request

You can adjust the Pre-Authorization Payment amount during the holding period if you used the authorization type preauth when you created the payment.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

Parameters for the Request Body

You can change the amount to a higher amount, not to a lower amount.

POST/payments/{paymentID}/authorization_adjustments

curl https://base-url-placeholder/payments/UUI754118889/authorization_adjustments
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '
  
{
    "amount": 70000
}

Response

Successful adjustment
422 Error

payment_reference string

The payment reference.

charge_info object

charge_result object

status string

Possible values:

success

The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

failed

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

unknown

The communication with the external system was not successful. Flywire can't determine if the charge process finished correctly.

{
    "payment_reference": "TQQ921794790",
    "charge_info": {
        "amount": 70000,
        "currency": "EUR"
    },
    "charge_result": {
        "status": "success"
    }
}

Adjusting the Pre-Authorization Payment failed - Amount is lower than original amount

422 Error

When does this happen?

The amount you tried to adjust to was lower than the originally authorized amount.

What should you do?

If you want to capture a lower amount, you don't need to adjust the amount before capturing.

{
    "type": "https://developers.flywire.com",
    "title": "Unprocessable entity",
    "status": 422,
    "detail": "Invalid parameters",
    "errors": null
}

Marking a Payment as processed

Request

This endpoint is only relevant for 529 Payments.

Usually, Flywire takes care of the payment process and captures the funds for you. After capturing the funds, Flywire moves the status of a payment to processed. For 520 Payments, since you are capturing the funds yourself, you have to move the payment into processed yourself.

This is necessary because:

It ensures that the payment is following the correct payment workflow.
It notifies Flywire that you received the funds.
It notifies your payer that you received the funds (if you implemented a system that sends notifications about status changes to your payers).

After a payment is processed by you, you should notify your payer that their payment was processed to avoid duplicate payments.
It prevents that a payment expires (if payment is not processed it will expire after its due date).

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

Parameters for the Request Body

POST/payments/{paymentID}/process

curl https://base-url-placeholder/payments/FWU125675432/process
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
  "external_reference": "My reference for the payment"
  }

Response

A 204 response will let you know that the payment has been successfully processed.

If you provided a notifications URL, you'll also receive a notification about the status change of the payment.

204 NO CONTENT

Cancelling a Payment

Request

Cancelling a payment puts a payment into the cancelled status.

When you cancel a Pre-Authorization Payment the blocked amount immediately returns back to the cardholder's credit.

Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire.

The payment status cancelled means that the payment has been cancelled and will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.

See Payment Status Notifications for information about notifications for this status.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

Digest Header

Add X-Flywire-Digest as a header to your request.

Exchange {your_digest_header} with the digest header you generated, see Authentication (via Digest Header).

Parameters for the Request Body

No request body needed.

POST/payments/{paymentID}/cancel

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

Response

A 204 response will let you know that the payment has been successfully cancelled.

If you provided a notifications URL, you'll also receive a notification about the status change of the payment.

204 NO CONTENT

Getting a List of all Payments

Request

You can use this endpoint to display a list of all payments in a UI.

Which payments will be returned in the list?

The list will contain all payments that have been created by you as a client with your API credentials via the Flywire API .

Don't use the list of payments as a source of truth regarding the payment status. If you want to get immediate updates about a payment's status, use notifications (see Payment Status Notifications).

Example for displaying a list of payments

Each parameter can be used as a column (for example payment reference or status). You can decide which parameters you want to display to help you identify a payment before you get more detailed information about it (see Getting Details about a Payment). Check the response to see which parameters of the payments are returned in the list.

Parameters for the Request Body

No request body needed.

Optional Query Parameters for Filtering

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

status stringquery parameter

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

Possible values

A payment can have the following statuses and notifications:

Status

Notification

Description

Initiated

initiated

The payment status initiated is the status for all new payments in Flywire. No funds have been received by Flywire at the initiated stage.

Definition of a "payment" within the Flywire system

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:

A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.
What is the payment reference?
The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

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

The payment reference is also important in other situations, for example:
- When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.
- The payment reference helps Flywire to identify the payment if you or your payer needs support.
When the payment reference is assigned, two things happen:
- The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).
- The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

authorized

Only for Pre-Authorization Payments.

What is a Pre-Authorization Payment?

A Pre-Authorization Payment temporary reserves the payment amount on a debit or credit card. The purpose of a pre-authorization is to verify that the cardholder has sufficient credit available to cover a transaction and to temporarily set aside that amount until you capture the funds.

Pre-Authorization Payments are only available for same-currency payments, not for FX payments.

Example for a Pre-Authorization Payment:

A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.

Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.

During the Stay: The guest orders room service for $50.

Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.

The payment has been authorized and is now in the holding period.

Processed

processed

The payment status goes from initiated to processed when Flywire has the confirmation that the funds have been received or captured via one of these ways:

Bank transfer: funds have been received in a Flywire bank account.
Card payments: funds have been captured in payer’s card.
Direct debit: instructions to capture the funds are in progress and correct.

For 529 Payments, you have to put a payment into the processed status yourself.

After a payment is processed by you, you should notify your payer that their payment was processed to avoid duplicate payments.

Guaranteed

guaranteed

The status changes to guaranteed when funds are received by Flywire and all the necessary validations for that payment method and corridor are successful (since Flywire performs a security check on every payment once the funds have been received).

At this point, you are guaranteed that Flywire will send you the funds.

Delivered

delivered

The status changes from guaranteed to delivered when Flywire sent you the funds in your daily batch disbursement. Payments are updated to delivered at a set time each day.

The status delivered is the end stage, the status of a delivered payment can't change.

Failed

failed

The status failed can only occur for card or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure.

Cancelled

cancelled

The payment status cancelled means that the payment has been cancelled and will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.

Scenarios for cancelled payments

Who cancelled?	Scenario	cancellation_reason in the payment status notification
You	You cancelled a payment via the API. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. See Cancelling a Payment	cancelled_by_user
The payer	Payers can cancel a payment in two different ways: You can give your payers the option to cancel a payment themselves if you implement this function in your UI. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. Payers can contact Flywire and ask for a payment to be cancelled.	cancelled_by_user
Flywire	There can be different reasons why Flywire cancels a payment: Verification not passed The payment didn’t pass Flywire validations. If funds were captured, an automatic refund will be created and funds will be returned directly to the source of funds.	rejected
	Duplicate payment The payer created 2 payments by mistake, and Flywire closed one of them after identifying the duplicate issue.	duplicated
	You or the payer contacted Flywire to cancel the payment.	cancelled_by_user
Automatic cancellation - Payment expired	When a payment expires it will automatically be cancelled. Expiring means the payment reached the expiration date without Flywire receiving the funds. When does a payment expire? A payment expires automatically after a while if no funds are received by Flywire: Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire. Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful. For API integration: Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt. For other integrations: Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful. The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.	expired
Direct debit payment failed	When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled. Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead. When do direct debit payments fail? A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.	unpaid

Reversed

reversed

This status has different meaning depending on the context:

2. Reversed type "unpaid"

This reversed type is only relevant for direct debits payments.

The status occurs when you (the client) received the funds from Flywire but Flywire did not receive the funds from your payer's bank account.

From a technical side this means:

The payment went into the delivered status (which means you received the funds from Flywire).
Then the payment fails and remains unpaid (which means Flywire did not receive the funds).

What does it mean when a direct debit payment is unpaid?

A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
Then Flywire will start a recovery process and the payment status will change from delivered to reversed.

Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.

filter stringquery parameter

You can use this filter to search for values in any of the fields of a recipient.

To narrow down the list of results, you must use this filter in combination with at least one recipient filter. You can use more than one, but maximum ten recipients.

Do not use this filter in automated queries. This filter is intended to be used on demand, not as an automatic query to keep dashboards updated. If you're sending too many requests within a certain time you can be cut off from using the Flywire API, see Rate Limits.

status transition dates date query parameter

Possible filters:

created_at, created_from, created_to
guaranteed_at, guaranteed_from, guaranteed_to
delivered_at, delivered_from, delivered_to
cancelled_at, cancelled_from, cancelled_to

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

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

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

GET/payments

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

Response

Pagination Parameters

payments array

payment_id string

The payment reference.

expiration_date date

The time and date the payment will expire automatically if no funds were received.

For card payments:

For API integration:

Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt.

For other integrations:

Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.

For Pre-Authorization Payments:

The expiration date is not the holding period length of a Pre-Authorization Payment. For Pre-Authorization Payments, you can disregard this parameter.

When does a payment expire?

A payment expires automatically after a while if no funds are received by Flywire:

Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.
Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.
For API integration:

Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt.

For other integrations:

Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.

The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.

status string

The current status of the payment.

Possible statuses

A payment can have the following statuses and notifications:

Status

Notification

Description

Initiated

initiated

The payment status initiated is the status for all new payments in Flywire. No funds have been received by Flywire at the initiated stage.

Definition of a "payment" within the Flywire system

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:

A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.
What is the payment reference?
The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

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

The payment reference is also important in other situations, for example:
- When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.
- The payment reference helps Flywire to identify the payment if you or your payer needs support.
When the payment reference is assigned, two things happen:
- The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).
- The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

authorized

Only for Pre-Authorization Payments.

What is a Pre-Authorization Payment?

Pre-Authorization Payments are only available for same-currency payments, not for FX payments.

Example for a Pre-Authorization Payment:

A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.

Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.

During the Stay: The guest orders room service for $50.

Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.

The payment has been authorized and is now in the holding period.

Processed

processed

The payment status goes from initiated to processed when Flywire has the confirmation that the funds have been received or captured via one of these ways:

Bank transfer: funds have been received in a Flywire bank account.
Card payments: funds have been captured in payer’s card.
Direct debit: instructions to capture the funds are in progress and correct.

For 529 Payments, you have to put a payment into the processed status yourself.

After a payment is processed by you, you should notify your payer that their payment was processed to avoid duplicate payments.

Guaranteed

guaranteed

At this point, you are guaranteed that Flywire will send you the funds.

Delivered

delivered

The status changes from guaranteed to delivered when Flywire sent you the funds in your daily batch disbursement. Payments are updated to delivered at a set time each day.

The status delivered is the end stage, the status of a delivered payment can't change.

Failed

failed

The status failed can only occur for card or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure.

Cancelled

cancelled

The payment status cancelled means that the payment has been cancelled and will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.

Scenarios for cancelled payments

Who cancelled?	Scenario	cancellation_reason in the payment status notification
You	You cancelled a payment via the API. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. See Cancelling a Payment	cancelled_by_user
The payer	Payers can cancel a payment in two different ways: You can give your payers the option to cancel a payment themselves if you implement this function in your UI. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. Payers can contact Flywire and ask for a payment to be cancelled.	cancelled_by_user
Flywire	There can be different reasons why Flywire cancels a payment: Verification not passed The payment didn’t pass Flywire validations. If funds were captured, an automatic refund will be created and funds will be returned directly to the source of funds.	rejected
	Duplicate payment The payer created 2 payments by mistake, and Flywire closed one of them after identifying the duplicate issue.	duplicated
	You or the payer contacted Flywire to cancel the payment.	cancelled_by_user
Automatic cancellation - Payment expired	When a payment expires it will automatically be cancelled. Expiring means the payment reached the expiration date without Flywire receiving the funds. When does a payment expire? A payment expires automatically after a while if no funds are received by Flywire: Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire. Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful. For API integration: Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt. For other integrations: Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful. The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.	expired
Direct debit payment failed	When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled. Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead. When do direct debit payments fail? A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.	unpaid

Reversed

reversed

This status has different meaning depending on the context:

2. Reversed type "unpaid"

This reversed type is only relevant for direct debits payments.

The status occurs when you (the client) received the funds from Flywire but Flywire did not receive the funds from your payer's bank account.

From a technical side this means:

The payment went into the delivered status (which means you received the funds from Flywire).
Then the payment fails and remains unpaid (which means Flywire did not receive the funds).

What does it mean when a direct debit payment is unpaid?

A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
Then Flywire will start a recovery process and the payment status will change from delivered to reversed.

Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.

status_transitions object

The status transitions provide you with a log when a payment went through different statuses. For this reason, the parameters only contain dates if the payment already went through the specific status.

See Payment Status Notifications for details about the statuses.

Name	Description
guaranteed_at string	The date and time when the payment was in status guaranteed.
delivered_at string	The date and time when the payment was in status delivered.
cancelled_at string	The date and time when the payment was in status cancelled.
authorized_at string	Only for Pre-Authorization Payments. The date and time when the payment was authorized. Note that the status of an authorized payment is initiated and will stay in this status until the funds are captured.

{
"total_entries": 367,
"total_pages": 37,
"page": 1,
"per_page": 10,
"payments": [
	{
		"payment_id": "TQQ871958420",
		"created_at": "2024-04-30T06:37:19Z",
		"expiration_date": "2024-05-03T06:37:19Z",
		"status": "delivered",
		"amount_from": 50000,
		"currency_from": "EUR",
		"amount_to": 50000,
		"currency_to": "EUR",
		"external_reference": "My external reference",
		"disbursement_id": "TQQ2024-04-30-1714459077",
		"status_transitions": {
		"guaranteed_at": "2024-04-30T06:37:32Z",
 		"delivered_at": "2024-04-30T06:37:57Z",
		"cancelled_at": null,
		"authorized_at": null
	},
		"payor_id": "My_payer_1"
	},
	{
...
	},
	{
		"payment_id": "TQQ963354950",
		"created_at": "2024-04-30T05:00:10Z",
		"expiration_date": "2024-05-04T05:00:09Z",
		"status": "guaranteed",
		"amount_from": 15000,
		"currency_from": "GBP",
		"amount_to": 17500,
		"currency_to": "EUR",
		"external_reference": "My external reference",
		"disbursement_id": null,
		"status_transitions": {
			"guaranteed_at": "2024-05-01T05:00:12Z",
			"delivered_at": null,
			"cancelled_at": null
			},
		"payor_id": "My_payer_2"
		}
	]
}

Getting Details about a Payment

Request

You can use this endpoint to show details about a payment in a UI.

The payment details show real-time information about the payment and can be used as a source of truth. There is no latency like there is for Getting a List of all Payments.

Example for displaying payment details

See Response for which details of the payment are returned so you can display them.

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

GET/payments/{paymentID}

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

Response

expiration_date date

The time and date the payment will expire automatically if no funds were received.

For card payments:

For API integration:

Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt.

For other integrations:

Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.

For Pre-Authorization Payments:

The expiration date is not the holding period length of a Pre-Authorization Payment. For Pre-Authorization Payments, you can disregard this parameter.

When does a payment expire?

A payment expires automatically after a while if no funds are received by Flywire:

Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.
Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.
For API integration:

Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt.

For other integrations:

Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful.

The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.

status string

The current status of the payment.

Possible statuses

A payment can have the following statuses and notifications:

Status

Notification

Description

Initiated

initiated

The payment status initiated is the status for all new payments in Flywire. No funds have been received by Flywire at the initiated stage.

Definition of a "payment" within the Flywire system

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:

A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.
What is the payment reference?
The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

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

The payment reference is also important in other situations, for example:
- When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.
- The payment reference helps Flywire to identify the payment if you or your payer needs support.
When the payment reference is assigned, two things happen:
- The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).
- The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

authorized

Only for Pre-Authorization Payments.

What is a Pre-Authorization Payment?

Pre-Authorization Payments are only available for same-currency payments, not for FX payments.

Example for a Pre-Authorization Payment:

A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.

Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.

During the Stay: The guest orders room service for $50.

Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.

The payment has been authorized and is now in the holding period.

Processed

processed

The payment status goes from initiated to processed when Flywire has the confirmation that the funds have been received or captured via one of these ways:

Bank transfer: funds have been received in a Flywire bank account.
Card payments: funds have been captured in payer’s card.
Direct debit: instructions to capture the funds are in progress and correct.

For 529 Payments, you have to put a payment into the processed status yourself.

After a payment is processed by you, you should notify your payer that their payment was processed to avoid duplicate payments.

Guaranteed

guaranteed

At this point, you are guaranteed that Flywire will send you the funds.

Delivered

delivered

The status changes from guaranteed to delivered when Flywire sent you the funds in your daily batch disbursement. Payments are updated to delivered at a set time each day.

The status delivered is the end stage, the status of a delivered payment can't change.

Failed

failed

The status failed can only occur for card or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure.

Cancelled

cancelled

The payment status cancelled means that the payment has been cancelled and will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.

Scenarios for cancelled payments

Who cancelled?	Scenario	cancellation_reason in the payment status notification
You	You cancelled a payment via the API. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. See Cancelling a Payment	cancelled_by_user
The payer	Payers can cancel a payment in two different ways: You can give your payers the option to cancel a payment themselves if you implement this function in your UI. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. Payers can contact Flywire and ask for a payment to be cancelled.	cancelled_by_user
Flywire	There can be different reasons why Flywire cancels a payment: Verification not passed The payment didn’t pass Flywire validations. If funds were captured, an automatic refund will be created and funds will be returned directly to the source of funds.	rejected
	Duplicate payment The payer created 2 payments by mistake, and Flywire closed one of them after identifying the duplicate issue.	duplicated
	You or the payer contacted Flywire to cancel the payment.	cancelled_by_user
Automatic cancellation - Payment expired	When a payment expires it will automatically be cancelled. Expiring means the payment reached the expiration date without Flywire receiving the funds. When does a payment expire? A payment expires automatically after a while if no funds are received by Flywire: Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire. Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful. For API integration: Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt. For other integrations: Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful. The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.	expired
Direct debit payment failed	When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled. Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead. When do direct debit payments fail? A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.	unpaid

Reversed

reversed

This status has different meaning depending on the context:

2. Reversed type "unpaid"

This reversed type is only relevant for direct debits payments.

The status occurs when you (the client) received the funds from Flywire but Flywire did not receive the funds from your payer's bank account.

From a technical side this means:

The payment went into the delivered status (which means you received the funds from Flywire).
Then the payment fails and remains unpaid (which means Flywire did not receive the funds).

What does it mean when a direct debit payment is unpaid?

A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
Then Flywire will start a recovery process and the payment status will change from delivered to reversed.

Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.

status_detail string

Details about the payment status.

Possible values for payment details and their relation to the payment status

Payment status (for callbacks)	Possible payment status details
initiated	initiated, processing
processed	verification
guaranteed	on_hold
reversed	reversed

status_transitions object

See Payment Status Notifications for details about the statuses.

Name	Description
guaranteed_at string	The date and time when the payment was in status guaranteed.
delivered_at string	The date and time when the payment was in status delivered.
cancelled_at string	The date and time when the payment was in status cancelled.
authorized_at string	Only for Pre-Authorization Payments. The date and time when the payment was authorized. Note that the status of an authorized payment is initiated and will stay in this status until the funds are captured.

payer object

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

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

recipient object

fields array

items array

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

mandate_id string

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

More info about the mandate PDF

The mandate PDF is the mandate fully written out "on paper" (but paperless as a PDF). The PDF will be delivered to your payer by email.

There are different types of PDFs depending on the direct debit scheme for the payments:

SEPA mandate

The file name for the PDF with the SEPA mandate contains the date the SEPA mandate was created and the mandate ID that was generated by Flywire.

BACS mandate

payment_method-details object

type string

The payment method type.

Possible values:

bank_transfer	Payment is done via bank transfer.
online	Payment is done via an alternative payment method (APM), through a third-party provider.
card	Payment is done via credit or debit card. You'll get additional information about the type of card in the parameter card_classification (either credit or debit).
direct_debit	Payment is done via direct debit.
529_payments	Payment is done via a 529 provider.

status string

The current status of the payment.

Possible statuses

A payment can have the following statuses and notifications:

Status

Notification

Description

Initiated

initiated

The payment status initiated is the status for all new payments in Flywire. No funds have been received by Flywire at the initiated stage.

Definition of a "payment" within the Flywire system

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:

A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.
What is the payment reference?
The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

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

The payment reference is also important in other situations, for example:
- When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.
- The payment reference helps Flywire to identify the payment if you or your payer needs support.
When the payment reference is assigned, two things happen:
- The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).
- The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

authorized

Only for Pre-Authorization Payments.

What is a Pre-Authorization Payment?

Pre-Authorization Payments are only available for same-currency payments, not for FX payments.

Example for a Pre-Authorization Payment:

A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay.

Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged.

During the Stay: The guest orders room service for $50.

Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit.

The payment has been authorized and is now in the holding period.

Processed

processed

The payment status goes from initiated to processed when Flywire has the confirmation that the funds have been received or captured via one of these ways:

Bank transfer: funds have been received in a Flywire bank account.
Card payments: funds have been captured in payer’s card.
Direct debit: instructions to capture the funds are in progress and correct.

For 529 Payments, you have to put a payment into the processed status yourself.

After a payment is processed by you, you should notify your payer that their payment was processed to avoid duplicate payments.

Guaranteed

guaranteed

At this point, you are guaranteed that Flywire will send you the funds.

Delivered

delivered

The status changes from guaranteed to delivered when Flywire sent you the funds in your daily batch disbursement. Payments are updated to delivered at a set time each day.

The status delivered is the end stage, the status of a delivered payment can't change.

Failed

failed

The status failed can only occur for card or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure.

Cancelled

cancelled

The payment status cancelled means that the payment has been cancelled and will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.

Scenarios for cancelled payments

Who cancelled?	Scenario	cancellation_reason in the payment status notification
You	You cancelled a payment via the API. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. See Cancelling a Payment	cancelled_by_user
The payer	Payers can cancel a payment in two different ways: You can give your payers the option to cancel a payment themselves if you implement this function in your UI. Guaranteed and delivered payments should not be cancelled. If you have to cancel them, please contact Flywire. Payers can contact Flywire and ask for a payment to be cancelled.	cancelled_by_user
Flywire	There can be different reasons why Flywire cancels a payment: Verification not passed The payment didn’t pass Flywire validations. If funds were captured, an automatic refund will be created and funds will be returned directly to the source of funds.	rejected
	Duplicate payment The payer created 2 payments by mistake, and Flywire closed one of them after identifying the duplicate issue.	duplicated
	You or the payer contacted Flywire to cancel the payment.	cancelled_by_user
Automatic cancellation - Payment expired	When a payment expires it will automatically be cancelled. Expiring means the payment reached the expiration date without Flywire receiving the funds. When does a payment expire? A payment expires automatically after a while if no funds are received by Flywire: Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire. Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful. For API integration: Card payments do not expire. If the charge has been unsuccessful, no other attempts of charging the card will be made. You need to create a new payment to try a new charge attempt. For other integrations: Card payments expire usually within 2 business days, when there was no attempted payment or the attempts to capture the funds were unsuccessful. The exact time within a payment expires depends on your individual settings that have been defined between you and Flywire.	expired
Direct debit payment failed	When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled. Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead. When do direct debit payments fail? A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.	unpaid

Reversed

reversed

This status has different meaning depending on the context:

2. Reversed type "unpaid"

This reversed type is only relevant for direct debits payments.

The status occurs when you (the client) received the funds from Flywire but Flywire did not receive the funds from your payer's bank account.

From a technical side this means:

The payment went into the delivered status (which means you received the funds from Flywire).
Then the payment fails and remains unpaid (which means Flywire did not receive the funds).

What does it mean when a direct debit payment is unpaid?

A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
Then Flywire will start a recovery process and the payment status will change from delivered to reversed.

Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.

reason object

Only if the payment failed.

description string

The reason why the payment failed that you can share with your payers. You can display this reason to your payer to help them figuring out what went wrong and possibly solve the problem.

There are different reasons depending on what the issue is.

Examples for failed payment reasons returned by the API

Issue	Reason returned by the API
Configuration or connectivity issues	Your transaction has not been successful, please try again. If the error persists select a different payment method or contact our customer support team.
Issues related with bank or card details, like invalid data or refused by the bank	Your transaction has been declined by your bank. Please try inserting correct, valid card/bank account details to complete the payment or contact your bank to resolve the issue.
Not enough balance or over amount limit	Your transaction has been declined by your bank. Please try increasing the available balance of your account, use a different card/bank account or contact your bank for further assistance.

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

metadata object

There are different kinds of metadata for a payment:

Metadata added by Flywire

Not present for 529 Payments.

tracking_url string (url)

Only for One Off Payments with payment method bank transfer.

The tracking URL leads your payer to the Flywire Payment Experience where they can track their payment.

As long as a payment is still in progress, payers can download the payment instructions for bank transfer payments there, including an authorization letter in case they need it.

There are two ways to give your payer the payment instructions for bank transfers:

You can use the instructions parameters and display them in your UI or an email.
You can display the tracking_url in your UI or an email. If your payer needs an authorization letter, they need to use the tracking URL and download the payment instructions from there, since the PDF download contains the authorization letter.

Metadata added by you

Only for 520 Payments and self-managed recurring payments. Not present for One Off Payments and Flywire-managed recurring payments.

Custom metadata is additional data entered by you when you create the payment, for example data you need to identify the payment in your system. Metadata can be useful when you want to add data that is not already covered by recipient fields, for example if you are not the one who set up the recipient and have no influence on the fields.

Metadata consist of pairs of keys and values, for example key Payer_ID_From_My_System and value ID12345.

instructions array

The payment instructions are only returned for One Off Payments when the payment method type is bank transfer.

This array of objects contains the payment instructions for your payer to enable them to send the money to Flywire via bank transfer.

Which objects are returned depend on various factors, for example from which country the payer is sending money.

Each object consists of an internal name, a label, and a value.

For displaying the instructions to your payer, use the label and the value.

UI Example:

There are two ways to give your payer the payment instructions for bank transfers:

You can use the instructions parameters and display them in your UI or an email.
You can display the tracking_url in your UI or an email. If your payer needs an authorization letter, they need to use the tracking URL and download the payment instructions from there, since the PDF download contains the authorization letter.

{
	"payment_id": "RUC928923284",
	"created_at": "2023-02-14T14:06:32Z",
	"expiration_date": "2023-02-16T14:06:32Z",
	"status": "initiated",
    "status_detail": "processing"
    "status_transitions": {
        "guaranteed_at": null,
        "delivered_at": null,
        "cancelled_at": null,
        "authorized_at": null
    },
	"amount_from": 94000,
	"currency_from": "EUR",
	"amount_to": 100000,
	"currency_to": "USD",
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    },
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 50000,
        }
    ],
    "charge_intent": {
        "initiator": "MERCHANT",
        "mode": "SUBSCRIPTION",
        "mandate_id": "MCZER20230214E2PEBOEF",
        "payor_id": "studentORparent123",
        "payment_method_token": "4ec7373376b0edc050d4"
        }
    },
    "payment_method_details": {
        "type": "card",
        "brand": "VISA",
        "card_classification": "credit",
        "card_expiration": "3/2030",
        "last_four_digits": "1111",
        "status": "failed",
        "reason": {
            "code": "012",
            "description": "Your transaction has been declined by your bank. Please try increasing the available balance of your account, use a different card/bank account or contact your bank for further assistance."
        }
    },    
    "external_reference": "My internal reference",
    "notifications_url": "https://webhook.site/c1e8",
    "disbursement_id": "FLW2018-02-26",
    "metadata": {
        "payor_id": "studentORparent123",
        "tracking_url": "https://payment.demo.flywire.com/tracking/f240fcd8-7337-4110-a472-afabaafb07da?token=bf54dbc0-6d96-469d-8197-f15b2741215d",
        "MyOwnMetadata": "My system info about the payment"
         }, 
    "instructions": [
        {
            "name": "iban",
            "label": "IBAN",
            "value": "ES3814740000140660146008"
        },
        {
            "name": "beneficiary",
            "label": "Beneficiary",
            "value": "Flywire"
        },
...
        {
            "name": "beneficiary_address",
            "label": "Beneficiary Address",
            "value": "Av. Aragón 30, 13J\r\n46021 Valencia, Spain"
        }
    ]
}

Creating a Refund for a Payment

Request

This endpoint lets you create a refund for a payment.

What happens after I created a refund?

After you created a refund, you need to use the resource Refunds to manage refunds.

For a detailed walkthrough about how to create and manage refunds see Use Case: Refunds.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).

Parameters for the Request Body

POST/payments/{paymentID}/refunds

curl https://base-url-placeholder/payments/FWU125675432/refunds
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
		“amount”: 10000,
		“external_reference”: “my-refunds-29”,
		“notifications_url”: “https://webhooks/notifications/refunds”
}

Response

refund_id string

The refund ID.

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

Format: R + recipient ID + 8 characters

Example: RPTUABCDE123

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

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

Refunds

A refund is a way to return funds back to your payer via Flywire. You can define if you want to return the full amount (full refund) or just part of the amount (partial refund) of the original payment.

Refund Essentials: What You Should Know

A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
Each refund is connected to one payment, it is not possible to create one "shared" refund for multiple payments.
A payment can only have one active refund at a time. When the refund is done (in status finished) you can create a new refund for the payment.
The refunded amount, whether it's one full refund or several partial refunds added together, can't be more than the initial payment amount.

Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

Refund bundles

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.

The refund bundle cycle

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.

bundle_id string

The refund bundle ID.

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

Format: BUDR + 8 characters

Example: BUDR123456HG

What is a refund bundle?

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

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.

status string

The current status of the refund.

Possible refund statuses

A refund can have the following statuses:

Status

Description

initiated

You have created a refund.

failed

There was a problem trying to create the refund.

Reasons for a failed refund

Error Reason	Description
not_found	The payment that the refund is supposed to be created for can't be found.
already_refund	The payment that the refund is supposed to be created for already has a refund in progress. A payment can only have one active refund at a time. When the refund is done (in status finished) you can create a new refund for the payment.
status	The payment that the refund is supposed to be created for is in a status that doesn't allow a refund to be created. A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
amount_ over_ remaining_ balance	The amount of the refund is bigger than the remaining payment balance.
minimum_ threshold	The amount of the refund is less than the minimum amount configured for the recipient. What is the minimum amount configured for a recipient? The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire. If you didn't customize the settings, the default limits are: Minimum: 5000 = 50.00 USD Maximum: 15000000 = 150000.00 USD When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items. What happens when a payment is not within the defined settings? When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned.
currency	Currency mismatch.
multiple	The payment that the refund is supposed to be created for is already fully refunded.

received

Flywire has received your money for the refund.

cancelled

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

Cancelling a Refund Essentials - What You Should Know:

You can only cancel a refund that is in status initiated, meaning that Flywire has not taken the first step for processing the refund and no money has been moved yet.
You can cancel a refund before and after the cut-off time of a recipient.
You can't cancel a refund bundle.

finished

Flywire has transferred the money back to your payer.

If a refund moves back from finished to received, it means Flywire couldn't transfer the money because the payer's bank rejected it. You don't need to take any action. Flywire will keep trying and notify you if the issue continues.

returned

After Flywire received the money from you, Flywire returned the money back to you instead of returning it to your payer.

In the rare case that a refund moves back from returned to received, it means that Flywire couldn't transfer the money back to you. Flywire will contact you if that happens.

{
  "refund_id": "RUUI123456789",
  "payment_id": "UUI123456789",
  "bundle_id": "BUUI123456789",
  "status": "pending",
  "amount": 10000,
  "currency": "USD",
  "external_reference": "my-refunds-29",
  "notifications_url": "https://webhooks/notifications/refunds"
}