Disbursement Status Notifications

Disbursement status notifications are callbacks that Flywire sends to notify you when a disbursement reaches a specific status. Currently, Flywire sends a notifications when a disbursement reaches the delivered status, indicating that Flywire has sent a bulk disbursement of funds to your institution's bank account.

Why should I use callbacks?

Using callbacks has several benefits:

• You can use callbacks to trigger the reconciliation of Flywire disbursements within your accounting systems, ERP, etc.

• You instantly receive aggregate data for the deposit, including total net amount, currency, and itemized counts for payments, refunds, and adjustments.

• You can pair the callback for the bulk disbursement deposit (the disbursement delivered callback) with individual payment callbacks (the payment delivered callback) using their shared disbursement_id.

• You can remove the need to manually monitor bank statements or log into the Flywire Dashboard to verify when your funds arrive.

When should I use callbacks?

If you have access to the Flywire Dashboard, callbacks are optional (but recommended) as you can manually monitor status updates there. If you don't have access to the Flywire Dashboard, it is highly recommended that you use callbacks to track status updates.

If you are using the Flywire API, callbacks are essential to ensure you get reliable updates in real-time. Without callbacks, your system would have to poll the API for updates, which is resource-intensive and can lead to performance bottlenecks or rate-limiting.

How do I get started?

• For your production environment: See How to set up Disbursement Status Notifications.

• For testing notifications: See Flywire API Sandbox

Disbursement Statuses and Notifications

A disbursement can have the following statuses and notifications:

Status	Notification	Description
Delivered	delivered	Flywire has sent the disbursement to your bank account.

Content of Disbursement Status Notifications

How to set up Disbursement Status Notifications

When setting up a portal with Flywire, you have the option to define a static callback URL. Flywire sends callback notifications to this URL when a disbursement is delivered. Disbursement callbacks are sent exclusively to this portal-level URL. To receive status notifications, the portal receiving the disbursement must have a valid callback URL configured. If you need to set up a static callback URL, please contact the Solutions team.

Validating Disbursement Status Notifications

Validating notifications is optional, as it’s on your server side, but for security reasons it is recommended to validate all notifications.

How to validate a notification

To validate a notification, check its X-Flywire-Digest header. This value is generated by Flywire using your Shared Secret to encrypt the notification body. To verify the notification, generate the digest using the same method and compare it to the X-Flywire-Digest value in the header. If they match, the notification is legitimate and hasn't been tampered with.

1. Retrieve the raw HTTP body of the notification you received.

   Make sure you use the raw HTTP body of the notification. You must generate the X-Flywire-Digest value using the exact payload you received in the notification. If you change the body in any way the values won't match later.

 

2. Encrypt the received notification twice:

   1) Encrypt the raw HTTP body of the received notification with your Shared Secret using the SHA-256 algorithm.

   2) Take the result and encrypt it in Base64.

   The examples show you how to do this in different programming languages. In each example, exchange the shared_key with your Shared Secret and message_body with the raw HTTP body of the notification.

   What is my Shared Secret?

   The Shared Secret is a string of characters used for security validations.

   For API integration:

   Your Shared Secret is used to validate notifications. You receive your Shared Secret together with your API credentials via a secure email after you registered your application.

   For other integrations:

   Your Shared Secret is used to validate notifications and authenticate requests. You receive your Shared Secret from the Flywire Solutions team after your portal has been set up (please contact the Solutions team in case you don't have your Shared Secret). Note that each portal might have a different shared secret. If you have access to multiple portals, make sure you use the correct shared secret for each portal.

   • Ruby
   • .NET
   • JavaScript

   digest = OpenSSL::Digest.new('sha256')
   encrypted_payload = OpenSSL::HMAC.digest(digest, shared_secret, notification_body)
   Base64.encode64(encrypted_payload).strip
   			
   # Step 1: Define the hashing algorithm to use for the HMAC.
   # This initializes the SHA-256 hashing mechanism.
   hash_algorithm = OpenSSL::Digest.new('sha256')
   
   # Step 2: Compute the HMAC in binary format.
   # This uses the shared secret and the message body to produce the HMAC signature.
   hmac_binary = OpenSSL::HMAC.digest(hash_algorithm, shared_secret, message_body)
   
   # Step 3: Encode the HMAC in Base64 for use in the X-Flywire-Digest header.
   x_flywire_digest = Base64.encode64(hmac_binary).strip

   public static string Digest(string shared_secret, string message_body)
   {
       // Step 1: Initialize the HMACSHA256 object with the shared secret.
       // This sets up the hashing algorithm (SHA-256) and the secret key for HMAC.
       using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(shared_secret)))
       {
           // Step 2: Convert the message body into a byte array.
           // The message body is the message payload you want to hash
           var bytes = Encoding.UTF8.GetBytes(message_body);
   
           // Step 3: Compute the HMAC hash of the message body.
           // This generates the HMAC using the shared secret and the message body.
           var hashedBytes = hmacsha256.ComputeHash(bytes);
   
           // Step 4: Convert the hashed byte array into a Base64 string.
           return Convert.ToBase64String(hashedBytes);
       }
   }

   const crypto = require('crypto');
   
   function createDigest(shared_secret, message_body) {
       // Step 1: Initialize the HMAC with the SHA-256 algorithm and the shared secret.
       const hmac = crypto.createHmac('sha256', shared_secret);
       
       // Step 2: Update the HMAC with the message body.
       // The message body is the message payload you want to hash
       hmac.update(message_body);
   
       // Step 3: Get the HMAC digest and encode it in Base64.
       const digestHeader = hmac.digest('base64');
       
       return digestHeader;  // The `digestHeader` is the X-Flywire-Digest header.
   }

    

3. Compare your Base64 string to the value in the X-Flywire-Digest parameter of the notification you received.

   If the values match, the notification came from Flywire and hasn't been changed by a third party.

   If the values don't match, you shouldn't trust the notification.