Payment Status Notifications

Payment Status Notifications enable you to track a payment while it makes its way through the payment workflow. Whenever a status change event occurs, for example when the payment status changes from initiated to processed, you'll get a notification to the URL you provided.

How do I get started?

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

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

Payment Status Notifications

  • Initiated
  • Authorized
  • Processed
  • Guaranteed
  • Delivered
  • Failed
  • Cancelled
  • Reversed

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

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: 

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

    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.

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

 

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.


  "event_type": "initiated",
  "event_date": "2021-05-20T11:24:45Z",
  "event_resource": "payments",
  "data": {
    "payment_id": "PTU146221637",
    "amount_from": "4225",
    "currency_from": "EUR",
    "amount_to": "5000",
    "currency_to": "USD",
    "status": "initiated",
    "expiration_date": "2021-05-31T11:24:45Z",
    "external_reference": "a-reference",
    "country": "ES",
    "payment_method": {
      "type": "card"
    },
    "recurring_id": "IPTQQ18ECD5B31AB",
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },
  }
}

Only for Pre-Authorization Payments.

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

 

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "authorized",
  "event_date": "2024-03-20T11:33:02Z",
  "event_resource": "charges",
  "data": {
    "payment_id": "PTU146221637",
    "amount_from": "4800",
    "currency_from": "EUR",
    "amount_to": "5000",
    "currency_to": "USD",
    "status": "authorized",
    "expiration_date": "2024-03-28T11:33:02Z",
    "external_reference": "a-reference",
    "country": "ES",
    "payment_method": {
      "type": "card"
    },
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },						
  }
}

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.

 

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

Only for card payments.

The brand of the card (for example, Visa or Mastercard).

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit

Only for card payments.

The card expiration date in the format MM/YYYY.

The last four digits of the card number or bank account number.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "processed",
  "event_date": "2021-05-20T11:25:02Z",
  "event_resource": "charges",
  "data": {
    "payment_id": "TQQ146221637",
    "amount_from": "4225",
    "currency_from": "EUR",
    "amount_to": "5000",
    "currency_to": "USD",
    "status": "processed",
    "expiration_date": "2021-05-31T11:24:45Z",
    "external_reference": "a-reference",
    "country": "ES",
    "payment_method": {
      "type": "card",
      "brand": "visa",
      "card_classification": "credit",
      "card_expiration": "08/2025",
      "last_four_digits": "3878" 
    },
    "recurring_id": "IPTQQ18ECD5B31AB",
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },
  }
}

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.

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

Only for card payments.

The brand of the card (for example, Visa or Mastercard).

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit

Only for card payments.

The card expiration date in the format MM/YYYY.

The last four digits of the card number or bank account number.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "guaranteed",
  "event_date": "2021-05-20T11:25:05Z",
  "event_resource": "payments",
  "data": {
    "payment_id": "PTU146221637",
    "amount_from": "4225",
    "currency_from": "EUR",
    "amount_to": "5000",
    "currency_to": "USD",
    "status": "guaranteed",
    "expiration_date": "2021-05-31T11:24:45Z",
    "external_reference": "a-reference",
    "country": "ES",
    "payment_method": {
      "type": "card",
      "brand": "visa",
      "card_classification": "credit",
      "card_expiration": "08/2025",
      "last_four_digits": "3878" 
    },
    "recurring_id": "IPTQQ18ECD5B31AB",
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },
  }
}

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.

 

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

Only for card payments.

The brand of the card (for example, Visa or Mastercard).

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit

Only for card payments.

The card expiration date in the format MM/YYYY.

The last four digits of the card number or bank account number.

payouts array

The recipient ID (also called portal code).

The recipient ID is the unique three-letter ID that identifies the recipient, for example FWU for Flywire University. The recipient ID has been assigned by Flywire when the recipient has been set up.

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.

The amount of this disbursement in your payout currency.

The disbursement ID.

The disbursement ID identifies a disbursement.

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

Format: recipient ID + initiation date (format YYYY-MM-DD) + string of characters

Example:  TQQ2024-04-18-1713458596.

A disbursement is a bundle of payments that Flywire transfers into your bank account. Flywire doesn't transfer each payment individually, but bundles payments together and transfers them in one disbursement on a regular basis.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "delivered",
  "event_date": "2021-05-20T11:48:02Z",
  "event_resource": "payments",
  "data": {
    "payment_id": "TQQ146221637",
    "amount_from": "4225",
    "currency_from": "EUR",
    "amount_to": "5000",
    "currency_to": "USD",
    "status": "delivered",
    "expiration_date": "2021-05-31T11:24:45Z",
    "external_reference": "a-reference",
    "country": "ES",
    "payment_method": {
      "type": "card",
      "brand": "visa",
      "card_classification": "credit",
      "card_expiration": "08/2025",
      "last_four_digits": "3878"
     },
    "payouts": [
      {
        "portal_code": "TQQ",
        "currency": "GBP",
        "amount": "28300",
        "disbursement_id": "SANDBOX-TQQ2024-04-18-1713458596"
      }
    ],
    "recurring_id": "IPTQQ18ECD5B31AB",						
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },
  }
}

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.

For any new failed charge attempt, Flywire will send a new failed payment status notification. If the retry succeeds, Flywire will send a processed notification. If the payer retries with a different payment method, the information in the payment_method object will change.

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

Only for card payments.

The brand of the card (for example, Visa or Mastercard).

Only for card payments.

Credit or debit card.

Possible values:

  • credit

  • debit

Only for card payments.

The card expiration date in the format MM/YYYY.

The last four digits of the card number or bank account number.

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.

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.

Flywire error code for the error message why charging the payment failed.

The reason why the payment failed for you as an internal information.

Do not expose the client_reason to your payers. The information is meant as internal information to give you more insight of why a payment failed.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "failed",
  "event_date": "2022-02-21T11:15:34Z",
  "event_resource": "charges",
  "data": {
	"payment_id": "MGT670199181",
	"amount_from": "420",
	"currency_from": "USD",
	"amount_to": "420",
	"currency_to": "USD",
	"status": "failed",
	"expiration_date": "2022-02-23T11:12:19Z",
	"external_reference": "Callback ID 1234",
	"country": "US",
	"payment_method": {
  		"type": "card",
  		"brand": "visa",
  		"card_classification": "credit",
   		"card_expiration": "01/2035",
  		"last_four_digits": "5555"
		},
	"reason": "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.",
	"reason_code": "012",
    "client_reason": "Not enough balance",
    "recurring_id": "IPTQQ18ECD5B31AB",						
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },
  }
}

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

 

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

The reason for the cancellation.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

payment_method object

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.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "cancelled",
  "event_date": "2021-05-20T11:33:02Z",
  "event_resource": "payments",
  "data": {
    "payment_id": "PTU146221637",
    "amount_from": "4225",
    "currency_from": "EUR",
    "amount_to": "5000",
    "currency_to": "USD",
    "status": "cancelled",
    "expiration_date": "2021-05-31T11:24:45Z",
    "external_reference": "a-reference",
    "country": "ES",
    "cancellation_reason": "cancelled_by_user",
    "payment_method": {
      "type": "card"   
    },
    "recurring_id": "IPTQQ18ECD5B31AB",	
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },											
  }
}

There are two types of reversed callbacks:

  • Reversed type refund
  • Reversed type unpaid

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

The type of the payment reversal.

Possible values:

  • refund

    This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

    This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

      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.

The entity ID depends on the type of reversed callback.

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.

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.

The reversed payment ID.

The reversed payment ID is a unique identifier for unpaid direct debit payments. It has the format REV_{payment reference}, for example REV_FLW356132734.

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.

reversed_amount object

The amount of the refund in the billing currency. This is the amount Flywire will take from the recipient to refund it back to the payer.

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

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

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

The amount of the payment reversal in the billing currency. This is the amount Flywire will take from the recipient to cover the unpaid payment.

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

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

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

currency object

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

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

The number of subunits of this currency's units, for example 100.

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 reason for the callback (Refund finished), indicates that this callback has been sent because a refund for the payment has been finished.

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.

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.

The Flywire code for a finished refund for a payment (106) .

Flywire error code for the error message why charging the payment failed.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
  "event_type": "reversed",
  "event_date": "2021-05-20T11:33:02Z",
  "event_resource": "payments",
  "data": {
    "payment_id": "PTU146221637",
    "amount_from": "4800",
    "currency_from": "EUR",
    "amount_to": "50000",
    "currency_to": "USD",
    "status": "reversed",
    "expiration_date": "2021-05-31T11:24:45Z",
    "external_reference": "a-reference",
    "country": "ES",
    "payment_method": {
      "type": "card"
    },
    "reversed_type": "refund",
    "entity_id": "RPTUDD91239F",
    "reversed_amount": {
        "value": "10000",
        "currency": {
            "code": "USD",
            "subunit_to_unit": "100"
        }
    },
    "reason": "Refund finished",
    "reason_code": "106"
    "recurring_id": "IPTQQ18ECD5B31AB",
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"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]"
    },
  }
}

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

    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.

Type of the event (status change).

Possible types:

initiated

guaranteed

delivered

cancelled

For payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

processed

failed

For charges of payments.

For details of the meaning of each status see Payment Status Notifications - Payment Statuses

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

The resource that has generated the notification.

Possible values:

  • payments

  • charges

data object

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.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing 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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount in the billing currency.

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

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 billing currency in ISO 4217 format.

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

The current status of the payment.

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.

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: 

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

    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.

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

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.

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

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

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

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

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment.

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

Processed

processed

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

  • Bank transfer: funds have been received in a Flywire bank account.

  • Card payments: funds have been captured in payer’s card.

  • Direct debit: instructions to capture the funds are in progress and correct.

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.

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.

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

  • Bank transfer payments expire usually within 5-8 business days, when no funds have been received by Flywire.

  • Direct debit payments expire usually within 2 business days, when the attempts to capture the funds were unsuccessful.

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

When a direct debit payment fails while a payment is in status processed or guaranteed it will be cancelled.

Note that if the direct debit payment is in status delivered and fails, it goes to status reversed instead.

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

    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.

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.

How long funds can be reserved depends on the card issuer and other circumstances. At the moment, Flywire can reserve the funds for 7 days. If you are not capturing the funds within the holding period, blocked amount is released back to the cardholder's credit.

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.

The unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

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

payment_method object

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.

The type of the payment reversal.

Possible values:

  • refund

    This reversed type means a refund for the payment has been finished. It can either be a partial or a full refund. If there are multiple partial refunds for a payment, you will receive a notification for each new finished refund. Keep in mind that there can only be one refund at a time for a payment.

    This status tells you that a refund has successfully been completed for the payment. For tracking the status of the refund from the beginning, you will get separate notifications, see Refund Status Notifications.

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

      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.

The entity ID depends on the type of reversed callback.

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.

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.

The reversed payment ID.

The reversed payment ID is a unique identifier for unpaid direct debit payments. It has the format REV_{payment reference}, for example REV_FLW356132734.

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.

reversed_amount object

The amount of the refund in the billing currency. This is the amount Flywire will take from the recipient to refund it back to the payer.

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

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

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

The amount of the payment reversal in the billing currency. This is the amount Flywire will take from the recipient to cover the unpaid payment.

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

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

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

currency object

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

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

The number of subunits of this currency's units, for example 100.

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 reason for the callback (Refund finished), indicates that this callback has been sent because a refund for the payment has been finished.

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.

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.

The Flywire code for a finished refund for a payment (106) .

Flywire error code for the error message why charging the payment failed.

The plan ID.

A plan ID is a unique identifier for a Flywire installment plan. A plan ID always starts with IP ("Installment Plan") followed by the recipient ID and 11 random characters.

Example: IPTQQ18EADF349BE

Plan IDs are only relevant for Flywire-managed recurring payments (see Plans for Recurring Payments). For self-managed recurring payments you don't use plan IDs coming from Flywire.

fields object

These are the fields of the recipient (also called "dynamic fields of a portal") , for details see Recipients - Fields. The fields are returned as pairs of the field id (for example student_id) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

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

The payer's state.

The payer's phone number.

The payer's email address.

{
   "event_type":"reversed",
   "event_date":"2023-04-28T12:02:23Z",
   "event_resource":"payments",
   "data":{
      "payment_id":"ALA356132734",
      "amount_from":"14700",
      "currency_from":"USD",
      "amount_to":"14700",
      "currency_to":"USD",
      "status":"reversed",
      "expiration_date":"2023-05-09T12:01:22Z",
      "external_reference":"0a78cc69-585f-4250-b368-1fa990a463b3",
      "country":"US",
      "payment_method":{
         "type":"direct_debit"
      },
	  "reversed_type": "unpaid",
	  "entity_id": "REV_ALA356132734",
	  "reversed_amount": {
			"value": "14700",
			"currency": {
			"code": "USD",
			"subunit_to_unit": "100"
			}
		},
		"reason": "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.",
		"reason_code": "012",
    	"recurring_id": "IPALA356132734",
	"fields":{
		"student_id": "ID123456",
		"student_last_name": "Smith"
	}, 
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "456 Elm Street",
		"address2": null,
		"city": "Springfield",
		"country": "US",
		"state": "IL",
		"zip": "62701",
		"phone": "0012175556789",
		"email": "[email protected]"
    },
  }
}

How to set up Payment Status Notifications

Types of Notification URLs

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

Parameters for Payment Status Notifications Settings

You'll encounter two parameters that influence the payment status notifications for a payment whenever you are creating a payment.

 

Parameter Description

external_reference

string

The external reference is used to match a notification to a particular payment. You can use any kind of identifier or reference from your own system you might need to identify the payment. The external reference is included in all status notifications for this payment (refer to Payment Status Notifications) to help you match the notification to the right payment using your own reference in addition to the Flywire-generated payment reference.

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.

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

 

Failed notifications: What happens if a callback can't get delivered?

When Flywire tries to send a notification to the callback URL you provided and receives an error, there will automatically three re-attempts:

  • First time with a delay of 180 seconds (3 minutes)

  • Second time with a delay of 1800 seconds (30 minutes)

  • Third time with a delay of 10800 seconds (3 hours)

Failed callback report

Flywire logs all failed callback sending attempts. If after the third try sending the callback is still unsuccessful, Flywire sends a failed callback report to an approved contact for review. You as a client must provide the contact details for someone to receive the failed callback report.

Validating Payment Status Notifications

Validating notifications is optional, as it’s on your server side, but for security reasons it is recommended to validate all notifications.

How to validate a notification

To validate a notification, check its X-Flywire-Digest header. This value is generated by Flywire using your Shared Secret to encrypt the notification body. To verify the notification, generate the digest using the same method and compare it to the X-Flywire-Digest value in the header. If they match, the notification is legitimate and hasn't been tampered with.

  1. Retrieve the raw HTTP body of the notification you received.

    Make sure you use the raw HTTP body of the notification. You must generate the X-Flywire-Digest value using the exact payload you received in the notification. If you change the body in any way the values won't match later.

 

  1. Encrypt the received notification twice:

    1) Encrypt the raw HTTP body of the received notification with your Shared Secret using the SHA-256 algorithm.

    2) Take the result and encrypt it in Base64.

    The examples show you how to do this in different programming languages. In each example, exchange the shared_key with your Shared Secret and message_body with the raw HTTP body of the notification.

    The Shared Secret is a string of characters used for security validations.

    For API integration:

    Your Shared Secret is used to validate notifications. You receive your Shared Secret together with your API credentials via a secure email after you registered your application.

    For other integrations:

    Your Shared Secret is used to validate notifications and authenticate requests. You receive your Shared Secret from the Flywire Solutions team after your portal has been set up (please contact the Solutions team in case you don't have your Shared Secret). Note that each portal might have a different shared secret. If you have access to multiple portals, make sure you use the correct shared secret for each portal.

    • Ruby
    • .NET
    • JavaScript 
    digest = OpenSSL::Digest.new('sha256')
encrypted_payload = OpenSSL::HMAC.digest(digest, shared_secret, notification_body)
Base64.encode64(encrypted_payload).strip
			
# Step 1: Define the hashing algorithm to use for the HMAC.
# This initializes the SHA-256 hashing mechanism.
hash_algorithm = OpenSSL::Digest.new('sha256')

# Step 2: Compute the HMAC in binary format.
# This uses the shared secret and the message body to produce the HMAC signature.
hmac_binary = OpenSSL::HMAC.digest(hash_algorithm, shared_secret, message_body)

# Step 3: Encode the HMAC in Base64 for use in the X-Flywire-Digest header.
x_flywire_digest = Base64.encode64(hmac_binary).strip
    public static string Digest(string shared_secret, string message_body)
{
    // Step 1: Initialize the HMACSHA256 object with the shared secret.
    // This sets up the hashing algorithm (SHA-256) and the secret key for HMAC.
    using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(shared_secret)))
    {
        // Step 2: Convert the message body into a byte array.
        // The message body is the message payload you want to hash
        var bytes = Encoding.UTF8.GetBytes(message_body);

        // Step 3: Compute the HMAC hash of the message body.
        // This generates the HMAC using the shared secret and the message body.
        var hashedBytes = hmacsha256.ComputeHash(bytes);

        // Step 4: Convert the hashed byte array into a Base64 string.
        return Convert.ToBase64String(hashedBytes);
    }
}
    const crypto = require('crypto');

function createDigest(shared_secret, message_body) {
    // Step 1: Initialize the HMAC with the SHA-256 algorithm and the shared secret.
    const hmac = crypto.createHmac('sha256', shared_secret);
    
    // Step 2: Update the HMAC with the message body.
    // The message body is the message payload you want to hash
    hmac.update(message_body);

    // Step 3: Get the HMAC digest and encode it in Base64.
    const digestHeader = hmac.digest('base64');
    
    return digestHeader;  // The `digestHeader` is the X-Flywire-Digest header.
}

     

  2. Compare your Base64 string to the value in the X-Flywire-Digest parameter of the notification you received.

    If the values match, the notification came from Flywire and hasn't been changed by a third party.

    If the values don't match, you shouldn't trust the notification.