Testing Recurring Payments

Self-Managed Recurring Payments: Card Scenarios

Decide which recipient you want to use.

What is a recipient?

A recipient - also called a portal - contains the information that is needed for receiving funds, like the receiving bank account , the currency in which Flywire takes payments from your payers, or specific fields your system requires to process a payment. Flywire assigns each recipient a unique identifier, called recipient ID or portal code.

You as a client can have multiple recipients, for example for different bank accounts or currencies.

Tip if you don't know which recipients are available to you or what their recipient ID is

You can use this request to get a list of all recipients that are available to you as a client and what their recipient ID is:

GET /payments/v1/recipients

For details see Getting a List of all available Recipients.

Create a Checkout Session.

You'll receive a URL for the UI form in the API response.

Since you are testing status notifications, make sure to provide a notifications URL where you can receive the notifications via callbacks.

How to create a Checkout Session for cards

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

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

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 /payments/v1/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"
}'

Open the URL for the form in your browser.

In your browser, add the event listener code to the page.

How to add the event listener code

Open the developer tools for your browser and add the following event listener code via the console.

window.addEventListener("message", (event) => {
    // IMPORTANT: Verify the origin of the data to ensure it is from Flywire
    // The use of indexOf ensures that the origin ends with ".flywire.com"
    if (event.origin.indexOf(".flywire.com")) {
        // If the message was sent from Flywire:
        // Extract the data from the event
        const result = event.data;
        if (result.source !== 'checkout_session') {
            return;
        }

        // Check if the session was successful and confirm_url is present:
        if (result.success && result.confirm_url) {
            // The session was successful and the confirm_url has been returned
            const confirm_url = result.confirm_url;
            console.log(result);
            // Use the confirm_url to confirm the Checkout Session
            console.log("Confirm URL:", confirm_url.url);
        } else {
            // Handle failure accordingly
            console.error("Session unsuccessful or confirm_url missing.");
        }
    }
});

Enter the magic values for the scenario you want to test in the fields First Name and Last Name.

All other fields except First Name and Last Name do not affect the test scenario, you can fill them with any data you want.

Scenarios for testing tokenization and charging payments

In these scenarios you tokenize the card and charge payments, either successfully or unsuccessfully.

When you use one of these magic values, the payment will go through the following flow:
Initiated > Processed > Guaranteed

If you want to move a payment to Delivered, see "Scenarios for testing payment status notifications".

Scenario	First Name	Last Name
"Happy path", meaning no errors. 3DS will be triggered. The card will be tokenized, and a payment that uses this card will successfully be charged.	RECURRING CARD	AUTH
"Happy path", meaning no errors. 3DS will not be triggered. The card will be tokenized, and a payment that uses this card will successfully be charged.	RECURRING CARD	APPROVED
Credit card is expired. The card will be tokenized, but payments that try to use this card will not be charged successfully.	RECURRING CARD	EXPIRED
Credit card is declined because of fraud suspicion. The card will be tokenized, but payments that try to use this card will not be charged sucessfully.	RECURRING CARD	FRAUD
Credit card doesn't have enough balance and can't be charged for this payment. The card will be tokenized, but payments that try to use this card will not be charged sucessfully.	RECURRING CARD	NOT ENOUGH BALANCE

Scenarios for testing payment status notifications

In these scenarios you tokenize the card and charge a payment. The payment will be charged successfully and is then automatically moved through different payment statuses depending on the magic value.

You'll get a notification for each status change, see Payment Status Notifications for more details about payment statuses and the notifications you can receive for them.

Scenario	First Name	Last Name
The payment will go from initiated to processed to guaranteed to delivered within a few seconds.	PAYMENT	DELIVERED

Enter a demo credit card details into the payment information fields.

Brand	Number	Expiration date	CVV
Visa	4111 1111 1111 1111	03/30	737
Mastercard	5454 5454 5454 5454	03/30	737
Amex	3700 0000 0000 002	03/30	7373

Send the form.

If you used a scenario that triggers 3DS authentication, you now see the Flywire 3DS authentication simulator. Enter the word password in the password field and click on continue to complete the authentication.

Check the console in your browser's development tools.

The event listener will return the URL for confirming the Checkout Session.

Confirm the Checkout Session.

How to confirm a Checkout Session

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 the postMessage (see 3. The postMessage of the Event Listener).

Why should you 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.

Parameters for the Request Body

No request body needed.

POST/payments/v1/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}"

You'll receive an payment method token and an mandate ID in the response.

What is 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.

Create and charge a payment with the payment method token and mandate ID you received.

This request requires the recipient and its exact configuration (fields, items, etc.).

How to create and charge a payment

This is only an example of how the request could look like. You need to make sure to insert your own recipient, its fields, items etc. You also need to use the Sandbox Base URL (https://api-platform-sandbox.flywire.com/payments/v1/) when you are in the Sandbox environment.
You'll find all details about creating and charging a payment in the resource description (see Creating a Payment within a Self-Managed Recurring Plan.

This endpoint is only for creating follow-up payments of a self-managed plan (see Use Case: Self-Managed Recurring Payments).

You need a payment method token, mandate ID and payor ID to use this request.

More information

The payment method token contains payer and payment method information.

The payer and payment information has been gathered via a UI form and stored in the payment_method object. This information is used for the future payments. The payer information is passed via the payment_method_token when you charge a payment.

Where do I find the payment method token?

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/payments/v1/payors/{payorId}/payment_methods

For details see Getting a List of all stored Payment Methods for a Payer.
It is mandatory to include the mandate ID when charging the payment.

Why is it mandatory?

For some card payments, this is mandatory to be compliant with policies. For example the mandate ID serves as the "Visa Transaction ID", which is mandatory since October 31st, 2022 (not providing the Visa Transaction ID could result in soft declines and fees for non-compliance). Other payment processors may require a similar ID for consent verification in the future.

Flywire generates mandate IDs for both cards and bank accounts to ensure future readiness.

Where do I find the mandate ID?

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

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

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

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

mandate_id string

Provide the mandate ID for this payment.

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 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 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 created and sent to your payer by Flywire, you don't need to create and send it yourself.

payment_method_token string

Provide the payment method token for this payment.

recipient object

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

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

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/payments/v1/payments/charge

curl https://base-url-placeholder/payments/charge
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
    "charge_intent": {
        "mode": "subscription"
    },
    "mandate_id": "MCHUV20220526UAUTYQ8W",
    "payment_method_token": "e1278a8863eaef9b7a7c",
    "payor_id": "payor_CCC",
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 5000,
        }
    ],
    "metadata": {
       "Internal-ID": "12345",
       "Int-Comment": "A comment about this payment"
    },
    "notifications_url": "http://a-callback-url.com/callback",
    "external_reference": "a-reference"
}

You'll receive the following notifications via callbacks:

If you tested tokenization and charging payments:

If you chose a success scenario:

Initiated

Processed

Guaranteed

If you chose a fail scenario:

Initiated

Cancelled

If you tested payment status notifications:

Payment delivered

Initiated

Processed

Guaranteed

Delivered

Self-Managed Recurring Payments: Direct Debit Scenarios

Decide which recipient you want to use.

What is a recipient?

A recipient - also called a portal - contains the information that is needed for receiving funds, like the receiving bank account , the currency in which Flywire takes payments from your payers, or specific fields your system requires to process a payment. Flywire assigns each recipient a unique identifier, called recipient ID or portal code.

You as a client can have multiple recipients, for example for different bank accounts or currencies.

Tip if you don't know which recipients are available to you or what their recipient ID is

You can use this request to get a list of all recipients that are available to you as a client and what their recipient ID is:

GET /payments/v1/recipients

For details see Getting a List of all available Recipients.

Create a Checkout Session.

You'll receive a URL for the UI form in the API response.

Since you are testing status notifications, make sure to provide a notifications URL where you can receive the notifications via callbacks.

How to create a Checkout Session for direct debit

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

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

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 /payments/v1/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"
}

Open the URL for the form in your browser.

In your browser, add the event listener code to the page.

How to add the event listener code

Open the developer tools for your browser and add the following event listener code via the console.

window.addEventListener("message", (event) => {
    // IMPORTANT: Verify the origin of the data to ensure it is from Flywire
    // The use of indexOf ensures that the origin ends with ".flywire.com"
    if (event.origin.indexOf(".flywire.com")) {
        // If the message was sent from Flywire:
        // Extract the data from the event
        const result = event.data;
        if (result.source !== 'checkout_session') {
            return;
        }

        // Check if the session was successful and confirm_url is present:
        if (result.success && result.confirm_url) {
            // The session was successful and the confirm_url has been returned
            const confirm_url = result.confirm_url;
            console.log(result);
            // Use the confirm_url to confirm the Checkout Session
            console.log("Confirm URL:", confirm_url.url);
        } else {
            // Handle failure accordingly
            console.error("Session unsuccessful or confirm_url missing.");
        }
    }
});

Enter the magic values for the scenario you want to test in the fields First Name and Last Name.

Scenarios for testing tokenization and charging payments

In these scenarios you tokenize the bank account and charge payments, either successfully or unsuccessfully.

When you use one of these magic values, the payment will go through the following flow:
Initiated > Processed > Guaranteed

If you want to move a payment to Delivered , use the magic values in the table "Scenarios for testing payment status notifications".

Scenario First Name Last Name

Payment fail.

The bank account will be tokenized but charging a payment will fail.

DIRECT DEBIT

FAIL

Connectivity fail.

The bank account will not be tokenized due to a connectivity error (either to Flywire or to the bank).

DIRECT DEBIT

CONNECTIVITY ERROR

"Happy path", meaning not an error scenario.

The bank account will be tokenized and payments that use this bank account will be successful.

DIRECT DEBIT

SUCCESS

Scenarios for testing payment status notifications

In these scenarios you tokenize the bank account and charge a payment. The payment will be charged successfully and is then automatically moved through different payment statuses depending on the magic value.

You'll get a notification for each status change, see Payment Status Notifications for more details about payment statuses and the notifications you can receive for them.

Scenario	First Name	Last Name
The payment will go from initiated to processed to guaranteed within a few seconds.	PAYMENT	GUARANTEED
The payment will go from initiated to processed to guaranteed to delivered within a few seconds.	PAYMENT	DELIVERED

Enter demo bank accounts, depending on the scheme your using:

For SEPA direct debit (for all scenarios)

Country	Spain (The demo IBAN is a Spanish IBAN, which means you must choose Spain as a country.)
IBAN	ES7921000813610123456789

For BACS direct debit (for all scenarios)

Country	United Kingdom
Sort Code	60-00-01
Account Number	00000019

For EFT Canada direct debit (for all scenarios)

Connect to the test bank account via Plaid with the following credentials. You can pick any bank you like at the "Pick your bank" screen, and any bank account at the "Pick your account" screen.

Username	user_good
Password	pass_good

Send the form.
The next steps depend on the scenario you want to test:
- If you chose the "connectivity fail" scenario, you'll see "Transaction failed" in the UI with a hint that connectivity issues occurred. The test scenario ends with that.
  
  Example of the end of a "connectivity failed" scenario
- If you chose the "fail" or "success" scenario, you have to create a payment. Complete the following steps to do this.
Check the console in your browser's development tools.

The event listener will return the URL for confirming the Checkout Session.

Confirm the Checkout Session.

How to confirm a Checkout Session

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 the postMessage (see 3. The postMessage of the Event Listener).

Why should you 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.

Parameters for the Request Body

No request body needed.

POST/payments/v1/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}"

You'll receive an payment method token and an mandate ID in the response.

What is 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 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 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 created and sent to your payer by Flywire, you don't need to create and send it yourself.

Create and charge a payment with the payment method token and mandate ID you received.

This request requires the recipient and its exact configuration (fields, items, etc.).

How to create and charge a payment

This endpoint is only for creating follow-up payments of a self-managed plan (see Use Case: Self-Managed Recurring Payments).

You need a payment method token, mandate ID and payor ID to use this request.

More information

The payment method token contains payer and payment method information.

The payer and payment information has been gathered via a UI form and stored in the payment_method object. This information is used for the future payments. The payer information is passed via the payment_method_token when you charge a payment.

Where do I find the payment method token?

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/payments/v1/payors/{payorId}/payment_methods

For details see Getting a List of all stored Payment Methods for a Payer.
It is mandatory to include the mandate ID when charging the payment.

Why is it mandatory?

For some card payments, this is mandatory to be compliant with policies. For example the mandate ID serves as the "Visa Transaction ID", which is mandatory since October 31st, 2022 (not providing the Visa Transaction ID could result in soft declines and fees for non-compliance). Other payment processors may require a similar ID for consent verification in the future.

Flywire generates mandate IDs for both cards and bank accounts to ensure future readiness.

Where do I find the mandate ID?

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

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

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

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

mandate_id string

Provide the mandate ID for this payment.

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 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 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 created and sent to your payer by Flywire, you don't need to create and send it yourself.

payment_method_token string

Provide the payment method token for this payment.

recipient object

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

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

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/payments/v1/payments/charge

curl https://base-url-placeholder/payments/charge
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
    "charge_intent": {
        "mode": "subscription"
    },
    "mandate_id": "MCHUV20220526UAUTYQ8W",
    "payment_method_token": "e1278a8863eaef9b7a7c",
    "payor_id": "payor_CCC",
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 5000,
        }
    ],
    "metadata": {
       "Internal-ID": "12345",
       "Int-Comment": "A comment about this payment"
    },
    "notifications_url": "http://a-callback-url.com/callback",
    "external_reference": "a-reference"
}

You'll receive the following notifications via callbacks:

If you tested tokenization and charging payments:

If you chose a success scenario:

Initiated

Processed

Guaranteed

If you chose a fail scenario:

Initiated

Cancelled

If you tested payment status notifications:

Payment guaranteed

Initiated

Processed

Guaranteed

Payment delivered

Initiated

Processed

Guaranteed

Delivered

Flywire-managed Recurring Payments: Card Scenarios

Decide which recipient you want to use.

What is a recipient?

A recipient - also called a portal - contains the information that is needed for receiving funds, like the receiving bank account , the currency in which Flywire takes payments from your payers, or specific fields your system requires to process a payment. Flywire assigns each recipient a unique identifier, called recipient ID or portal code.

You as a client can have multiple recipients, for example for different bank accounts or currencies.

Tip if you don't know which recipients are available to you or what their recipient ID is

You can use this request to get a list of all recipients that are available to you as a client and what their recipient ID is:

GET /payments/v1/recipients

For details see Getting a List of all available Recipients.

Create a Checkout Session.

You'll receive a URL for the UI form in the API response.

Since you are testing status notifications, make sure to provide a notifications URL where you can receive the notifications via callbacks.

How to create a Checkout Session

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 /payments/v1/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"
}

Open the URL for the form in your browser.

In your browser, add the event listener code to the page.

How to add the event listener code

Open the developer tools for your browser and add the following event listener code via the console.

window.addEventListener("message", (event) => {
    // IMPORTANT: Verify the origin of the data to ensure it is from Flywire
    // The use of indexOf ensures that the origin ends with ".flywire.com"
    if (event.origin.indexOf(".flywire.com")) {
        // If the message was sent from Flywire:
        // Extract the data from the event
        const result = event.data;
        if (result.source !== 'checkout_session') {
            return;
        }

        // Check if the session was successful and confirm_url is present:
        if (result.success && result.confirm_url) {
            // The session was successful and the confirm_url has been returned
            const confirm_url = result.confirm_url;
            console.log(result);
            // Use the confirm_url to confirm the Checkout Session
            console.log("Confirm URL:", confirm_url.url);
        } else {
            // Handle failure accordingly
            console.error("Session unsuccessful or confirm_url missing.");
        }
    }
});

Enter the magic values for the scenario you want to test in the fields First Name and Last Name.

All other fields except First Name and Last Name do not affect the test scenario, you can fill them with any data you want.

Scenario	First Name	Last Name
"Happy path", meaning no errors. 3DS will be triggered. The card will be tokenized, and a payment that uses this card will successfully be charged.	RECURRING CARD	AUTH
"Happy path", meaning no errors. 3DS will not be triggered. The card will be tokenized, and a payment that uses this card will successfully be charged.	RECURRING CARD	APPROVED
Credit card is expired. The card will be tokenized, but payments that try to use this card will not be charged successfully.	RECURRING CARD	EXPIRED
Credit card is declined because of fraud suspicion. The card will be tokenized, but payments that try to use this card will not be charged sucessfully.	RECURRING CARD	FRAUD
Credit card doesn't have enough balance and can't be charged for this payment. The card will be tokenized, but payments that try to use this card will not be charged sucessfully.	RECURRING CARD	NOT ENOUGH BALANCE

Enter a demo credit card details into the payment information fields.

Brand	Number	Expiration date	CVV
Visa	4111 1111 1111 1111	03/30	737
Mastercard	5454 5454 5454 5454	03/30	737
Amex	3700 0000 0000 002	03/30	7373

Send the form.

Check the console in your browser's development tools.

The event listener will return the URL for confirming the Checkout Session.
Confirm the Checkout Session.
How to confirm a Checkout Session
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 the postMessage (see 3. The postMessage of the Event Listener).

Why should you 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.

Parameters for the Request Body

No request body needed.
POST/payments/v1/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}"

You'll receive the following notifications via callbacks:

For the installment plan:

For all scenarios:

In Progress

For the first payment:

If you chose a success scenario:

Initiated

Processed

Guaranteed

If you chose a fail scenario:

Initiated

Cancelled