Testing Refunds

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/

1. Prepare your test.

To test refunds, you have to create one refund bundle with two refunds:

The first refund contains a magic value to move the refund to a specific status.
The second refund contains a magic value to make the bundle reach the cut-off time (simply to speed up the test).

Note that a refund can only use one magic value, which is why you have to create two refunds.

Since a refund requires a payment and every payment can only have one active refund, you also have to create two payments:

Both payments must be for the same recipient (this ensures that both refunds will be in the same bundle).
Both payments must be in status Delivered (this ensures a refund can be created for the payment).

How to create test payments for refunds

If you already have suitable test payments, use Getting a List of all Payments and filter it to one recipient and delivered payments.

For all integrations: You can use Testing Payment Flows to quickly create two payments that move into delivered with the magic value SANDBOX_TO_DELIVERED_STATUS.

For Elements: Alternatively, you can tokenize a card or bank account with the magic value PAYMENT DELIVERED and create two payments with the token you receive.

For 529 payments with the Flywire API: You can create two test payments with the magic value SANDBOX_TO_DELIVERED_STATUS.

2. Create a refund for the first payment.

This is the refund that will be moved to a specific status.

Use the following parameters:

amount integer

Any amount lower or exactly like the original payment amount.

external_reference string

Depends on which status you want to move the refund to:

Move Refund to Status...	external_reference
Received	#SANDBOX_TO_RECEIVED_STATUS
Finished	#SANDBOX_TO_FINISHED_STATUS

Will the magic value be visible or filtered out?

It depends on the magic value and the place where the external_reference is returned:

	external_reference returned in...
	API response returned after creating the refund	Callback notification	API response returned for getting details about the refund
#SANDBOX_TO_RECEIVED_STATUS	visible My test refund #SANDBOX_TO_RECEIVED_STATUS	filtered out My test refund	filtered out My test refund
#SANDBOX_TO_FINISHED_STATUS	visible My test refund #SANDBOX_TO_FINISHED_STATUS	filtered out My test refund	filtered out My test refund
#SANDBOX_CUT_OFF_REACHED	visible My test refund #SANDBOX_CUT_OFF_REACHED	visible My test refund #SANDBOX_CUT_OFF_REACHED	visible My test refund #SANDBOX_CUT_OFF_REACHED

notifications_url string (url)

A URL where you can receive callbacks to test the notifications.

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

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/

POST/payments/v1/payments/{paymentID}/refunds

https://api-platform-sandbox.flywire.com/payments/v1/payments/FWU125675432/refunds
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"
  -d '{
		“amount”: 10000,
		“external_reference”: “My test refund#SANDBOX_TO_RECEIVED_STATUS”,
		“notifications_url”: “https://webhooks/notifications/refunds”
}

3. Check the notifications.

You created a refund which automatically also created a refund bundle. You'll receive the following notifications:

Refund initiated

Refund bundle pending

5. Create a refund for the second payment.

This is the refund that makes the bundle reach the cut-off time.

The refunds won't move forward in the process yet, since the refund bundle must reach its cut-off time first. You could just wait until the cut-off time is reached, but you probably want to use a magic value to fast forward time and make the bundle reach the cut-off time immediately.

Use the following parameters:

amount integer

Any amount lower or exactly like the original payment amount.

external_reference string

Must be #SANDBOX_CUT_OFF_REACHED

Will the magic value be visible or filtered out?

It depends on the magic value and the place where the external_reference is returned:

	external_reference returned in...
	API response returned after creating the refund	Callback notification	API response returned for getting details about the refund
#SANDBOX_TO_RECEIVED_STATUS	visible My test refund #SANDBOX_TO_RECEIVED_STATUS	filtered out My test refund	filtered out My test refund
#SANDBOX_TO_FINISHED_STATUS	visible My test refund #SANDBOX_TO_FINISHED_STATUS	filtered out My test refund	filtered out My test refund
#SANDBOX_CUT_OFF_REACHED	visible My test refund #SANDBOX_CUT_OFF_REACHED	visible My test refund #SANDBOX_CUT_OFF_REACHED	visible My test refund #SANDBOX_CUT_OFF_REACHED

notifications_url string (url)

A URL where you can receive callbacks to test the notifications.

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

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/

POST/payments/v1/payments/{paymentID}/refunds

https://api-platform-sandbox.flywire.com/payments/v1/payments/FWU125675444/refunds
	-X POST
	-H "Content-Type: application/json"
	-H "X-Authentication-Key: {api_key}"
	-d '{
		“amount”: 10000,
		“external_reference”: “My test refund to reach the cut-off time#SANDBOX_CUT_OFF_REACHED”,
		“notifications_url”: “https://webhooks/notifications/refunds”
		}

5. Check the notifications.

Now that the bundle has reached the cut-off time you'll receive the following notifications:

Refund bundle pending - marked for approval (Only for manual approvals. For automatic approvals, no notification is sent.)

6. Approve the bundle if needed.

Depending on the settings for the recipient of the refund, the approval either happens automatically or you have to manually approve it.

If you are not sure if you need to approve the bundle manually, check the approval settings for the recipient, see Recipients - Refunds: Cut-off time and Approval.

Details about manual and automatic approvals

All refund bundles must be approved before processing, but there is a difference between how they get approved. It depends on the settings for the recipient of the original payment which type of approval is needed:

Type of approval	approval_type (setting for the recipient)
Manual approval Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).	manual
Automatic approval Flywire processes refund bundles automatically after the cut-off time.	automatic

Type of approval

approval_type (setting for the recipient)

Manual approval

Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).

manual

Automatic approval

Flywire processes refund bundles automatically after the cut-off time.

automatic

To add or change the settings for refund approvals of a recipient please contact the Solutions team.

Help for approving refund bundles

Parameters for the Request Body

No request body needed.

How to Resolve the Path Placeholders of the Endpoint

Exchange {bundleID} in the endpoint with the actual refund bundle ID.

What is the refund bundle ID?

The refund bundle ID is a unique reference generated by Flywire to identify a refund bundle.

Format:

BUDR1AB23CD4

BUDR8 hexadecimal

What is a refund bundle?

Flywire processes refunds collectively in refund bundles to streamline the reconciliation process. Bundling refunds means Flywire only needs to collect money from the original payment recipient once, reducing the number of transactions needed for refunds.

The refund bundle cycle

Creating a refund for recipient A automatically generates a refund bundle for recipient A.
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.

More details about the cut-off time

The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.

The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.

You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.

When the cut-off time for recipient A is reached, Flywire either processes the bundle or requires your approval first, based on the recipient's settings.

More details about approvals

Type of approval	approval_type (setting for the recipient)
Manual approval Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).	manual
Automatic approval Flywire processes refund bundles automatically after the cut-off time.	automatic

Type of approval

approval_type (setting for the recipient)

Manual approval

Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).

manual

Automatic approval

Flywire processes refund bundles automatically after the cut-off time.

automatic

To add or change the settings for refund approvals of a recipient please contact the Solutions team.

For details about how to approve a refund bundle see see Approving a refund bundle.

Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.

Refund Bundle Essentials: What You Should Know

A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.

Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

What is the difference between a refund and a refund bundle?

Refunds

A refund is a way to return funds back to your payer via Flywire. You can define if you want to return the full amount (full refund) or just part of the amount (partial refund) of the original payment.

Refund Essentials: What You Should Know

A payment needs to be in status Delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).
Each refund is connected to one payment, it is not possible to create one "shared" refund for multiple payments.
A payment can only have one active refund at a time. When the refund is done (in status finished) you can create a new refund for the payment.
The refunded amount, whether it's one full refund or several partial refunds added together, can't be more than the initial payment amount.

Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

Refund bundles

The refund bundle cycle

Creating a refund for recipient A automatically generates a refund bundle for recipient A.
Each recipient has a set cut-off time for their refund bundles. All refunds created for the recipient will be added to the bundle until the cut-off time is reached.

More details about the cut-off time

The cut-off time controls when Flywire starts to process pending refunds. Since Flywire processes refunds in bundles and not as single refunds, there is a time span where you can add more refunds to a bundle before it gets processed. For example, if the cut-off time is 1 day, you can add more refunds to the refund bundle for 1 day until Flywire starts processing it or - if your refund bundles need approval - until the bundle can be approved and then processed.

The cut-off time is set individually for each recipient. Please contact the Solutions team if you want to set or change the cut-off time for a recipient.

You can also specify a timezone when setting up the cut-off time for a recipient with Flywire.

When the cut-off time for recipient A is reached, Flywire either processes the bundle or requires your approval first, based on the recipient's settings.

More details about approvals

Type of approval	approval_type (setting for the recipient)
Manual approval Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).	manual
Automatic approval Flywire processes refund bundles automatically after the cut-off time.	automatic

Type of approval

approval_type (setting for the recipient)

Manual approval

Manual approvals create an extra step in processing refunds. Flywire waits for your approval before processing a refund bundle (see Approving a refund bundle).

manual

Automatic approval

Flywire processes refund bundles automatically after the cut-off time.

automatic

To add or change the settings for refund approvals of a recipient please contact the Solutions team.

For details about how to approve a refund bundle see see Approving a refund bundle.

Creating a refund for recipient A now creates a new bundle (no matter if the previous bundle is being processed or waiting for approval) and the cycle starts again.

Refund Bundle Essentials: What You Should Know

A refund bundle has a bundle ID that enables you to identify it and retrieve all refunds in this bundle.

Refunds and bundles are recipient-specific. The settings for refunds (how the money will be collected, the cut-off time for refund bundles, and if approvals are needed for a bundle) depend on the recipient of the original payment.
A refund is always part of a refund bundle, even if the bundle only contains one refund. This means even if you only create one single refund, there will automatically be a refund bundle created for it.

POST/payments/v1/refund_bundles/{bundleID}/approve

curl https://base-url-placeholder/refund_bundles/BUDRW12345678/approve
  -X POST
  -H "Content-Type: application/json"
  -H "X-Authentication-Key: {api_key}"

7. Check the notifications.

Now that the bundle is approved you'll receive the following notifications:

Refund bundle approved

Within 5 minutes, the refund will move into the status you chose and you'll get more notifications:

"Received" Scenario
"Finished" Scenario

Refund received

Refund bundle received

This is the end of this scenario.

If there are more refunds in the bundle, all refunds in the bundle will change their status from initiated to received.

Refund received

Refund bundle received

Refund finished

Payment reversed

This is the end of this scenario.

Only the refund you created will change its status from received to finished.
If there are other refunds in the bundle, they will change their status to received.