Recurring Plans

This resource is only relevant for Flywire-managed recurring payments.

List of endpoints

Description Endpoint

Getting a List of all Installment Plans

GET/recurring_plans

Getting Details about an Installment Plan

GET/recurring_plans/{planID}

Cancelling an Installment Plan

POST/recurring_plans/{planID}/ cancel

About Recurring Plans

The recurring plans resource allows you to access data for installment plans.

For recurring payments with Flywire-managed plans, payments are always part of an installment plan. An installment plan contains the settings, for example the number of installments and the total amount of all payments for this plan. The unique identifier for an installment plan is the plan ID.

Getting a List of all Installment Plans

This endpoint lets you retrieve a list of all installment plans for recipients you have access to.

In the example, the "View Details" button triggers another API request, see Getting Details about an Installment Plan.

You can also use this request to build a payer wallet if you filter the list by payor_id.

Example for displaying the list of installment plans in your backend:

Request

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 by payor_id to only return installment plans for a specific payer.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

This filter can be used for creating a payer wallet.

You can filter the list by one or more (max. 10) specific recipients to only get payments for those recipients back. If you use more than one recipient, divide them by commas (",").

You need to use the recipient ID of the recipient as a value.

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

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

Status Notification Description

in_progress

in progress

The installment plan has started and is in progress.

Payments will be created by Flywire according to the plan.

You will receive notifications for each payment of the plan under the same notifications URL you provided for the plan, see Payment Status Notifications for details about those notifications.
paused -

The payer initiated a Pay in Full payment.

A Pay in Full payment is an out of schedule payment that can be manually triggered by the payer. With this option, the payer can pay the full remaining amount of the installment plan at once. If a payer has the option to do this depends on your settings for the installment plan.

  • If the Pay in Full payment has been successfully Delivered, the installment plan moves to Finished.

  • If the Pay in Full payment was not successful, the payment gets Cancelled and the installment plan moves back to In Progress.

Note that this status does not trigger a callback notification.

finished

finished

The installment plan has been successfully completed, meaning the total amount has been paid.

While you are getting this notification, your payer will get an email from Flywire informing them that the installment plan has successfully completed.

cancelled

cancelled

The installment plan has been cancelled.

Cancelling an installment plan means the plan was stopped before the total amount was paid. No more payments will be created for this plan.

  • You as a client can cancel an installment plan via Flywire Dashboard and via the API.

  • Payers can cancel an installment plan if you give them the option in a payer wallet you created.

  • Flywire automatically cancels an installment plan if a payment of the plan keeps failing.

    When charging a payment of a plan fails, Flywire will try to charge again once a day for the next 3 days after the first failure. If the charge keeps failing, the payment and the installment plan will be cancelled.

You can filter the list for a specific creation date, for example {endpoint-path}?created_at=2024-01-09.

Optional Query Parameters for Pagination

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

Pagination parameters are added as query parameters with the request in the format

{endpoint_path}?page=2&per_page=10

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/recurring_plans 

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

recurring_plans array

This array contains the installment plans. Each installment plan contains:

The time and date the installment plan was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

The external reference.

The external reference is used to match a notification to an installment plan. All payments belonging to the plan will also use this external reference. It is included in notifications about the installment plan and all payments belonging to the plan. You can use any kind of identifier or reference from your own system that helps you identify the plan and its payments. Max size of 50 characters.

The external reference is called callback_id in the installment plan notifications.

For tracking installment plans via notifications see Installment Plan Status Notifications.

For tracking payments via notifications see Payment Status Notifications.

The notifications URL to receive callbacks for the installment plan and all payments belonging to this plan.

For tracking installment plans via notifications see Installment Plan Status Notifications.

For tracking payments via notifications see Payment Status Notifications.

The number of installments of this installment plan.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

The recipient ID.

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

The plan ID.

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

Example: IPTQQ18EADF349BE

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

The status of the installment plan.

Status Notification Description

in_progress

in progress

The installment plan has started and is in progress.

Payments will be created by Flywire according to the plan.

You will receive notifications for each payment of the plan under the same notifications URL you provided for the plan, see Payment Status Notifications for details about those notifications.
paused -

The payer initiated a Pay in Full payment.

A Pay in Full payment is an out of schedule payment that can be manually triggered by the payer. With this option, the payer can pay the full remaining amount of the installment plan at once. If a payer has the option to do this depends on your settings for the installment plan.

  • If the Pay in Full payment has been successfully Delivered, the installment plan moves to Finished.

  • If the Pay in Full payment was not successful, the payment gets Cancelled and the installment plan moves back to In Progress.

Note that this status does not trigger a callback notification.

finished

finished

The installment plan has been successfully completed, meaning the total amount has been paid.

While you are getting this notification, your payer will get an email from Flywire informing them that the installment plan has successfully completed.

cancelled

cancelled

The installment plan has been cancelled.

Cancelling an installment plan means the plan was stopped before the total amount was paid. No more payments will be created for this plan.

  • You as a client can cancel an installment plan via Flywire Dashboard and via the API.

  • Payers can cancel an installment plan if you give them the option in a payer wallet you created.

  • Flywire automatically cancels an installment plan if a payment of the plan keeps failing.

    When charging a payment of a plan fails, Flywire will try to charge again once a day for the next 3 days after the first failure. If the charge keeps failing, the payment and the installment plan will be cancelled.

The total amount of the installment plan (sum of all installments) in the billing currency.

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

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

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

{
    "total_entries": 21,
    "total_pages": 3,
    "page": 1,
    "per_page": 2,
    "recurring_plans": [
        {
            "created_at": "2024-04-05T11:09:46Z",
            "external_reference": "My external reference",
            "notifications_url": "https://webhook.site/5f2acad62",
            "number_of_installments": 4,
            "payor_id": "my_payer_id_1",
            "recipient_id": "TQQ",
            "recurring_id": "IPTQQ18EADF349BE",
            "status": "in_progress",
            "total_amount": 50000
        },							
        {
            "created_at": "2024-03-07T09:13:30Z",
            "number_of_installments": 4,
            "payor_id": "my_payer_id_2",
            "recipient_id": "TQQ",
            "recurring_id": "IPTQQ18F52545931",
            "status": "finished",
            "total_amount": 2000000
        }

    ]
}

Getting Details about an Installment Plan

This endpoint lets you retrieve details about an installment plan.

In the example, the "Cancel Plan" button triggers another API request, see Cancelling an Installment Plan.

You can also use this request to build a payer wallet.

Example for displaying installment plan details in your backend:

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {planID} in the endpoint with the actual plan ID.

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

Example: IPTQQ18EADF349BE

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

You get the plan ID in the response after you created an installment plan.

After that, you can also find the plan ID in the callback notifications:

GET/recurring_plans/{planID} 

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

Response

The plan ID.

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

Example: IPTQQ18EADF349BE

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

The status of the installment plan.

Status Notification Description

in_progress

in progress

The installment plan has started and is in progress.

Payments will be created by Flywire according to the plan.

You will receive notifications for each payment of the plan under the same notifications URL you provided for the plan, see Payment Status Notifications for details about those notifications.
paused -

The payer initiated a Pay in Full payment.

A Pay in Full payment is an out of schedule payment that can be manually triggered by the payer. With this option, the payer can pay the full remaining amount of the installment plan at once. If a payer has the option to do this depends on your settings for the installment plan.

  • If the Pay in Full payment has been successfully Delivered, the installment plan moves to Finished.

  • If the Pay in Full payment was not successful, the payment gets Cancelled and the installment plan moves back to In Progress.

Note that this status does not trigger a callback notification.

finished

finished

The installment plan has been successfully completed, meaning the total amount has been paid.

While you are getting this notification, your payer will get an email from Flywire informing them that the installment plan has successfully completed.

cancelled

cancelled

The installment plan has been cancelled.

Cancelling an installment plan means the plan was stopped before the total amount was paid. No more payments will be created for this plan.

  • You as a client can cancel an installment plan via Flywire Dashboard and via the API.

  • Payers can cancel an installment plan if you give them the option in a payer wallet you created.

  • Flywire automatically cancels an installment plan if a payment of the plan keeps failing.

    When charging a payment of a plan fails, Flywire will try to charge again once a day for the next 3 days after the first failure. If the charge keeps failing, the payment and the installment plan will be cancelled.

recipient object

The recipient ID (also called portal code).

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

fields array

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

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

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

Identifier of the field.

The value for this field.

The time and date the installment plan was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

The total amount of the installment plan (sum of all installments) in the billing currency.

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

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

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

The currency of the installment plan in ISO 4217 format.. This is always the same currency as the billing currency.

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

The number of installments of this installment plan.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

The date of the first payment of the installment plan.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

The date of the last payment of the installment plan.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

The date when the next payment for the installment plan is due.

This parameter is only present for plans that are still in_progress, not for finished or cancelled plans.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

The amount that has already been paid for the whole installment plan in the billing currency.

As soon as a payment is in delivered, the payment amount is reflected in the amount_paid_value parameter.

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

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

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

The remaining amount due for the whole installment plan in the billing currency.

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

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

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

charges array

An array of all charges of this installment plan.

A charge is a completed or future payment within an installment plan. There are different kinds of charges (hover to highlight the examples on the right):

Completed charges

Completed charges have a payment reference and a status for the payment.

This includes:

Successful charges

Successful payments in various statuses.

As soon as a payment is in delivered, the payment amount is reflected in the amount_paid_value parameter.

Unsuccessful charges

Unsuccessful charges are failed payments.

When charging a payment of a plan fails, Flywire will try to charge again once a day for the next 3 days after the first failure. If the charge keeps failing, the payment and the installment plan will be cancelled.

"Pay-in-Full" charges

A Pay in Full payment is an out of schedule payment that can be manually triggered by the payer. With this option, the payer can pay the full remaining amount of the installment plan at once. If a payer has the option to do this depends on your settings for the installment plan.

Future charges

Future charges are scheduled for a time in the future and don't have a payment reference or status yet.

The identifier of the charge.

The payment amount in the billing currency.

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

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

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

The billing currency in ISO 4217 format.

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

The date for when the payment is scheduled.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

For future charges of the installment plan, the payment_id is null since the payment has not been created yet.

The payment reference.

The payment reference identifies a payment.

The format for a payment reference is:

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

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

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

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

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

For future charges of the installment plan, the payment status is null since the payment has not been created yet.

The current status of the payment.

A payment can have the following statuses and notifications:

Status Notification Description

Initiated

initiated

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

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

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

    The payment reference identifies a payment.

    The format for a payment reference is:

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

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

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

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

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

  2. When the payment reference is assigned, two things happen:

    • The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).

    • The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

authorized

Only for Pre-Authorization Payments.

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

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

Example for a Pre-Authorization Payment:

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

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

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

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

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

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

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

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

Processed

processed

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

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

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

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

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

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

Guaranteed

guaranteed

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

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

Delivered

delivered

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

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

Failed

failed

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

Cancelled

cancelled

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

Who cancelled? Scenario cancellation_reason in the payment status notification

You

You cancelled a payment via the API.

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

See Cancelling a Payment

 cancelled_by_user
The payer

Payers can cancel a payment in two different ways:

  • You can give your payers the option to cancel a payment themselves if you implement this function in your UI.

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

  • Payers can contact Flywire and ask for a payment to be cancelled.

 cancelled_by_user
Flywire

There can be different reasons why Flywire cancels a payment:

  • Verification not passed

    The payment didn’t pass Flywire validations. If funds were captured, an automatic refund will be created and funds will be returned directly to the source of funds.

rejected

 

  • Duplicate payment

    The payer created 2 payments by mistake, and Flywire closed one of them after identifying the duplicate issue.

 duplicated

  • You or the payer contacted Flywire to cancel the payment.

 cancelled_by_user
Automatic cancellation - Payment expired

When a payment expires it will automatically be cancelled. Expiring means the payment reached the expiration date without Flywire receiving the funds.

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

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

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

  • For API integration:

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

    For other integrations:

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

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

expired

Direct debit payment failed

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

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

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

 unpaid

Reversed

reversed

This status has different meaning depending on the context:

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

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

This reversed type is only relevant for direct debits payments.

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

From a technical side this means:

  • The payment went into the delivered status (which means you received the funds from Flywire).

  • Then the payment fails and remains unpaid (which means Flywire did not receive the funds).

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

  • Then Flywire will start a recovery process and the payment status will change from delivered to reversed.

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

 
{
    "recurring_id": "IPTQQ191E6DBE533",
    "status": "paused",
 	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "created_at": "2024-09-12T15:30:56Z",
    "total_amount": 900000,
    "currency": "EUR",
    "number_of_installments": 3,
    "payor_id": "my_payer_id",
    "recurring_receivables_start_date": "2024-09-12T15:30:55.000+00:00",
    "recurring_receivables_end_date": "2024-11-12T16:30:55.000+00:00",
    "next_installment_date": "2024-10-12T15:30:55.000+00:00",
    "amount_paid_value": 300000,
    "remaining_amount_value": 600000,
    "charges": [
        {
            "id": 1800,
            "amount": 300000,
            "currency": "EUR",
            "scheduled_at": "2024-09-12T15:30:55.000+00:00",
            "payment_id": "TQQ294358388",
            "status": "cancelled"
        },
        {
            "id": 1801,
            "amount": 300000,
            "currency": "EUR",
            "scheduled_at": "2024-09-13T15:30:55.000+00:00",
            "payment_id": "TQQ294328372",
            "status": "delivered"
        },	
        {
            "id": 1802,
            "amount": 600000,
            "currency": "EUR",
            "scheduled_at": "2024-10-06T15:00:22.000+00:00",
            "payment_id": "TQQ294328373",
            "status": "initiated"
        },													
        {
            "id": 1803,
            "amount": 300000,
            "currency": "EUR",
            "scheduled_at": "2024-11-12T15:30:55.000+00:00",
            "payment_id": null,
            "status": null
        },
        {
            "id": 1804,
            "amount": 300000,
            "currency": "EUR",
            "scheduled_at": "2024-12-12T16:30:55.000+00:00",
            "payment_id": null,
            "status": null
        }
    ]
}

Cancelling an Installment Plan

Cancelling an installment plan means the plan was stopped before the total amount was paid. No more payments will be created for this plan.

  • You as a client can cancel an installment plan via Flywire Dashboard and via the API.

  • Payers can cancel an installment plan if you give them the option in a payer wallet you created.

  • Flywire automatically cancels an installment plan if a payment of the plan keeps failing.

    When charging a payment of a plan fails, Flywire will try to charge again once a day for the next 3 days after the first failure. If the charge keeps failing, the payment and the installment plan will be cancelled.

You can also use this request for a payer wallet.

Request

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {planID} in the endpoint with the actual plan ID.

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

Example: IPTQQ18EADF349BE

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

You get the plan ID in the response after you created an installment plan.

After that, you can also find the plan ID in the callback notifications:

POST/recurring_plans/{planID}/ cancel 

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

Response

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

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

204 NO CONTENT