Testing Self-Managed Recurring Payments

This page guides you through testing your integration - it guides you through creating payments and testing various behaviors. It does not cover all possible payment flows. For simulating payment flows and testing callbacks for each payment status, refer to Testing Payment Flows.

Testing requires you to make API calls in the Sandbox environment:

Make sure you have credentials for the API Sandbox.

Remember to use the Sandbox environment for all tests:

https://api-platform-sandbox.flywire.com/

Testing Card Payment Scenarios

1. Prepare your test scenario.

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.
Help for finding recipients
The list of recipients contains all the recipients that are available to you as a client. You can display this list in your UI, for example as a drop down, so that the person creating the payment in your system can choose one of the recipients.

If you don’t have any recipients the request will still be successful, but the list will be empty.
Parameters for the Request Body

No request body needed.

Optional Query Parameters for Pagination

This endpoint supports pagination. If you are not providing any pagination parameters, the response is returned with default pagination settings.

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

Default setting

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

page integerquery parameter

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

per_page integer query parameter

Enables you to define how many results will be included per page.

Possible values: min 1, max 100
GET /payments/v1/recipients
curl https://base-url-placeholder/recipients?page=1&per_page=100 -X GET -H "Content-Type: application/json" -H "X-Authentication-Key: {api_key}"

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 charge in their account 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

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 schemes SEPA and ACH.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

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

charge_intent object

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

These fields enable you to pass payer data to pre-fill the fields of the form.

Help for pre-filling payer fields

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

Pre-filling fields is optional. If no values are provided, the fields will be empty for the payer to complete.
Pre-filling fields alone does not affect if fields are editable. Pre-filled fields remain editable unless you explicitly made them read-only or hide them via the settings.

Best practice

Before pre-filling payer fields, consider who the actual payer is.

The form asks for the cardholder or bank account owner’s information. There can be cases when the personal data you have on stored (for example, in your ERP system) is different from the data for the actual payer. Always consider which information you store in your system and how useful it is for pre-filling fields.

Example: Students log into your school portal to pay tuition. In most cases, their parents pay the tuition with their credit card. If you automatically pre-fill the payer fields with the student's profile info, every student has to correct the info and change it to their parent's information.

This distinction is crucial if you plan to hide fields or make them read-only. If you use the wrong data for pre-filling fields and make it impossible for the payer to change it, you could prevent them from completing the payment.

You can to set these fields to hidden or read-only for the payer through settings in the options object.

More info about setting fields to hidden or read-only

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

All payer fields are required to send the form. If your settings would prevent the payer from submitting the form - for example you're hiding the email field but provided an invalid address- the field automatically becomes visible and editable.

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

options object

These settings affect how the Elements form is displayed to your payer.

If you want to set payer fields to hidden or read-only, read this information first.

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

form object

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

boolean

Controls if the payer fields in the Element form can be edited by the payer:

true: All payer fields will be displayed but are not editable.
false (default): All payer fields will be displayed and are editable.

You can set all fields to read-only and then overwrite the setting for individual fields.

More info about controlling which fields can be edited by the payer

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

payor_fields object

Here you can define hidden and read_only settings for individual payer fields.

List of all available fields

first_name
last_name
address
city
country
state
phone
email
zip

If you defined a global setting via the payor_fields_read_only parameter, the settings for an individual field will overwrite the global setting.

More info about controlling which fields can be edited by the payer

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

Example:

first_name object

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",
    "schema": "cards",						
    "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,
		    "payor_fields_read_only": true,
		    "payor_fields": {
        	   "first_name": {
           	      "hidden": false,
                  "read_only": false
                  },
              "last_name": {
                 "hidden": true,
                 "read_only": false
                 }
              }
    },
    "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.");
        }
    }
});

2. Enter the magic values for your test scenario.

Enter the magic values in the fields First Name and Last Name. The other payer data fields do not affect the test scenario.

First Name Last Name Will the card be tokenized? Will 3DS be triggered? Will payments with this card be successful? Statuses for payments with this card Scenario Description

RECURRING CARD AUTH

yes

yes

yes

Initiated → Processed → Guaranteed

"Happy path" with 3DS
Use this scenario if you want to test 3DS behavior.

RECURRING CARD APPROVED

yes

no

yes

Initiated → Processed → Guaranteed

"Happy path" without 3DS

Use this scenario if you want to skip the 3DS verification.

PAYMENT DELIVERED

yes

no

yes

Initiated → Processed → Guaranteed → Delivered

"Happy path" with delivered payments

Use this scenario if you want to create payments that go into the delivered status.

RECURRING CARD EXPIRED

yes

no

no

Initiated → Cancelled

Card is expired
Use these scenarios if you want to test payments that fail.

RECURRING CARD FRAUD

yes

no

no

Initiated → Cancelled

Card is declined

RECURRING CARD NOT ENOUGH BALANCE

yes

no

no

Initiated → Cancelled

Card doesn't have enough balance

First Name	Last Name	Will the card be tokenized?	Will 3DS be triggered?	Will payments with this card be successful?	Statuses for payments with this card	Scenario Description
RECURRING CARD	AUTH	yes	yes	yes	Initiated → Processed → Guaranteed	"Happy path" with 3DS Use this scenario if you want to test 3DS behavior.
RECURRING CARD	APPROVED	yes	no	yes	Initiated → Processed → Guaranteed	"Happy path" without 3DS Use this scenario if you want to skip the 3DS verification.
PAYMENT	DELIVERED	yes	no	yes	Initiated → Processed → Guaranteed → Delivered	"Happy path" with delivered payments Use this scenario if you want to create payments that go into the delivered status.
RECURRING CARD	EXPIRED	yes	no	no	Initiated → Cancelled	Card is expired	Use these scenarios if you want to test payments that fail.
RECURRING CARD	FRAUD	yes	no	no	Initiated → Cancelled	Card is declined
RECURRING CARD	NOT ENOUGH BALANCE	yes	no	no	Initiated → Cancelled	Card doesn't have enough balance

3. Enter test credit card details.

Does it matter which card I use for the scenario?

No. All test cards work with all magic values and trigger the chosen scenario.

What is the purpose of the different test cards?

You can try out different cards from different countries to test the behavior of the element when card country and payer country don't match.

How can non-matching countries affect the element behavior?

Choose currency

If the card currency doesn't match the currency of the payer's country, and if there is an option to pay in either of them, the payer can choose which currency they want to pay in. They have two options: The currency of the card they are paying with and the currency of the country they have chosen for their address.

Accept to pay in card currency

This message appears if the card currency doesn't match the currency of the payer's country and there is no option to pay in the country's currency.

After clicking "Accept", the payer can proceed to pay. Alternatively, they can use a different card for the payment.

The demo cards must be used together with cardholder name magic values.

Number Expiration date CVV Currency Issuing Country Type

Visa

4010 1000 0000 0016 03/30 737 EUR DE Debit

4988 4388 4000 0012 03/30 737 EUR ES Debit

4242 4201 0000 0017 03/30 737 GBP GB Credit

4761 3600 0000 0017 03/30 737 INR IN Debit

4111 1111 1111 1111 03/30 737 USD US Credit

Mastercard

2222 4000 1000 0016 03/30 737 CAD CA Credit

5163 6136 0000 0014 03/30 737 AUD AU Debit

5252 5202 0000 0017 03/30 737 JPY JP Debit

5454 5454 5454 5454 03/30 737 USD US Credit

American Express (Amex)

3700 0000 0000 002 03/30 7373 USD
US
Credit

Number	Expiration date	CVV	Currency	Issuing Country	Type
Visa
4010 1000 0000 0016	03/30	737	EUR	DE	Debit
4988 4388 4000 0012	03/30	737	EUR	ES	Debit
4242 4201 0000 0017	03/30	737	GBP	GB	Credit
4761 3600 0000 0017	03/30	737	INR	IN	Debit
4111 1111 1111 1111	03/30	737	USD	US	Credit
Mastercard
2222 4000 1000 0016	03/30	737	CAD	CA	Credit
5163 6136 0000 0014	03/30	737	AUD	AU	Debit
5252 5202 0000 0017	03/30	737	JPY	JP	Debit
5454 5454 5454 5454	03/30	737	USD	US	Credit
American Express (Amex)
3700 0000 0000 002	03/30	7373	USD	US	Credit

4. Complete the test payment.

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

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 a recurring 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.

6. Create a payment with the tokenized card.

All payments you charge with the tokenized card will behave according to the scenario you chose. The payer's first and last name (which include the magic values) are part of the payment method token you received and can't be changed.

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.).

Tip if you don't know the configuration of a recipient (fields, items, etc.)

You can see the full configuration of a recipient with this request (replace {id} with the recipient ID):

GET/payments/v1/recipients/{recipientId}

The configuration will show you the fields, items, and settings of a recipient.

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.
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).

Why?

This endpoint creates a recurring payment within a self-managed plan. This is a manual step since Flywire doesn't know your payment schedule, meaning you have to ensure that recurring payments are created on time. If you want recurring payments to get created automatically, you can use Flywire-Managed Plans.

You need a payment method token, mandate ID and payer 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 a recurring 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.

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.

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 a recurring 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.

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.

payment_method_token string

Provide the payment method token for this payment.

What is 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 you store them via Flywire Elements. 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.

Format:

String of 20 characters, for example:

a1b2c3d4e5f67890abcd

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.

payor_id string

The payor_id depends on how you want to uniquely identify a payer. Usually, you use an ID from another system, for example your ERP. Spaces are not allowed.

When you are creating follow-up payments you must use the same payor_id you used when you created the Checkout Session.

recipient object

id string

The recipient ID (also called portal code).

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

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

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.

How to find out which fields are required for a recipient

You have two options:

Checking via the API

You can check which fields are required for a recipient (portal) with this request (replace {recipientId} with the recipient ID):

GET/payments/v1/recipients/{recipientId}

Required fields have the required parameter set to true. For more info see Getting Details about a Recipient.

Checking online

You can check which fields are required by checking your portal configuration.

id string

Identifier of the field.

value string

The value for this field.

items array

What is an item?

An item is something that your payer can pay for (for example: tuition fees, housing, etc.). When you create a payment, you display the items to your payer and they can choose for which items they want to pay. How many items there are depends on the recipient's configuration.

Can I use multiple items?

You can only use one item in this request. The id of the item must be called default.

id string

Identifier of the item.

You can only use one item in this request. The id of the item must be called default.

amount integer

The amount for this item in the billing currency,

What is the billing currency?

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

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

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

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

What is metadata?

Custom metadata is additional data entered by you when you create the payment, for example data you need to identify the payment in your system. Metadata can be useful when you want to add data that is not already covered by recipient fields, for example if you are not the one who set up the recipient and have no influence on the fields.

Metadata consist of pairs of keys and values, for example key Payer_ID_From_My_System and value ID12345.

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

external_reference string

The external reference.

The external reference helps you to identify a payment, since the Flywire-generated payment reference might not be the way you typically identify payments. With the external reference, you can enter your own identifier, such as an ID or invoice number.

The external reference is included in all status notifications to help you map a payment to a callback notification. (see Payment Status Notifications)

You can provide an external reference with a max size of 50 characters.
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"
}

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

5. Check the callbacks for your test scenario.

You'll receive the following notifications via callbacks:

If you chose a scenario with successful payments:

Initiated

Processed

Guaranteed

f you chose a scenario with successful payments that go into the delivered status:
Initiated

Processed

Guaranteed

Delivered

If you chose a scenario with failed payments:

Initiated

Cancelled

Testing Direct Debit Payment Scenarios

1. Prepare your testing scenario.

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.
Help for finding recipients
The list of recipients contains all the recipients that are available to you as a client. You can display this list in your UI, for example as a drop down, so that the person creating the payment in your system can choose one of the recipients.

If you don’t have any recipients the request will still be successful, but the list will be empty.
Parameters for the Request Body

No request body needed.

Optional Query Parameters for Pagination

This endpoint supports pagination. If you are not providing any pagination parameters, the response is returned with default pagination settings.

Pagination parameters are added as query parameters with the request in the format {endpoint_path}?page=2&per_page=10

Default setting

The default setting is:

page=1 (start on page 1)

per_page=10 (display 10 entries per page)

page integerquery parameter

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

per_page integer query parameter

Enables you to define how many results will be included per page.

Possible values: min 1, max 100
GET /payments/v1/recipients
curl https://base-url-placeholder/recipients?page=1&per_page=100 -X GET -H "Content-Type: application/json" -H "X-Authentication-Key: {api_key}"

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

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 schemes SEPA and ACH.	tokenization_and_pay
For creating a new mandate for an existing card.	new_mandate

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

charge_intent object

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

These fields enable you to pass payer data to pre-fill the fields of the form.

Help for pre-filling payer fields

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

Pre-filling fields is optional. If no values are provided, the fields will be empty for the payer to complete.
Pre-filling fields alone does not affect if fields are editable. Pre-filled fields remain editable unless you explicitly made them read-only or hide them via the settings.

Best practice

Before pre-filling payer fields, consider who the actual payer is.

You can to set these fields to hidden or read-only for the payer through settings in the options object.

More info about setting fields to hidden or read-only

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

options object

These settings affect how the Elements form is displayed to your payer.

If you want to set payer fields to hidden or read-only, read this information first.

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

form object

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

boolean

Controls if the payer fields in the Element form can be edited by the payer:

true: All payer fields will be displayed but are not editable.
false (default): All payer fields will be displayed and are editable.

You can set all fields to read-only and then overwrite the setting for individual fields.

More info about controlling which fields can be edited by the payer

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

payor_fields object

Here you can define hidden and read_only settings for individual payer fields.

List of all available fields

first_name
last_name
address
city
country
state
phone
email
zip

If you defined a global setting via the payor_fields_read_only parameter, the settings for an individual field will overwrite the global setting.

More info about controlling which fields can be edited by the payer

When using Elements, you can control which payer fields can be edited by your payer - either by setting them to read-only or be completely hiding the field from the payer.

You can configure read-only at three levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session) Global form settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field > Global Form This means Smart Rendering settings win over individual field settings, and individual field settings win over global form settings.

You can configure the visibility of fields at two levels:
Smart Rendering settings (if you are using Smart Rendering) Individual field settings (defined in the form options when creating a Checkout Session)	What happens if a field has conflicting settings at multiple levels? Smart Rendering > Individual Field This means Smart Rendering settings win over individual field settings.

What happens if something goes wrong? - Automatic Field Unlocking

Automatic field unlocking happens for a hidden or read-only field when:

you didn't submit a value through the Checkout Session (results in an empty field for the payer to fill out)
you submitted an invalid value through the Checkout Session (results in a field showing the invalid value, highlighted with an error message so that the payer can correct it)

Example:

first_name object

Note for the recipient for direct debit payments

The recipient's billing currency must match the currency of the direct debit scheme. For example, since BACS is only available in the UK you can only use recipients that have GBP as their billing currency.

If the recipient's billing currency doesn't match the direct debit scheme, 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",
    "schema": "dd_sepa",						
    "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,
		    "payor_fields_read_only": true,
		    "payor_fields": {
        	   "first_name": {
           	      "hidden": false,
                  "read_only": false
                  },
              "last_name": {
                 "hidden": true,
                 "read_only": false
                 }
              }
    },								
    "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.");
        }
    }
});

2. Enter the magic values for your test scenario.

Enter the magic values in the fields First Name and Last Name. The other payer data fields do not affect the test scenario.

First Name Last Name Will the bank account be tokenized? Will payments with this bank account be successful? Statuses for payments with this card Scenario Description

DIRECT DEBIT

SUCCESS

yes

yes

Initiated

"Happy path" but payments will not move to further statuses.

Use this scenario if you want to tokenize the bank account and create successful payments.

PAYMENT DELIVERED

yes

yes

Initiated → Processed → Guaranteed → Delivered

"Happy path", payments will move into status delivered.

Use this scenario if you want to tokenize the bank account and create successful payments that move into status Delivered.

DIRECT DEBIT

FAIL

yes

no

Initiated → Cancelled

Payment failure

Use this scenario if you want to tokenize the bank account and create payments that will fail.

Details about the failed direct debit scenario

A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.

DIRECT DEBIT

CONNECTIVITY ERROR

no

-

-

Connectivity failure

Use this scenario if you want to simulate a connectivity error (either to Flywire or to the bank) that prevents tokenization of the bank account.

First Name	Last Name	Will the bank account be tokenized?	Will payments with this bank account be successful?	Statuses for payments with this card	Scenario Description
DIRECT DEBIT	SUCCESS	yes	yes	Initiated	"Happy path" but payments will not move to further statuses. Use this scenario if you want to tokenize the bank account and create successful payments.
PAYMENT	DELIVERED	yes	yes	Initiated → Processed → Guaranteed → Delivered	"Happy path", payments will move into status delivered. Use this scenario if you want to tokenize the bank account and create successful payments that move into status Delivered.
DIRECT DEBIT	FAIL	yes	no	Initiated → Cancelled	Payment failure Use this scenario if you want to tokenize the bank account and create payments that will fail. Details about the failed direct debit scenario A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc.
DIRECT DEBIT	CONNECTIVITY ERROR	no	-	-	Connectivity failure Use this scenario if you want to simulate a connectivity error (either to Flywire or to the bank) that prevents tokenization of the bank account.

3. Enter test bank account details.

All test bank accounts work with all magic values and trigger the chosen scenario.

For SEPA direct debit

Country

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

IBAN

ES7921000813610123456789

For BACS direct debit

Country
United Kingdom

Sort Code

60-00-01

Account Number

00000019

For ACH direct debit

Country
United States

Routing Number

123456789

Account Number

123456789

Account Type You can choose either Checking or Savings, both will work for the test.

For EFT Canada direct debit

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

4. Complete the test payment.

Confirm the mandate screen and send the form.

5. For connectivity fail scenarios: Check the error message.

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

6. For all other scenarios: Confirm the Checkout Session.

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

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 a recurring 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.

7. Create a payment with the tokenized bank account.

All payments you charge with the tokenized bank account will behave according to the scenario you chose. The payer's first and last name (which include the magic values) are part of the payment method token you received and can't be changed.

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.).

Tip if you don't know the configuration of a recipient (fields, items, etc.)

You can see the full configuration of a recipient with this request (replace {id} with the recipient ID):

GET/payments/v1/recipients/{recipientId}

The configuration will show you the fields, items, and settings of a recipient.

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.
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).

Why?

This endpoint creates a recurring payment within a self-managed plan. This is a manual step since Flywire doesn't know your payment schedule, meaning you have to ensure that recurring payments are created on time. If you want recurring payments to get created automatically, you can use Flywire-Managed Plans.

You need a payment method token, mandate ID and payer 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 a recurring 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.

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.

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 a recurring 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.

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.

payment_method_token string

Provide the payment method token for this payment.

What is 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 you store them via Flywire Elements. 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.

Format:

String of 20 characters, for example:

a1b2c3d4e5f67890abcd

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.

payor_id string

The payor_id depends on how you want to uniquely identify a payer. Usually, you use an ID from another system, for example your ERP. Spaces are not allowed.

When you are creating follow-up payments you must use the same payor_id you used when you created the Checkout Session.

recipient object

id string

The recipient ID (also called portal code).

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

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

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.

How to find out which fields are required for a recipient

You have two options:

Checking via the API

You can check which fields are required for a recipient (portal) with this request (replace {recipientId} with the recipient ID):

GET/payments/v1/recipients/{recipientId}

Required fields have the required parameter set to true. For more info see Getting Details about a Recipient.

Checking online

You can check which fields are required by checking your portal configuration.

id string

Identifier of the field.

value string

The value for this field.

items array

What is an item?

An item is something that your payer can pay for (for example: tuition fees, housing, etc.). When you create a payment, you display the items to your payer and they can choose for which items they want to pay. How many items there are depends on the recipient's configuration.

Can I use multiple items?

You can only use one item in this request. The id of the item must be called default.

id string

Identifier of the item.

You can only use one item in this request. The id of the item must be called default.

amount integer

The amount for this item in the billing currency,

What is the billing currency?

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

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

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

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

What is metadata?

Custom metadata is additional data entered by you when you create the payment, for example data you need to identify the payment in your system. Metadata can be useful when you want to add data that is not already covered by recipient fields, for example if you are not the one who set up the recipient and have no influence on the fields.

Metadata consist of pairs of keys and values, for example key Payer_ID_From_My_System and value ID12345.

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

external_reference string

The external reference.

The external reference helps you to identify a payment, since the Flywire-generated payment reference might not be the way you typically identify payments. With the external reference, you can enter your own identifier, such as an ID or invoice number.

The external reference is included in all status notifications to help you map a payment to a callback notification. (see Payment Status Notifications)

You can provide an external reference with a max size of 50 characters.
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"
}

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

8. Check the callbacks for your test scenario.

You'll receive the following notifications via callbacks:

If you chose a scenario with successful payments that doesn't move the payment:

Initiated

If you chose a scenario with successful payments that moves payments into delivered:
Initiated

Processed

Guaranteed

Delivered

If you chose a scenario with failed payments:

Initiated

Cancelled

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

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

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

Country	United States
Routing Number	123456789
Account Number	123456789
Account Type	You can choose either Checking or Savings, both will work for the test.