Checkout for Scheduled Payments

Scheduled payments allow you to collect future payments with variable amounts on specific dates. All payments that belong together are bundled into one Payment Request.

Scheduled payments are a type of recurring payment.

Example:

"Store your card to pay 200 now, 500 next month, and 400 in two months."

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 schedule of payments using a card.

Basic Settings

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

To use scheduled payments the amount here must be set to 0.
The amount for each payment is set in the amount parameter in scheduledPayments.data.instalments.

Payment Schedule Settings

scheduledPayments object

data object

instalments array

An array of objects for each payment (installment) that should be scheduled and collected in the future.

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,

  // The amount must be 0 for scheduled payments
  amount: 0,

  // The payment schedule
  scheduledPayments: {
    type: "scheduled",
    data: {
      instalments: [
        {
          amount: 100.50,
          date: "2021-05-01"
        },
        {
          amount: 899.50,
          date: "2021-06-01"
        },
      ],
      serviceDescription: "Optional purpose of the payment"
    }
  }
};

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.

More info about receiving payment information

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

The payment flow for the Checkout integration is:

Customer enters information.

Your customer opens the Checkout Experience form on your website and enters their payment details.
Information is sent back to your website.

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

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

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

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

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

returnUrl :

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

onCompleteCallback:
The payer stays on the original page. You specify an onCompleteCallback function in the Checkout configuration that handles the parameters containing payment information. The parameters are returned as a JSON args object to the callback handler.
Advantages of using onCompleteCallback
- Immediate Handling
  
  Since the data is passed directly to your callback, you can handle the payment confirmation on the same page without a redirect.
- Dynamic Updates
  
  You can dynamically update the page (e.g., show a success message) without leaving the current view, providing a smoother user experience.
- Flexibility
  
  You can implement custom logic directly in the callback, such as updating the UI or logging information for analytics.
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.)

http://httpbin.org/get?reference=2e828d42-9b90-4cbd-969c-7320bd559115&status=active&amount=0&payment_method=scheduled

Example for response via onCompleteCallback handler:

string

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

Possible values:

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

{
  "status": "active",
  "paymentMethod": "scheduled",
  "amount": 0,
  "reference": "82804964-0497-4e07-990a-60076a463a29"
}

Managing Scheduled Payments

If you are using the

Flywire API: via the Payment Request resource

If you are using no integrations: via

Client Dashboard (as a Payment Request)