Configuring the Payout Module
Payout Setting is the administrative configuration page for the Payout Module. From this page, you can enable the module, select the available payout methods, configure the Stripe and/or PayPal Connected App records, configure notification settings, and enable US Tax Tracking.
Requirements
- Administrator System Role.
- Active Payout license on the portal.
- A Stripe and/or PayPal Integration record with live API credentials.
Open the Payout Setting Page
- From the Setup home page, go to Create > Rewards.
- Click Payout Setting.
If the Payout Setting tab is not visible, the portal does not have an active Payout license. Contact Magentrix to enable the feature.
Enable the Module and Select Vendors
- Click Enable at the top of the page.
- In Select available payout methods, move Stripe, PayPal, or both from the Available column to the Selected column.
- For each selected vendor, choose the matching Connected App (an Integration record with live API credentials):
- Stripe Connected App — required if Stripe is selected.
- PayPal Connected App — required if PayPal is selected.
- Click Save.
On save, the platform performs two side effects automatically:
- Vendor webhooks are registered. Stripe gets a webhook for account.updated, payout.paid, payout.failed, payout.updated, payout.created, and customer.updated. PayPal gets a webhook for PAYMENT.PAYOUTSBATCH.DENIED and related payout batch events. The webhook URLs are {magentrixUrl}/payoutprofile/stripewebhookhandler and {magentrixUrl}/payoutprofile/paypalwebhookhandler.
- Module account fields are provisioned. If they are missing, the platform creates an AccountId lookup field on the Reward, PayoutProfile, and PayoutTransaction entities and adds the lookup to the default layout of each. This roll-up is what lets the Payout Dashboard group transactions by partner account.
If you switch to a different Connected App later (for example, rotating credentials), the platform re-registers the webhook on the new app on the next save.
Financial Policy Settings
| Setting | What It Does |
|---|
| Pass Transaction Fees to Partner | When on, the partner sees the vendor fee on each transaction and the fee is deducted from the payment amount. When off, the platform absorbs the fee. The Payout Dashboard and the partner's Reward Program page both surface the fee when this is on. |
| Enable US Tax Tracking | When on, partners are prompted for tax information during onboarding (Tax Report). Earnings accumulate against the configured year so you can produce US 1099-style reports. When off, no tax prompt is shown and tax data is not collected. |
Role Access
Admins control which partner users can see the Setup Withdrawal flow and submit payout claims.
- In the Payout Setting page, locate the Access tab and then the Role list. Each Partner Role on the portal appears with a checkbox.
- Check the Roles whose users should be allowed to set up a Payout Profile.
- Click Save.
Partners in unchecked Roles still see their Reward Program page and earned rewards but cannot configure a Payout Profile or request a withdrawal. Use this to restrict cash payouts to a subset of your partner audience (for example, only Gold-tier partners).
Notifications
The Payout Module sends notifications whenever a Payout Profile is created or changed. Configure the recipients and the template here:
- Notify partner account owners. When on, the owner of the partner's Account record is notified each time a Payout Profile changes. Useful when account managers should be aware of payment changes on their accounts.
- Internal email addresses to notify. A multi-line list of internal email addresses (one per line or comma-separated) that should receive the same notification. Useful for finance or compliance teams.
- Email template. Pick the Email Template to use. If left blank, the platform falls back to the internal template named [INTERNAL] Payout Admin Setting - Payout Profile Updated Notification To Partner Account Owners.
Saving and Re-enabling
It is possible to disable the Payout Module by clicking the Disable button.
Disabling the module hides the Payout Profile flow from partners and prevents new payout claims from being created.
The existing configuration is preserved, and re-enabling the module restores the previous settings.
If the Connected App record for a vendor is changed, the vendor webhook is re-created automatically the next time the configuration is saved.
Troubleshooting Tips
- If Save returns a vendor error, confirm the Connected App Integration record has valid live API credentials and the corresponding vendor account is in a healthy state.
- If saving succeeds but webhook events do not arrive, confirm the public Magentrix URL is reachable and that the events listed above are enabled on the vendor side.
- If a partner reports they cannot see Setup Withdrawal, confirm their Role is in the access list, the module is enabled, and they are on a Cash Reward Program.
- For full symptom-by-symptom resolutions, see Payout Module Troubleshooting.
<< Payout Module Checklist | Payout Dashboard >>