Checkout for Pre-Authorization Payments

The Checkout integration enables you to create Pre-Authorization Payments, but not to capture the funds (see Next Step: Capturing the Funds).

What is a Pre-Authorization Payment?

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

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

Example for a Pre-Authorization Payment:

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

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 two steps of creating and capturing Pre-Authorization Payments

1. Pre-authorization of funds (via Checkout , Flywire API or Elements )

   With pre-authorization, you reserve funds on the card for a certain amount of time (the holding period). The funds are reserved but not withdrawn.

   How do I pre-authorize funds?

   Via Checkout :

   You can create a single Pre-Authorization Payment, see Checkout for Pre-Authorization Payments.

   Via Flywire API:

   You can create a single Pre-Authorization Payment as a Payment Request, see Creating a Payment Request.

   Via Elements:

   You have two options:

   • You can create a single Pre-Authorization Payment.

   • You can also start Self-Managed Recurring Payments with a Pre-Authorization Payment.

   How long is 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. The period starts from the day the Pre-Authorization Payment is created.

   If you want to hold funds for longer, you can extend the holding period.

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

   The blocked amount returns back to the cardholder's credit:

   • if you don't capture the funds within the holding period

   • if you cancel a Pre-Authorization Payment (immediately after cancelling)

   Can I change the amount that is being reserved?

   Yes, there is an option to adjust the pre-authorization amount, see Adjusting or Extending a Pre-Authorization Payment.

   If you created the Pre-Authorization Payment via Checkout or the Flywire API:

   You can always extend the holding period and adjust the amount during the holding period.

   If you created the Pre-Authorization Payment via Elements:

   You can extend the holding period and adjust the amount during the holding period unless you manually set the authorization to finalwhen you created the payment.

2. Capturing the funds (via the Flywire API)

   When the funds are captured, the card is charged and funds are withdrawn. You can manually capture funds anytime during the holding period.

   If you want to hold funds for longer, you can extend the holding period.

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

   Do I have to capture the exact pre-authorized amount?

   You can capture the exact pre-authorized amount or less, but not more.

   If you capture less, the remaining balance is released back to the cardholder immediately and the payment will be updated to reflect the captured amount.

   What happens if I don't capture the payment during the holding period?

   The blocked amount returns back to the cardholder's credit:

   • if you don't capture the funds within the holding period

   • if you cancel a Pre-Authorization Payment (immediately after cancelling)

Configuration Example for creating a Pre-Authorization Payment

Basic Settings

env string

Specifies the environment for Checkout. Default if not supplied: demo

Possible values:

• demo (Sandbox)

• prod (Production environment)

recipientCode string

Specifies the portal (also called recipient) that will receive the payment.

What is a portal?

A portal (also called recipient) defines who receives the money from payments to Flywire.

You as a client have an account with Flywire called company and define at least one portal for this company. This portal contains settings like the bank account that receives the money from payments and the currency in which Flywire takes payments from your payers.

You can have more than one portal, for example one portal for testing purposes and one production portal. Or you could have multiple portals because you want to receive money into different bank accounts or currencies.

The portal code identifies the portal. The portal code has been assigned by Flywire when the portal has been set up.

Format:

Either: 3 letters (ABC)

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

If you are using the demo environment, your portal code might be different from the one you are using in production.

Payer Info and Custom Info

Optionally pre-fill fields and decide which input pages will be shown. See Pre-filling Fields of the Form for details.

Payment Settings

The payment amount to be held on the card:

amount decimal

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 portal's configuration and is defined when the portal is set up by Flywire.

The amount is specified as a decimal (1000.25).

paymentAuthorization object

type string

Must be pre_auth

After-Payment Settings

Specify the returnUrl or an onCompleteCallback handler. See After-Payment Settings for details.

Using callbacks is optional, but highly recommended.

Callbacks give you important updates about the status of the payment. See Payment Status Notifications for details.

callbackId string

The external reference.

The external reference helps you to identify a payment, since the Flywire-generated payment reference might not be the way you typically identify payments. With the external reference, you can enter your own identifier, such as an ID or invoice number.

The external reference is included in all status notifications to help you map a payment to a callback notification. (see Payment Status Notifications)

If you are using the Checkout or Pay-By-Link integration:

The external reference is called "callback ID" here. You'll find the callbackId in the external_reference parameter of the callback.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

callbackUrl string (url)

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

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

A static callback URL is a fixed URL defined in your portal. All payments for this portal will send callbacks to this URL.

The static callback URL has been defined when your portal was set up. If you don't use a static callback URL yet and want to start using it, please reach out to your Flywire contact.

Dynamic URL

A dynamic callback URL is a URL that you define when you create the payment. Since this URL can be different for every payment you create, it is called dynamic.

For Pay-By-Link and Checkout , you define the URL via the callbackUrl parameter.

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

You cannot provide a dynamic callback URL for payments that are part of a Payment Request. To receive callbacks about those payments, you have to use the static URL. Alternatively, you can use callback notifications for Payment Request status updates, but note that the content of those callbacks are different from payment status callbacks.

How defining static and dynamic URLs affect callbacks

= not set

= set

 

Static URL	Dynamic URL	Result
		You won't receive callbacks .
		You'll receive callbacks to your static URL. You'll also receive callbacks for payments that are part of Payment Requests.
		You'll receive callbacks to both URLs. You'll also receive callbacks for payments that are part of Payment Requests, but only to the static URL.
		You'll receive callbacks to your dynamic URL You will not receive callbacks for payments that are part of Payment Requests since there is no static URL.

 

If you are using the Checkout or Pay-By-Link integration:

If you want to receive callbacks, you must provide a callback URL and a callback ID, otherwise no callbacks will be triggered. You also must set the callback version to 2.

callbackVersion string

The version of the callback. Possible values:

• 2 (for version 2)

If you want to receive callbacks, you must provide the callback version and it must be version 2.

Try it out!

var config = {
  env: "demo",
  recipientCode: "Your Flywire Portal Code",

  // Other checkout parameters (e.g. pass some payer info and set requestPayerInfo to true)
  firstName: "John",
  lastName: "Doe",
  requestPayerInfo: true,

  // The amount to be held
  amount: 210.00,

  // Mark this payment as a pre-authorization 
  paymentAuthorization: {
      type: "pre_auth"
  },
	
  // Specify the returnUrl or an onCompleteCallback handler
  returnUrl: "https://httpbin.org/get",
		
  // Callbacks are strongly recommended
  callbackId: "REF1234",
  callbackUrl: "https://api.yourdomain.com/flywire-notifications",
  callbackVersion: "2"
};

After Payment Completion

Information returned via returnUrl or onCompleteCallback handler

Once a the payer has successfully entered their details and the Checkout Experience form is closed, you receive information about the payment either via the returnUrl or the onCompleteCallback handler.

More info about receiving payment information

The after-payment settings define how information is sent back to your website.

The payment flow for the Checkout integration is:

1. Customer enters information.

   Your customer opens the Checkout Experience form on your website and enters their payment details.

2. Information is sent back to your website.

   After the payment is completed, the Checkout Experience window automatically closes after a few seconds.

   This triggers the Checkout integration to send back the payment status and details to your website. This can be done in two different ways:

   You can either use the returnUrl parameter or the onCompleteCallback parameter, never both.

   For security reasons, the token is only returned via onCompleteCallback handler. The returnUrl does not return the token.

   This means that when you are tokenizing, you must only use the onCompleteCallback handler.

   returnUrl :

   While the payer is redirected to the return URL, Flywire attaches query string parameters containing payment information to the set URL. This way, your website can receive and process the payment information without requiring additional API calls.

   onCompleteCallback:

   The payer stays on the original page. You specify an onCompleteCallback function in the Checkout configuration that handles the parameters containing payment information. The parameters are returned as a JSON args object to the callback handler.

   Advantages of using onCompleteCallback

   • Immediate Handling

     Since the data is passed directly to your callback, you can handle the payment confirmation on the same page without a redirect.

   • Dynamic Updates

     You can dynamically update the page (e.g., show a success message) without leaving the current view, providing a smoother user experience.

   • Flexibility

     You can implement custom logic directly in the callback, such as updating the UI or logging information for analytics.

3. You use the information for your own systems and the customer.

   You can use the returned parameters to update your backend, display information to your payer, or for your internal logging and processing of payments.

Example for response via returnUrl:

(Click to see the return URL in JSON formatting. For a detailed description of the parameters see the response via onCompleteCallback handler below.)

https://httpbin.org/get?reference=TVO817932102&status=success&amount=4000&payment_method=credit_card&sig=b1a30dbe88e65d1f5b055efa511a4c2094716ccd86c1a8b65c514b6e26fff8d7

Example for response via onCompleteCallback handler:

amount decimal

The amount that is now held on the card.

payment_method string

Always credit_card since Pre-Authorization Payments are only possible with credit cards.

reference string

The payment reference.

What is the payment reference?

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

sig string

The sig is a cryptographic signature generated by Flywire that verifies that the data has not been altered during transmission. The sig is returned via returnUrl or the onCompleteCallback handler (depending on which one you are using). You can use it to verify the other parameters in the response, see Signature Verification.

status string

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

Possible values:

success	The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.
error	The communication with the external system was successful, but no charge will happen. The external system refused the charge.
active	Only for scheduled payments and subscriptions. The scheduled payment(s) or subscription has successfully been created and is now active.
pending	Always returned for bank transfer payments and never returned for online payments. The payment creation was successful, but since the payer has to make a bank transfer manually, Flywire doesn't know if and when this will happen.

{
"args": {
	"amount": "4000",
	"payment_method": "credit_card",
	"reference": "TVO817932102",
	"sig": "b1a30dbe88e65d1f5b055efa511a4c2094716ccd86c1a8b65c514b6e26fff8d7",
	"status": "success"
},

Information returned via callback

After the payment is successfully created you'll receive two callbacks:

1. Initiated (the usual callback for all new payments, see Payment Status Notifications for details)

   More info about status initiated

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

   Definition of a "payment" within the Flywire system

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

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

      What is the payment reference?

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

      Format:

      Either: ABC123456789

      3-letter portal/recipient ID 9 numbers

      Or: 1AB12CD452ABC1D

      number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

   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.

2. Authorized (a special callback just for Pre-Authorization Payments)

   More info about status authorized

   Only for Pre-Authorization Payments.

   What is a Pre-Authorization Payment?

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

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

   Example for a Pre-Authorization Payment:

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

   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 is 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. The period starts from the day the Pre-Authorization Payment is created.

   If you want to hold funds for longer, you can extend the holding period.

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

   The blocked amount returns back to the cardholder's credit:

   • if you don't capture the funds within the holding period

   • if you cancel a Pre-Authorization Payment (immediately after cancelling)

Callback for Status "Authorized"

event_type string

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

event_date date

The time when the event (status change) occurred.

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

Understanding the time zone in the timestamp

The last part of a timestamp indicates the time zone:

• Z → Means UTC (Coordinated Universal Time).

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

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

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

event_resource string

The resource that has generated the notification.

Possible values:

• payments

• charges

data object

payment_id string

The payment reference.

What is the payment reference?

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

amount_from string

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.

currency_from string

The payer currency.

Format:

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

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

amount_to string

The payment amount in the billing currency.

What is the billing currency?

The billing currency is the currency in which the recipient of the payment is billing their payer. The billing currency depends on the portal's configuration and is defined when the portal 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_to string

The billing currency.

Format:

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

What is the billing currency?

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

status string

The current status of the payment.

Possible statuses

A payment can have the following statuses and notifications:

Status	Notification	Description
Initiated	initiated	The payment status initiated is the status for all new payments in Flywire. No funds have been received by Flywire at the initiated stage. Definition of a "payment" within the Flywire system In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire:  A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process. What is the payment reference? The payment reference is an ID generated by Flywire to identify a payment. Format: Either: ABC123456789 3-letter portal/recipient ID 9 numbers Or: 1AB12CD452ABC1D number 8 alphanums number 5-alphanum portal/recipient ID With the payment reference, the payment can be tracked through the different stages of the payment process. The payment reference is also important in other situations, for example: When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds. The payment reference helps Flywire to identify the payment if you or your payer needs support. When the payment reference is assigned, two things happen: The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency). The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.
	authorized	Only for Pre-Authorization Payments. What is a Pre-Authorization Payment? A Pre-Authorization Payment temporary reserves the payment amount on a debit or credit card. The purpose of a pre-authorization is to verify that the cardholder has sufficient credit available to cover a transaction and to temporarily set aside that amount until you capture the funds. Pre-Authorization Payments are only available for same-currency payments, not for FX payments. Example for a Pre-Authorization Payment: A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay. Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged. During the Stay: The guest orders room service for $50. Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit. The payment has been authorized and is now in the holding period. How long is 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. The period starts from the day the Pre-Authorization Payment is created. If you want to hold funds for longer, you can extend the holding period. If you want to release the block on the funds before the holding period ends, you can cancel the Pre-Authorization Payment. The blocked amount returns back to the cardholder's credit: if you don't capture the funds within the holding period if you cancel a Pre-Authorization Payment (immediately after cancelling)
	adjusted	Only for Pre-Authorization Payments. What is a Pre-Authorization Payment? A Pre-Authorization Payment temporary reserves the payment amount on a debit or credit card. The purpose of a pre-authorization is to verify that the cardholder has sufficient credit available to cover a transaction and to temporarily set aside that amount until you capture the funds. Pre-Authorization Payments are only available for same-currency payments, not for FX payments. Example for a Pre-Authorization Payment: A guest checks into a hotel for a three-night stay, and you place a pre-authorization on their credit card for the estimated cost of the stay. Check-In: You pre-authorizes $600 on the guest's credit card ($150 per night plus $150 deposit). This reduces the guest's available credit by $600 but is not yet charged. During the Stay: The guest orders room service for $50. Check-Out: The final bill is $500 ($450 for room charges plus $50 for room service). You capture $500 from the pre-authorization. The remaining $100 from the original hold is returned to the guest's available credit. The amount that is being held on the card has been adjusted.
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.
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 , online (PayPal etc.) or direct debit payments. It occurs when there’s an issue to capture the funds. The notification will contain the reason for the failure. Any subsequent attempt will either trigger another failed status or alternatively processed if the retry succeeds.
Cancelled	cancelled	The payment status Cancelled means that the payment will not be processed. If Flywire already received the funds, Flywire will return the funds to the payer.
Reversed	reversed	This status has different meaning depending on the context: 1. Reversed type "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. 2. Reversed type "unpaid" This reversed type is only relevant for direct debits payments. The status occurs when you (the client) received the funds from Flywire but Flywire did not receive the funds from your payer's bank account. From a technical side this means: The payment went into the delivered status (which means you received the funds from Flywire). Then the payment fails and remains unpaid (which means Flywire did not receive the funds). What does it mean when a direct debit payment is unpaid? A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc. Then Flywire will start a recovery process and the payment status will change from delivered to reversed. Note that if the payment fails in an earlier status (processed or guaranteed) the payment will be cancelled instead of reversed.

expiration_date date

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

For card payments:

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 is 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. The period starts from the day the Pre-Authorization Payment is created.

When does a payment expire?

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

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

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

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

external_reference string

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 callbackId parameter when you created the payment.

country string

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

payment_method object

type string

The payment method type.

Possible values:

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

fields object

These are the fields of the recipient (also called "custom fields of a portal") . The fields are returned as pairs of the field id (for example booking_reference) and the value (for example ID123456). Which fields are returned depends on the individual configuration of the recipient.

More info about recipient fields

Custom fields are fields that are specific to your portal.

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 reach out to your Flywire contact if you require payer information to be returned.

first_name string

The payer's first name.

last_name string

The payer's last name.

middle_name string

The payer's middle name.

address1 string

The payer's first line of address.

address2 string

The payer's second line of address.

city string

The payer's city.

zip string

The payer's zip code.

country string

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

state string

The payer's state.

phone string

The payer's phone number.

email string

The payer's email address.

{
  "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":{ 
		"booking_reference": "ID123456",
		"booking_description": "A description"
	}, 
	"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]"
    },						
  }
}

Next Step: Capturing the Funds

Capturing the funds can be done via the Flywire API, see Capturing the Funds for a Pre-Authorization Payment.