Checkout for Flywire-Managed Recurring Payments

With Flywire-managed recurring payments, you use Flywire's pre-defined installment plans. You only have to configure the plan settings (for example the number of installments) in Flywire Dashboard, Flywire will take care of the rest.

Since Flywire knows your plan settings, payments get initiated automatically according to the schedule.

Flywire also manages all emails to your payers on your behalf - these are mandatory to inform them about the recurring payments.

You need access to Flywire Dashboard to define the settings for the plans. If you don't have access yet, contact your Relationship Manager.

Available payment methods:

  • Card

How do Checkout Sessions of this type work? 

  1. You have to create a Checkout Session to either generate a URL or a session ID, depending on your implementation.

  2. Your payer accesses the UI Form on your website where they fill it out and confirm it.

  3. You get a postMessage via the event listener that contains a URL for confirming the Checkout Session.

  4. You confirm the Checkout Session.

  5. You receive the installment plan ID in the response.

Creating a Checkout Session for Flywire-Managed Recurring Payments

Request

Parameters for the Request Body

charge_intent object

payor object

You have the option to pass payer information to pre-fill the fields of the UI form.

For a description of all fields and their valid values form see:

options object

Contains settings for the UI form.

form object

recipient object

Contains the fields of the recipient.

fields array

It depends on the recipient which fields are optional or required. If a field is required, you must provide it here. Optional fields can be left out.

items array

POST /checkout/sessions
curl https://base-url-placeholder/checkout/sessions
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
    "type": "recurring",
    "charge_intent": {
        "mode": "installment"
    },
   "payor": {
		"first_name": "Peter",
		"last_name": "Payer",
		"address": "123 High Street",
		"city": "London",
		"country": "GB",
		"state": "",
		"phone": "0044123456789",
		"email": "[email protected]",
		"zip": "SW1A 1AA"
    },
    "options": {
        "form": {
            "locale": "en",
			"show_payor_information": true
        }
    },
	"recipient": {
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 33000
        }
    ],
    "notifications_url": "https://webhook.site/9bf9cf8d-1d8c-46d1-b147-ca5841ff2ede",
    "external_reference": "My payment reference",
    "recipient_id": "TQQ",
    "payor_id": "my_payer_ID"
}

Response

hosted_form object

Only relevant when you render the form via iframe. More info:

warnings array

errors array

You can decide which information from the response you want to filter out in your backend before passing the URL to your frontend.

{
"id": "494d2e9d-c0c9-407c-9094-5b3b2a02c00f",
"expires_in_seconds": 1800,
"hosted_form": {
	"url": "https://payment-checkout-dev-apache.flywire.cc/v1/form?session_id=494d2e9d-c0c9-407c-9094-5b3b2a02c00f",
	"method": "GET"
},
"warnings": []
}

When are warnings returned?

If the warning array contains warnings, it means that you tried to pre-fill the UI form with invalid values. You can use these warnings to check the data in your system for mistakes.

Are warnings an error?

No, warnings inform you of issues with field values, but you will still receive the URL and can display the form to your payer.

How do the warnings affect the form?

If a drop down field (like country) is affected by invalid values, the field will be empty, meaning no selection from the drop down is made yet. Your payer has to select the value from the drop down manually.

hosted_form object

Only relevant when you render the form via iframe. More info:

warnings array

errors array

You can decide which information from the response you want to filter out in your backend before passing the URL to your frontend.

{
"id": "e6bf6f63-46e0-4bd7-9bce-8106c02d0b3f",
"expires_in_seconds": 1800,
"hosted_form": {
	"url": "https://payment-checkout-dev-apache.flywire.cc/v1/form?session_id=e6bf6f63-46e0-4bd7-9bce-8106c02d0b3f",
	"method": "GET"
},
"warnings": [
	{
		"source": "email",
		"errors": [
			{
				"text": "must be a valid email",
				"error_type": "invalid_email"
    		}
   		]
  	}
  ]
}

The Payer's side: Filling out and sending the UI Form

After you created the Checkout Session, your payer accesses the UI Form on your website. Depending on the UI Form, your payer goes through different steps to fill it out and send it.

What does my payer see?

The postMessage of the Event Listener

After your payer sent the form, the event listener will return a successful postMessage. The postMessage contains the following information:

confirm_url object

Contains the confirm URL. The confirm URL is the full url for the request to confirm the session, already resolved with the correct session ID.

payor object

The email address your payer entered in the UI Form.

{
confirm_url: {
	method: "POST",
	url: "https://api-platform.flywire.com/payments/v1/checkout/sessions/494d2e9d-c0c9-407c-9094-5b3b2a02c00f/confirm",
	},
payor: {
email: "[email protected]"
},
source: "checkout_session",  
plan_id: "IPTQQ18EADF349BE",
success: true,
}

Confirming a Checkout Session

Request

As a security measure to ensure that you are the one who created the session, you have to confirm the Checkout Session.

 

How to Resolve the Path Placeholders of the Endpoint

You don't need to manually resolve the {ID} in the endpoint, as Flywire provides the fully resolved URL via postMessage.

Why should I use the confirm url from the postMessage?

  • It already contains the correct Checkout Session ID, no need to retrieve it from somewhere else.

  • You always receive the URL after the form has been sent. If you would try to confirm a Checkout Session before the form has been sent, you'll get an error message

You can only send the request to confirm the Checkout Session once. After a Checkout Session has been confirmed, you'll receive an error if you try to confirm it again.

POST/checkout/sessions/{ID}/confirm

curl https://base-url-placeholder/checkout/sessions/494d2e9d-c0c9-407c-9094-5b3b2a02c00f/confirm
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

If you provided a notifications URL for the payment, you’ll start receiving notifications that let you track the payment’s progress (refer to Payment Status Notifications) and the progress of the installment plan (refer to Installment Plan Status Notifications).
{
    "plan_id": "IPTQQ18EADF349BE"
}