Hosting Earnings Dashboard & Paying Your Users

when you choose to host your own earnings dashboard and pay your users directly , you’ll need to implement the processes that power capturing commission data from wildfire displaying earnings to the correct user managing payout eligibility based on commission status executing user payouts through your own rewards platform this guide outlines the high level flow and links to in depth resources to help you prepare for development during the onboarding process understanding the anonymized user identifier (aui) the anonymized user identifier (aui) is the key value that links commission records from wildfire to the correct user in your system in the tracking id pass through authentication method, you simply pass a uuid as the aui this uuid is included in all commission records so you can match them to your user accounts for oauth partners , wildfire retrieves the aui from your authentication token — typically from the sub field, though this can be configured based on your token format in this case, we still recommend using a uuid for consistency and uniqueness why it matters regardless of authentication method, the aui is the critical link between the commission data wildfire sends and the earnings records you display in your own dashboard 1\ capturing commission data wildfire makes commission event data available via the commission api , which serves as the system of record your system can map individual commissions to the correct user using the aui if you register for callbacks , wildfire will send best effort notifications when a commission is imported or when its status changes these callbacks can help you update your earnings dashboard in near real time important callbacks are considered "best effort" as they are not retried if delivery fails always use the commission api as your authoritative source, scheduling regular pulls to ensure you have a complete and accurate commission history for full details on api usage, callback setup, and payload formats, see syncing commission data via api and callbacks » 2\ associating earnings with the correct user each commission record includes the aui which is reported back as trackingcode via the commission api this is how you'll map earnings to the correct user 3\ understanding commission statuses commission records go through several statuses before they are eligible for payout your earnings dashboard should display these statuses clearly to users so expectations are set appropriately list of all statuses “pending” is the default state of a new commission 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 commission should be included in the relevant payment report for full status definitions and their handling, see syncing commission data via api and callbacks » 4\ when to show earnings to users (recommendation) users want timely feedback about their earnings to provide the best experience, we recommend adding commission records to your users’ dashboards as soon as possible , displaying them in the pending state initially because merchants generally do not pay out until after return periods have elapsed, commissions often remain in the pending status for an extended time return periods typically last 30+ days, and in certain verticals like travel, payouts may only occur after the service (e g , a trip) has been completed — which can be weeks or months later it’s important for users to see their pending commissions early so they understand they have earnings in progress we also encourage our partners to clearly communicate these timing nuances in the dashboard or associated messaging being transparent about why earnings take time to confirm helps set expectations and prevents user frustration 5\ handling reversals and refunds occasionally, a commission may be reversed (e g , canceled order, return) you should account for these in earnings display – adjust totals accordingly so users see accurate available earnings payout eligibility checks – ensure reversals are subtracted from earnings before approving payouts more on reversal handling is covered in the syncing commission data via api and callbacks » guide 6\ populating your earnings dashboard with commission data ingested and mapped to users via the aui, you can surface lifetime earnings – all time totals (including pending and paid) available balance – amount eligible for payout (commissions in paid status) transaction history – individual records with merchant, date, status, and amount if you’d like to test your dashboard integration, you can use sample commission data sample commission data » 7\ executing payouts since you are paying users directly, you will determine the minimum payout threshold (if applicable) in your rewards platform run a payout job that selects users whose available balance exceeds the threshold transfer funds through your chosen payment method (e g , paypal, account deposit, gift cards) mark those transactions as “paid” in your internal system for audit purposes wildfire’s role ends at providing accurate, up to date commission data and transmitting funds to you, our partner; all funds movement to users happens within your infrastructure 8\ putting it all together the high level flow for your team user shops via your hosted shopping portal merchant reports sale to wildfire commission record created in wildfire your system ingests the commission via the api (optionally supplemented by callbacks) map to user via aui update dashboard with new earnings and status payout eligible users once commission status is paid