website logo
WildlinkWildfire-corpFeaturesNetworkCompanyPricingResourcesContact us
⌘K
Wildfire Systems Knowledgebase
Partner Admin
Commission History
Performance Summary
Desktop Solutions
Browser Extension Authentication
Implementing Wildfire Coupons into an existing Chrome Extension
How to Implement OAuth in a Chrome Extension
Direct tracking code injection to extension
Mobile Solutions
Android MCA SDK Guide
Android MCA Permission Compliance
How to implement the Mobile Safari Extension
Wildfire APIs
Country filtering and multiple applications
Public Commission Sample Data
Getting to know the Wildfire JSON Data Feeds
Creating links
Commission History
Gift Card
Merchants and Domains
Merchant Images
Tracking Code (TC) Parameter
Syncing Commission Data via API and Callbacks
Working with Wildfire Coupon Data
Getting started with the Wildfire API Postman collection
FAQ and General Resources
Jump Track
Best Practices
6 Reasons Why a User Might Not Get Credit for Earning
FTC Compliance Overview
Stand-Down Policy Compliance
Docs powered by archbee 
16min

Syncing Commission Data via API and Callbacks

Once your users start generating sales, you'll want your system to sync the associated data so that you can show these sales to your users, send push notifications, etc.  There are two ways to get this transaction data: pull them from our API or receive callbacks from our system.  In most cases, you'll want to receive callbacks to keep your system in sync as closely as possible, but you'll also want to hit the API to pull batches of transactions in case a callback wasn't successful.  At this time, we do not re-attempt failed callbacks.

Getting Commission Data via the Wildfire API

To see the API docs for how to fetch transaction data see the API reference.

Getting Commission Data via Callbacks

To set up your callback URL, in your partner admin tool, select the application you want to configure and then select the gear icon.  Here you can enter a callback URL (please ensure it's an HTTPS endpoint) and a callback key.  The callback key can be any value.  The purpose of the callback key is to ensure that the callback is valid (and that a rogue entity is not invoking your callback URL with false data).

Once you have configured your callback settings, if you have any sales data, you can select the "resend callback" icon next to the sale and it will send the callback payload to your callback URL.  You can use this feature to test that your callback settings are configured correctly.

Callback Body

The content of the body is different depending on what version of the APIs your application is configured to use.  By default, we subscribe an application when it is created to the most recent version of our APIs.  Wildfire will not auto-update your application to a new version of the APIs but you may request to have your application(s) upgraded.  Please contact your Client Success Manager to determine your application's current API version and/or to request an upgrade. 

A V3 callback request will have a body similar to this:

JSON
|
{
   "ID":"96d0a222-c84c-4b6b-8722-8fb8447f9565",
   "Type":"Commission",
   "Action":"create",
   "Payload":{
      "CommissionID":12345,
      "ApplicationID":0,
      "MerchantID":123456,
      "DeviceID":19283,
      "SaleAmount":{
         "Amount":"321",
         "Currency":"USD"
      },
      "Amount":{
         "Amount":"3.211",
         "Currency":"USD"
      },
      "Status":"PENDING",
      "TrackingCode":"012345-6780a-bcdef0-12345",
      "EventDate":"2019-09-12T01:22:33Z",
      "CreatedDate":"2019-09-13T02:22:33.987654Z",
      "ModifiedDate":"2019-09-13T02:22:33.987654Z",
      "MerchantOrderID":"397254095",
      "MerchantSKU":"465056245"
   },
   "CreatedDate":"2019-09-15T00:11:33.987654Z"
}


A V4 callback request will have a body similar to this:

JSON
|
{
  "ID": "87f0a400-c84c-4b6b-8722-8fb8447f9565",
  "Type": "Commission",
  "Action": "create",
  "Payload": {
    "CommissionID": 775109,
    "ApplicationID": 0,
    "MerchantID": 98813,
    "DeviceID": 12345,
    "SaleAmount": {
      "Amount": "384.65",
      "Currency": "USD"
    },
    "Amounts": [
      {
        "Amount": "2.88475",
        "Currency": "USD",
        "SplitPart": "APPLICATION"
      },
      {
        "Amount": "5.7695",
        "Currency": "USD",
        "SplitPart": "DEVICE"
      }
    ],
    "Status": "PAID",
    "TrackingCode": "012345-6780a-bcdef0-74932",
    "EventDate": "2022-10-27T23:08:45Z",
    "LockingDate": "2022-10-27T23:08:45Z",
    "CreatedDate": "2022-10-27T23:08:45.898588Z",
    "ModifiedDate": "2022-10-27T23:13:45.898588Z",
    "MerchantOrderID": "1234582725",
    "MerchantSKU": "sku123nd"
  }
}


Note: *Both of the above examples include whitespace/indentation for readability, but when generating the HMAC check to verify this callback came from Wildfire, the callback body must be evaluated without modification (i.e. it should contain no indentation/whitespace/formatting).

Example v3 body without whitespace:

JSON
|
{"ID":"96d0a222-c84c-4b6b-8722-8fb8447f9565","Type":"Commission","Action":"create","Payload":{"CommissionID":12345,"ApplicationID":0,"MerchantID":123456,"DeviceID":19283,"SaleAmount":{"Amount":"321","Currency":"USD"},"Amount":{"Amount":"3.211","Currency":"USD"},"Status":"PENDING","TrackingCode":"012345-6780a-bcdef0-12345","EventDate":"2019-09-12T01:22:33Z","CreatedDate":"2019-09-13T02:22:33.987654Z","ModifiedDate":"2019-09-13T02:22:33.987654Z","MerchantOrderID":"397254095","MerchantSKU":"465056245"},"CreatedDate":"2019-09-15T00:11:33.987654Z"}


Example v4 body without whitespace:

JSON
|
{"ID":"87f0a400-c84c-4b6b-8722-8fb8447f9565","Type":"Commission","Action":"create","Payload":{"CommissionID":775109,"ApplicationID":0,"MerchantID":98813,"DeviceID":12345,"SaleAmount":{"Amount":"384.65","Currency":"USD"},"Amounts":[{"Amount":"2.88475","Currency":"USD","SplitPart":"APPLICATION"},{"Amount":"5.7695","Currency":"USD","SplitPart":"DEVICE"}],"Status":"PAID","TrackingCode":"012345-6780a-bcdef0-74932","EventDate":"2022-10-27T23:08:45Z","LockingDate":"2022-10-27T23:08:45Z","CreatedDate":"2022-10-27T23:08:45.898588Z","ModifiedDate":"2022-10-27T23:13:45.898588Z","MerchantOrderID":"1234582725","MerchantSKU":"sku123nd"}


Key Values

Type: "Commission"

Action: "create", "update"

Payload Key Values

CommissionID: Unique ID for this commission, when updates are sent this ID will be the same.

ApplicationID: The ID of the application with which the purchase was made.

DeviceID: The ID for the user’s device that made the purchase.

MerchantID: The ID for a merchant. This value can be used to match to a merchant in the JSON feed.

SaleAmount 

  • Amount:  Reported sale amount from merchant. Note: Some merchants don't report sale amount, this can be 0.
  • Currency: The original currency in which the purchase was made. This value is not converted to the application default currency.

Amounts: This is an array with up to two maps with data for the user’s earnings and the application’s earnings. If you pay your end user you will only see a map for the application SplitPart. If Wildfire pays your end users you will see two maps, one containing the user’s earnings and the other containing the application’s earnings.

  • Amount: The commission amount, this can be a negative number in the case of a canceled or returned order to offset the original commission (this will have a new ID).
  • Currency: Commissions are always converted to your application's default currency (e.g. if your default currency is CAD, this value will be sent via API and callback in CAD).
  • SplitPart: A split part is the amount of money allocated to one or two entities depending on the configuration of your application(s). In instances where you pay your end users directly, you will only ever see an Application split part. If Wildfire pays your end users on your behalf, this response will include both the Application SplitPart and the Device (end user) SplitPart.  Note: SplitPart was added in v4 of commission records.
    • Application: Represents your portion of a commission.
    • Device: Represents the end user's portion of a commission. Only present in cases where Wildfire is paying your end user.
  • List of all statuses:
    • “Pending” is the default state of a new transaction that is expected to earn a commission amount (i.e. not disqualified).
    • “Confirmed” indicates that the merchant has locked the commission and has committed to making a payment for that individual earning. Though this signal indicates a commitment from the merchant, it should be viewed the same as the PENDING status from a risk perspective as no money has changed hands (i.e. the merchant has not paid the network). Note: Confirmed status was added in v4 of commission records.
    • “Ready” indicates that the merchant has paid us for the commission and the payment is just awaiting the next payment cycle (at the beginning of each month).
    • “Paid” indicates that the record has been paid to the partner (and the user, if Wildfire pays users on behalf of the partner), and the transaction should be included in the relevant payment report.
    • “Disqualified” indicates that the transaction was not eligible for earning.  Some merchants don't report these records.  Others (like Ticketmaster) report these records.  An example of a “Disqualified” sale is a pre-sale ticket. Another case where Disqualified is used is when a merchant does not pay for a commission (i.e. a merchant goes out of business). When commissions are determined to be uncollectible, the commission will be moved to a Disqualified status


TrackingCode: This is the value referred to Tracking Code (TC) Parameter

EventDate: Timestamp for when the order was placed.

CreatedDate: Timestamp for when the commission was entered into our database.

ModifiedDate: Timestamp for the last time this commission was modified in our database.

LockingDate: The period of time that the merchants give themselves to reverse or adjust a transaction.

MerchantOrderID: Order ID provided by the merchant for this transaction. Note:This value may be blank, not every merchant reports an order ID.

MerchantSKU: SKU number for item purchased. Note: This value may be blank, not every merchant reports SKU values.

Callback Headers

The headers for a callback will look like this:

JSON
|
{
  "User-Agent": "Wildlink_Callback_Bot/1.0",
  "Content-Length": "412",
  "Cache-Control": "no-cache",
  "Content-Type": "application/json",
  "X-Wf-Signature": "sha256=c8abc5baf0a109d3365f90b1f783a9f71eaecd1746fcf39b9b4b1b3417b84cca",
  "Accept-Encoding": "gzip"
}


Note the "X-WF-Signature" value is the HMAC encoded value of the POST body using a sha256 encoding type and using the Callback Key value that you set.  A PHP example for how to generate this signature (to compare it to the one in the headers to verify that the request is authentic) looks like this:

Text
|
$post_body = file_get_contents('php://input');
$signature = hash_hmac("sha256", $post_body, $callback_key);


Note: Altering the body of the callback sent by Wildfire will result in a mismatched signature.

Retry logic

At the time of the writing of this article, Wildfire does not support retrying failed callbacks.  We do intend to add this feature in the future, but in the meantime we recommend using the API calls (see get all commissions) on a regular basis (i.e. daily) to compensate for the possibility of incomplete callbacks.





Updated 16 Mar 2023
Did this page help you?
Yes
No
UP NEXT
Working with Wildfire Coupon Data
Docs powered by archbee 
TABLE OF CONTENTS
Getting Commission Data via the Wildfire API
Getting Commission Data via Callbacks
Callback Body
Key Values
Payload Key Values
Callback Headers
Retry logic