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 or custom code, set the user meta from that source'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)
- 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, etc. | × 100 (cents) |
| 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=usd
destination=acct_xxx
transfer_group=wallet_withdrawal_<row_id>
description="Wallet withdrawal #<row_id>"