Orders

This resource is only relevant for 529 Payments.

List of endpoints

Description Endpoint

Creating an Order

POST/orders

Editing an Order

PATCH/orders/{orderId}

Charging an Order (Creating a Payment)

POST/orders/{orderId}/charge

What is an Order?

You can think of an order as like a "shopping cart" for your payment. It contains all the information needed to create a payment in Flywire, but you can go back and edit it before actually creating a payment with it.

An order contains:

  • the payer information

    A payer is the person who is sending you funds.

    Depending on your business model, the person who is paying might not be the same person you are asking to pay.
    For example, if you are a school and ask students to pay tuition, the person who actually pays might be a parent. In that case, Flywire expects the parent's information when asking for the payer, even though your system considers the student the payer.

  • the recipient information

    A recipient contains the information that is needed for receiving funds, for example, bank details or specific fields your system requires to process a payment.

    You as a client can have multiple recipients. For example, if you want Flywire to send funds to different recipients or if you have different bank accounts for different recipients. Each recipient has a unique three-letter ID.

    Recipients vs. portals
    You might know recipients under the name portals, they refer to the same thing.

  • the offer chosen for this payment

    An offer is the price for an available payment method (credit card, bank transfer, etc.) for a payment.

    Example: The payer needs to pay 5,000 USD for tuition, one of the offers is "Pay 4,300 CNY via Bank Transfer". The offer tells the payer what they have to pay, including FX rates and fees if those apply.

    The amount to pay (price) in offers can change due to FX rates. The final amount is only "locked in" when you create a payment from the order.

    If a payment is done in two different currencies, the amount your payer pays depends on the current FX rate. Since FX rates frequently change, the amount to pay can change too.

    The amount to pay for an offer (given in the price parameter) is the amount at the time you requested the offer. It can change at any moment, even if the offer is used for an order.

    The offers that are available for a payment depends on a combination of the following factors:

    • The chosen recipient.

    • The country or countries involved in the payment (for example, paying from China to the US).

    • The amount of money being paid.

    An offer can also contain additional information needed from the payer to process the payment.

  • optional: A notifications 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.

    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

     

    Even though it is not mandatory, you should provide a notifications URL in order to receive status changes of a payment. When the status of a payment changes, you will receive a notification from Flywire via the provided URL. See Payment Status Notifications for more information.

What is the difference between an order and a payment?

An order is not a payment. An order is the final step before creating a payment.

You can think of an order as like a "shopping cart" for your payment. It contains all the information needed to create a payment in Flywire, but you can go back and edit it before actually creating a payment with it.

An order doesn't have a payment reference yet. As soon as you confirm (charge) an order, it gets a payment reference and turns into a payment.

In everyday usage, a "payment" usually refers to the entire process of making a payment through Flywire. But the term "payment" has a specific meaning in Flywire: 

  1. A payment is considered created when a payment reference is assigned to it, not any earlier stage in the process.

    The payment reference identifies a payment.

    The format for a payment reference is:

    Recipient ID followed by a string of characters, for example FWU744586810.

    With the payment reference, the payment can be tracked during its journey through the different stages of the payment process.

    The payment reference is also important in other situations, for example:

    • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

    • The payment reference helps Flywire to identify the payment if you or your payer needs support.

  2. When the payment reference is assigned, two things happen:

    • The FX rate is locked in for FX payments (FX = "foreign exchange", a payment where one currency has to be converted to a different currency).

    • The payment starts its journey in status initiated, and its progress traceable via the payment reference. If you are using Flywire Dashboard, you can view the payment on your dashboard.

Creating an Order

Request

This endpoint creates an order.

Creating an order does not create a payment. To create a payment, you have to charge the order you created.

 

Parameters for the Request Body

payer object

The payer's first name.

If the payer is a company or organization, use the organization name as the first name.

The payer's middle name.

The last name (family name) of the payer.

If the payer is a company or organization, use the organization name as the last name.

The first line of the payer's address.

The residential address is required for legal reasons, which is why PO boxes are not permitted.

The second line of the payer's address.

The payer's city.

The payer's zip code.

The country of the payer in ISO 3166-1 Alpha-2 country code format.

You need to use the same country you used when you where getting the offer. Otherwise you'll get an error (see Orders).

The state of the payer in the format of only the second part of the ISO 3166-2 code, for example for US-NY the value is NY.

The phone number of the payer (including the country code).

Use 00 in front of the country code, for example, "0044123456" for country code 44.

The payer's email address.

recipient object

The recipient ID (also called portal code).

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.

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.

If the recipient has multiple items defined, you must include all items in the order. See Items of a recipient. If the recipient has no items defined, you must include the default item in the order.

The Flywire API expects every recipient to have at least one item. If no item(s) were specified when the recipient was set up, the Flywire API interprets that as one item which has the id "default".

Identifier of the item.

If the recipient has multiple items defined, you must include all items in the order. See Items of a recipient. If the recipient has no items defined, you must include the default item in the order.

The Flywire API expects every recipient to have at least one item. If no item(s) were specified when the recipient was set up, the Flywire API interprets that as one item which has the id "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.

offer object

An offer is the price for an available payment method (credit card, bank transfer, etc.) for a payment.

Example: The payer needs to pay 5,000 USD for tuition, one of the offers is "Pay 4,300 CNY via Bank Transfer". The offer tells the payer what they have to pay, including FX rates and fees if those apply.

The amount to pay (price) in offers can change due to FX rates. The final amount is only "locked in" when you create a payment from the order.

If a payment is done in two different currencies, the amount your payer pays depends on the current FX rate. Since FX rates frequently change, the amount to pay can change too.

The amount to pay for an offer (given in the price parameter) is the amount at the time you requested the offer. It can change at any moment, even if the offer is used for an order.

The offers that are available for a payment depends on a combination of the following factors:

  • The chosen recipient.

  • The country or countries involved in the payment (for example, paying from China to the US).

  • The amount of money being paid.

An offer can also contain additional information needed from the payer to process the payment.

See Offers for details about the offer object.

ID of the offer that you want to use for this order.

You can find the offer ID in the response after getting the list of offers.

The offer ID is a string of characters that uniquely identifies a specific offer.

Example format: MTAxMSEgcHXfY8Fua499cmFuc2Zlcl9l7XigRWM

fields array

Some countries' regulations require extra fields in order to process a payment depending on the selected offer. If an offer contains any extra fields, they are required fields.

  • Paying in China with certain methods requires the payer to provide their Chinese identification number and exact name that appears on the ID.

  • Paying in India with certain methods requires the payer to provide their PAN number and source of funds.

  • Paying in Brazil with certain methods requires the payer to provide their CPF number (Cadastro de Pessoas Físicas or Natural Persons Register).

Identifier of the field.

The value for this field.

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.

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

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.

POST/orders 

curl https://base-url-placeholder/orders
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
 	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    }, 
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
	"items": [
		{
			"amount": 80000,
			"id": "tuition"
		},
		{
			"amount": 40000,
			"id": "housing"
		}
	],
	"offer": {
		"id": "MTAwMDAgcHRfYmFua190cmFuc2Zlcl9jYWQgRVM=",
		"fields": [
			{
				"id": "pan_number",
				"value": "12345678"
			}
		]
	},
	"notifications_url": "http://consumer-url.com/notifications",
	"external_reference": "xyz123456",
	"metadata": {
		"external_payment_id": "PAYd910447bbf9fed52e3131e"
		}
}'

Response

  • Order creation success
  • 422 Error - offer ID invalid
  • 422 Error - item amount invalid

The order ID.

The order ID is a string of characters that uniquely identifies a specific order. The order ID gets automatically assigned to an order when a new order is created. Example order ID: 52c6a5df-b6c6-40bc-a71a-fefb82ad96b3

The time and date the order was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

payer object

The payer information is not automatically included. Returning payer information is disabled by default and needs to be enabled by Flywire.

Please contact the Solutions team if you require payer information to be returned.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

The ISO2 code of the payer country (the country the money was sent from).

The payer's state.

The payer's phone number.

The payer's email address.

recipient object

The recipient ID (also called portal code).

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.

fields array

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

Identifier of the item.

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.

offer object

An offer is the price for an available payment method (credit card, bank transfer, etc.) for a payment.

Example: The payer needs to pay 5,000 USD for tuition, one of the offers is "Pay 4,300 CNY via Bank Transfer". The offer tells the payer what they have to pay, including FX rates and fees if those apply.

The amount to pay (price) in offers can change due to FX rates. The final amount is only "locked in" when you create a payment from the order.

If a payment is done in two different currencies, the amount your payer pays depends on the current FX rate. Since FX rates frequently change, the amount to pay can change too.

The amount to pay for an offer (given in the price parameter) is the amount at the time you requested the offer. It can change at any moment, even if the offer is used for an order.

The offers that are available for a payment depends on a combination of the following factors:

  • The chosen recipient.

  • The country or countries involved in the payment (for example, paying from China to the US).

  • The amount of money being paid.

An offer can also contain additional information needed from the payer to process the payment.

See Offers for details about the offer object.

ID of the offer that is used for this order.

The offer ID is a string of characters that uniquely identifies a specific offer.

Example format: MTAxMSEgcHXfY8Fua499cmFuc2Zlcl9l7XigRWM

fields array

Some countries' regulations require extra fields in order to process a payment depending on the selected offer. If an offer contains any extra fields, they are required fields.

  • Paying in China with certain methods requires the payer to provide their Chinese identification number and exact name that appears on the ID.

  • Paying in India with certain methods requires the payer to provide their PAN number and source of funds.

  • Paying in Brazil with certain methods requires the payer to provide their CPF number (Cadastro de Pessoas Físicas or Natural Persons Register).

Identifier of the field.

The value for this field.

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 unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

metadata object

There are different kinds of metadata for a payment:

Metadata added by Flywire

Not present for 529 Payments.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

Only for One Off Payments with payment method bank transfer.

The tracking URL leads your payer to the Flywire Payment Experience where they can track their payment.

As long as a payment is still in progress, payers can download the payment instructions for bank transfer payments there, including an authorization letter in case they need it.

Some international payments require an Authorization letter.

It explains the partnership between you and Flywire, and contractually authorizes Flywire to collect payments on your behalf.

The authorization letter always comes together with the payment instructions for the bank transfer.

There are two ways to give your payer the payment instructions for bank transfers:

  1. You can use the instructions parameters and display them in your UI or an email.

  2. You can display the tracking_url in your UI or an email. If your payer needs an authorization letter, they need to use the tracking URL and download the payment instructions from there, since the PDF download contains the authorization letter.

Metadata added by you

Only for 520 Payments and self-managed recurring payments. Not present for One Off Payments and Flywire-managed recurring payments.

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.

{
	"id": "52c6a5df-b6c6-40bc-a71a-fefb82ad96b3",
	"created_at": "2020-10-20 17:41:27 UTC",
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    }, 
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
	"items": [
		{
			"amount": 80000,
			"id": "tuition"
		},
		{
			"amount": 40000,
			"id": "housing"
		}
	],
	"offer": {
		"id": "MTAwMDAgcHRfYmFua190cmFuc2Zlcl9jYWQgRVM=",
		"fields": [
			{
				"id": "pan_number",
				"value": "12345678"
			}
		]
	},
	"notifications_url": "http://consumer-url.com/notifications",
	"external_reference": "xyz123456",
	"metadata": {
		"external_payment_id": "PAYd910447bbf9fed52e3131e"
		}
}

Creating the order failed - invalid offer ID or invalid country

422 Error

When does this happen?

This error can have two different causes:

  1. The offer ID you used for creating the order is invalid. Ensure that the offer ID you are using is correct.

  2. You tried to create an order with a payer country that is different from the country you used when you were getting the offer for this order. You need to use the same country in both requests.

{
  "type": "https://developers.flywire.com",
  "status": 422,
  "title": "Bad Request",
  "detail":"Invalid parameters",
  "errors": [
    {
      "source": "/offer/id",
      "param": "id",
      "type": "invalid_param",
      "message": "is invalid"
    }

Creating the order failed - parameter item with invalid amount

422 Error

When does this happen?

You'll get this error when you try to create an order with a payment amount that is below or above the limits set in the settings object of a recipient (see Recipients - Settings ).

The settings of a recipient define the minimum and maximum amount for a payment. These limits are defined when you set up the recipient with Flywire.

If you didn't customize the settings, the default limits are:

  • Minimum: 5000 = 50.00 USD

  • Maximum: 15000000 = 150000.00 USD

When payments to your recipient contain multiple items, the limits apply to the sum of the amounts of all items.

When you try to create a payment with an amount that is below or above the set limits, you will not be able to create the payment and an error response will be returned. 

{
"type": "https://developers.flywire.com",
"title": "Bad Request",
"status": 422,
"detail": "Invalid parameters",
"errors": [
	{
	"source": "/recipient/items",
	"param": "items",
	"type": "invalid_param",
	"message": "Amount must be greater than $50.00"
	}
		]
}

Editing an Order

Request

This endpoint allows you to edit an order.

How to Resolve the Path Placeholders of the Endpoint

Exchange {orderId} in the endpoint with the order ID.

The order ID is a string of characters that uniquely identifies a specific order. The order ID gets automatically assigned to an order when a new order is created. Example order ID: 52c6a5df-b6c6-40bc-a71a-fefb82ad96b3

You get the order ID in the response after you created an order.

Parameters for the Request Body

You can edit all parameters of an existing order except the recipient ID.

Parameters you can edit:

payer object

The payer information is not automatically included. Returning payer information is disabled by default and needs to be enabled by Flywire.

Please contact the Solutions team if you require payer information to be returned.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

The ISO2 code of the payer country (the country the money was sent from).

The payer's state.

The payer's phone number.

The payer's email address.

recipient object

Contains the fields of the recipient.

Do not include the recipient ID in the recipient object.

When creating an order, the recipient is defined by the recipient ID, which can't be changed later. Including the recipient ID in the request body for editing will result in an error, even if it matches the original ID.

fields array

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

If the recipient has multiple items defined, you must include all items in the order. See Items of a recipient. If the recipient has no items defined, you must include the default item in the order.

The Flywire API expects every recipient to have at least one item. If no item(s) were specified when the recipient was set up, the Flywire API interprets that as one item which has the id "default".

Identifier of the item.

If the recipient has multiple items defined, you must include all items in the order. See Items of a recipient. If the recipient has no items defined, you must include the default item in the order.

The Flywire API expects every recipient to have at least one item. If no item(s) were specified when the recipient was set up, the Flywire API interprets that as one item which has the id "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.

offer object

An offer is the price for an available payment method (credit card, bank transfer, etc.) for a payment.

Example: The payer needs to pay 5,000 USD for tuition, one of the offers is "Pay 4,300 CNY via Bank Transfer". The offer tells the payer what they have to pay, including FX rates and fees if those apply.

The amount to pay (price) in offers can change due to FX rates. The final amount is only "locked in" when you create a payment from the order.

If a payment is done in two different currencies, the amount your payer pays depends on the current FX rate. Since FX rates frequently change, the amount to pay can change too.

The amount to pay for an offer (given in the price parameter) is the amount at the time you requested the offer. It can change at any moment, even if the offer is used for an order.

The offers that are available for a payment depends on a combination of the following factors:

  • The chosen recipient.

  • The country or countries involved in the payment (for example, paying from China to the US).

  • The amount of money being paid.

An offer can also contain additional information needed from the payer to process the payment.

See Offers for details about the offer object.

ID of the offer that you want to use for this order.

You can find the offer ID in the response after getting the list of offers.

The offer ID is a string of characters that uniquely identifies a specific offer.

Example format: MTAxMSEgcHXfY8Fua499cmFuc2Zlcl9l7XigRWM

fields array

Some countries' regulations require extra fields in order to process a payment depending on the selected offer. If an offer contains any extra fields, they are required fields.

  • Paying in China with certain methods requires the payer to provide their Chinese identification number and exact name that appears on the ID.

  • Paying in India with certain methods requires the payer to provide their PAN number and source of funds.

  • Paying in Brazil with certain methods requires the payer to provide their CPF number (Cadastro de Pessoas Físicas or Natural Persons Register).

Identifier of the field.

The value for this field.

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.

metadata object

You can specify up to 20 metadata pairs.

Maximum length for keys: 40 characters

Maximum length for values: 500 characters

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.

PATCH/orders/{orderId} 

curl https://base-url-placeholder/orders
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    }, 
	"recipient": {
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},         
	"items": [
		{
			"amount": 80000,
			"id": "tuition"
		},
		{
			"amount": 40000,
			"id": "housing"
		}
	],
	"offer": {
		"id": "MTAwMDAgcHRfYmFua190cmFuc2Zlcl9jYWQgRVM=",
		"fields": {
			"id": "pan_number",
			"value": "12345678"
			}
		},
	"notifications_url": "http://consumer-url.com/notifications",
	"external_reference": "xyz123456",
	"metadata": {
	"external_payment_id": "PAYd910447bbf9fed52e3131e"
	}
}

Response

  • Order editing success
  • 422 Error - recipient ID
Editing an order does not generate a new order ID - the returned order ID is the order ID of the original order you edited.

The order ID.

The order ID is a string of characters that uniquely identifies a specific order. The order ID gets automatically assigned to an order when a new order is created. Example order ID: 52c6a5df-b6c6-40bc-a71a-fefb82ad96b3

The time and date the order was created.

The date and time format is given in ISO 8601 standard. This format represents the date as "YYYY-MM-DD HH:MM:SS" followed by the time zone indicator (for example "UTC")

payer object

The payer information is not automatically included. Returning payer information is disabled by default and needs to be enabled by Flywire.

Please contact the Solutions team if you require payer information to be returned.

The payer's first name.

The payer's last name.

The payer's middle name.

The payer's first line of address.

The payer's second line of address.

The payer's city.

The payer's zip code.

The ISO2 code of the payer country (the country the money was sent from).

The payer's state.

The payer's phone number.

The payer's email address.

recipient object

The recipient ID (also called portal code).

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.

fields array

Fields of a recipient (also called a portal) are fields that are specific to that recipient. Depending on how you use Flywire, you might know them under the names dynamic fields, custom fields, or student fields.

Fields are defined when the recipient (also called portal) is set up by Flywire. They are additional fields that the payer has to fill out when they make their payment (additional to the standard payer fields that are the same for all recipients).

Typically, these are fields your own system needs to be able to process and reconcile the payment. While some fields are common across many recipients, others are unique to yours.

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.

Identifier of the item.

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.

offer object

An offer is the price for an available payment method (credit card, bank transfer, etc.) for a payment.

Example: The payer needs to pay 5,000 USD for tuition, one of the offers is "Pay 4,300 CNY via Bank Transfer". The offer tells the payer what they have to pay, including FX rates and fees if those apply.

The amount to pay (price) in offers can change due to FX rates. The final amount is only "locked in" when you create a payment from the order.

If a payment is done in two different currencies, the amount your payer pays depends on the current FX rate. Since FX rates frequently change, the amount to pay can change too.

The amount to pay for an offer (given in the price parameter) is the amount at the time you requested the offer. It can change at any moment, even if the offer is used for an order.

The offers that are available for a payment depends on a combination of the following factors:

  • The chosen recipient.

  • The country or countries involved in the payment (for example, paying from China to the US).

  • The amount of money being paid.

An offer can also contain additional information needed from the payer to process the payment.

See Offers for details about the offer object.

ID of the offer that is used for this order.

The offer ID is a string of characters that uniquely identifies a specific offer.

Example format: MTAxMSEgcHXfY8Fua499cmFuc2Zlcl9l7XigRWM

fields array

Some countries' regulations require extra fields in order to process a payment depending on the selected offer. If an offer contains any extra fields, they are required fields.

  • Paying in China with certain methods requires the payer to provide their Chinese identification number and exact name that appears on the ID.

  • Paying in India with certain methods requires the payer to provide their PAN number and source of funds.

  • Paying in Brazil with certain methods requires the payer to provide their CPF number (Cadastro de Pessoas Físicas or Natural Persons Register).

Identifier of the field.

The value for this field.

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 unique identifier you provided for the payment to help you match the callback to the payment.

For API integrations:

You provided this identifier via the external_reference parameter.

For all other integrations:

You provided this identifier via the callback_id parameter.

metadata object

There are different kinds of metadata for a payment:

Metadata added by Flywire

Not present for 529 Payments.

The payer ID (payor_id) uniquely identifies a payer. You provided the payer ID when your created the payment. Usually, you use an ID from another system, like your ERP.

Only for One Off Payments with payment method bank transfer.

The tracking URL leads your payer to the Flywire Payment Experience where they can track their payment.

As long as a payment is still in progress, payers can download the payment instructions for bank transfer payments there, including an authorization letter in case they need it.

Some international payments require an Authorization letter.

It explains the partnership between you and Flywire, and contractually authorizes Flywire to collect payments on your behalf.

The authorization letter always comes together with the payment instructions for the bank transfer.

There are two ways to give your payer the payment instructions for bank transfers:

  1. You can use the instructions parameters and display them in your UI or an email.

  2. You can display the tracking_url in your UI or an email. If your payer needs an authorization letter, they need to use the tracking URL and download the payment instructions from there, since the PDF download contains the authorization letter.

Metadata added by you

Only for 520 Payments and self-managed recurring payments. Not present for One Off Payments and Flywire-managed recurring payments.

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.

{
	"id": "52c6a5df-b6c6-40bc-a71a-fefb82ad96b3",
	"created_at": "2020-10-20 17:41:27 UTC",
	"payer": {
		"first_name": "Peter",
		"last_name": "Payer",
		"middle_name": null,		
		"address1": "789 Calle Mayor",
		"address2": null,
		"city": "Madrid",
		"country": "ES",
		"state": null,
		"zip": "28013",
		"phone": "0034912345678",
		"email": "[email protected]"
    }, 
	"recipient": {
		"id": "FWU",
   		"fields": [
            {
                "id": "custom_field_1",
                "value": "ID12345"
            },
			{
				"id": "custom_field_2",
				"value": "2020"
			}
        ]
	},
	"items": [
		{
			"amount": 80000,
			"id": "tuition"
		},
		{
			"amount": 40000,
			"id": "housing"
		}
	],
	"offer": {
		"id": "MTAwMDAgcHRfYmFua190cmFuc2Zlcl9jYWQgRVM=",
		"fields": [
			{
				"id": "pan_number",
				"value": "12345678"
			}
		]
	},
	"notifications_url": "http://consumer-url.com/notifications",
	"external_reference": "xyz123456",
	"metadata": {
		"external_payment_id": "PAYd910447bbf9fed52e3131e"
		}
}

Editing the order failed - recipient ID cannot be updated

422 Error

When does this happen?

You included the recipient ID in the request to edit the order.

Do not include the recipient ID in the recipient object.

When creating an order, the recipient is defined by the recipient ID, which can't be changed later. Including the recipient ID in the request body for editing will result in an error, even if it matches the original ID.

{
    "type": "https://developers.flywire.com",
    "title": "Unprocessable entity",
    "status": 422,
    "detail": "Invalid parameters",
    "errors": [
        {
            "source": "/recipient/id",
            "param": "id",
            "type": "invalid_param",
            "message": "cannot be updated"
        }
    ]
}

Charging an Order (Creating a Payment)

Request

When you confirm ("charge") an order, it creates a payment in Flywire. Once the order is charged successfully, Flywire will return the payment reference to you via the payment_reference parameter.

The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

With the payment reference, the payment can be tracked during its journey through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

 

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {orderId} in the endpoint with the order ID.

The order ID is a string of characters that uniquely identifies a specific order. The order ID gets automatically assigned to an order when a new order is created. Example order ID: 52c6a5df-b6c6-40bc-a71a-fefb82ad96b3

You get the order ID in the response after you created an order.

POST/orders/{orderId}/charge 

curl https://base-url-placeholder/orders/52c6a5df-b6c6-40bc-a71a-fefb82ad96b3/charge
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

Response

The payment reference.

The payment reference identifies a payment.

The format for a payment reference is:

Recipient ID followed by a string of characters, for example FWU744586810.

With the payment reference, the payment can be tracked during its journey through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

The payment amount in the payer currency.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

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 payer currency in ISO 4217 format.

The payer currency is the currency the payer pays in. If the payer currency is different from the billing currency, it will be converted to the billing currency.

The payment amount 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 billing currency in ISO 4217 format.

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.

{
	"payment_reference": "FWU425810948",
    "amount_from": 30400,
    "currency_from": "EUR",
    "amount_to": 30200,
    "currency_to": "USD"
}