Payout providers (PayPal Payouts)

With a payout provider connected you can pay approved payout statements directly from Billing → Payouts instead of paying outside the platform and marking them paid by hand.

What is available#

For partners paid by bank wire, Payoneer, crypto or other methods, pay outside TrackCrown and use Mark paid… with a reference, or export the mass-payment CSV for your bank or provider. See Payout statements.

Connect PayPal Payouts#

You need a PayPal business account with Payouts enabled and a REST app in the PayPal developer dashboard.

1. In PayPal's developer dashboard create (or open) a REST app and copy its Client ID and Secret — sandbox or live.

2. In TrackCrown open Billing → Providers (/app/billing/providers).

3. On the PayPal Payouts card fill in:

   Field	Notes
   Environment	Sandbox (test) or Live.
   Client id	From the PayPal app.
   Secret	Stored encrypted (AES-256-GCM); never shown again. Leave empty later to keep it.
   Webhook id	Optional; "enables automatic status updates".
   Enabled	On.

4. Click Connect (later Save).

5. Recommended: copy Webhook URL (subscribe to PAYMENT.PAYOUTS-ITEM. events)* — https://app.trackcrown.com/api/webhooks/paypal/<workspace id> — create a webhook for it in the PayPal app subscribed to the PAYMENT.PAYOUTS-ITEM.* events, then paste PayPal's Webhook id here and save.

Disconnect deletes the stored credentials; payouts already sent keep their provider status.

Pay statements with PayPal#

1. Make sure partners have PayPal as payment method with their PayPal e-mail (Profile → Payment details).
2. In Billing → Payouts, approve the statements.
3. Select the approved statements and choose Pay with PayPal → Send to PayPal.

TrackCrown sends one PayPal batch for the selection:

• Each statement is one item: the statement total rounded to cents, in the statement's currency, to the partner's PayPal e-mail; the item ID is the statement ID.
• Statements are skipped (and listed) when they are not approved ("approve it first"), were already sent and have not failed ("already sent to the provider (…)"), the partner has no PayPal e-mail, or there is nothing to pay.
• The batch ID is derived from the workspace and the selected statement IDs (and, for a statement sent again, the batch of its failed attempt). PayPal refuses a reused batch ID for 30 days, so clicking again for the same selection can never pay twice.

Status updates#

Statements stay approved while PayPal processes them. When an item reaches SUCCESS, the statement is marked paid with method paypal and PayPal's transaction ID as Reference, the payment is written to the audit log (payout.paid), and the partner gets the "Payout sent" notification — like Mark paid….

Updates arrive:

• By webhook — every event is verified with PayPal's verify-webhook-signature API before it is applied; unverified calls are refused (HTTP 401).
• By Refresh statuses on the providers page — re-reads open batches from PayPal. Use it when no webhook is configured.

Failed payments#

Items that end as FAILED, RETURNED, BLOCKED, REFUNDED, REVERSED, DENIED, UNCLAIMED or CANCELED keep the statement approved. The provider's status and error are shown:

• in the Provider column of Billing → Payouts (for example "PayPal · FAILED" with the error underneath);
• on the statement's page, in the PayPal payment card with the status, batch and item IDs and the error: "PayPal did not pay this statement. It stays approved: fix the cause … and send it again, or pay it another way and use Mark paid."

Fix the cause (for example the partner's PayPal e-mail), then click Send to PayPal again on the statement (and confirm), or select it again on Billing → Payouts → Pay with PayPal. The retry goes out in a new batch to the partner's current PayPal e-mail; PayPal never retries the failed item itself, so this cannot pay twice. Late events of the failed batch are ignored once the statement has been sent again. You can also pay it another way and use Mark paid….

Security#

• Secrets are encrypted with a key derived from the platform's APP_SECRET and never returned to the browser.
• Only admins and owners (billing write) can connect providers and send payments.
• Connecting, disconnecting, each PayPal send (payout.provider_send) and each manual refresh are written to the audit log.

Related#

• Payout statements
• Partner payments and payment methods