Payout Module Troubleshooting

Symptom-by-symptom resolutions for the most common Payout Module issues, covering license gating, role access, vendor onboarding, webhooks, tax tracking, transaction failures, and country support. If your symptom isn't here, double-check the module is enabled, the vendor Connected App holds valid live credentials, and the partner's Role is in the access list.

The Payout Setting Page Returns Not Found

Symptom: Going to Rewards > Payout Setting returns a 404 or the menu item is missing.

Cause: The portal does not have an active Payout license. The Setting page is gated by HasLicenseForPayout; without the license the controller returns Not Found.

Resolution: Contact Magentrix to confirm the Payout license is active on your portal. Once activated, the page becomes visible and the module can be enabled.

Cannot Save Payout Setting

Symptom: Save returns an error like "Payout method must be selected" or a vendor-specific error.

Causes:

• No payout method selected. Even with all other settings, you must move at least one method (Stripe or PayPal) to the Selected column. The platform refuses to save the setting otherwise.
• Missing Connected App. If a method is selected, you must pick the matching Connected App Integration record.
• Invalid vendor credentials. If the Connected App holds credentials that the vendor rejects, webhook registration fails and the save errors out.

Resolution: Confirm at least one method is selected, the matching Connected App is attached, and the Integration record contains valid live API credentials. Test the Integration record independently if possible.

A Partner Cannot See the Setup Withdrawal Button

Symptom: A partner opens a Reward Program and does not see Setup Withdrawal.

Causes and resolutions:

1. The Reward Program is not type Cash Reward. Payout only applies to Cash Reward programs. Confirm the program type.
2. The Payout Module is disabled. Open Configuring the Payout Module and confirm the Enabled state.
3. The partner is an internal user, not a partner. Setup Withdrawal is only shown to partner users.

Transaction Stuck in "Pending Processing"

Symptom: A payout transaction never advances from created to paid or failed.

Cause: Magentrix sent the payment but the vendor webhook is not reporting back. Status transitions depend entirely on incoming webhook events.

Resolution:

1. Verify the webhook URL is reachable. The platform registers {magentrixUrl}/payoutprofile/stripewebhookhandler and {magentrixUrl}/payoutprofile/paypalwebhookhandler on save. Both must be reachable from the public internet.
2. Confirm the events are subscribed. Stripe must deliver account.updated, payout.paid, payout.failed, payout.updated, payout.created, customer.updated. PayPal must deliver PAYMENT.PAYOUTSBATCH.DENIED and related batch events.
3. Re-save the Payout Setting — this re-registers the vendor webhooks. Useful if the webhook was deleted on the vendor side or the Connected App was rotated.
4. Inspect the vendor dashboard. If Stripe or PayPal shows the payment as completed but Magentrix still says created, the issue is webhook delivery, not the payment itself.

Webhooks Stop Working After Rotating Vendor Credentials

Symptom: Vendor credentials were changed on the Connected App; new transactions stop reporting back.

Cause: The webhook on the vendor side was registered with the old credentials and is no longer valid.

Resolution:

• Check the vendor dashboard (Stripe or PayPal) to confirm whether payouts are being processed.

• If Magentrix shows no updates, rely on the platform’s reconciliation job — it will process missed or undelivered webhook events.

• Only re-save the Payout Setting if the webhook registration itself was deleted or corrupted. For simple key rotations on the same Connected App, re-saving is not required.

A Partner Cannot Complete Vendor Onboarding

Symptom: The partner clicks Setup Withdrawal, picks a vendor, and gets stuck during onboarding (Stripe Connect or PayPal authorization).

Causes and resolutions:

1. Unsupported country. Stripe Connect requires the partner's country to be supported by Stripe; PayPal Payouts has its own country list. The platform's PayoutCountry table marks which countries are supported by each vendor. If a partner is in an unsupported country, the vendor lookup will not include their country.
2. Missing bank details. Some countries require additional fields (IBAN, branch code, etc.). The platform's PayoutCountry configuration lists which fields are required. Direct partners to provide what the vendor asks for.
3. Vendor account verification. Stripe and PayPal both perform identity checks. The partner may need to complete additional verification on the vendor side before the onboarding completes.

A Payment Failed

Symptom: A transaction status is failed.

Resolution:

1. Open the transaction. The vendor's failure reason is recorded on the record (insufficient funds at platform, invalid destination, account closed, etc.).
2. Address the underlying cause:
   • Invalid destination → partner updates their Payout Profile.
   • Account closed → partner re-onboards.
   • Compliance hold → resolve with the vendor.
3. From Review Claims, re-add the affected reward(s) to a new batch and click Pay.

Partner Did Not Complete the Tax Report

Symptom: With US Tax Tracking enabled, a partner cannot be paid because the Tax Report is missing.

Cause: Tax tracking gates payments. The partner is prompted for tax information at first onboarding, and the dashboard flags partners who skipped or never completed the prompt.

Resolution: Ask the partner to open their Payout Profile and complete the Tax Report. Until the report is filed, payments to that partner are blocked. Administrators can also see flagged partners on the Payout Dashboard.

A Payout Batch Cannot Be Deleted

Symptom: Delete Payout returns an error on the Review Claims page.

Cause: Payments in flight at the vendor cannot be cancelled from Magentrix. Delete is allowed only before Pay is clicked.

Resolution: If the payment has already gone to the vendor, monitor the transaction status. If you need to recover funds, work with the vendor (Stripe or PayPal) to reverse or refund the payment, then add a corrective adjustment in your finance system.

<< Review Claims