Testing Payment Flows

To ensure your system handles callbacks reliably, Flywire recommends testing specific payment flow scenarios. This page guides you through testing payment flows, which means moving a payment into different statuses and receiving the callbacks for each status.

Test Scenarios and their Magic Values

Below you can find all Flywire-recommended test scenarios. Depending on your system, some of the edge cases might not apply to you.

Magic Value (as payer's first name)	Payment flow
SANDBOX_TO_GUARANTEED_STATUS	Successful Payment - realistic disbursement Initiated → Processed → Guaranteed → moved daily at 4:00 PM UTC (Monday through Friday) Delivered This scenario simulates a realistic disbursement. Instead of advancing immediately, payments created with this magic value are held in Guaranteed until they get "disbursed" - which means they move to Delivered daily at 4:00 PM UTC (Monday through Friday). If you create multiple test payments with this value, you create a realistic disbursement file that contains multiple payments. This magic value can be used for all payment methods.
SANDBOX_TO_DELIVERED_STATUS	Successful Payment - disbursed immediately Initiated → Processed → Guaranteed → Delivered This magic value moves a payment into delivered immediately. This magic value can be used for all payment methods. Be aware that this is not a realistic payment behavior and creates disbursement files that contain only one payment, since every time a payment is moved to Delivered a new disbursement file is generated. Usually, all payments for the day get bundles into one disbursement file.
SANDBOX_TO_CANCEL_STATUS	Unsuccessful Payment - cancelled payment Initiated → Cancelled This scenario simulates a cancelled payment. This magic value can be used for all payment methods.
SANDBOX_TO_VERIFICATION	Successful Payment - with simulated successful verification Initiated → Processed → after 2 hours Guaranteed → moved daily at 4:00 PM UTC (Monday through Friday)Delivered This magic value simulates a payment that fails automated checks and gets routed to manual review which ends up being successful. This can happen for any payment method if a manual review (for example document collection or quality checks) is necessary. The manual compliance review time is simulated as 2 hours, but note that the actual duration on a real compliance review differs depending on the necessary reviews.
SANDBOX_TO_VERIFICATION_FAILED	Unsuccessful Payment - with simulated failed verification Initiated → Processed → after 2 hours Cancelled The magic value simulates a payment that fails automated checks and gets routed to manual review and fails the check. This can happen for any payment method if document collection or quality checks fail and cannot be manually corrected by contacting the payer. The manual compliance review time is simulated as 2 hours, but note that the actual duration on a real compliance review differs depending on the necessary reviews.
SANDBOX_CANCELLED_BACK_TO_PROCESS_STATUS	Re-initiated Cancelled Payment Initiated → Cancelled → Initiated → Processed → Guaranteed → Delivered This can happen for payments made via bank transfer, card, or alternative payment methods. In some edge cases, the Cancelled status isn't final. It is important to ensure that your platform can handle callbacks that occur after cancelled. When can this happen? For bank transfer: A bank transfer is automatically cancelled if Flywire doesn't receive the funds in time. However, if the payer sent funds but they did not arrive before the cancellation or there was a bank delay, Flywire will re-initiate and process the payment if the FX rate is similar. This moves a payment from cancelled back through the standard flow. For payment via card and alternative payment methods: If the third-party caused the payment to go into cancelled even though the transaction was successful, Flywire is able to re-initate the payment.
SANDBOX_TO_REVERSED_STATUS	Reversed Direct Debit Payment Initiated → Processed → Guaranteed → Delivered → Reversed This scenario is only for direct debit payments. This payment flow can happen when a direct debit payment remains unpaid: The direct debit payment went into the delivered status (which means you received the funds from Flywire). Then the direct debit payment fails and remains unpaid (which means Flywire did not receive the funds). What does it mean when a direct debit payment is unpaid? A direct debit payment can fail when it was initiated but the Flywire partner (for example, the bank) could not retrieve the funds from the payer's bank account, which means the payment remains unpaid and Flywire doesn't receive the funds. There can be different reasons for this, for example due to insufficient funds, payment was cancelled by the bank, account is closed, wrong account number, payer cancelled the payment, etc. Then Flywire will start a recovery process and the payment status will change from delivered to reversed.
SANDBOX_TO_REVERSED_REFUND	Refund for a Payment Initiated → Processed → Guaranteed → Delivered This scenario simulates a payment with a refund. The magic value triggers the following flow: Payment gets created and delivered. Then a refund is created, pushed to the finished status, and the bundle is automatically generated. (You won't receive any callbacks for those refunds and bundles). The reversed callback is sent with information about the refund. While the payment status remains delivered, you will receive a callback that the payment has been reversed due to a refund. This magic value can be used for all payment methods.
SANDBOX_SMALL_UNDERPAYMENT_STATUS SANDBOX_SMALL_OVERPAYMENT_STATUS	Underpayment Initiated ($1000) → Processed ($1000) → Guaranteed ($950) → Delivered ($950) Overpayment Initiated ($1000) → Processed ($1000) → Guaranteed ($1050) → Delivered ($1050) This can only happen for bank transfer as the payment method (because the payment is completed manually outside of the Flywire platform). If the payer transfers a slightly wrong amount, the payment amount that is Guaranteed (and will be Delivered ) can be different from the Initiated amount. The guaranteed amount will always be the same as the delivered amount. Example A payer books an exchange rate with Flywire to send $2000 via bank transfer. An initiated status and value of $2000 is sent to you via the callback notification. When the payer sends funds via online banking or at their physical bank, they send above or below the quoted amount of $2000. Flywire will accept this amount if it is within a specific threshold. Flywire amount change tolerances are: 200.00 USD or equivalent under the booked exchange amount 1000.00 USD or equivalent over the booked exchange amount If the payment is within these tolerances: A guaranteed status with an updated value in the amount parameter is sent to you via the callback notification. If the payment is outside of these tolerances (excessively under or over the initiated value): Flywire will contact you to ask if you would like to accept the payment or return it back to the payer. If this happens, the payment will be placed on hold and follow the payments on hold flow.

Testing Payment Flows Guide

The quickest, easiest way to create a payment and move it to different statuses is via the Pay-By-Link integration, which is why this guide uses this option. There are other guides for helping you test payments with specific integrations.

1. Fill out the form to open your demo portal.

Enter the recipient ID of your portal.

What is the recipient ID (also called portal code)?

The recipient ID identifies the recipient (also called portal). The recipient ID has been assigned by Flywire when the recipient has been set up.

Format:

Either: 3 letters (ABC)

Or: 5 alphanumeric characters, always starting with a letter (ABC1D)

You must use a portal that exists in the demo environment.
Choose your test scenario and use the magic value for it.

For the callback URL, you have the following options:

a) Use your own static or dynamic callback URL. If your portal has a static URL that you want to use for this test, leave the field empty. If your portal has a static URL but you want to use a different one for this test, you can overwrite it with a dynamic url here.

Dynamic vs. static URL

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

b) Use a temporary URL from webhook.site, paste it into to the field, and receive the callbacks live on this page.

Enter an external reference to make it easier to identify your test payment (optional). The reference will be returned in the callbacks.

Recipient (Portal Code)

Magic Value

Callback URL

⚪ Want to receive callbacks here? Use a webhook.site URL

External Reference

2. In your portal: Complete all steps until you are on the payment tracking page.

Choose a country.
Choose a payment method.

The best payment method for testing purposes is bank transfer, since most payment flows can be simulated with this payment method. You can choose other payment methods too, but you need to ensure that the scenario you are testing is possible for the payment method.

For SANDBOX_TO_REVERSED_STATUS you need to chose a direct debit payment.
You can leave the payer information as it is, or enter different demo data. This data does not affect the scenario.

The payer's first name can't be changed because it contains the magic value you chose.
Depending on your portal settings, you might have to complete more steps before you reach the payment tracking page.
Stop once you reach the payment tracking page. The callbacks for your chosen scenario will trigger now.

Important: If you chose credit card or direct debit, it is not necessary to provide any data. Do not enter any card or direct debit details, and do not click any buttons in the credit card payment simulator.

There are separate testing scenarios for testing credit card behavior, and at this point, you only want to test the payment flow. Entering additional data may break the payment flow test.

3. Wait for the callbacks to be returned.

Depending on your scenario, this might take a few minutes.

If you used the generated URL, you will now receive the callbacks according to your scenario on this page.

Magic value used	Callbacks you will receive
SANDBOX_TO_GUARANTEED_STATUS	Successful Payment - realistic disbursement Initiated Processed Guaranteed After moving to delivered - happens daily at 4:00 PM UTC (Monday through Friday): Delivered
SANDBOX_TO_DELIVERED_STATUS	Successful Payment - disbursed immediately Initiated Processed Guaranteed Delivered
SANDBOX_TO_CANCEL_STATUS	Unsuccessful Payment - cancelled payment Initiated Cancelled
SANDBOX_TO_VERIFICATION	Successful Payment - with simulated successful verification Initiated Processed After 2 hours: Guaranteed After moving to delivered - happens daily at 4:00 PM UTC (Monday through Friday): Delivered
SANDBOX_TO_VERIFICATION_FAILED	Unsuccessful Payment - with simulated failed verification Initiated Processed After 2 hours: Cancelled
SANDBOX_CANCELLED_BACK_TO_PROCESS_STATUS	Re-initiated Cancelled Payment Initiated Cancelled Initiated Processed Guaranteed Delivered
SANDBOX_TO_REVERSED_STATUS	Reversed Payment (only for direct debit) Initiated Processed Guaranteed Delivered Reversed
SANDBOX_TO_REVERSED_REFUND	Payment with a refund Initiated Processed Guaranteed Delivered Reversed
SANDBOX_SMALL_UNDERPAYMENT_STATUS	Underpayment Initiated (with original amount) Processed (with original amount) Guaranteed (with amount minus 50) Delivered (with amount minus 50)
SANDBOX_SMALL_OVERPAYMENT_STATUS	Overpayment Initiated (with original amount) Processed (with original amount) Guaranteed (with amount plus 50) Delivered (with amount plus 50)

Complete all steps to receive callbacks here.