How Does The Payroll Gateway Work?
You can always retrieve commission-related data using the OData API (programmatically - or using BI tools such as Excel, Tableau, Microsoft Power BI). This lets you retrieve transactions, rewards, users, teams, plans, calculations, etc.
However, sometimes you need a trigger indicating that rewards have been released. One way to be notified of reward release is to use Zapier, which implements a "rewards released" trigger. Zapier can then push payment data to your cloud platform.
Another option is to configure a Payroll Gateway, which will invoke a web resource controlled by you when rewards are released. We will pass detailed payment information to your web resource (typically a web page or web service). In turn, you can process received data and effect payment of commissions.
To configure a payment gateway:
- Login to your workspace
- Browse to Settings > Connections
- Add a payment gateway
- Enter your target URL
- Enter your secret
- Click on Save
The secret you supply will be used by your web resource to verify that passed-in information indeed comes from your Sales Cookie tenant (not an unauthorized third-party). Once configured, your provided secret can never be read back from the Sales Cookie Web UI. Your provided secret will only be passed when making callbacks to your web resource (using header X-Secret).
In your implementation, you should check that the secret is indeed the expected one. Processed POST-ed data, which will be the same CSV content as when you export reward details from your calculation - including headers, such as:
Plan,Calculation,Calculation Start,Calculation End,Calculation Status,Beneficiary,Beneficiary Tags,Beneficiary Enrollment,Manager Approval,Reward Type,Reward Details,Reward Value,Reward Value Currency,Beneficiary Value,Beneficiary Value Currency,Assignment %,Attainment Label,Attainment Difficulty,Attainment Value,Attainment Threshold,Attainment Metric,Attainment Measure,Attainment User,Attainment Team,Attainment %,Recoverable,Non-Deductible,Estimated,Manual,Pay Once,Edited,Created,Updated,Created By,Updated By,Release Date,Explanation
My Plan,My Calculation,2021-12-02,2021-12-02,Rewards Released,John Doe (user@example.com),,Ok,Ok,% of Revenue,100.0% of revenue (this level),6.50,USD,6.50,USD,100,L1,Easy,6.50,0,revenue,total,John Doe (user@example.com),,N/A,No,No,No,No,No,No,2021-12-02 18:30:48,2021-12-02 00:00:00,John Doe (user@example.com),John Doe (user@example.com),2021-12-02,
The following HTTP headers are passed in when calling your URL:
- X-Secret - the secret to verify
- X-RequestId - a unique request ID
- X-CalculationId - the released calculation's ID
- X-CalculationName - the released calculation's name
- X-ReleaseType - the associated release action
- Set to "Rewards" for rewards released
- Set to "Credits" for credits released
We recommend the following best practices:
- Always check that header X-Secret matches your supplied secret. Otherwise, unauthorized callers may discover your URL and POST invalid payment data to your URL.
- Do NOT issue actual payment for records whose estimated value is "Yes" or "True". Those records represent estimated commission amounts - not actual ones.
- Implement duplicate payment handling, in case your admin releases rewards multiple times for the same calculation.
- Promptly respond to HTTP requests and process received data offline. We retry up to 10 times, so your URL may be called several time (ex: you are processing the call but we received an HTTP timeout on the response).
- Consider grouping payments by beneficiary. There may be multiple entries per payee (ex: a payee received a base commission, plus an accelerated amount for the same calculation).
- Use the correct property for payments, and pay attention to currencies:
- The "Reward Value" (and associated "Reward Value Currency") is based on your workspace's default currency.
- The "Beneficiary Value" (and associated "Beneficiary Value Currency") is based on each payee's currency.
- You are responsible for making actual API calls to your payroll provider (ex: ADP). Using the payment gateway, you have an opportunity to connect to Intranet-protected resources which may be inaccessible to us.
- Do not assume a fixed number of CSV headers. A plan may be configured to include additional fields, which will appear in headers and provided data.
- Rewards are released on a per-calculation basis, so you may need to aggregate payouts across multiple calculations.
- If commission adjustments are made after release, no post event will be issued (unless you re-release again).
Related Articles
How Can I Bulk-Export Payouts For Payroll?
You can always retrieve payout data using the OData API (programmatically - or using BI tools such as Excel, Tableau, Microsoft Power BI). This lets you retrieve payouts, payees, plans, calculations, etc. Here are the steps to multi-select export ...How Does Plan Version Tracking Work?
Plan Snapshot When you run a calculation, we take a full snapshot of your plan. This means you can always go back to any calculation and review how the plan was setup at the time your calculation ran. To view a calculation's plan snapshot: Edit your ...How Do Advanced SQL Statements Work?
What Are Advanced SQL Statements? Our technical team may configure advanced SQL statements which operate directly against the database. This is done a/ for performance reasons, b/ to perform complex queries spanning multiple entities, or c/ to ...How Do Email Notifications Work When Releasing Credits / Rewards?
When you release credits or rewards, you have the option to notify payees via email. Only payees with a non-zero estimated OR actual calculated reward (for the released calculation) will receive an email. Payees which have no payouts will not be ...How Can I Change My Account's Email Address?
We do not support email addresses changes via self-service for the following reasons: To prevent possible abuse related to changing one's email address To prevent employees leaving their organization from taking confidential data with them To work ...