Client-Side Notification

You can use your completion notification URL to send us a client-side notification when a customer completes your offer by embedding the URL in your offer’s confirmation page.

 

Sample Flow

  1. A customer clicks your offer in our offer wall and we generate a unique ID called a click ID (e.g., U1234). The click ID allows us to identify both the customer and your offer.
  2. We redirect the customer to your offer’s landing page and pass you the click ID through a parameter of your choice in your landing page’s URL (e.g., sid=U1234).
  3. You retrieve the click ID and store it somewhere.
  4. The customer fulfills your offer’s requirements and you…
    1. assign the click ID to your notification URL’s tp_sid parameter,
    2. sign the URL’s query string with a UNIX timestamp (UTC) and HMAC-MD5 hash and,
    3. embed the URL in your confirmation page using an iframe.
  5. The customer loads the confirmation page and the iframe hits the notification URL, passing us the click ID and hash.
  6. We validate the click ID and hash, and then deliver the customer’s product.

 

Completion Notification URL

Your account manager will supply you with your completion notification URL. It will look something like this:

https://tpc.trialpay.com/?tp_aid=3126&tp_sid=&tp_t=&tp_v1=

The URL requires the following values:

  • tp_aid — Your advertiser ID (supplied by your account manager)
  • tp_sid — The click ID (which we’ll pass to you)
  • tp_t — A UNIX timestamp (UTC) of the current time
  • tp_v1 — An HMAC-MD5 hash of the URL’s query string

 

Sending The Notification

To send us a client-side notification when a customer completes your offer:

  1. Assign the click ID we passed you to the notification URL’s tp_sid parameter.
  2. Generate a UNIX timestamp (UTC) of the current time and assign it to the notification URL’s tp_t parameter.
  3. Generate an HMAC-MD5 hash of the notification URL’s query string (the tp_aid, tp_sid, and tp_t parameters) and assign the hash to the snippet’s tp_v1 parameter (see Signing The Query String, below).
  4. Embed the notification URL in your offer’s confirmation page. Most advertisers do this with iframe, div, or img tags.

 

Signing The Query String

You must sign the completion notification URL’s query string with a UNIX timestamp and HMAC-MD5 hash. If the timestamp is more than 30 minutes old or the hash is invalid, we will reject the notification.

To sign the query string:

  1. Generate a UNIX timestamp (UTC) and assign it to the notification URL’s tp_t parameter.
  2. Generate an HMAC-MD5 hash of the URL’s query string (the tp_aid, tp_sid, and tp_t parameters) using using your scripting language’s HMAC-MD5 hashing function and your shared key (supplied by your account manager).
  3. Assign the generated hash to the URL’s tp_v1 parameter.

Example

Let’s say your shared key is f44061b0a9 and your notification URL, with the customer’s click ID in place, looks like this:

https://tpc.trialpay.com/?tp_aid=3126&tp_sid=U1234&tp_t=&tp_v1=

You generate a UNIX timestamp and assign it to the tp_t parameter:

https://tpc.trialpay.com/?tp_aid=3126&tp_sid=U1234&tp_t=1282786502&tp_v1=

Next, you generate an HMAC-MD5 hash of the query string (the part in bold below)…

https://tpc.trialpay.com/?tp_aid=3126&tp_sid=U1234&tp_t=1282786502&tp_v1=

… and assign the hash to the tp_v1 parameter:

https://tpc.trialpay.com/?tp_aid=3126&tp_sid=U1234&tp_t=1282786502&tp_v1=71bb5f5f87548e818bbc7ac6509a5674

Finally, you embed the entire completion notification URL in an iframe…

<iframe height="1" width="1" border="0" style="width: 1px; height: 1px; border: 0px solid white;" frameborder="0" scrolling="no" src="https://tpc.trialpay.com/?tp_aid=3126&tp_sid=U1234&tp_t=1282786502&tp_v1=71bb5f5f87548e818bbc7ac6509a5674"></iframe>

… and add the iframe to your offer’s confirmation page.

 

Additional Parameters

You can pass us any parameters we support — just ask your account manager to enable any parameters you’d like to include. Once enabled, add the new parameters to your completion notification URL’s query string and include them when you generate your HMAC-MD5 hash.