KYC Flow
KYC submission inside Wallet Central. Modal + dedicated page — same engine as the legacy KYC modal.
What Customers See
┌──────────────────────────────────────────────┐
│ H1: KYC verification │
│ Sub: Verify identity to unlock features │
├──────────────────────────────────────────────┤
│ Status banner │
│ ✓ KYC VERIFIED (if approved) │
│ ⏱ Under review (if pending) │
│ ✗ Rejected: <admin note> (if rejected) │
│ ◯ Verify your account (if missing) │
├──────────────────────────────────────────────┤
│ What you need (admin description) │
│ "Upload one government-issued photo ID" │
├──────────────────────────────────────────────┤
│ Form │
│ Full name [________________] │
│ Document type [ Passport ▼ ] │
│ Document number [________________] │
│ File 1 [ Choose file… ] │
│ File 2 (opt) [ Choose file… ] │
│ File 3 (opt) [ Choose file… ] │
├──────────────────────────────────────────────┤
│ [ Submit for review ] │
└──────────────────────────────────────────────┘
(After submit)
┌──────────────────────────────────────────────┐
│ ⏱ Under review │
│ We'll email you within 1 business day. │
│ [ Back to wallet ] │
└──────────────────────────────────────────────┘
Status Banner
| Status | Banner |
|---|---|
approved | green "✓ KYC VERIFIED" — form hidden, "All features unlocked" message |
pending | amber "⏱ Under review" — form hidden, no submit |
rejected | red "✗ Rejected: <admin_note>" — form re-rendered, customer can resubmit |
| missing | grey "◯ Verify your account" — form rendered |
Auto-Redirect From Gated Views
When customer hits a KYC-gated view (e.g. /wallet-central/withdraw/) without approval:
- View renders the locked card
- Locked card has "Verify now" button
- Click → navigates to
/wallet-central/kyc/?return_to=withdraw - After submission → "Under review" page shows "Back to <return_to>" link
Customer never gets stuck — every gated surface routes back here.
Form Fields
| Field | Required |
|---|---|
| Full name | yes |
| Document type | yes — dropdown from admin's list |
| Document number | yes |
| File 1..N | at least 1; admin sets max (1-5) |
| File constraint | Default |
|---|---|
| Max file size | 5 MB |
| Allowed types | JPEG, PNG, WebP, PDF |
Re-Submit After Rejection
Rejected status auto-renders the form. Admin note shown above. Customer fixes the issue → submits → status flips back to pending.
Common Scenarios
Customer submitted blurry photo
Admin rejects with note "Photo blurry, please re-upload clearer photo." Customer's banner goes red with the note. They re-submit.
Customer can't submit — file too big
Their image is over the size cap. They compress and try again. Error shown inline.
Approved customer still seeing locked features
Cache stale. Admin → WC Status Tools → Wallet → Clear cache. Customer reload.
Privacy
Documents stored outside the public uploads directory. Direct URL access blocked. Image proxies require authenticated capability check.
GDPR — personal data export + eraser plugins auto-include / delete wallet KYC data.
When Something Goes Wrong
| Problem | Fix |
|---|---|
| File upload rejected | MIME or size cap — verify allowed types and max size |
| Form not visible after rejection | Admin note empty or theme CSS hiding it |
| Status banner stale after admin approve | Cache bust failed — clear via Status Tools |
| Documents not visible to admin | Upload directory permissions — should be 0755 dirs / 0644 files |
For developers — hooks
Hooks
| Hook | Type | When |
|---|---|---|
wkwp_kyc_submit_validate | filter | extra validation, return WP_Error to reject |
wkwp_kyc_status_changed | action | every status transition |
wkwp_kyc_document_check_mime | filter | accept extra MIMEs |
wkwp_central_kyc_after_submit | action | post-submit hook for analytics |
Same engine as legacy
Form posts to the same AJAX action used by the legacy My Wallet KYC modal. Single submission engine, two UI surfaces.
Related
- KYC (engine)
- Withdraw (KYC-gated)
- Send Money (KYC-gated)
- QR Pay (KYC-gated)