Testing Flywire-Managed Recurring Payments

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/

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

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

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

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.

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