Skip to main content
Version: 1.7.3

Web Messaging

TaxBandits API enables you to get notified when the recipient completes their W-9, W-8BEN, or W-8BEN-E Forms either via Webhooks or by calling the Status endpoint. These methods can be used in both RequestByEmail and RequestByUrl methods. In addition to these, our API offers a new way to get notified if you use the RequestByUrl method, which is Web Messaging!

Web messaging is typically a mechanism that enables cross-origin communication between a page and an iframe embedded in it.

How Web Messaging Works?​

If you have embedded the URL generated by TaxBandits in your application as an iframe, TaxBandits can enable communication between the child frame and parent frame using the Window.Postmessage feature of the browser. This PostMessage event is triggered instantly once the W-9/W-8 form is electronically signed and submitted.

Web messaging can be set up for a particular account only upon request, and it won't be available by default. To enable web messaging, you can send an email to developer@taxbandits.com.

Once web messaging is enabled in your account, the iFrame will send a message to the parent whenever a recipient completes Form W-9/Form W8-BEN. You can use this message to configure the UI on your site.

The post message payload will have the Payee Reference, Status, Form Type, and iat (epoch time in UTC).

Sample Message :​

{
"uid": "a465421b-c878-471a-8d0e-3b6912336b65",
"iat": "1516239022",
"Status": "Signed",
"PayeeRef": "TMG108687",
"FormType": "FORMW9"
}

Parameters:​

FieldDescription
uidUnique D included in the iFrame URL provided by TaxBandits in the RequestByUrl response.
iatIssued At Time (epoch time in UTC)
StatusStatus of the Form W-9 or Form W-8BEN
Expected Values: Signed, Cancelled
PayeeRefUnique payee identifier given in the RequestByUrl API request.
FormTypeUser signed and submitted Form type.
Expected Values: FORMW9, FORMW8BEN, FORMW8BENE

Note: You can see the PostMessage event from the browser's Developer Tools. For Chrome dev tools, the message can be accessed under the Sources Tab, and on the right of the sources, click “Global Listeners” and from there, click the “message”.

Security measures to be taken while receiving the message:​

  • Firstly, you need to verify the message's origin and ensure it is from the TaxBandits domain.
  • Match the UID (received in the payload) with the W-9/W-8BEN UID (received in the response of WHCertificate/RequestByUrl) to see whether both are the same.
  • Verify the IAT (Issued At Time) received in the payload.
note

We highly recommend following the best practices listed in the MDN documentation.

Here is a sample script that can be used at the parent frame to receive the PostMessage from the embedded TaxBandits iFrame:​


<script type='text/javascript'>
// Create IE + others compatible event handler
var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";
var eventer = window[eventMethod];
var messageEvent = eventMethod == "attachEvent" ? "onmessage" : "message";
// Listen to message from child window
eventer(messageEvent,function(e) {
alert(e.data); // show the payload in alert
console.log('Message from TaxBandits!: ',e.data); // log the payload in console
},false);
</script>