Checkout Sessions

Save Card
Save Card & Pay
New Mandate for saved Card
Direct Debit Save
Direct Debit Save & Pay

Your payer will see a zero amount payment after this type of Checkout Session.
Tokenizing a card requires a payment. Since there is no payment when the payer only saves (tokenizes) their card, Flywire creates a payment with an amount of 0 in the background for the purpose of tokenization. Your payer will be able to see this "0 charge" payment in their bank statement.

Parameters for the Request Body

type string

The type of the Checkout Session.

Possible values:

For saving a card or bank account without creating the first payment immediately.	tokenization
For saving card or bank account and creating the first payment immediately. Currently only available for cards and direct debit scheme SEPA.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

schema string

Defines if this Checkout Session is for card or direct debit payments. For direct debit, it also defines the type of direct debit scheme.

Possible values:

Card payments	cards
SEPA direct debit	dd_sepa
BACS direct debit	dd_bacs Only available in mode tokenization.
EFT Canada direct debit	dd_eft Only available in mode tokenization.
ACH direct debit	dd_ach Only available in mode tokenization.

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": "tokenization",
    "charge_intent": {
	   "mode": "subscription"
    },
   "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": {
            "action_button": "save",
            "locale": "en",
            "show_flywire_logo": true
        }
    },
    "schema": "cards",
    "payor_id": "MyPayerID",
    "recipient_id": "FLW"
}'

Mandatory emails

Self-managed recurring payments require you to send mandatory emails to your payer.

You have two options for charging the first payment:

Standard: Payment gets processed immediately.
Pre-Authorization: You have to capture the funds manually. For details refer to Use Case: Pre-Authorization Payments.

First Payment Standard
First Payment as Pre-Authorization

Parameters for the Request Body

type string

The type of the Checkout Session.

Possible values:

For saving a card or bank account without creating the first payment immediately.	tokenization
For saving card or bank account and creating the first payment immediately. Currently only available for cards and direct debit scheme SEPA.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

action_button string

Controls the label for the action button of the UI form.

Possible values

save (default value)
next
pay

Note: The label will be translated according to the locale parameter.

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

schema string

Defines if this Checkout Session is for card or direct debit payments. For direct debit, it also defines the type of direct debit scheme.

Possible values:

Card payments	cards
SEPA direct debit	dd_sepa
BACS direct debit	dd_bacs Only available in mode tokenization.
EFT Canada direct debit	dd_eft Only available in mode tokenization.
ACH direct debit	dd_ach Only available in mode tokenization.

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": "tokenization_and_pay",
    "charge_intent": {
        "mode": "subscription"
    },
   "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": {
            "action_button": "save",
            "locale": "en",
            "show_flywire_logo": 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": "Payment ID12456",
    "recipient_id": "FLW",
    "schema": "cards",
    "payor_id": "MyPayerID"
}

Parameters for the Request Body

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

action_button string

Controls the label for the action button of the UI form.

Possible values

save (default value)
next
pay

Note: The label will be translated according to the locale parameter.

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

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": "tokenization_and_pay",
	"charge_intent": {
		"capture": "manual",
		"authorization": "preauth",
		"mode": "subscription"
	},
   "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": {
            "action_button": "save",
            "locale": "en",
            "show_flywire_logo": 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": "Payment ID12456",
    "recipient_id": "FLW",
    "schema": "cards",
    "payor_id": "MyPayerID"
}

Your payer will see a zero amount payment after this type of Checkout Session.
Tokenizing a card requires a payment. Since there is no payment when the payer only saves (tokenizes) their card, Flywire creates a payment with an amount of 0 in the background for the purpose of tokenization. Your payer will be able to see this "0 charge" payment in their bank statement.

Parameters for the Request Body

type string

The type of the Checkout Session.

Possible values:

For saving a card or bank account without creating the first payment immediately.	tokenization
For saving card or bank account and creating the first payment immediately. Currently only available for cards and direct debit scheme SEPA.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

schema string

Defines if this Checkout Session is for card or direct debit payments. For direct debit, it also defines the type of direct debit scheme.

Possible values:

Card payments	cards
SEPA direct debit	dd_sepa
BACS direct debit	dd_bacs Only available in mode tokenization.
EFT Canada direct debit	dd_eft Only available in mode tokenization.
ACH direct debit	dd_ach Only available in mode tokenization.

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": "new_mandate",
    "charge_intent": {
        "mode": "subscription",
		"payment_method_token": "UW6JqAuMcJje-SyR3iIG"
    },
    "options": {
        "form": {
            "action_button": "save",
            "locale": "en",
            "show_flywire_logo": true
        }
    },
    "schema": "cards",
    "payor_id": "MyPayerID",
    "recipient_id": "FLW"
}'

The form works and looks slightly different for each direct debit scheme.

Parameters for the Request Body

type string

The type of the Checkout Session.

Possible values:

For saving a card or bank account without creating the first payment immediately.	tokenization
For saving card or bank account and creating the first payment immediately. Currently only available for cards and direct debit scheme SEPA.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

schema string

Defines if this Checkout Session is for card or direct debit payments. For direct debit, it also defines the type of direct debit scheme.

Possible values:

Card payments	cards
SEPA direct debit	dd_sepa
BACS direct debit	dd_bacs Only available in mode tokenization.
EFT Canada direct debit	dd_eft Only available in mode tokenization.
ACH direct debit	dd_ach Only available in mode tokenization.

For BACS

Since BACS is only available in the UK you can only use recipients that have GBP as their billing currency. If you are trying to use a non-GPB recipient you'll receive a 422 error, see Response after creating a Checkout Session.

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": "tokenization",
    "charge_intent": {
        "mode": "subscription"
    },
   "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": {
			"action_button": "save",
			"locale": "en",				
            "show_flywire_logo": true
        }
    },										
    "schema": "dd_sepa",
    "payor_id": "payorCCC",
    "recipient_id": "UUI"
}

Saving the bank account and creating the first payment at the same time (tokenization_and_pay) is currently only available for SEPA.

Mandatory emails

Self-managed recurring payments require you to send mandatory emails to your payer.

Parameters for the Request Body

type string

The type of the Checkout Session.

Possible values:

For saving a card or bank account without creating the first payment immediately.	tokenization
For saving card or bank account and creating the first payment immediately. Currently only available for cards and direct debit scheme SEPA.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

charge_intent object

mode string

The mode of a payment depends on three factors:

Frequency: Are the intervals for the payment regular or irregular?
Purchase: Is it one single purchase or are new goods/services purchased?
Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

There is no fallback default value for mode. You need to provide a mode for each request.

Mode	Frequency	Purchase	Delivery
installment	regular or irregular intervals	Single purchase of goods or services	Single delivery (can be in advance, at any time during the plan, or at the end)
subscription	Regular intervals	Multiple purchases (for new or renewed goods or services)	Multiple and regular deliveries
unscheduled	No pre-agreed intervals	Multiple purchases (for new or renewed goods or services)	Multiple deliveries at no pre-agreed intervals

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

schema string

Defines if this Checkout Session is for card or direct debit payments. For direct debit, it also defines the type of direct debit scheme.

Possible values:

Card payments	cards
SEPA direct debit	dd_sepa
BACS direct debit	dd_bacs Only available in mode tokenization.
EFT Canada direct debit	dd_eft Only available in mode tokenization.
ACH direct debit	dd_ach Only available in mode tokenization.

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": "tokenization_and_pay",
    "charge_intent": {
        "mode": "subscription"
    },
   "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": {
			"action_button": "save",
			"locale": "en",				
            "show_flywire_logo": true
        }
    },
	"recipient": {
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 3300
        }
    ],
    "notifications_url": "https://webhook.site/9bf9cf8d-1d8c-46d1-b147-ca5841ff2ede",
    "external_reference": "Payment ID12456",
    "recipient_id": "UUI",
    "schema": "dd_sepa",
	"payor_id": "payorCCC"
}'

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

show_payor_information boolean

The show_payor_information parameter gives you the option to skip the payer information page of the form. This shortens the time your payer has to interact with the form if you already provided all the necessary information. If you skip the page, the page for selecting the payment method is shown immediately.

If you don't provide the parameter, the payer information page is shown by default.

Note:

If you want to skip the page, all mandatory payer information fields must be pre-filled by you.
If field values are missing or are invalid, the payer information page will be displayed so that the payer can add or correct the information.

Possible values:

true default, payer information page is displayed
false payer information page is not displayed, page for selecting the payment method is shown immediately

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

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"
}

You have two options for One Off payments, depending on which payment methods you want to make available:

With the Checkout Experience form:

You let the payer choose from all available payment methods which one they want to use for this single payment.

With the Card Payment Element:

You allow only cards as the available payment method for this single payment.

Checkout Experience (Multiple Payment Methods)
Payment Element (Card Only)

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

show_payor_information boolean

The show_payor_information parameter gives you the option to skip the payer information page of the form. This shortens the time your payer has to interact with the form if you already provided all the necessary information. If you skip the page, the page for selecting the payment method is shown immediately.

If you don't provide the parameter, the payer information page is shown by default.

Note:

If you want to skip the page, all mandatory payer information fields must be pre-filled by you.
If field values are missing or are invalid, the payer information page will be displayed so that the payer can add or correct the information.

Possible values:

true default, payer information page is displayed
false payer information page is not displayed, page for selecting the payment method is shown immediately

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

Mandatory emails

If you use the default setting false, you have to send the mandatory emails to your payer yourself, see One Off Payments: Emails to Your Payer.

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": "one_off",
    "charge_intent": {
        "mode": "one_off"
    },
   "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",
    "enable_email_notifications": true
}

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

show_payor_information boolean

The show_payor_information parameter gives you the option to skip the payer information page of the form. This shortens the time your payer has to interact with the form if you already provided all the necessary information. If you skip the page, the page for selecting the payment method is shown immediately.

If you don't provide the parameter, the payer information page is shown by default.

Note:

If you want to skip the page, all mandatory payer information fields must be pre-filled by you.
If field values are missing or are invalid, the payer information page will be displayed so that the payer can add or correct the information.

Possible values:

true default, payer information page is displayed
false payer information page is not displayed, page for selecting the payment method is shown immediately

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

Mandatory emails

If you use the default setting false, you have to send the mandatory emails to your payer yourself, see One Off Payments: Emails to Your Payer.

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": "one_off",
	"schema": "cards",
    "charge_intent": {
        "mode": "one_off"
    },
   "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",
    "enable_email_notifications": true
}

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:

Payment Element if you are using Flywire Elements
Checkout Experience if you are using Checkout

options object

Contains settings for the UI form.

form object

locale string

The language you want to translate the form to. The localization affects the labels of the form fields and the action button.

The default is English (“en”).

List of possible language values

Language	Value for `locale`
English	en
Spanish	es-ES
Chinese	zh-CN
Korean	ko
Portuguese	pt-PT
Japanese	ja
French	fr-FR
Bahasa Indonesia	id
Arabic	ar
Vietnamese	vi
Italian	it-IT
German	de-DE

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

notifications_url string (url)

The notifications URL enables you to receive callbacks about the payment status (see Payment Status Notifications).

The notifications URL is the dynamic URL for receiving callbacks.

Dynamic vs. static URL

There are two different URLs for receiving callbacks:

Static URL

For API integrations:

When you set up your application that accesses the Flywire API, you had the option to define a notifications URL. This is the static notifications URL. Callbacks will be sent to this URL for all payments you created via the Flywire API.

The recipient of a payment may also have a static notifications URL defined which might be different from your static notifications URL as a client. In that case, callbacks will also be sent to the recipient's notifications URL.

For other integrations:

When you set up your portal together with Flywire, you had the option to define a callback URL for that portal. Callbacks will be sent to this URL for all payments for this portal.

If you don't use a static callback URL yet and want to start using it, please contact the Solutions team.

Dynamic URL

The URL you can set in a parameter when you are creating a payment is the dynamic notifications URL. Since this URL can be different for every payment you create, it is called dynamic.

How defining static and dynamic URLs affect callbacks

= not set

= set

Static URL	Dynamic URL	Result
		You won't receive notifications.
		You'll receive notifications to your static URL.
		For API integrations: The dynamic URL will override the static URL and you'll receive notifications only to the dynamic URL. For other integrations: You'll receive callbacks to both URLs. This is called "dual callback URL". A dual callback URL means you defined a static URL in your portal and you are sending callbacks to a different callback URL via the parameter for the payment. In this case, callbacks will be sent to both URLs. This approach can be useful if you want to update two separate systems.
		You'll receive notifications to your dynamic URL

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": "one_off",
	"charge_intent": {
		"capture": "manual",
		"authorization": "preauth",
		"mode": "one_off"
	},
   "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": {
            "action_button": "save",
            "locale": "en",
            "show_flywire_logo": 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": "Payment ID12456",
    "recipient_id": "FLW",
    "schema": "cards",
    "payor_id": "MyPayerID"
}

Card
Direct Debit SEPA
Direct Debit BACS
Direct Debit EFT Canada
Direct Debit ACH

The payer sees a form that collects the payer and card information. After the payer confirmed the form, the payment is created. With Smart Rendering, the appearance of the element and the displayed fields may vary based on your customizations.

Your payer sees the SEPA form where they can enter their payer and bank account information.

After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info.

Your payer sees the BACS form where they can enter their payer and bank account information.

After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info.

Your payer sees the EFT Canada form where they can enter their payer information.

After entering their information, your payer will be redirected to Plaid. The third-party implementation will lead your payer through the steps to connect to their bank account.

After your payer successfully connected to their bank account, they will be redirected to the EFT Canada direct debit Form.

Back at the EFT Canada direct debit form, your payer can either edit their payer info, connect to a different bank account or confirm the information.

Your payer sees the ACH form where they can enter their payer and bank account information.

After entering their info, your payer will see the mandate confirmation screen ("Review mandate info") to confirm or edit their info.

Your payer sees the Flywire-Plans form that collects the payer information.

After entering their information, your payer is asked to pick the installment plan (number of installments) and the payment method they want to use.

Your payer is then asked to either create a Flywire account or log into an existing one.

After creating an account or logging into an existing one, your payer sees an overview of the plan they choose.

Your payer is then asked to enter their card information to pay for the payments.

An installment plan with the information provided is now created. The window will close automatically after a few seconds.

It depends on which One Off Payment Checkout Session you created:

Checkout Experience (Multiple Payment Methods)
Payment Element (Card Only)

Your payer sees the form that collects the payer information.

After entering their information, your payer is asked to pick the payment method they want to use.

Depending on the payment method, the last screen will either ask for card or bank account information to be used for this payment or give the payer bank details so that they can make a bank transfer.

The payer sees a form that collects the payer and card information. After the payer confirmed the form, the payment is created. With Smart Rendering, the appearance of the element and the displayed fields may vary based on your customizations.

After your payer sent the form, the event listener will return a successful postMessage.

A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.

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. You need to use this email address to send mandatory emails to your payer, see

Recurring Payments: Emails to Your Payer
Pre-Authorization Payments: Emails to Your Payer
One Off Payments: Emails to Your Payer (only if you opted for sending emails yourself)

Make sure you use the email address you got via the postMessage for the emails to your payer. Even if you already have an email address in your system, your payer might have updated the email address 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",
success: true
}

After your payer sent the form, the event listener will return a successful postMessage.

A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.

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,
}

It depends on which One Off Payment Checkout Session you created:

Checkout Experience (Multiple Payment Methods)
Payment Element (Card Only)

After your payer sent the form, the event listener will return a successful postMessage.

A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.

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. You need to use this email address to send mandatory emails to your payer, see

Recurring Payments: Emails to Your Payer
Pre-Authorization Payments: Emails to Your Payer
One Off Payments: Emails to Your Payer (only if you opted for sending emails yourself)

Make sure you use the email address you got via the postMessage for the emails to your payer. Even if you already have an email address in your system, your payer might have updated the email address 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",  
  reference: "LRP688625939",
  success: true,
}

After your payer sent the form, the event listener will return a successful postMessage.

A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.

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. You need to use this email address to send mandatory emails to your payer, see

Recurring Payments: Emails to Your Payer
Pre-Authorization Payments: Emails to Your Payer
One Off Payments: Emails to Your Payer (only if you opted for sending emails yourself)

Make sure you use the email address you got via the postMessage for the emails to your payer. Even if you already have an email address in your system, your payer might have updated the email address 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",
success: true
}

After your payer sent the form, the event listener will return a successful postMessage.

A successful postMessage confirms that the form was submitted and that you can confirm the Checkout Session now. However, it does not indicate payment success. Payment status updates will be sent via callback notifications, see Payment Status Notifications for details.

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. You need to use this email address to send mandatory emails to your payer, see

Recurring Payments: Emails to Your Payer
Pre-Authorization Payments: Emails to Your Payer
One Off Payments: Emails to Your Payer (only if you opted for sending emails yourself)

Make sure you use the email address you got via the postMessage for the emails to your payer. Even if you already have an email address in your system, your payer might have updated the email address 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",
success: true
}

After you confirmed the Checkout Session, you receive the payment method token and mandate ID. If you created a Checkout Session of type tokenize_and_pay you also receive information about the payment that has been created.

About the Payment Method Token

The payment method token is a unique string of numbers and characters that gets assigned to a card or bank account when they are stored. It identifies the payment method (e.g., last four digits of a card or bank account) and includes payer details, such as the cardholder or account owner. Note: the payer may differ from the purchaser, like a parent paying a student’s tuition.

Important Information

One payment method token can be used for multiple mandate IDs.
The payment method token needs to be included in each payment.

Since the token already contains information about the payer, sending the token means that you don’t need to include payer information manually in a payment anymore.
The payer information in the payment method token can be different from the payer information stored in your system.

The token stores the information gathered in the UI form. Even if you pre-filled the form with data from your system, the payer might have edited the fields in the form. This can be the case when data in your system is wrong (misspelled names etc.) or when the actual payer is different from what your system considers a “payer” (for example, your system contains information about your students as “payers” but the actual payer (card holder or bank account owner) is a parent).

Where can I find the payment method token for a payer?

The payment method token is returned to you in the response after you confirmed a Checkout Session.

You can also find all payment method tokens for a payer (identified by their payor_id) with this request:

GET/payors/{payorId}/payment_methods

For details see Getting a List of all stored Payment Methods for a Payer.

About the Mandate ID

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

More info about the mandate PDF

The mandate PDF is the mandate fully written out "on paper" (but paperless as a PDF). The PDF is delivered to your payer by email.

There are different types of PDFs depending on the direct debit scheme for the payments:

SEPA mandate

The SEPA mandate is a PDF with the written out SEPA contract. A SEPA mandate has a specific format and strictly defined content. It is part of the SEPA payment system, and you cannot charge a bank account without having a SEPA mandate.

The file name for the PDF with the SEPA mandate contains the date the SEPA mandate was created and the mandate ID that was generated by Flywire.

The SEPA mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

BACS mandate

The BACS mandate is a PDF with the written out contract including the Direct Debit Guarantee for BACS. A BACS mandate has a specific format and strictly defined content. It is part of the BACS payment system, and you cannot charge a bank account without having a BACS mandate.

The BACS mandate is created and sent to your payer by a third-party provider, you don't need to create and send it yourself.

EFT Canada mandate

The mandate PDF for EFT Canada is called PAD (Pre-Authorized Debit Agreement). It is a PDF that always has the same format and content, but you need to provide the current date.

Process for delivering the mandate (PAD) for EFT Canada:

Download the PAD PDF from Flywire.

You can download the Flywire PAD here: Download PAD PDF
Insert the correct date (when the payer agreed to EDT Canada direct debit) into the Flywire PAD PDF.
Send it to your payer as an email attachment. The email needs to contain the following information:
- Total number of scheduled payments
- Total payment amount
- First payment date
- Last payment date
- Flywire PAD (as an attachment)

ACH mandate

The ACH mandate is a PDF containing the written ACH authorization agreement. An ACH mandate has a specific format and required content, as defined by ACH regulations. It is part of the ACH payment system, and you cannot charge a bank account without obtaining an ACH mandate.

The ACH mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

Storing the mandate ID

Each mandate ID belongs to a specific plan (an installment plan, a subscription, etc.). You need to store the mandate together with the information about the plan and its payments in your system to ensure that you will be able to identify it.

The mandate PDF for bank accounts has other specific policies for storing:

Direct debit mandates for SEPA and BACS have to be stored for 3 years. Since the emails with the mandate are managed by Flywire (for SEPA and ACH) or Finastra (for BACS), Flywire or Finastra will store the mandate for you.

What is the mandate PDF?

The mandate PDF is the mandate fully written out "on paper" (but paperless as a PDF). The PDF is delivered to your payer by email.

There are different types of PDFs depending on the direct debit scheme for the payments:

SEPA mandate

The SEPA mandate is a PDF with the written out SEPA contract. A SEPA mandate has a specific format and strictly defined content. It is part of the SEPA payment system, and you cannot charge a bank account without having a SEPA mandate.

The file name for the PDF with the SEPA mandate contains the date the SEPA mandate was created and the mandate ID that was generated by Flywire.

The SEPA mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

BACS mandate

The BACS mandate is a PDF with the written out contract including the Direct Debit Guarantee for BACS. A BACS mandate has a specific format and strictly defined content. It is part of the BACS payment system, and you cannot charge a bank account without having a BACS mandate.

The BACS mandate is created and sent to your payer by a third-party provider, you don't need to create and send it yourself.

EFT Canada mandate

The mandate PDF for EFT Canada is called PAD (Pre-Authorized Debit Agreement). It is a PDF that always has the same format and content, but you need to provide the current date.

Process for delivering the mandate (PAD) for EFT Canada:

Download the PAD PDF from Flywire.

You can download the Flywire PAD here: Download PAD PDF
Insert the correct date (when the payer agreed to EDT Canada direct debit) into the Flywire PAD PDF.
Send it to your payer as an email attachment. The email needs to contain the following information:
- Total number of scheduled payments
- Total payment amount
- First payment date
- Last payment date
- Flywire PAD (as an attachment)

ACH mandate

The ACH mandate is a PDF containing the written ACH authorization agreement. An ACH mandate has a specific format and required content, as defined by ACH regulations. It is part of the ACH payment system, and you cannot charge a bank account without obtaining an ACH mandate.

The ACH mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

Using the mandate ID for recurring payments

The mandate ID needs to be included in each payment that belongs to the same plan (for example, installments of an installment plan or payments for an ongoing subscription). If the payer wants to pay for a different plan, you need to generate a new mandate.

How do I generate a new mandate ID?

New card or bank account

If a payer wants to use a new card or bank account for a plan, you have to save (and therefore tokenize) the card or bank account, as this will also give you a mandate.
Existing card

If a payer wants to use an existing card that is already tokenized, you can generate a new mandate for the new plan with this card.

Where do I find existing mandate IDs?

You can find all mandate IDs for a payment method token with this request:

GET/payors/{payorId}/payment_methods/{token}

For details see Getting the Mandate IDs for a Payment Method Token.

If you provided a notifications URL for the payment, you’ll start receiving notifications that let you track the payment’s progress (see Payment Status Notifications).

The content of the response depends on which type of Checkout Session you created:

Card tokenization
Card tokenization_and_pay
Card new_mandate
Direct Debit tokenization
Direct Debit tokenization_and_pay

payment_method object

Contains information about the payment method the payer used and the payment method token.

You can display the card information in your UI for your payer to make it easier for them to identify which card they saved in your system.

mandate object

It is mandatory to include the mandate ID when charging the payment.

id string

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

surcharge object

Only returned if a surcharge applies to the payment. If a surcharge is applied and you are handling emails to your payer yourself, you need to include the surcharge information in the pre-notification email.

A surcharge may apply in certain situations, including, but not limited to, mismatches between card currency and payer country, as well as the use of certain card types. If a surcharge applies and the percentage of it depends on the individual settings for the recipient of the payment.

{
"payment_method": {
	"token": "232301485cfa4b36bc28",
	"type": "card",
	"card_classification": "credit",
	"last_four_digits": "1111",
	"card_expiration": "03/2030",
	"country": "US",
	"brand": "visa",
	"issuer": "JPMORGAN CHASE BANK, N.A."
	},
"mandate": {
	"id": "MCRUC20230330uAM584YC"
	"surcharge": {
		"percentage": 0.03
		}
	}
}

payment_reference string

The payment reference.

charge_info object

payment_method object

Contains information about the payment method the payer used and the payment method token.

You can display the card information in your UI for your payer to make it easier for them to identify which card they saved in your system.

type string

The payment method type.

Possible values:

bank_transfer	Payment is done via bank transfer.
online	Payment is done via an alternative payment method (APM), through a third-party provider.
card	Payment is done via credit or debit card. You'll get additional information about the type of card in the parameter card_classification (either credit or debit).
direct_debit	Payment is done via direct debit.
529_payments	Payment is done via a 529 provider.

mandate object

It is mandatory to include the mandate ID when charging the payment.

id string

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

More info about the mandate PDF

The mandate PDF is the mandate fully written out "on paper" (but paperless as a PDF). The PDF is delivered to your payer by email.

There are different types of PDFs depending on the direct debit scheme for the payments:

SEPA mandate

The SEPA mandate is a PDF with the written out SEPA contract. A SEPA mandate has a specific format and strictly defined content. It is part of the SEPA payment system, and you cannot charge a bank account without having a SEPA mandate.

The file name for the PDF with the SEPA mandate contains the date the SEPA mandate was created and the mandate ID that was generated by Flywire.

The SEPA mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

BACS mandate

The BACS mandate is a PDF with the written out contract including the Direct Debit Guarantee for BACS. A BACS mandate has a specific format and strictly defined content. It is part of the BACS payment system, and you cannot charge a bank account without having a BACS mandate.

The BACS mandate is created and sent to your payer by a third-party provider, you don't need to create and send it yourself.

EFT Canada mandate

The mandate PDF for EFT Canada is called PAD (Pre-Authorized Debit Agreement). It is a PDF that always has the same format and content, but you need to provide the current date.

Process for delivering the mandate (PAD) for EFT Canada:

Download the PAD PDF from Flywire.

You can download the Flywire PAD here: Download PAD PDF
Insert the correct date (when the payer agreed to EDT Canada direct debit) into the Flywire PAD PDF.
Send it to your payer as an email attachment. The email needs to contain the following information:
- Total number of scheduled payments
- Total payment amount
- First payment date
- Last payment date
- Flywire PAD (as an attachment)

ACH mandate

The ACH mandate is a PDF containing the written ACH authorization agreement. An ACH mandate has a specific format and required content, as defined by ACH regulations. It is part of the ACH payment system, and you cannot charge a bank account without obtaining an ACH mandate.

The ACH mandate is created and sent to your payer by Flywire, you don't need to create and send it yourself.

surcharge object

Only returned if a surcharge applies to the payment. If a surcharge is applied and you are handling emails to your payer yourself, you need to include the surcharge information in the pre-notification email.

A surcharge may apply in certain situations, including, but not limited to, mismatches between card currency and payer country, as well as the use of certain card types. If a surcharge applies and the percentage of it depends on the individual settings for the recipient of the payment.

{
"payment_reference": "RUC208967136",
"charge_info": {
	"amount": 100000,
	"currency": "EUR"
	},
"payment_method": {
	"token": "232301485cfa4b36bc28",
	"type": "card",
	"card_classification": "credit",
	"last_four_digits": "1111",
	"card_expiration": "03/2030",
	"country": "US",
	"brand": "visa",
	"issuer": "JPMORGAN CHASE BANK, N.A."
	},
"mandate": {
	"id": "MCRUC20230330uAM584YC"
	"surcharge": {
		"percentage": 0.03
		}
	}
}

payment_method object

Contains information about the payment method the payer used and the payment method token.

You can display the card information in your UI for your payer to make it easier for them to identify which card they saved in your system.

mandate object

It is mandatory to include the mandate ID when charging the payment.

id string

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

surcharge object

Only returned if a surcharge applies to the payment. If a surcharge is applied and you are handling emails to your payer yourself, you need to include the surcharge information in the pre-notification email.

A surcharge may apply in certain situations, including, but not limited to, mismatches between card currency and payer country, as well as the use of certain card types. If a surcharge applies and the percentage of it depends on the individual settings for the recipient of the payment.

{
"payment_method": {
	"token": "232301485cfa4b36bc28",
	"type": "card",
	"card_classification": "credit",
	"last_four_digits": "1111",
	"card_expiration": "03/2030",
	"country": "US",
	"brand": "visa",
	"issuer": "JPMORGAN CHASE BANK, N.A."
	},
"mandate": {
	"id": "MCRUC20230330uAM584YC"
	"surcharge": {
		"percentage": 0.03
		}
	}
}

payment_method object

Contains information about the payment method the payer used and the payment method token.

mandate object

It is mandatory to include the mandate ID when charging the payment.

id string

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

{
    "payment_method": {
        "token": "_jRS8z0CrDyDI2KshDPZ",
        "type": "direct_debit",
        "last_four_digits": "6789"
    },
    "mandate": {
        "id": "MUUI20230131XCGPRT"
    }
}

charge_info object

payment_method object

Contains information about the payment method the payer used and the payment method token.

mandate object

It is mandatory to include the mandate ID when charging the payment.

id string

The mandate ID.

The mandate ID is a Flywire-generated ID that represents the payer's consent for recurring payments, much like a signature authorizing future payments.

After tokenizing a card or bank account, the mandate ID is returned to you in the mandate_id parameter or in the id parameter inside the mandate object.

Format of mandate IDs

Payment Method

Mandate ID Format

Bank account

MT+ recipient ID + date of mandate generation + string of characters

Example: MTQQ20240430NTZTZX

Card that has only been tokenized, payments are charged later

MC + ZER + date of mandate generation + string of characters

Example: MCZER20240430SaA8rNHh

Card that has been tokenized and the first payment has been charged immediately

MC + recipient ID + date of mandate generation + string of characters

Example: MCTQQ20240430HaB7fKMg

It is mandatory to include the mandate ID when charging the payment.

For bank accounts, the mandate is represented by the mandate ID and additionally in PDF form.

{
    "payment_reference": "RUC670821548",
    "charge_info": {
        "amount": 101300,
        "currency": "EUR"
    },
    "payment_method": {
        "token": "UW6JqAuMcJje-SyR3iIG",
        "type": "direct_debit",
        "last_four_digits": "6789"
    },
    "mandate": {
        "id": "MRUC20230330QBZ6MP"
    }

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"
}

If you provided a notifications URL for the payment, you’ll start receiving notifications that let you track the payment’s progress (see Payment Status Notifications).

charge_info object

{
"payment_reference": "RUC208967136",
"charge_info": {
	"amount": 100000,
	"currency": "EUR"
	}
}

Keep in mind that for Pre-Authorization Payments, the payment amount is only being held on the card. The payment is not processed any further until you capture the funds.

If you provided a notifications URL for the payment, you’ll start receiving notifications that let you track the payment’s progress (see Payment Status Notifications).

charge_info object

{
"payment_reference": "RUC208967136",
"charge_info": {
	"amount": 100000,
	"currency": "EUR"
	}
}

Checkout Sessions

List of endpoints

1. Creating a Checkout Session

Request

Self-Managed Recurring Payments

Flywire-Managed Recurring Payments

One Off Payment

Pre-Authorization Payment

Response

2. The Payer's Side: Filling out the Form

What does the payer see on my page?

Self-Managed Recurring Payments

Flywire-Managed Recurring Payments

One Off Payment

Pre-Authorization Payment

3. The postMessage of the Event Listener

Self-Managed Recurring Payments

Flywire-Managed Recurring Payments

One Off Payment

Pre-Authorization Payment

4. Confirming a Checkout Session

Request

Response

Self-Managed Recurring Payments

Flywire-Managed Recurring Payments

One Off Payment

Pre-Authorization Payment