Payment Requests

List of endpoints

Description

Endpoint
Getting a List of all Payment Requests

GET/commercial/v1/payment-requests

Getting Details about a Payment Request

GET/commercial/v1/payment-requests/{paymentRequestID}

Creating a Payment Request

POST/commercial/v1/payment-requests

Editing a Payment Request

PATCH/commercial/v1/payment-requests/{paymentRequestID}

Cancelling a Payment Request

PATCH/commercial/v1/payment-requests/{paymentRequestID}/status

Deleting a Payment Request

DELETE/commercial/v1/payment-requests/{paymentRequestID}

 

About the Payment Request Resource

The Payment Request resource enables you to create and manage Payment Requests.

A Payment Request is a way to ask your customer to make a payment, typically by sending them a link. Unlike links for standalone payments, links to a Payment Request are stateful, which means they retain the information if a payment has already been made.

image

For a single payment, the link shows the amount to pay. Since the link is stateful, visiting the link again after the payment is made shows the information that the amount is already paid.
image

For multiple installments, the link shows an overview about all installments in this request and lets the payer pay for them individually. Since the link is stateful, the overview gets updated whenever a payment is made.
image

For subscriptions, the payer can save the payment method for all payments of this subscription. They also get an overview about past and upcoming payments of this subscription. Since the link is stateful, the overview gets updated whenever a payment is made.

Payment Requests also serve as an umbrella sitting on top of one or multiple payments. In Dashboard, the Payment Request tab shows you all different kinds of Payment Requests:

Another benefit compared to standalone payments is that Payments Requests can be edited after they are created, for example, you can add more payments to it (see Managing Payment Requests).

If your goal is only to create links to Payment Requests that you can give to your payer, be aware that there are two ways to create Payment Request links: via query parameters and via API requests. Which one you should use depends on your use case and the level of integration you want to achieve.

To create links, you have two options:

1) Build the link with image Pay-By-Link using query parameters (see Payment Request Links).

  • When you are using query parameters, you can only create links for a Payment Request with a single payment.

  • When building Payment Request links via query parameters, you must include a unique value, like a booking reference. This ensures that the system generates a unique Payment Request ID. If the query parameters and values are identical, the same Payment ID will be generated.

2) Build the link with the imageFlywire API (see Payment Requests or Subscriptions).

  • With the API, you can create Payment Requests (with single payments or multiple installments, with or without a due date) and subscriptions.

  • You don't need a unique identifier value since the API will generate a unique ID independently of the parameter values.

Getting a List of all Payment Requests

Request

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

Which Payment Requests will be returned in the list?

The list will contain all Payment Requests you have access to, meaning all Payment Requests that have been created for portals that are assigned to your company.

If a Payment Request has been deleted, it won't be returned in the list, see Deleting a Payment Request.

Example for displaying a list of Payment Requests

Each parameter can be used as a column (for example the status). Check the response to see which parameters are returned in the list.

image

 

Parameters for the Request Body

No request body needed.

Optional Query Parameters for Filtering

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

You can filter the list for a status. Possible values:

ACTIVE The Payment Request is active - this is the normal state without any issues.
CANCELLED The Payment Request has been cancelled via the API or Dashboard.
PAID All installments of the Payment Request have been fully paid.
FAILED The Payment Request has at least one FAILED installment.
In the context of the API, the value is in uppercase.
In the context of Payment Request callbacks, this value is in lowercase.

You can filter the list by recipient ID (also called portal code).

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)

Enables you to filter the list to items created after the specified date/time.

You can define the date/time in two different formats:

Date only

YYYY-MM-DD, for example 2025-05-18.

Timestamp

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

Enables you to filter the list to items created before the specified date/time.

You can define the date/time in two different formats:

Date only

YYYY-MM-DD, for example 2025-05-18.

Timestamp

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

Optional Query Parameters for Pagination

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

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

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

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

Possible values: min 1, max 100

GET/commercial/v1/payment-requests 

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

Response

Pagination Parameters

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

The total number of pages available.

The current page of the results.

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

paymentRequests array

The unique identifier of the Payment Request or subscription.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

The Payment Request link that you give to your payer. The link can be accessed through a browser without authentication.

image

For a single payment, the link shows the amount to pay. Since the link is stateful, visiting the link again after the payment is made shows the information that the amount is already paid.
image

For multiple installments, the link shows an overview about all installments in this request and lets the payer pay for them individually. Since the link is stateful, the overview gets updated whenever a payment is made.
image

For subscriptions, the payer can save the payment method for all payments of this subscription. They also get an overview about past and upcoming payments of this subscription. Since the link is stateful, the overview gets updated whenever a payment is made.

The date and time the Payment Request (or subscription) was created.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The date and time the Payment (or subscription) has been updated the last time in the Flywire system.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The current status of the Payment Request.

ACTIVE The Payment Request is active - this is the normal state without any issues.
CANCELLED The Payment Request has been cancelled via the API or Dashboard.
PAID All installments of the Payment Request have been fully paid.
FAILED The Payment Request has at least one FAILED installment.
In the context of the API, the value is in uppercase.
In the context of Payment Request callbacks, this value is in lowercase.

recipient object

The portal code for this portal (also called recipient).

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)

fields array

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.

Identifier of the field.

The value for this field.

The billing currency.

Format:

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

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.

payments array

This array contains all payments associated with the Payment Request. Only payments that have already been created (meaning they have a payment reference) are included in this array. Upcoming payments that haven't been created yet are not included.

The payment reference.

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

The current status of the payment.

A payment can have the following statuses and notifications:

Status Notification Description

Initiated

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

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

image adjusted

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 amount that is being held on the card has been adjusted.

Processed

image 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

image 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

image 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

image 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

image 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

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

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.

sender object

Contains the payer information.

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

address object

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's state.

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

The payer's zip code.

Example: SW1A

installments array

This array contains the installments of the Payment Request or subscription.

The installment ID.

The installment ID is a unique identifier generated by Flywire to identify an installment within a Payment Request or a subscription.

Format:

123456

6 numbers

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

If there already has been a payment (partial or full) for the installment, the paid amount is stated here 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 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 remaining to be paid for this installment 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 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 current status of the installment.

Possible values:

NOT_INITIATED No payments have been initiated for this installment.
FAILED

The FAILED status means an installment has a payment attached to it that is either in status Failed or Cancelled.

There is no subsequent payment attached to this installment that fixed the issue.

A subscription will no longer generate further installments until the issues for this installment have been fixed.
VERIFICATION A payment has been charged for this installment, but it is still in a verification state and hasn't reached the Guaranteed status yet.
PAID The installment has been fully paid.
CANCELLED The installment has been cancelled via the imageFlywire API or Client Dashboard.

For Payment Requests:

If no date is returned, the installment doesn't have a due date. For multiple installments, note that either all have a due date or none do.

For subscriptions:

Installments for subscriptions always have a due date.

The due date on which to process the payment and collect the amount.

Format:

YYYY-MM-DD, for example 2025-05-18.

Payments are processed by Flywire at 08:00 (8am) UTC every day.

payments array

Contains the payment reference(s) of any payments associated with this installment. The array is empty if no payment has been created for the installment yet.

There is an additional payments array in root which gives you more information about the payment status.

tags array

Contains events for Payment Requests and subscriptions. Can be used for displaying a history of events.

Name of the event. Possible values are:

SENT Flywire sent the initial email to the payer, informing them that a Payment Request or subscription has been created.
SEEN The payer opened the Flywire payment page for the Payment Request or subscription.
REMINDER

Flywire sent a reminder email to the payer.
CARD_REMINDER

Flywire sent a request to the payer to update their card details.

CARD_SAVED

The payer has saved a card for recurring payments.
CARD_REMOVED

The payer had removed a saved card.
IGNORE_OVERPAYMENT

There was an overpayment for this payment and a warning message was shown in the Client Dashboard. A user dismissed the warning message by clicking the "Dismiss" button and now the warning won't be shown again.
EXPIRED_NOTIFICATION

Flywire sent an email to the payer, indicating that the Payment Request or subscription is no longer valid because the expiration date has passed.

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.
EXPIRATION_REMINDER

Flywire sent an email to the payer to remind them that there are 24 hours remaining before the Payment Request or subscription expires.

The time and date when the even occurred.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The expiration date of the Payment Request or subscription (if it has one).

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

{
  "totalEntries": 22,
  "totalPages": 2,
  "page": 0,
  "perPage": 10,
  "paymentRequests": [
{
	"id": "7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"publicLink": "https://app.flywire.com/rest/payment-request/pay/public/7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"createTime": "2024-08-13T06:33:33Z",
	"updateTime": "2024-08-13T06:33:33Z",
	"status": "ACTIVE",
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
	"currency": "EUR",
	"payments": [
		{
			"id": "TVO802017131",
			"status": "delivered"
		}
	],	
      "sender": {
        "firstName": "Troy",
        "lastName": "Traveler",
        "email": "[email protected]",
        "phone": "+441234567890",
        "address": {
          "street1": "123 Fake Street",
          "street2": "Apt 4B, Dream Tower",
          "city": "Faketown",
          "state": "Imaginaryshire",
          "country": "GB",
          "postalCode": "AB1 2CD"
        }
      }, 
      "installments": [
        {
          "id": 134312,
          "amount": 50000,
		  "amountPaid": 0,
          "amountDue": 50000,
		  "serviceDescription": "This is the second installment",
          "status": "NOT_INITIATED",
		  "date": "2025-03-31",
          "payments": []
        },
        {
          "id": 134311,
          "amount": 60000,
		  "amountPaid": 60000,
          "amountDue": 60000,
		  "serviceDescription": "This is the first installment",
          "status": "PAID",
		  "date": "2025-02-31",
          "payments": [
            "TVO227007381"
          ]
        }
      ],
	"tags": [
		{
		"name": "SENT",
		"date": "2024-08-13T06:33:32"
		},
		{
		"name": "SEEN",
		"date": "2024-08-30T09:51:13"
		}
	],
	"expirationDate": null
	},
...
  ]
}

Getting Details about a Payment Request

Request

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

Example for displaying details of a Payment Request

Check the response to see which details are returned so you can display them.

image

 

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentRequestID} in the endpoint with the Payment Request ID.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

Where can I find the Payment Request ID?

With the imageFlywire API:

The ID is returned in the response after creating a Payment Request.

You can also find them in the list of all Payment Requests.

With imageCheckout :

If you created a Payment Request via Checkout, you can find the ID in the reference parameter that is returned to you either via the returnUrl or the onCompleteCallback handler.

With imageClient Dashboard:

If you are using Dashboard, you find the Payment Request link (which includes the ID) in the Payment Request details as long as the Payment Request is still open.

 

Parameters for the Request Body

No request body needed.

GET/commercial/v1/payment-requests/{paymentRequestID} 

curl https://base-url-placeholder/payment-requests/959c09e5-a27b-49e9-8f92-e9e13374cfdd
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

The unique identifier of the Payment Request or subscription.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

The Payment Request link that you give to your payer. The link can be accessed through a browser without authentication.

image

For a single payment, the link shows the amount to pay. Since the link is stateful, visiting the link again after the payment is made shows the information that the amount is already paid.
image

For multiple installments, the link shows an overview about all installments in this request and lets the payer pay for them individually. Since the link is stateful, the overview gets updated whenever a payment is made.
image

For subscriptions, the payer can save the payment method for all payments of this subscription. They also get an overview about past and upcoming payments of this subscription. Since the link is stateful, the overview gets updated whenever a payment is made.

The date and time the Payment Request (or subscription) was created.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The date and time the Payment (or subscription) has been updated the last time in the Flywire system.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The current status of the Payment Request.

ACTIVE The Payment Request is active - this is the normal state without any issues.
CANCELLED The Payment Request has been cancelled via the API or Dashboard.
PAID All installments of the Payment Request have been fully paid.
FAILED The Payment Request has at least one FAILED installment.
In the context of the API, the value is in uppercase.
In the context of Payment Request callbacks, this value is in lowercase.

recipient object

The portal code for this portal (also called recipient).

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)

fields array

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.

Identifier of the field.

The value for this field.

The billing currency.

Format:

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

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.

payments array

This array contains all payments associated with the Payment Request. Only payments that have already been created (meaning they have a payment reference) are included in this array. Upcoming payments that haven't been created yet are not included.

The payment reference.

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

The current status of the payment.

A payment can have the following statuses and notifications:

Status Notification Description

Initiated

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

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

image adjusted

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 amount that is being held on the card has been adjusted.

Processed

image 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

image 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

image 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

image 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

image 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

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

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.

sender object

Contains the payer information.

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

address object

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's state.

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

The payer's zip code.

Example: SW1A

installments array

This array contains the installments of the Payment Request or subscription.

The installment ID.

The installment ID is a unique identifier generated by Flywire to identify an installment within a Payment Request or a subscription.

Format:

123456

6 numbers

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

If there already has been a payment (partial or full) for the installment, the paid amount is stated here 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 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 remaining to be paid for this installment 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 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 current status of the installment.

Possible values:

NOT_INITIATED No payments have been initiated for this installment.
FAILED

The FAILED status means an installment has a payment attached to it that is either in status Failed or Cancelled.

There is no subsequent payment attached to this installment that fixed the issue.

A subscription will no longer generate further installments until the issues for this installment have been fixed.
VERIFICATION A payment has been charged for this installment, but it is still in a verification state and hasn't reached the Guaranteed status yet.
PAID The installment has been fully paid.
CANCELLED The installment has been cancelled via the imageFlywire API or Client Dashboard.

For Payment Requests:

If no date is returned, the installment doesn't have a due date. For multiple installments, note that either all have a due date or none do.

For subscriptions:

Installments for subscriptions always have a due date.

The due date on which to process the payment and collect the amount.

Format:

YYYY-MM-DD, for example 2025-05-18.

Payments are processed by Flywire at 08:00 (8am) UTC every day.

payments array

Contains the payment reference(s) of any payments associated with this installment. The array is empty if no payment has been created for the installment yet.

There is an additional payments array in root which gives you more information about the payment status.

tags array

Contains events for Payment Requests and subscriptions. Can be used for displaying a history of events.

Name of the event. Possible values are:

SENT Flywire sent the initial email to the payer, informing them that a Payment Request or subscription has been created.
SEEN The payer opened the Flywire payment page for the Payment Request or subscription.
REMINDER

Flywire sent a reminder email to the payer.
CARD_REMINDER

Flywire sent a request to the payer to update their card details.

CARD_SAVED

The payer has saved a card for recurring payments.
CARD_REMOVED

The payer had removed a saved card.
IGNORE_OVERPAYMENT

There was an overpayment for this payment and a warning message was shown in the Client Dashboard. A user dismissed the warning message by clicking the "Dismiss" button and now the warning won't be shown again.
EXPIRED_NOTIFICATION

Flywire sent an email to the payer, indicating that the Payment Request or subscription is no longer valid because the expiration date has passed.

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.
EXPIRATION_REMINDER

Flywire sent an email to the payer to remind them that there are 24 hours remaining before the Payment Request or subscription expires.

The time and date when the even occurred.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The expiration date of the Payment Request or subscription (if it has one).

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

{
	"id": "7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"publicLink": "https://app.flywire.com/rest/payment-request/pay/public/7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"createTime": "2024-08-13T06:33:33Z",
	"updateTime": "2024-08-13T06:33:33Z",
	"status": "ACTIVE",
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
	"currency": "EUR",
	"payments": [
		{
			"id": "TVO802017131",
			"status": "delivered"
		}
	],	
      "sender": {
        "firstName": "Troy",
        "lastName": "Traveler",
        "email": "[email protected]",
        "phone": "+441234567890",
        "address": {
          "street1": "123 Fake Street",
          "street2": "Apt 4B, Dream Tower",
          "city": "Faketown",
          "state": "Imaginaryshire",
          "country": "GB",
          "postalCode": "AB1 2CD"
        }
      }, 
      "installments": [
        {
          "id": 134312,
          "amount": 50000,
		  "amountPaid": 0,
          "amountDue": 50000,
		  "serviceDescription": "This is the second installment",
          "status": "NOT_INITIATED",
		  "date": "2025-03-31",
          "payments": []
        },
        {
          "id": 134311,
          "amount": 60000,
		  "amountPaid": 60000,
          "amountDue": 60000,
		  "serviceDescription": "This is the first installment",
          "status": "PAID",
		  "date": "2025-02-31",
          "payments": [
            "TVO227007381"
          ]
        }
      ],
	"tags": [
		{
		"name": "SENT",
		"date": "2024-08-13T06:33:32"
		},
		{
		"name": "SEEN",
		"date": "2024-08-30T09:51:13"
		}
	],
	"expirationDate": null
	},

Creating a Payment Request

Request

This endpoint creates a Payment Request.

Parameters for the Request Body

recipient object

The portal code for this portal (also called recipient).

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)

fields array

It depends on your settings if a custom field is optional or required.

There are two layers of required fields:

Fields that are required due to settings in your Dashboard

If a field is set to required in Client Dashboard, you must provide it when you create the Payment Request or subscription. Optional fields can be left out.

You can check the settings in imageClient Dashboard under "Settings - Payment Requests". If your user doesn't have the permissions to view this tab, you can create a new Payment Request in Dashboard and check which fields are marked as required.

Fields that are required due to settings for the portal

If a field is required for the portal, it is required to create the payment. This means if a field is not required in Dashboard but is required for the portal, you have the option to not provide it when you create the Payment Request or subscription. But since it is required to create the payment, your payer has to fill out the field in the Checkout Experience form.

You have two options:

Checking via the API

You can check which fields are required for a recipient (portal) with this request (replace {recipientId} with the recipient ID):

GET/payments/v1/recipients/{recipientId}

Required fields have the required parameter set to true. For more info see Getting Details about a Recipient.

Checking online

You can check which fields are required by checking your portal configuration.

Identifier of the field.

The value for this field.

It depends on your Dashboard settings whether and which sender (payer) fields are required.

You can check the settings in imageClient Dashboard under "Settings - Payment Requests". If your user doesn't have the permissions to view this tab, you can create a new Payment Request in Dashboard and check which fields are marked as required.

sender object

Contains the payer information.

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

address object

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's state.

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

The payer's zip code.

Example: SW1A

installments array

This array contains the installments of the Payment Request.

Help for creating installments:

To create a Payment Request for a single payment, simply add just one installment in the array.
If you are using a date, either all installments must have a date or none do.

A description of the purpose of the payment.

This description is only visible to you in Dashboard, not to the payer.

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 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 due date on which to process the payment and collect the amount. Must be a future date.

Format:

YYYY-MM-DD, for example 2025-05-18.

Payments are processed by Flywire at 08:00 (8am) UTC every day.

You can give the Payment Request or subscription an expiration date. Must be a future date.

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.

You can use two different formats:

Date only

YYYY-MM-DD, for example 2025-05-18.

Timestamp

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

If you use the date only format, the missing timestamp is automatically added as midnight, for example:  2026-08-23 is interpreted as 2026-08-23T00:00:00Z.

createOptions object

Here you can define whether the payer is required to save their selected payment method (either card or direct debit). Saving the payment method is useful for subscriptions and Payment Requests with multiple installments.

false

Default.

The payer doesn't have to save their payment method.

If there are any future installments, the payer still has the option to save their payment method after they made the payment. Note that the option is only shown if the future installments have a due date and if they payer chose a payment method that can be saved.

image

true

The payer must save their selected payment method for future use. This means the Checkout Experience will request the payer’s consent to store the payment method and consenting is required to complete the payment.

image

With this setting:

  • The Checkout Experience will only display card or direct debit payment methods to the payer since these are the payment methods that can be saved).

  • Future installments are automatically charged when due.

Defines if this is a Pre-Authorization Payment.

  • true: This is a Pre-Authorization Payment. Note that this is only available for Payment Requests with a single installment.

  • false: This is a not a Pre-Authorization Payment.

Note for Pre-Authorization Payments

Installments:

If you want to define this Payment Request as a Pre-Authorization Payment, you can only add one installment.

Payment options:

It is recommended to leave out the paymentOptionsConfig object for Pre-Authorization Payments. The system will automatically default to the appropriate configuration, meaning the Checkout Experience will only show credit cards as payment options.

If you filter the payment type manually to anything other than credit card only, you will get an error.

paymentOptionsConfig object

filters object

By default, Flywire displays all payment options for a portal. In some cases, you might want to restrict the available payment options, for example if you want to accept only bank transfers for payments over a certain amount or only show card payments a certain time before a booking.

You can use two filters to restrict payment options:

  • Restrict to specific types of payments

  • Restrict to specific currencies

Payment method type filters.

Each filter you add means show this option. Each filter you leave out means hide this option.

For example, credit_card ,online means: Show card payment options and online alternative pay options, but no bank transfer options.

If you don't provide any filters, all payment method types will be displayed in the Checkout Experience.

bank_transfer Bank transfer option - payer receives instructions how to transfer the money to Flywire
credit_card Card payment options - credit or debit cards
online Alternative online payment options - e.g. PayPal
direct_debit Direct debit option - funds are automatically withdrawn from the payer’s bank account
moto_payment MOTO (Mail Order / Telephone Order) payment – payments entered manually by a Flywire agent

Payment currency filters. The filters restrict payment options based on currencies:

local

Show only payment options in the payer's local currency (e.g., only GBP for a payer in the UK).
foreign

Show only payment options not in the payers local currency (e.g., everything but GBP options for a payer in the UK).
fx

Only show payment options that are a different currency to the billing currency (e.g., everything but GBP if your billing currency is GBP).

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

Only show payment options that are in the same currency as the billing currency (e.g., only GBP if your billing currency is GBP).

Be careful with combining those filters. Your payer might end up not being able to pay if you restrict the options too much. As a best practice, use either local/ foreign (when you want the options to depend on the payer's country) or fx / nonFX (when you want the options to depend on your billing currency).

By default, Flywire automatically sends an email after a Payment Request or subscription is created. Here you can disable the email in case you want to send this email yourself.

true (default)

Flywire sends the "Payment Request created" email to your payer.

Flywire sends the automatic emails to the payer's default email address.

The payer's default email address is the email address saved in the Flywire system.

Even if you pre-filled the payer information with an email address, your payer might have changed it when filling out the form.

This means that the default email address in the Flywire system might be different from the one you have in your system.

  1. With the imageFlywire API:

    You can look it up by Getting Details about a Payment.

  2. If you are using callbacks, you can also find the email address in the callbacks for the payment, see Payment Status Notifications.

    Note for callbacks:

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

Flywire does not send the "Payment Request created" email to your payer.

Even if this email is disabled, all other automatic emails will still be sent by Flywire. See Payment Requests and Subscriptions: Emails to Your Payer for all emails and their content.

POST/commercial/v1/payment-requests 

curl https://base-url-placeholder/payment-requests
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	}, 
      "sender": {
        "firstName": "Troy",
        "lastName": "Traveler",
        "email": "[email protected]",
        "phone": "+441234567890",
        "address": {
          "street1": "123 Fake Street",
          "street2": "Apt 4B, Dream Tower",
          "city": "Faketown",
          "state": "Imaginaryshire",
          "country": "GB",
          "postalCode": "AB1 2CD"
        }
      },
	"installments":[
         {
            "serviceDescription": "First installment",
            "amount": 12000,
            "date": "2025-06-12T11:26:19Z"
         },
         {
            "serviceDescription": "Second installment",
            "amount": 45050,
            "date": "2025-12-12"
         }
    ],
	"expirationDate": "2025-04-29T22:59:00Z",						
	"createOptions" : {
		"requireSavePaymentMethod": true,
		"preAuth": false,
		"paymentOptionsConfig" : {
			"filters": {
				"type": [
					"credit_card",
					"online",
					"direct_debit"
				],
				"currency": [
					"local",
					"foreign",
					"fx"
				]		
		},						
		"sendCreateEmail": true									
	}'

Response

The unique identifier of the Payment Request or subscription.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

The Payment Request link that you give to your payer. The link can be accessed through a browser without authentication.

image

For a single payment, the link shows the amount to pay. Since the link is stateful, visiting the link again after the payment is made shows the information that the amount is already paid.
image

For multiple installments, the link shows an overview about all installments in this request and lets the payer pay for them individually. Since the link is stateful, the overview gets updated whenever a payment is made.
image

For subscriptions, the payer can save the payment method for all payments of this subscription. They also get an overview about past and upcoming payments of this subscription. Since the link is stateful, the overview gets updated whenever a payment is made.

The date and time the Payment Request (or subscription) was created.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The date and time the Payment (or subscription) has been updated the last time in the Flywire system.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The current status of the Payment Request.

ACTIVE The Payment Request is active - this is the normal state without any issues.
CANCELLED The Payment Request has been cancelled via the API or Dashboard.
PAID All installments of the Payment Request have been fully paid.
FAILED The Payment Request has at least one FAILED installment.
In the context of the API, the value is in uppercase.
In the context of Payment Request callbacks, this value is in lowercase.

recipient object

The portal code for this portal (also called recipient).

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)

fields array

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.

Identifier of the field.

The value for this field.

The billing currency.

Format:

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

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.

payments array

This array contains all payments associated with the Payment Request. Only payments that have already been created (meaning they have a payment reference) are included in this array. Upcoming payments that haven't been created yet are not included.

The payment reference.

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

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

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

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

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

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

The current status of the payment.

A payment can have the following statuses and notifications:

Status Notification Description

Initiated

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

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

image adjusted

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 amount that is being held on the card has been adjusted.

Processed

image 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

image 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

image 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

image 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

image 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

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

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.

sender object

Contains the payer information.

The payer's first name.

The payer's last name.

The payer's email address.

The payer's phone number.

The phone number must include the area code indicated by a "plus" sign, for example +44 1234 567 890

address object

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's state.

The payer's country.

The value is stated in the 2-letter ISO country code, for example ES for Spain,

The payer's zip code.

Example: SW1A

installments array

This array contains the installments of the Payment Request or subscription.

The installment ID.

The installment ID is a unique identifier generated by Flywire to identify an installment within a Payment Request or a subscription.

Format:

123456

6 numbers

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

If there already has been a payment (partial or full) for the installment, the paid amount is stated here 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 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 remaining to be paid for this installment 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 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 current status of the installment.

Possible values:

NOT_INITIATED No payments have been initiated for this installment.
FAILED

The FAILED status means an installment has a payment attached to it that is either in status Failed or Cancelled.

There is no subsequent payment attached to this installment that fixed the issue.

A subscription will no longer generate further installments until the issues for this installment have been fixed.
VERIFICATION A payment has been charged for this installment, but it is still in a verification state and hasn't reached the Guaranteed status yet.
PAID The installment has been fully paid.
CANCELLED The installment has been cancelled via the imageFlywire API or Client Dashboard.

For Payment Requests:

If no date is returned, the installment doesn't have a due date. For multiple installments, note that either all have a due date or none do.

For subscriptions:

Installments for subscriptions always have a due date.

The due date on which to process the payment and collect the amount.

Format:

YYYY-MM-DD, for example 2025-05-18.

Payments are processed by Flywire at 08:00 (8am) UTC every day.

payments array

Contains the payment reference(s) of any payments associated with this installment. The array is empty if no payment has been created for the installment yet.

There is an additional payments array in root which gives you more information about the payment status.

tags array

Contains events for Payment Requests and subscriptions. Can be used for displaying a history of events.

Name of the event. Possible values are:

SENT Flywire sent the initial email to the payer, informing them that a Payment Request or subscription has been created.
SEEN The payer opened the Flywire payment page for the Payment Request or subscription.
REMINDER

Flywire sent a reminder email to the payer.
CARD_REMINDER

Flywire sent a request to the payer to update their card details.

CARD_SAVED

The payer has saved a card for recurring payments.
CARD_REMOVED

The payer had removed a saved card.
IGNORE_OVERPAYMENT

There was an overpayment for this payment and a warning message was shown in the Client Dashboard. A user dismissed the warning message by clicking the "Dismiss" button and now the warning won't be shown again.
EXPIRED_NOTIFICATION

Flywire sent an email to the payer, indicating that the Payment Request or subscription is no longer valid because the expiration date has passed.

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.
EXPIRATION_REMINDER

Flywire sent an email to the payer to remind them that there are 24 hours remaining before the Payment Request or subscription expires.

The time and date when the even occurred.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

The expiration date of the Payment Request or subscription (if it has one).

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

{
	"id": "7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"publicLink": "https://app.flywire.com/rest/payment-request/pay/public/7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"createTime": "2024-08-13T06:33:33Z",
	"updateTime": "2024-08-13T06:33:33Z",
	"status": "ACTIVE",
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
	"currency": "EUR",
	"payments": [
		{
			"id": "TVO802017131",
			"status": "delivered"
		}
	],	
      "sender": {
        "firstName": "Troy",
        "lastName": "Traveler",
        "email": "[email protected]",
        "phone": "+441234567890",
        "address": {
          "street1": "123 Fake Street",
          "street2": "Apt 4B, Dream Tower",
          "city": "Faketown",
          "state": "Imaginaryshire",
          "country": "GB",
          "postalCode": "AB1 2CD"
        }
      }, 
      "installments": [
        {
          "id": 134312,
          "amount": 50000,
		  "amountPaid": 0,
          "amountDue": 50000,
		  "serviceDescription": "This is the second installment",
          "status": "NOT_INITIATED",
		  "date": "2025-03-31",
          "payments": []
        },
        {
          "id": 134311,
          "amount": 60000,
		  "amountPaid": 60000,
          "amountDue": 60000,
		  "serviceDescription": "This is the first installment",
          "status": "PAID",
		  "date": "2025-02-31",
          "payments": [
            "TVO227007381"
          ]
        }
      ],
	"tags": [
		{
		"name": "SENT",
		"date": "2024-08-13T06:33:32"
		},
		{
		"name": "SEEN",
		"date": "2024-08-30T09:51:13"
		}
	],
	"expirationDate": null
	},

Editing a Payment Request

Request

This endpoint lets you edit the following settings of a Payment Request:

  • Expiration date of the Payment Request

  • Installments of the Payment Request

    The installments array you submit in the request body will completely replace the data in the existing installment array:

    Adding an installment without an ID will create a new installment.
    Adding an installment with an existing ID will edit it.
    Not adding an existing installment with its ID will remove it.
    Since the ID is used to match installments, it is not possible to edit the ID.

After the edit, an email will automatically be sent to the payer informing them about the change, see Emails for Payment Requests.

Flywire sends the automatic emails to the payer's default email address.

The payer's default email address is the email address saved in the Flywire system.

Even if you pre-filled the payer information with an email address, your payer might have changed it when filling out the form.

This means that the default email address in the Flywire system might be different from the one you have in your system.

  1. With the imageFlywire API:

    You can look it up by Getting Details about a Payment.

  2. If you are using callbacks, you can also find the email address in the callbacks for the payment, see Payment Status Notifications.

    Note for callbacks:

    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.

 

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentRequestID} in the endpoint with the Payment Request ID.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

Where can I find the Payment Request ID?

With the imageFlywire API:

The ID is returned in the response after creating a Payment Request.

You can also find them in the list of all Payment Requests.

With imageCheckout :

If you created a Payment Request via Checkout, you can find the ID in the reference parameter that is returned to you either via the returnUrl or the onCompleteCallback handler.

With imageClient Dashboard:

If you are using Dashboard, you find the Payment Request link (which includes the ID) in the Payment Request details as long as the Payment Request is still open.

Parameters for the Request Body

Installments

The installments array you submit in the request body will completely replace the data in the existing installment array:

Adding an installment without an ID will create a new installment.
Adding an installment with an existing ID will edit it.
Not adding an existing installment with its ID will remove it.
Since the ID is used to match installments, it is not possible to edit the ID.

The installment ID.

The installment ID is a unique identifier generated by Flywire to identify an installment within a Payment Request or a subscription.

Format:

123456

6 numbers

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

A description of the purpose of the payment.

This description is only visible to you in Dashboard, not to the payer.

The due date on which to process the payment and collect the amount. Must be a future date.

Format:

YYYY-MM-DD, for example 2025-05-18.

Payments are processed by Flywire at 08:00 (8am) UTC every day.

Expiration date

If there was no expiration date, you can add one with this parameter.
If there already was an expiration date, you can overwrite it with this parameter.
You can remove an existing expiration date by leaving this parameter out or by submitting it as empty ("").
Note that leaving out the parameter doesn't leave the expiration date unchanged. Leaving it out will remove the expiration date.

You can give the Payment Request or subscription an expiration date. Must be a future date.

Expiration dates limit the time a Payment Request or subscription can be paid, for example in cases like event registrations or invoices with late fees. Once expired, no payments can be made. Setting an expiration date is optional.

The expiration date applies to the entire Payment Request (or subscription), preventing any payments after it passes. In contrast, a due date applies to an individual payment within a Payment Request (or subscription), and payments can still be paid after the due date.

You can use two different formats:

Date only

YYYY-MM-DD, for example 2025-05-18.

Timestamp

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

The last part of a timestamp indicates the time zone:

  • Z → Means UTC (Coordinated Universal Time).

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

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

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

If you use the date only format, the missing timestamp is automatically added as midnight, for example:  2026-08-23 is interpreted as 2026-08-23T00:00:00Z.

PATCH/commercial/v1/payment-requests/{paymentRequestID} 

curl https://base-url-placeholder/payment-requests/959c09e5-a27b-49e9-8f92-e9e13374cfdd
  -X PATCH
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
    "installments":[
         {
           "id": 2411941,
           "amount": 12055,
           "serviceDescription": "edited installment",
		   "date": "2026-05-18"
        }
    ],
    "expirationDate": "2026-02-18T14:57:36Z"
}'

Response

A 204 response will let you know that the installments have successfully been updated.

An email will now automatically be sent to the payer informing them about the change, see Emails for Payment Requests.

Flywire sends the automatic emails to the payer's default email address.

The payer's default email address is the email address saved in the Flywire system.

Even if you pre-filled the payer information with an email address, your payer might have changed it when filling out the form.

This means that the default email address in the Flywire system might be different from the one you have in your system.

  1. With the imageFlywire API:

    You can look it up by Getting Details about a Payment.

  2. If you are using callbacks, you can also find the email address in the callbacks for the payment, see Payment Status Notifications.

    Note for callbacks:

    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.

204 NO CONTENT

Cancelling a Payment Request

Request

Cancelling a Payment Request or a subscription means:

  • It is permanently put in the CANCELLED status.

  • All future installments will cancelled and payments will not be charged.

  • Your customer will be notified about the cancellation via email and won't be able to make payments anymore.

Cancelling a Payment Request or subscription cannot be undone.

Unlike deleting, cancelling does not remove the Payment Request or subscription from the system, meaning you will still be able to view it in Dashboard and retrieve it via the API.

Deleting Cancelling

Deleting a Payment Request or subscription permanently removes it from the system, which means:

  • You can't view it in Dashboard anymore.

  • You can't retrieve it via the API anymore.

  • All future installments will cancelled.

  • Your customer won't be able to make payments anymore.

Deleting a Payment Request or subscription cannot be undone.

Cancelling a Payment Request or a subscription means:

  • It is permanently put in the CANCELLED status.

  • All future installments will cancelled and payments will not be charged.

  • Your customer will be notified about the cancellation via email and won't be able to make payments anymore.

Cancelling a Payment Request or subscription cannot be undone.

Unlike deleting, cancelling does not remove the Payment Request or subscription from the system, meaning you will still be able to view it in Dashboard and retrieve it via the API.

 

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentRequestID} in the endpoint with the Payment Request ID.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

Where can I find the Payment Request ID?

With the imageFlywire API:

The ID is returned in the response after creating a Payment Request.

You can also find them in the list of all Payment Requests.

With imageCheckout :

If you created a Payment Request via Checkout, you can find the ID in the reference parameter that is returned to you either via the returnUrl or the onCompleteCallback handler.

With imageClient Dashboard:

If you are using Dashboard, you find the Payment Request link (which includes the ID) in the Payment Request details as long as the Payment Request is still open.

Parameters for the Request Body

Must be CANCEL

You can optionally provide an email address where the cancellation email gets sent to.

If you don't provide an email address, Flywire will use the payer's default email address.

The payer's default email address is the email address saved in the Flywire system.

Even if you pre-filled the payer information with an email address, your payer might have changed it when filling out the form.

This means that the default email address in the Flywire system might be different from the one you have in your system.

  1. With the imageFlywire API:

    You can look it up by Getting Details about a Payment.

  2. If you are using callbacks, you can also find the email address in the callbacks for the payment, see Payment Status Notifications.

    Note for callbacks:

    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.

See Payment Requests and Subscriptions: Emails to Your Payer for the content of the cancellation email.

PATCH/commercial/v1/payment-requests/{paymentRequestID}/status 

curl https://base-url-placeholder/payment-requests/959c09e5-a27b-49e9-8f92-e9e13374cfdd/status
  -X PATCH
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"statusChange" : "CANCEL",
	"cancelNotificationAddress" : "[email protected]"
	}'

Response

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

The cancellation email will automatically be sent to the address you provided. See Emails for Payment Requests for the content of the email.

204 NO CONTENT

Deleting a Payment Request

Request

Deleting a Payment Request or subscription permanently removes it from the system, which means:

  • You can't view it in Dashboard anymore.

  • You can't retrieve it via the API anymore.

  • All future installments will cancelled.

  • Your customer won't be able to make payments anymore.

Deleting a Payment Request or subscription cannot be undone.

Deleting Cancelling

Deleting a Payment Request or subscription permanently removes it from the system, which means:

  • You can't view it in Dashboard anymore.

  • You can't retrieve it via the API anymore.

  • All future installments will cancelled.

  • Your customer won't be able to make payments anymore.

Deleting a Payment Request or subscription cannot be undone.

Cancelling a Payment Request or a subscription means:

  • It is permanently put in the CANCELLED status.

  • All future installments will cancelled and payments will not be charged.

  • Your customer will be notified about the cancellation via email and won't be able to make payments anymore.

Cancelling a Payment Request or subscription cannot be undone.

Unlike deleting, cancelling does not remove the Payment Request or subscription from the system, meaning you will still be able to view it in Dashboard and retrieve it via the API.

 

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentRequestID} in the endpoint with the Payment Request ID.

This ID has been automatically generated when the Payment Request or subscription was created.

This ID is publicly visible at the end of the Payment Request link, for example:

https://app.flywire.com/rest/payment-request/pay/public/959c09e5-a27b-49e9-8f92-e9e13374cfdd

Format:

959c09e5-a27b-49e9-8f92-e9e13374cfdd

32 hexadecimal characters grouped into 8-4-4-4-12

Where can I find the Payment Request ID?

With the imageFlywire API:

The ID is returned in the response after creating a Payment Request.

You can also find them in the list of all Payment Requests.

With imageCheckout :

If you created a Payment Request via Checkout, you can find the ID in the reference parameter that is returned to you either via the returnUrl or the onCompleteCallback handler.

With imageClient Dashboard:

If you are using Dashboard, you find the Payment Request link (which includes the ID) in the Payment Request details as long as the Payment Request is still open.

Parameters for the Request Body

No request body needed.

DELETE/commercial/v1/payment-requests/{paymentRequestID} 

curl https://base-url-placeholder/payment-requests/959c09e5-a27b-49e9-8f92-e9e13374cfdd
  -X DELETE
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

A 204 response will let you know that the Payment Request has been successfully deleted.

204 NO CONTENT