kyc_approved event the BE provisions an Alfred customer (POST /customers/create), files the KYC text (POST /customers/{id}/kyc) and pipes the SumSub documents (POST /customers/{id}/kyc/{subId}/files), then finalizes (updateKycStatusByCircle). Alfred reviews and phones home via webhook. GET /eligibility — the widget's mount gate — reads the resulting alfred_kyc_status kyc-property and decides what the widget renders.The four states a trader can land in with Alfred after passing our internal SumSub KYC.
PENDING.alfred_kyc_status: APPROVED.REJECTED.What each trader wants in each state. Each has an actor sequence below.
alfred_kyc_status: APPROVED → eligibility: { eligible: true }.PENDING → eligibility throws ALFRED_KYC_PENDING.REJECTED → eligibility throws ALFRED_KYC_REJECTED.UPDATE_REQUIRED → eligibility returns a fallback descriptor. See the KYC fallback page.Reproduce-on-dev sequences for each terminal state. The update-required flow lives on the KYC fallback page.
__dev/seed-kyc-and-provision?country=AR → customer created, KYC text + documents submitted.__dev/approve-kyc → pushes KYC COMPLETED webhook to Alfred.COMPLETED back → handleKycEvent writes alfred_kyc_status: APPROVED.GET /eligibility → { eligible: true }.__dev/seed-kyc-and-provision?country=AR only — do not approve.statusKyc: IN_REVIEW). No terminal webhook arrives — Alfred dev does not auto-progress.GET /eligibility → throws ALFRED_KYC_PENDING.KYC FAILED webhook with the customer's live submissionId (via __dev/emit-kyc-status on the playground).FAILED back → handleKycEvent maps to alfred_kyc_status: REJECTED.GET /eligibility → throws ALFRED_KYC_REJECTED.POST /psp/alfred/__dev/emit-kyc-status resolves your customerId + live submissionId server-side and pushes the synthetic KYC webhook to Alfred, which fans it back and updates alfred_kyc_status. Pick a status (CREATED / IN_REVIEW / COMPLETED / FAILED / UPDATE_REQUIRED) to drive any flow — fire it from the Dev playground.Each code corresponds to a distinct widget screen / inline message. Verify the FE renders the right copy per code.
| Code | Where it comes from | User-visible message (expected) |
|---|---|---|
USER_NOT_VERIFIED | setSessionData, initiate-* | "Please complete your KYC to use this feature." |
ALFRED_KYC_PENDING | setSessionData, initiate-* | "Your verification is under review — please try again shortly." |
ALFRED_KYC_REJECTED | setSessionData, initiate-* | "Verification was rejected by the payment provider — contact support." |
ALFRED_NOT_AVAILABLE_FOR_COUNTRY | checkEligibility, setSession | "This payment method is not available in your country." |
ALFRED_CUSTOMER_NOT_PROVISIONED | checkEligibility | Internal — should auto-resolve via kyc_approved event. |
ALFRED_MAINTENANCE_MODE | initiate-* | "The service is undergoing maintenance — try again shortly." |
ALFRED_WITHDRAWALS_FROZEN | initiate-withdrawal only | "Withdrawals are temporarily frozen." |
ALFRED_SESSION_NOT_OWNED | requireSession | Generic 403 — should never reach a real user. |
ALFRED_CROSS_BORDER_NOT_SUPPORTED | setSessionData | "Your account is registered in X — you can't deposit Y." |
Raw 111301 bleeding through | Alfred (any 4xx) | Should be wrapped by the widget — verify it never shows literally. Bug #1 (AR/CO/DO source) is closed, but the FE wrapper stays as defense. |
For QA who want to inspect inbound Alfred webhook traffic in BE logs.
FIAT_DEPOSIT_RECEIVED — Alfred saw the bank credit. Persisted to session; widget stepper updates.TRADE_COMPLETED — fiat → USDC conversion done on Alfred's side.ON_CHAIN_INITIATED — Alfred dispatched the on-chain transfer to our liquidation address.ON_CHAIN_COMPLETED — funds confirmed on-chain. Triggers DepositManualCreateJob and credits the user.FIAT_TRANSFER_COMPLETED → setWithdrawalStatus({ status: completed }) → WithdrawalCompleteJob.FAILED → setWithdrawalStatus({ status: rejected }) → WithdrawalRejectJob (balance restored).COMPLETED → our handler writes alfred_kyc_status: APPROVED to user_kyc_data.REJECTED → alfred_kyc_status: REJECTED.UPDATE_REQUIRED → LIVE writes alfred_kyc_status: UPDATE_REQUIRED → drives the fallback form (see KYC fallback).PENDING / others → mapped to PENDING; does not unblock the widget.Signature: t=<unix>,s=<hex> header. We HMAC-SHA256 the body with alfred_webhook_secret (from PSP_ALFRED_CLIENT_CONFIG env var). Replay window is 5 minutes. Failed signature → 401, no state mutation.