Checkout for Subscriptions

image

Subscription payments allow you to collect future payments with a fixed amount on regular intervals.For subscriptions, you cannot create or edit installments yourself - they are automatically generated by Flywire based on the rules that have been defined for the subscription.

In Dashboard, you can find subscriptions under "Payment Requests".

Subscription payments are a type of recurring payment.

Recurring payments (also called repeat payments) are payments that charge the same card or bank account multiple times. The payer agrees to the type of recurring payment and allows their card or bank account information being stored for future payments. This means the future payments can be charged without the payer being present.

How are recurring payments collected?

Recurring payments can either be collected in two ways:

  • setting up a repeat-authority on a card

  • setting up a direct debit for a bank account

Which countries and currencies are supported?

For up-to-date currency and country coverage details please reach out to your Flywire contact.

Example:

"Store your card to pay 200 on the first of each month for one year."

Who handles future payment creation and emails to your payer?

Flywire will create the payments and send communications on your behalf at the appropriate times.

Configuration Example

The following code sample shows how to configure the Checkout integration to initiate a subscription of payments using a card.

You have two options for collecting an immediate initial payment:

  1. Same amount as the regular subscription amount:

    You can collect the initial payment of a subscription immediately by not specifying a startDate. The start date will default to today.

  2. Different amount as the regular subscription amount: Include an amount on the base config object.

If you don't provide a startDate and specify an amount on the base config object, the two amounts will combined into one single initial payment.

 

Basic Settings

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

Possible values:

  • demo (Sandbox)

  • prod (Production environment)

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

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

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

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

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

Format:

Either: 3 letters (ABC)

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

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

After-Payment Settings

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

Payer Info and Custom Info

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

Payment Settings

amount decimal

You can take an initial payment (for example a deposit) f you use an amount greater than 0. If no initial payment is required use 0.

You have two options for collecting an immediate initial payment:

  1. Same amount as the regular subscription amount:

    You can collect the initial payment of a subscription immediately by not specifying a startDate. The start date will default to today.

  2. Different amount as the regular subscription amount: Include an amount on the base config object.

If you don't provide a startDate and specify an amount on the base config object, the two amounts will combined into one single initial payment.

Subscription Settings

scheduledPayments object

Must be subscription.

data object

Object containing the settings for the subscription.

The payment amount in the billing currency.

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

The amount is specified as a decimal (1000.25).

The date when the first payment of the subscription will be collected. Must be today or a future date in format:

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

You can collect the initial payment of a subscription immediately by not specifying a startDate. The start date will default to today.

The last date on which a payment will be collected. Must be a future date in yyyy-MM-dd format.

Leave blank for open-ended subscriptions.

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

A description of the purpose of the payment.

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

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

  // Specify the returnUrl or an onCompleteCallback handler
  returnUrl: "https://httpbin.org/get",

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

  //Initial payment such as deposit if any, otherwise 0
  amount: 20,

  //The Subscription Schedule
  scheduledPayments: {
    type: "subscription",
    data: {
      amount: 80,
      startDate: "2023-03-30",
      endDate: "2023-05-10",
      cadence: {
        occurrence: 1,
        timeUnit: "weeks",
      },
      serviceDescription: "Weekly Subscription"
    }
  }
};

After Payment Completion

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

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

The payment flow for the Checkout integration is:

  1. Customer enters information.

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

  2. Information is sent back to your website.

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

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

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

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

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

    returnUrl :

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

    onCompleteCallback:

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

    • Immediate Handling

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

    • Dynamic Updates

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

    • Flexibility

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

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

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

Example for response via returnUrl:

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

https://postman-echo.com/get?reference=d1fda11c-44f5-463a-a75b-9c97c2c1f46a&status=active&amount=1200.11&amountCurrency=USD&
payerAmount=1069&payerAmountCurrency=EUR&payment_method=subscription

Example for response via onCompleteCallback handler:

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

Possible values:

success The communication with the external system was successful, and a charge will happen. The actual transfer of funds can take a few days depending on the system.

error

The communication with the external system was successful, but no charge will happen. The external system refused the charge.

active
Only for scheduled payments and subscriptions.

The scheduled payment(s) or subscription has successfully been created and is now active.

pending
Always returned for bank transfer payments and never returned for online payments.

The payment creation was successful, but since the payer has to make a bank transfer manually, Flywire doesn't know if and when this will happen.

Only returned if an initial immediate payment is taken.

The payment amount in the billing currency.

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

The amount is specified as a decimal (1000.25).

Is always subscription (as per the value passed in the config).

The ID of the payment request.

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

Only returned if an initial immediate payment is taken.

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.

Only returned if an initial immediate payment is taken.

The payment amount in the payer currency.

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

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

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

Only returned if an initial immediate payment is taken.

The payer currency.

Format:

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

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.
{
  "status": "active",
  "amount": 1200.11,
  "paymentMethod": "subscription"
  "reference": "d475906f-17ff-45f7-812e-52f9a06f21ae",						
  "amountCurrency": "USD",
  "payerAmount": 1069,
  "payerAmountCurrency": "EUR",
}

Managing Subscription Payments

If you are using the imageFlywire API: via the Subscriptions resource
If you are using no integrations: via imageClient Dashboard (as a Payment Request)