Testing 529 Payments

Testing Notifications for 529 Payments

Remember to use the Sandbox environment for all requests.

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. Get an offer for the test payment.

When you're getting a list of offers with, Flywire will return all the offers available for the combination of recipient, amount to pay, and country of the payer.

Do not re-use offer IDs for different payments.

You need to get an offer each time you want to create a payment. The offer ID depends on the provided amount, country and currency, so different IDs will be generated for the same payment method.

Parameters for the Request Body

No request body is needed.

Required Query Parameters

The amount to pay. It must be greater than 0.

You need to provide the amount in your 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 country code (in ISO 3166-1 alpha-2 format) of the payer's country (meaning the country the money will be sent from).

This is the country of the payer. This means that later, when you are creating the order, you need to use the same country for the country parameter of the payer 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.

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.

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

curl https://base-url-placeholder/offers?amount=12000&country=US&recipient=FWU&page=1&per_page=10
  -X GET
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

3. Create an order with magic values.

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 Testing 529 Payments).

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"
		}
}'

1. Use magic values as the payer’s first name to create a test scenario:

Scenario first_name

Guaranteed

Flywire has received the funds.

 SANDBOX_TO_GUARANTEED_STATUS

Delivered

Flywire has received the funds and processed the payment.

 

 SANDBOX_TO_DELIVERED_STATUS

Cancelled

The payment has been cancelled.

 SANDBOX_TO_CANCEL_STATUS

2. Add a notifications url.

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

curl https://api-platform-sandbox.flywire.com/payments/v1/orders
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
 	"payer": {
		"first_name": "YOUR MAGIC VALUE",
...
    }, 
..
	"notifications_url": "http://your-notifications-url.com",
}

4. Create the test payment.

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

5. Check the notifications.

  • "Guaranteed" Scenario
  • "Delivered" Scenario
  • "Cancelled" Scenario

Within the next 30 seconds:

Initiated

Processed

Guaranteed

This is the end of this scenario.

Within the next 1 minute:

Initiated

Processed

Guaranteed

Delivered

This is the end of this scenario.

Within the next 10 seconds:

Initiated

Cancelled

This is the end of this scenario.