Why webhook‑driven payout integrations are important
Merchants who automatically pay partner commissions reduce manual work, avoid errors and speed up reconciliations. Affilentra provides payout exports and webhooks as handoff points. In practice, a small integration middleware is required that accepts export data, forwards it to external payout providers (PayPal Payouts, Wise, Stripe Connect), reports status changes back, and generates accounting receipts. This article shows precisely which configurations and steps are required.
Overview: architecture and responsibilities
- Affilentra: Generates payout exports and fires webhook events with the payout batches.
- Middleware (your system or a small connector service): Validates the webhook, maps fields, calls provider APIs, handles provider callbacks, creates receipts and writes status back into Affilentra.
- Payout providers (PayPal, Wise, Stripe Connect): Execute payments and deliver payment references / webhooks for final status.
Prerequisites before integration
- Affilentra installation (self‑hosted) with enabled webhook system and export function. SSL for the webhook endpoint.
- Account and API credentials with the target providers (sandbox access for testing).
- Middleware with an HTTPS endpoint, a persistent store (DB), and the ability to generate files/PDFs and attach them to Affilentra.
Step 1: Define the payout export in Affilentra cleanly
Configure a payout export in Affilentra that provides all required fields. Recommended format: JSON or CSV with UTF‑8. Important fields:
- payout_id (unique internal ID)
- partner_id / partner_identifier
- payee_type (email | iban | account_id)
- payee_address (email, IBAN, bank account ID)
- amount (decimal, e.g. 123.45)
- currency (ISO code, e.g. EUR)
- gross / net / fee (if they should be reported separately)
- description / reference
Important: Define a field for an external reference (provider_reference) and a status field (pending / sent / failed / reconciled) — the middleware will populate these.
Step 2: Configure the webhook in Affilentra
- Create a webhook endpoint in Affilentra that sends an event when a payout export is executed (e.g. payout_exported).
- Secure the webhook event with an HMAC signature (shared secret). The middleware verifies this signature against the received payloads.
- Set up retries in Affilentra (e.g. 3 attempts with exponential backoff) and record error messages in logs.
Step 3: Middleware – flow and implementation points
The middleware is the central element. Core responsibilities:
- Webhook validation (signature, schema, duplicate check).
- Mapping: convert the Affilentra export into the provider payload.
- Provider call: create batches, set idempotency keys, handle API errors.
- Status management: process provider responses and report status back to Affilentra.
- Receipt generation: produce PDF/CSV/JSON, attach to the payout and hand over to accounting.
Mapping examples (practical)
- PayPal: map payee_address → receiver_email, amount + currency → amount, use sender_batch_id = payout_id.
- Wise: if IBAN is present, create a recipient, create a quote (if currency conversion), and create a transfer with reference = payout_id.
- Stripe Connect: for connected accounts use the destination parameter or send payouts on behalf of the Connected Account; if necessary perform a Transfer first.
Provider specifics & tips
- PayPal Payouts: use batch payouts for efficiency; set sender_batch_id for idempotency; store payout_item_id and batch_status for later reconciliation.
- Wise: create the recipient once and reuse the recipient_id; be aware of a possible quote step when converting currencies.
- Stripe Connect: check whether your flow should use Transfers to connected accounts or external bank accounts; use idempotency keys and list balance_transfers.
Status feedback to Affilentra and reconciliation
How to ensure reliable booking runs:
- Immediately after provider response: update Affilentra payouts with provider_reference, status = sent (or failed) and fee information.
- Implement a listener for provider webhooks (e.g. PayPal/Stripe webhooks). When a final status (SUCCESS/FAILED/COMPLETED) arrives the middleware updates the status in Affilentra.
- Perform regular reconciliations: compare the Affilentra export, provider reports and bank statements; log and alert on discrepancies.
Automatically generate accounting receipts
Automated receipts are a prerequisite for audit-proof accounting. Procedure:
- Generate one PDF receipt per payout containing the following information: payout_id, partner_id, partner name/address, gross/net/fees, currency, provider payment reference, timestamp.
- Also attach the provider receipt (API download from PayPal/Stripe/Wise) to the payout in Affilentra or store it in the accounting system.
- Export formats: CSV for bulk imports, PDF for individual booking receipts, optionally XML/DATEV-compatible depending on the target accounting system.
Error handling, idempotency and operations
- Idempotency: Use unique keys at the provider (e.g., payout_id as sender_batch_id) to avoid duplicate payments.
- Retries: Implement backoff strategies for temporary errors and a manual review queue for persistent failures.
- Monitoring & Alerting: Log webhook payloads, provider responses and reconciliation diffs; configure alerts for discrepancies.
- Sandbox testing: Run integration cycles in the sandbox mode of all three providers before starting production runs.
Use case: Payout flow (brief description)
1) Affilentra generates a payout export and fires payout_exported to your middleware. 2) Middleware validates, maps fields and calls the provider API. 3) Provider confirms with a reference → middleware updates Affilentra with status=sent and provider_reference. 4) Provider sends the final webhook (e.g. completed) → middleware sets status=reconciled, deducts fees and creates a PDF receipt that is attached to Affilentra.
Conclusion and next step
The technical integration of Affilentra payouts with PayPal, Wise and Stripe Connect via webhooks is a clearly structured process: clean export, secure webhook delivery, middleware with provider mapping, reliable status feedback and automatic receipt generation. This lets merchants retain control over terms and traceability while partners receive transparent payout histories.
Act now: Choose how to get started: discuss your requirements and test environment with the Affilentra team and begin the integration. More information and contact: https://affilentra.de
Next step
Try Affilentra yourself
A unified platform that transparently brings together product provisioning, tracking, conversion validation, commission calculation and payout across clearly separated roles; option for a self-hosted installation with a perpetual license without revenue sharing; merchants retain control over products, terms and marketing materials; partners receive personal tracking links and a traceable payout history.