Subscriptions

List of endpoints

Description

Endpoint
Getting a List of all Subscriptions

GET/commercial/v1/subscriptions

Getting Details about a Subscription

GET/commercial/v1/subscriptions/{subscriptionID}

Creating a Subscription

POST/commercial/v1/subscriptions

Editing a Subscription

PATCH/commercial/v1/subscriptions/{subscriptionID}

Pausing, Resuming, or Cancelling a Subscription

PATCH/commercial/v1/subscriptions/{subscriptionID}/status

Cancelling an Installment of a Subscription

PATCH/commercial/v1/subscriptions/{subscriptionID}/installment/{installmentID}/status

Deleting a Subscription

DELETE/commercial/v1/subscriptions/{subscriptionID}

 

About the Subscriptions Resource

The subscriptions resource enables you to manage Subscriptions.

Getting a List of all Subscriptions

Request

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

Which subscriptions 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 subscription has been deleted, it won't be returned in the list, see Deleting a Subscription.

Example for displaying a list of subscriptions

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 subscription is active - this is the normal state without any issues.
CANCELLED The subscription has been cancelled via the API or Dashboard.
PAID The subscription has reached its end date, it has at least one PAID installment, and all other installments are either PAID or CANCELLED.
FAILED The subscription has at least one FAILED installment.
PAUSED The subscription has been paused via the API or Dashboard.
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/subscriptions 

curl https://base-url-placeholder/subscriptions
  -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).

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

ACTIVE The subscription is active - this is the normal state without any issues.
CANCELLED The subscription has been cancelled via the API or Dashboard.
PAID The subscription has reached its end date, it has at least one PAID installment, and all other installments are either PAID or CANCELLED.
FAILED The subscription has at least one FAILED installment.
PAUSED The subscription has been paused via the API or Dashboard.
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 subscription. 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).

subscription object

Contains information about the subscription.

The date when the first payment of the subscription will be collected.

Format:

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

The last date on which a payment for this subscription will be collected.

Format:

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

If the subscription has been paused: The date when the subscription is automatically resumed.

The resumeDate parameter is only returned if the subscription is PAUSED and has an automatic resume date.

Format:

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

You can pause and resume subscriptions via the imageFlywire API (see Pausing, Resuming, or Cancelling a Subscription) or imageClient Dashboard.

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.

cadence object

Contains the intervals at which payments are collected.

Example: For collecting a payment every 2 weeks set occurance to 2 and timeUnit to WEEKS.

Defines how many units of time (timeUnit) should pass between each payment.

Specifies the unit of time, for example weeks or years, for the occurrence.

Possible values:

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

If there is an initial amount for the subscription: the amount to be charged as an immediate payment.

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 you're hosting your own subscription management page for payers, provide the link here. This allows payers to manage their subscriptions outside of Flywire.

This option is only available for subscriptions, not for Payment Requests.

A description of the purpose of the payment.

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

{
  "totalEntries": 22,
  "totalPages": 2,
  "page": 0,
  "perPage": 10,
  "subscriptions": [
 {
	"id": "7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"publicLink": "https://app.flywire.com/rest/payment-request/pay/public/4bde36d9-482e-42c7-994c-cc1225531ae9",
	"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": 134311,
          "amount": 50000,
		  "amountPaid": 0,
          "amountDue": 50000,
          "status": "NOT_INITIATED",
		  "date": "2025-03-31",
          "payments": []
        },
        {
          "id": 134312,
          "amount": 60000,
		  "amountPaid": 60000,
          "amountDue": 60000,
          "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
	},
	"subscription": {
       "startDate": "2025-06-20",
       "endDate": "2028-06-01",
	   "resumeDate": null,
       "amount": 100000,
       "cadence": {
           "occurrence": 1,
           "timeUnit": "MONTHS"
       },
	   "initialAmount": 90000,
   	   "manageLink": "https://my-manage-link.example",					
	},
	"serviceDescription": "Gold Membership subscription"
},
[...]
}

Getting Details about a Subscription

Request

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

Example for displaying details of a subscription

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

 

How to Resolve the Path Placeholders of the Endpoint

Replace {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

 

Parameters for the Request Body

No request body needed.

GET/commercial/v1/subscriptions/{subscriptionID} 

curl https://base-url-placeholder/subscriptions/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 subscription.

ACTIVE The subscription is active - this is the normal state without any issues.
CANCELLED The subscription has been cancelled via the API or Dashboard.
PAID The subscription has reached its end date, it has at least one PAID installment, and all other installments are either PAID or CANCELLED.
FAILED The subscription has at least one FAILED installment.
PAUSED The subscription has been paused via the API or Dashboard.
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.

paymentsarray

This array contains all payments associated with the subscription. 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).

subscription object

Contains information about the subscription.

The date when the first payment of the subscription will be collected.

Format:

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

The last date on which a payment for this subscription will be collected.

Format:

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

If the subscription has been paused: The date when the subscription is automatically resumed.

The resumeDate parameter is only returned if the subscription is PAUSED and has an automatic resume date.

Format:

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

You can pause and resume subscriptions via the imageFlywire API (see Pausing, Resuming, or Cancelling a Subscription) or imageClient Dashboard.

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.

cadence object

Contains the intervals at which payments are collected.

Example: For collecting a payment every 2 weeks set occurance to 2 and timeUnit to WEEKS.

Defines how many units of time (timeUnit) should pass between each payment.

Specifies the unit of time, for example weeks or years, for the occurrence.

Possible values:

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

If there is an initial amount for the subscription: the amount to be charged as an immediate payment.

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 you're hosting your own subscription management page for payers, provide the link here. This allows payers to manage their subscriptions outside of Flywire.

This option is only available for subscriptions, not for Payment Requests.

A description of the purpose of the payment.

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

{
	"id": "7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"publicLink": "https://app.flywire.com/rest/payment-request/pay/public/4bde36d9-482e-42c7-994c-cc1225531ae9",
	"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": 134311,
          "amount": 50000,
		  "amountPaid": 0,
          "amountDue": 50000,
          "status": "NOT_INITIATED",
		  "date": "2025-03-31",
          "payments": []
        },
        {
          "id": 134312,
          "amount": 60000,
		  "amountPaid": 60000,
          "amountDue": 60000,
          "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
	},
	"subscription": {
       "startDate": "2025-06-20",
       "endDate": "2028-06-01",
	   "resumeDate": null,
       "amount": 100000,
       "cadence": {
           "occurrence": 1,
           "timeUnit": "MONTHS"
       },
	   "initialAmount": 90000,
   	   "manageLink": "https://my-manage-link.example",					
	},
	"serviceDescription": "Gold Membership subscription"
}

Creating a Subscription

Request

Tips for creating subscriptions

Installments:

For subscriptions, you don't define the individual installments, since they are generated based on the set of rules you define for this subscription.

You can add or edit installments later, but the first installment of the subscription is always automatically generated.
If the first installment is due today, a second installment is also automatically generated (based on the cadence).

Initial amount:

All installments for a subscription have the same amount, but you have the option to charge a different initial amount - for example for an initial membership fee.

If the first installment is due today, the initial amount is added to that first installment.
If the first installment is in the future, a separate installment for the initial amount is created and is due today.

Start and due date:

You can collect the first installment immediately by leaving out the start date.

If no start date is defined, the first due date is today.
If a start date is defined, the start date is the first due date.

 

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

A description of the purpose of the payment.

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

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.

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.

subscription object

Contains the rules that you want to define for the the subscription.

The date when the first payment of the subscription will be collected.

Format:

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

The last date on which a payment for this subscription will be collected.

Format:

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

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.

cadence object

Contains the intervals at which payments are collected.

Example: For collecting a payment every 2 weeks set occurance to 2 and timeUnit to weeks.

Defines how many units of time (timeUnit) should pass between each payment.

Specifies the unit of time, for example weeks or years, for the occurrence.

Possible values:

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

If there is an initial amount for the subscription: the amount to be charged as an immediate payment.

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 you're hosting your own subscription management page for payers, provide the link here. This allows payers to manage their subscriptions outside of Flywire.

This option is only available for subscriptions, not for Payment Requests.

POST/commercial/v1/subscriptions 

curl https://base-url-placeholder/subscriptions
-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"
        }
      },
	"serviceDescription": "Gold Membership subscription",
	"expirationDate": null,
	"createOptions": {
		"requireSavePaymentMethod": true,
		"paymentOptionsConfig": {
			"filters": {
				"type": [
					"credit_card",
					"online",
					"direct_debit"
				],
				"currency": [
					"local",
					"foreign",
					"fx"
				]
			}
		},
		"sendCreateEmail": true
	},
	"subscription": {
		"startDate": "2025-06-20",
		"endDate": "2028-06-01",
		"amount": 1000000,
		"cadence": {
			"occurrence": 1,
			"timeUnit": "MONTHS"
		},
		"initialAmount": 90000,
		"manageLink": "https://my-manage-link.example"
	}
}

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

ACTIVE The subscription is active - this is the normal state without any issues.
CANCELLED The subscription has been cancelled via the API or Dashboard.
PAID The subscription has reached its end date, it has at least one PAID installment, and all other installments are either PAID or CANCELLED.
FAILED The subscription has at least one FAILED installment.
PAUSED The subscription has been paused via the API or Dashboard.
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.

paymentsarray

This array contains all payments associated with the subscription. 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).

subscription object

Contains information about the subscription.

The date when the first payment of the subscription will be collected.

Format:

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

The last date on which a payment for this subscription will be collected.

Format:

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

If the subscription has been paused: The date when the subscription is automatically resumed.

The resumeDate parameter is only returned if the subscription is PAUSED and has an automatic resume date.

Format:

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

You can pause and resume subscriptions via the imageFlywire API (see Pausing, Resuming, or Cancelling a Subscription) or imageClient Dashboard.

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.

cadence object

Contains the intervals at which payments are collected.

Example: For collecting a payment every 2 weeks set occurance to 2 and timeUnit to WEEKS.

Defines how many units of time (timeUnit) should pass between each payment.

Specifies the unit of time, for example weeks or years, for the occurrence.

Possible values:

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

If there is an initial amount for the subscription: the amount to be charged as an immediate payment.

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 you're hosting your own subscription management page for payers, provide the link here. This allows payers to manage their subscriptions outside of Flywire.

This option is only available for subscriptions, not for Payment Requests.

A description of the purpose of the payment.

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

{
	"id": "7b2bbb4e-a9c2-4285-9bc3-551fb3d29c22",
	"publicLink": "https://app.flywire.com/rest/payment-request/pay/public/4bde36d9-482e-42c7-994c-cc1225531ae9",
	"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": 134311,
          "amount": 50000,
		  "amountPaid": 0,
          "amountDue": 50000,
          "status": "NOT_INITIATED",
		  "date": "2025-03-31",
          "payments": []
        },
        {
          "id": 134312,
          "amount": 60000,
		  "amountPaid": 60000,
          "amountDue": 60000,
          "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
	},
	"subscription": {
       "startDate": "2025-06-20",
       "endDate": "2028-06-01",
	   "resumeDate": null,
       "amount": 100000,
       "cadence": {
           "occurrence": 1,
           "timeUnit": "MONTHS"
       },
	   "initialAmount": 90000,
   	   "manageLink": "https://my-manage-link.example",					
	},
	"serviceDescription": "Gold Membership subscription"
}

Editing a Subscription

Request

This endpoint lets you edit a subscription. What you can edit:

  • Expiration date of the subscription

  • The subscription object (start and end date, cadence, etc.)

    When you edit the subscription object, the system removes all pending (future) installments and generates new ones based on the updated rules.

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

 

How to Resolve the Path Placeholders of the Endpoint

Replace {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

Parameters for the Request Body

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.

subscriptionobject

When you edit the subscription object, the system removes all pending (future) installments and generates new ones based on the updated rules.

You can edit the following parameters:

The date when the first payment of the subscription will be collected.

Format:

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

When will the next installment be charged after editing the startDate?

startDate is defined and in the future

the first due date is the startDate

startDate is defined and in the past

the first due date is the next upcoming recurrence based on the cadence (calculated from startDate)

startDate is not defined

the first due date is today

The last date on which a payment for this subscription will be collected.

Format:

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

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.

cadenceobject

Contains the intervals at which payments are collected.

Example: For collecting a payment every 2 weeks set occurance to 2 and timeUnit to weeks.

Defines how many units of time (timeUnit) should pass between each payment.

Specifies the unit of time, for example weeks or years, for the occurrence.

Possible values:

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

If you're hosting your own subscription management page for payers, provide the link here. This allows payers to manage their subscriptions outside of Flywire.

This option is only available for subscriptions, not for Payment Requests.

PATCH/commercial/v1/subscriptions/{subscriptionID} 

curl https://base-url-placeholder/subscriptions/959c09e5-a27b-49e9-8f92-e9e13374cfdd
  -X PATCH
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"expirationDate": "2028-06-20",
	"subscription": {
		"startDate": "2025-06-20",
		"endDate": "2028-06-01",
		"amount": 100000,
		"cadence": {
			"occurrence": 1,
			"timeUnit": "MONTHS"
		},
		"manageLink": "https://my-manage-link.example",					
	}
}'

Response

A 204 response will let you know that the subscription has successfully been updated.

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

204 NO CONTENT

Pausing, Resuming, or Cancelling a Subscription

Request

You can edit the status of a subscription in the following way:

PAUSE

Pausing a subscription puts it on hold until it is

a) manually resumed or

b) automatically resumed as defined by the resume date (optional)

A paused subscription has the PAUSED status,
RESUME

Resumes a PAUSED subscription.

A resumed subscription has the normal ACTIVE status.
CANCEL

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.

 

  • PAUSE
  • RESUME
  • CANCEL

How to Resolve the Path Placeholders of the Endpoint

Replace {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

Parameters for the Request Body

You can edit the status of a subscription in the following way:

PAUSE

Pausing a subscription puts it on hold until it is

a) manually resumed or

b) automatically resumed as defined by the resume date (optional)

A paused subscription has the PAUSED status,
RESUME

Resumes a PAUSED subscription.

A resumed subscription has the normal ACTIVE status.
CANCEL

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.

If you want the subscription to be automatically resumed at a specific date, you can enter the date here.

Format:

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

PATCH/commercial/v1/subscriptions/{subscriptionID}/status 

curl https://base-url-placeholder/subscriptions/959c09e5-a27b-49e9-8f92-e9e13374cfdd/status
  -X PATCH
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"statusChange" : "PAUSE",
	"resumeDate": "2025-02-07T08:27:19Z"
}'

How to Resolve the Path Placeholders of the Endpoint

Replace {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

Parameters for the Request Body

You can edit the status of a subscription in the following way:

PAUSE

Pausing a subscription puts it on hold until it is

a) manually resumed or

b) automatically resumed as defined by the resume date (optional)

A paused subscription has the PAUSED status,
RESUME

Resumes a PAUSED subscription.

A resumed subscription has the normal ACTIVE status.
CANCEL

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.

PATCH/commercial/v1/subscriptions/{subscriptionID}/status 

curl https://base-url-placeholder/subscriptions/959c09e5-a27b-49e9-8f92-e9e13374cfdd/status
  -X PATCH
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"statusChange" : "RESUME"
}'

How to Resolve the Path Placeholders of the Endpoint

Replace {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

Parameters for the Request Body

You can edit the status of a subscription in the following way:

PAUSE

Pausing a subscription puts it on hold until it is

a) manually resumed or

b) automatically resumed as defined by the resume date (optional)

A paused subscription has the PAUSED status,
RESUME

Resumes a PAUSED subscription.

A resumed subscription has the normal ACTIVE status.
CANCEL

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.

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/subscriptions/{subscriptionID}/status 

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

Response

A 204 response will let you know that the status change of the subscription was successful.

If you cancelled the subscription, an email will be sent to the payer, see Emails for Subscriptions.

204 NO CONTENT

Cancelling an Installment of a Subscription

Request

Purpose of cancelling installments

For subscriptions, it can be necessary to cancel an installment in case a subscription is "stuck" due to a failed installment. Subscriptions normally generate the next installment automatically, but not if a previous installment has FAILED or is overdue. To fix this, you can cancel the failed installment. Once it's cancelled, the system will ignore it and resume the regular schedule.

Cancelling installments is only possible for subscriptions, not for Payment Requests.

What does cancelling mean?

Cancelling an installment means:

  • The installment is permanently put in the cancelled status.

  • A cancelled installment will not be charged

Cancelling an installment cannot be undone.

When can an installment be cancelled?

An installment can be cancelled if it is in status 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.

An installment can be cancelled if its due date has passed
If the due date has not passed yet, an installment cannot be cancelled (even if it is still unpaid)
An installment cannot be cancelled if it is PAID

 

How to Resolve the Path Placeholders of the Endpoint

Replace {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

Replace {installmentID} in the endpoint with 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

It depends on whether the installment belongs to a Payment Request or a Subscription.

Installment IDs are included in the response after creation, see Creating a Payment Request or Creating a Subscription.

For existing Payment Requests or Subscriptions, you can retrieve the installment IDs by using Getting Details about a Payment Request or Getting Details about a Subscription.

Parameters for the Request Body

Must be CANCEL

PATCH/commercial/v1/subscriptions/{subscriptionID}/installment/{installmentID}/status 

curl https://base-url-placeholder/subscriptions/959c09e5-a27b-49e9-8f92-e9e13374cfdd/installments/134311/status
  -X PATCH
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"statusChange" : "CANCEL"
	}'

Response

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

204 NO CONTENT

Deleting a Subscription

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 {subscriptionID} in the endpoint with the subscription ID.

The subscription ID is the unique identifier for the 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

Where can I find the subscription ID?

With the imageFlywire API:

The subscription ID is returned to you in the response after creating a subscription.

For looking up IDs of existing subscriptions, you can use the API request for Getting a List of all Subscriptions.

With imageCheckout :

If you created a subscription 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 subscription ID) in the Payment Request (subscription) details as long as the Payment Request (subscription) is still active.

Parameters for the Request Body

No request body needed.

DELETE/commercial/v1/subscriptions/{subscriptionID} 

curl https://base-url-placeholder/subscriptions/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 subscription has been successfully deleted.

204 NO CONTENT