Stripe Payout
Pay out approved wallet withdrawals to a customer's Stripe Connected Account.
Setting up?
Skip to Payout Settings → Stripe for the step-by-step keys + Connect onboarding walkthrough.
What It Does
| For | Means |
|---|---|
| Customer | Picks "Stripe" as the withdrawal method, completes Stripe onboarding once. Future withdrawals land in their bank via Stripe Connect |
| Admin | Approve → plugin calls Stripe Transfers API → instant payout |
What You Need
- A Stripe account with Connect enabled
- Your Connect platform application live
- API secret keys (test + live)
Setup
1. Plugin settings
Wallet → Settings → Payout → Stripe
| Field | Notes |
|---|---|
| Enable | toggle exposure on the withdrawal method radio |
| Mode | test for staging / live for production |
| Test Secret Key | sk_test_... |
| Live Secret Key | sk_live_... |
| Currency | base currency for payouts |
| Description prefix | shown on the Stripe transfer description |
| Auto-fetch onboarding link | when ON, generates Stripe onboarding URL automatically when needed |
2. Customer Connect Account
The plugin needs the customer's acct_xxx ID to know where to send.
Option A — Plugin-managed onboarding (recommended)
Enable "Auto-fetch onboarding link". When a customer requests their first Stripe withdrawal:
- Plugin creates an Express Connect account
- Saves the account ID to the customer's profile
- Generates a Stripe-hosted onboarding URL
- Redirects customer to complete onboarding
Once done, future withdrawals just work.
Option B — Bring-your-own integration
If you already collect Stripe Connect account IDs via another plugin (Dokan / WCFM Connect / custom), set the user meta from that plugin's hook. Wallet plugin reads from the same key.
How Approval Works
When admin clicks Approve on a Stripe-method withdrawal:
- Plugin reads the customer's connected account ID
- Converts amount to smallest currency unit (cents / paise)
- Calls Stripe Transfers API
- Stripe returns the transfer ID (
tr_xxx) - Status flips
pending→paid(Stripe transfers are instant) - Customer's bank gets the money on Stripe's standard payout schedule (T+2 to T+7 depending on country)
Test vs Live Keys
| Mode | Use for | Connected accounts |
|---|---|---|
test | dev / staging | Stripe test connected accounts (acct_test_...) |
live | production | real acct_xxx IDs |
Each Stripe environment has its own connected accounts — IDs are not portable.
Currency Handling
Plugin auto-converts to Stripe's smallest currency unit:
| Currency | Multiplier |
|---|---|
| USD, EUR, GBP, INR, etc. | × 100 (cents / paise) |
| JPY, KRW, VND | × 1 (zero-decimal currencies) |
| BHD, KWD, OMR | × 1000 (three-decimal) |
Override via filter for unusual currencies.
Webhooks (optional)
Transfers are immediate so webhooks aren't strictly needed. Optionally subscribe to:
transfer.createdtransfer.failedtransfer.reversed
Webhook URL: shown in the plugin settings. Set the webhook signing secret on the same tab.
Reconciliation
SELECT id, amount, fee,
JSON_EXTRACT(error, '$.stripe_transfer_id') AS transfer_id,
paid_at
FROM wp_wkwc_wallet_withdrawal
WHERE status = 'paid' AND method = 'stripe'
AND paid_at >= '2026-04-01';
The transfer ID (tr_xxx) is searchable in the Stripe dashboard.
Common Failures
| Stripe error | What it means | Fix |
|---|---|---|
account_invalid | Customer's Stripe account closed or restricted | Reject withdrawal, refund balance |
balance_insufficient | Your platform's available balance is too low | Top up Stripe balance from dashboard |
currency_mismatch | Connected account doesn't support the payout currency | Customer needs to update Stripe profile |
transfers_not_allowed | Connect onboarding incomplete | Resend onboarding link |
When Something Goes Wrong
| Problem | Fix |
|---|---|
| Customer can't pick Stripe at withdrawal | Method enabled in admin settings? |
| Onboarding link doesn't open | Stripe API key wrong; check Mode + Secret Key |
| Webhook signature invalid | Re-copy the signing secret; rotate if compromised |
| Amount off by 100× | Custom currency missing from smallest-unit map; filter to add |
For developers — hooks
Hooks
| Hook | Type | When |
|---|---|---|
wkwp_stripe_payout_request_body | filter | mutate the form body before send |
wkwp_stripe_payout_response | action | after Stripe API response |
wkwp_stripe_smallest_unit | filter | currency multiplier override |
wkwp_stripe_webhook_event | action | webhook event received |
API call shape
POST /v1/transfers
amount=12345
currency=inr
destination=acct_xxx
transfer_group=wallet_withdrawal_<row_id>
description="Wallet withdrawal #<row_id>"