Testing Pre-Authorization Payments

1. Choose the recipient for the test payment.

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

The default setting is:

  • page=1 (start on page 1)

  • per_page=10 (display 10 entries per page)

Enables you to access a specific page of the results.

Possible values: Any positive number except zero.

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

Possible values: min 1, max 100

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

2. Create a Checkout Session.

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

Parameters for the Request Body

The type of the Checkout Session. Must be tokenization_and_pay for Pre-Authorization Payments.

charge_intent object

Must be manual. This parameter ensures that you are able to manually capture the funds within the holding period.

The authorization type defines if the blocked amount can be changed during the holding phase.

Possible values:

  • preauth : The amount that has been authorized can be changed during the holding phase, see .

  • final: The amount that has been authorized is final and cannot be changed.

The mode of a payment depends on three factors:

  • Frequency: Are the intervals for the payment regular or irregular?

  • Purchase: Is it one single purchase or are new goods/services purchased? 

  • Delivery: Are the goods/services delivered once or in multiple deliveries?

Available modes

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

installment

regular or irregular intervals

Single purchase of goods or services

Single delivery (can be in advance, at any time during the plan, or at the end)

subscription

Regular intervals

Multiple purchases (for new or renewed goods or services)

Multiple and regular deliveries

unscheduled

No pre-agreed intervals

Multiple purchases (for new or renewed goods or services)

Multiple deliveries at no pre-agreed intervals

payor object

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

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

Before pre-filling the payer fields, consider your use case and who the actual payer will be. The UI forms collect the card holder or bank account owner information. There can be cases when this person is different from the payer in your system.

For example, if you are a school and your system stores information about a student, you consider the student as the “payer”. But the person who actually pays could be the student’s parent. In this case, it would not make sense to pre-fill the fields with the student’s information, since the card holder is a different person. On the other hand, the payer can always edit the fields in the UI form, which means even if you are pre-filling the fields with the wrong details the payer can always correct them.

In order to create the best payment experience for your payers, consider which information you store in your system and how useful it is for them when fields are already filled out.

options object

Contains settings for the UI form.

form object

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

Possible values

  • save (default value)

  • next

  • pay

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

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

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

Controls if the "Powered by Flywire" logo is shown at the bottom of the form.

true displays the logo, false hides the logo.

The logo is shown below the action button of the UI form:

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.

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

GET/recipients/{recipientId}

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

Identifier of the field.

The value for this field.

items array

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.

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

Identifier of the item.

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

The amount for this item in 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.

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.

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

 

The external reference.

The external reference is used to match a notification to a particular payment. You can use any kind of identifier or reference from your own system you might need to identify the payment. The external reference is included in all status notifications for this payment (refer to Payment Status Notifications) to help you match the notification to the right payment using your own reference in addition to the Flywire-generated payment reference.

You can provide an external reference with a max size of 50 characters.

The recipient ID.

The recipient ID is the unique three-letter ID that identifies the recipient, for example FWU for Flywire University. The recipient ID has been assigned by Flywire when the recipient has been set up.

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

For details see Getting a List of all available Recipients.

Must be cards for Pre-Authorization Payments since only card payments can be pre-authorized.

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.
POST /checkout/sessions
curl https://base-url-placeholder/checkout/sessions
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
    "type": "tokenization_and_pay",
	"charge_intent": {
		"capture": "manual",
		"authorization": "preauth",
		"mode": "subscription"
	},
   "payor": {
		"first_name": "Peter",
		"last_name": "Payer",
		"address": "123 High Street",
		"city": "London",
		"country": "GB",
		"state": "",
		"phone": "0044123456789",
		"email": "[email protected]",
		"zip": "SW1A 1AA"
    },
    "options": {
        "form": {
            "action_button": "save",
            "locale": "en",
            "show_flywire_logo": true
        }
    },
	"recipient": {
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
    "items": [
        {
            "id": "default",
            "amount": 33000,
        }
    ],
    "notifications_url": "https://webhook.site/9bf9cf8d-1d8c-46d1-b147-ca5841ff2ede",
    "external_reference": "Payment ID12456",
    "recipient_id": "FLW",
    "schema": "cards",
    "payor_id": "MyPayerID"
}

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

3. Open the URL for the form in your browser.

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

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.");
        }
    }
});

5. Enter the magic values for the scenario you want to test.

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

Scenario First Name Last Name

3DS will be triggered before the payment will be created.

The payment will stay in initiated until captured.

RECURRING CARD AUTH

3DS will not be triggered and the payment will be immediately created.

The payment will stay in initiated until captured.

RECURRING CARD APPROVED

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

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

8. Check the console in your browser's development tools.

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

9. Confirm the 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 postMessage.

Why should I use the confirm url from the postMessage?

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

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

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

POST/checkout/sessions/{ID}/confirm

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

You'll receive the payment reference in the response.

10. Check the notifications.

The payment is now created according to your scenario. You'll receive the following notifications:

Initiated

Authorized (immediately after initiated)