Testing Refunds

Testing Refund Notifications

1. Choose a test payment for which you want to create a test refund.

A payment needs to be in status delivered before you can create a refund for it (see Payment Statuses for details about payment statuses).

Where do I find a test payment that is in status delivered?

  • If you already have test payments and need a list of all payments available to you, see Getting a List of all Payments.

  • If you are using self-managed recurring payments and want to create a test payment specifically for this test, you can create a card or direct debit payment and move it into delivered.

  • If you are using 529 Payments, you can also move a test payment into delivered.

2. Create a refund for the payment using magic values.

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

Yes, you can use magic values in addition to a reference. Just put it before the magic value. For example, if your reference is "My test refund" you can use "My test refund #SANDBOX_TO_RECEIVED_STATUS". You can even use hashtags (#) within your reference.

No, in the notifications, the magic value will be filtered out, meaning the My test refund #SANDBOX_TO_RECEIVED_STATUS will just be "My test refund".

Only in the API response after creating the refund, the magic value will be visible (for example "My test refund #SANDBOX_TO_RECEIVED_STATUS".

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.
https://api-platform-sandbox.flywire.com/payments/v1/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

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

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.

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. To do this, create a new refund with the cut-off time magic value for the same recipient of the first refund. This ensures that the new refund will be added to the bundle that contains the first refund.

You can find out who the recipient of the first refund is by checking the payment details of the payment you created the refund for, see Getting Details about a Payment.

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

Yes, you can use magic values in addition to a reference. Just put it before the magic value. For example, if your reference is "My test refund" you can use "My test refund #SANDBOX_TO_RECEIVED_STATUS". You can even use hashtags (#) within your reference.

No, in the notifications, the magic value will be filtered out, meaning the My test refund #SANDBOX_TO_RECEIVED_STATUS will just be "My test refund".

Only in the API response after creating the refund, the magic value will be visible (for example "My test refund #SANDBOX_TO_RECEIVED_STATUS".

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.
https://api-platform-sandbox.flywire.com/payments/v1/FWU125675432/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.

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

 

 

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

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.

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

Format: BUDR + 8 characters

Example: BUDR123456HG

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

  1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

    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.

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

    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

     

     

    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.

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

The refund bundle ID is returned to you in the response after you created a refund, see Creating a Refund for a Payment.

For existing refund bundles, you can see the refund bundle ID by getting the list of refund bundles via

GET/refund_bundles
, see Getting a list of all your refund bundles.

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

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

  1. Creating a refund for recipient A automatically generates a refund bundle for recipient A.

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

    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.

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

    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

     

     

    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.

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