Installment Plan Status Notifications

Installment plan status notifications enable you to track the progress of a plan.

How do I get started?

• For testing notifications: See Flywire API Sandbox

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

Installment Plan Statuses

Status	Notification	Description
in_progress	in progress	The installment plan has started and is in progress. Payments will be created by Flywire according to the plan. You will receive notifications for each payment of the plan under the same notifications URL you provided for the plan, see Payment Status Notifications for details about those notifications.
finished	finished	The installment plan has been successfully completed, meaning the total amount has been paid. While you are getting this notification, your payer will get an email from Flywire informing them that the installment plan has successfully completed.
cancelled	cancelled	The installment plan has been cancelled. Cancelling an installment plan means the plan was stopped before the total amount was paid. No more payments will be created for this plan. Who can cancel an installment plan? You as a client can cancel an installment plan via Flywire Dashboard and via the API. Payers can cancel an installment plan if you give them the option in a payer wallet you created. Flywire automatically cancels an installment plan if a payment of the plan keeps failing. When charging a payment of a plan fails, Flywire will try to charge again once a day for the next 3 days after the first failure. If the charge keeps failing, the payment and the installment plan will be cancelled.

Content of Installment Plan Status Notifications

How to set up Installment Plan Status Notifications

When you are creating an installment plan (see Checkout Sessions - Flywire-Managed Recurring Payments), you'll encounter two parameters that influence the status notifications:

Parameter	Description
external_reference string	The external reference. The external reference is used to match a notification to an installment plan. All payments belonging to the plan will also use this external reference. It is included in notifications about the installment plan and all payments belonging to the plan. You can use any kind of identifier or reference from your own system that helps you identify the plan and its payments. Max size of 50 characters. The external reference is called callback_id in the installment plan notifications. For tracking installment plans via notifications see Installment Plan Status Notifications. For tracking payments via notifications see Payment Status Notifications.
notifications_url string (url)	The notifications URL to receive callbacks for the installment plan and all payments belonging to this plan. For tracking installment plans via notifications see Installment Plan Status Notifications. For tracking payments via notifications see Payment Status Notifications.

Validating Installment Plan 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.