YesCash Core API

POST /v1/core/profile

Submit ctomer profile (identity-attribute capture).

Ctomer profile submission per `§B.2.2`. Captures the minimum identity-attribute set for sanctions screening and KYC document matching; triggers identity resolution per the API specification silent merge across the three outcomes); the response shape is uniform across all three outcomes per `§B.2.2.2` silent-merge defence. Sanctions screening per the API specification post-submit; outcomes surface via `GET /v1/core/profile` (`stat`, `kycStat`) and the `ctomer.stat_changed` webhook stream. **Self-referential URL convention.** Per `§B.1.4` Part B URL convention, this is `POST /v1/core/profile`, NOT `/v1/core/profile/me` or `/v1/core/ctomers/{id}/profile`. Per FM.3.11, POST-as-update — the same endpoint handles both create (`PENDING` ctomer's first submission) and update. **Idempotency.** Within `PENDING` per `§B.2.2.5`; same idempotency key returns the original response. Post-`PENDING` profile-update semantics: forward dependency on the post-VALID profile-update workflow (out of v1 scope per `§B.4.4`).

Parameters

Request body

application/json: ProfileSubmitRequest

Responses

GET /v1/core/profile

Read authenticated ctomer's profile, stat, KYC state, identifiers.

Profile-read per `§B.2.3`. Substantive ctomer-state observation surface — consumed at ctomer-app login-success per the `§A.7` profile-fetch-then-gate pattern, at navigation to profile / stat screens, and at state refresh in response to the `ctomer.stat_changed` webhook. Carries: identity attributes (echoed and post-processed); current stat per matrix v4 `§2`; KYC lifecycle state; currently-active identifier set per `§A.8.2`; partner-scoped `subscriptionId`.

Parameters

Responses

POST /v1/core/kyc-sessions

Initiate principal-served KYC capture session.

KYC session creation per `§B.4.2`. **Empty request body** — session-purpose is determined server-side from the ctomer's KYC lifecycle state per the API specification `kycStat = NOT_STARTED`; resume for `IN_PROGRESS`; `RESUBMISSION` for `RESTRICTED` + `REMEDIATION_REQUIRED`). The empty-body posture preserves the structural defence that **the principal owns the KYC decision** per platform rules. Returns a session-bound webview URL on the principal-controlled `kyc.{YesCash}.yescash.example` host. Partner-app opens the URL in an in-app webview; capture happens entirely in the principal's environment; partner-app is the display host only. See `§B.5` for the webview wire-level behaviour and closure-signal handling. **Server-side idempotency** per `§B.4.2.5` — an existing in-progress session within TTL is returned for resumability; the `X-Idempotency-Key` is still required per FM.5. **Path convention.** Hyphenated `/kyc-sessions` per `§B.0.3` + `§B.4.2.1`; App B DevGuide's `/kyc/sessions` form is editorial drift and is surfaced as the API specification.3` candidate.

Parameters

Responses

GET /v1/core/kyc-sessions/{kycSessionId}

Read KYC session lifecycle state.

KYC session-state read per `§B.4.3`. **Session-lifecycle only** — no KYC outcome details, no verification-pipeline state, no artefact-level signal. KYC outcomes surface via `GET /v1/core/profile` (`kycStat` field) and the `ctomer.stat_changed` webhook stream (Partner-Only spec). The deliberate split keeps `§B.4.3` as session-lifecycle-only surface; outcome-surfacing duplication is avoided per `§B.4.3`.

Parameters

Responses

POST /v1/core/quotes

Create a partner-issued signed quote (re-presented to principal).

Quote creation per App B flow B.2 + `§B.18.6` sandbox reachability. The partner-app re-presents the ctomer's pricing intent to the principal; the principal applies the the API specification.5 three-measure pricing envelope per `§D5` and returns a signed quote per `§D3`. **Note on inventory.** `§B.0.3` section-structure table omits this endpoint; App B canonical wire traces and the `§B.18.6` sandbox reachability table treat it as load-bearing. This YAML follows App B / `§B.18.6` per Step 27 Q1a. The `§B.0.3` inventory gap is surfaced as an the API specification.3` editorial-cleanup candidate (additive correction; no substantive contract change). **Quote validity.** 60-second TTL per `§B.6` general case; 30-minute CFPB ceiling for -YesCash quotes per the API specification.5 `§D4`.

Parameters

Request body

application/json: QuoteCreateRequest

Responses

GET /v1/core/quotes/{quoteId}

Fetch a signed quote by id.

Quote-detail read per `§B.6.2`. Observational; no state transitions. Ctomer-stat gating permits `VALID`, `MONITORED`, `RESTRICTED`; `PENDING` MAY fetch if the partner-app has surfaced a quote pre-promotion; `BLOCKED` / `CLOSED` reject. Quote mt resolve in the ctomer's `Subscription` scope per `§B.1.3` partner-scoping at the data layer.

Parameters

Responses

GET /v1/core/quotes/{quoteId}/disclosure

Fetch regulator-aligned disclosure for a quote.

Regulator-aligned disclosure per `§B.7`. Returns a `disclosureToken` binding the served disclosure version to the `(quoteId, MasterCtomerId)` context; the token is single-e at acceptance per `§B.7.3`. The ctomer cannot accept a quote without first fetching this disclosure — the substantive ctomer-protection defence is that acceptance is committed against a regulator-aligned disclosure. **Language negotiation.** Per `§B.7.2.3`: `Accept-Language` → ctomer profile preference → YesCash default. **Caching.** `Cache-Control: no-store` per RFC 7234 — disclosure token is single-e and time-bound; caching is operationally wrong.

Parameters

Responses

POST /v1/core/quotes/{quoteId}/accept

Accept a quote (pricing commitment; creates transfer at registered).

Quote-acceptance per `§B.6.3`. The ctomer commits to the pricing terms; the principal creates the transfer shell in **`registered`** state per the API specification.1 `§D2` + matrix v4 `§4.12` `TRF_INITIATION_QUOTE_ACCEPTED`. The next state transition is driven by `/transfers/{id}/submit` (`§B.9`) — which attaches beneficiary + payout method + purpose and triggers the fast-check pipeline. **Ctomer-stat gating (G2 per `§B.16`).** `VALID` / `MONITORED` permit; `RESTRICTED` rejects with `ctomer.statBlocking`; `PENDING` rejects with `ctomer.statInsufficient`. The three-measure pricing envelope is re-checked at acceptance time; envelope-breach returns `quote.envelopeBreach` (422). **Idempotency.** Same key returns the original 201 with same `transferId`; the principal does NOT switch to 200 on retry per FM.5. **Three ctomer-commitment moments.** Per `§B.12.5`: (1) pricing commitment here at `/accept`; (2) recipient + destination commitment at `/submit`; (3) release-funds commitment at `/confirm` via device-bound assertion.

Parameters

Request body

application/json: QuoteAcceptRequest

Responses

GET /v1/core/beneficiaries

List the ctomer's beneficiaries.

Paginated beneficiary list per `§B.8.3`. Default state filter **excludes ARCHIVED**; partner-app may include ARCHIVED via the `states` query parameter for archived-list views. Cursor pagination per FM.3.10. Sort: `lastedAt` descending (most recently ed first); then `createdAt` descending for never-ed beneficiaries. Sort is fixed at v1.

Parameters

Responses

POST /v1/core/beneficiaries

Create a beneficiary (triggers asynchrono screening).

Beneficiary creation per `§B.8.2` + the API specification.3 `§D3`. Returns 202 Accepted with state `PENDING`; the screening pipeline per the API specification.3 `§D6` (sanctions + PEP + adverse-media) drives the `PENDING → VALID / MONITORED / BLOCKED` transition asynchronoly (typically seconds-to-minutes). **Destination identifiers are NOT collected at beneficiary creation** per the API specification.3 `§D3.3`. They accumulate per-transfer at `/transfers/{id}/submit` (`§B.9`); the `payoutMethods[]` array on `GET /v1/core/beneficiaries/{id}` populates as transfers complete. **Within-ctomer match.** Re-creating a beneficiary with identity attributes matching an existing record produces a second record (principal does not de-duplicate at the contract surface); within-ctomer matches surface as AML signals per `§D4.4`.

Parameters

Request body

application/json: BeneficiaryCreateRequest

Responses

GET /v1/core/beneficiaries/{beneficiaryId}

Read beneficiary detail (identity attributes, state, payout methods).

Beneficiary-detail read per `§B.8.4`. Includes echoed identity attributes, current state, accumulated payout-method list (masked destination identifiers per `§B.8.4.4` masking convention; full identifier never returned), and `ctomerActionExpected` UX hint per `§B.8.6`. Cross-ctomer AML signals per the API specification. Screening evidence and operator-decision rationale per `§D9.4` are **NOT surfaced**. Partner-app sees operational consequence only.

Parameters

Responses

POST /v1/core/beneficiaries/{beneficiaryId}/archive

Archive a beneficiary (one-way ctomer-initiated).

Beneficiary-archive per `§B.8.5` + the API specification.3 `§D7`. State transitions to `ARCHIVED`; the beneficiary is excluded from default list views; the record is retained per regulatory retention. **One-way transition** per the API specification.3` — the ctomer cannot un-archive; re-creation produces a new beneficiary record (no inherited payout-method history; identity-resolution per `§D4` may surface `within_ctomer_match_*` AML signals). **Ctomer-stat gating.** Allowed in `VALID`, `MONITORED`, `RESTRICTED`, `BLOCKED`; rejected in `PENDING` and `CLOSED`. The wider gating is the ctomer's-record-cleanup permission preserved even when transactability is gated. **BLOCKED beneficiaries cannot be archived by the ctomer** per the API specification.3 `§D2` (BLOCKED is terminal-from-ctomer-side; operator-only-exit). Rejects with `beneficiary.archiveBlocked`.

Parameters

Responses

GET /v1/core/transfers

List the ctomer's transfers (summary projection).

Paginated transfer list per `§B.14.3`. Summary projection only — full detail (`confirmationChallenge`, `cancellation`, `refund`, `stateHistory`) requires per-item `GET /v1/core/transfers/{transferId}` calls. **Wider ctomer-stat gating per [C4].** Mirrors `§B.14.2.2` — `VALID`, `MONITORED`, `RESTRICTED`, `BLOCKED` permit; only `PENDING` (defensive — a PENDING ctomer cannot have transfers per `§B.6.3` quote-acceptance gate) and `CLOSED` reject. The read-access-wider carve-out per `§B.16.4` [C4] is regulator-aligned: ctomers retain visibility into their own transfers across stat transitions. **Filters.** `states` (comma-separated `TransferState` values); `createdSince` (RFC 3339 timestamp); `cursor` (opaque pagination per FM.3.10); `limit` (default 50; max 200). Default `states`: all non-terminal states pl terminal states from the last 30 days per `§B.14.3.3`.

Parameters

Responses

GET /v1/core/transfers/{transferId}

Read transfer detail (state-conditional fields; re-issues confirmationChallenge).

Single-transfer detail per `§B.14.2`. Carries all state-conditional fields populated per the current `transferStat` per the `TransferDetailResponse` schema. The endpoint is the partner-app's primary mechanism for transfer-state observability — every transition documented in `§B.10.3` is observable here. **`confirmationChallenge` re-issuance per `§B.14.2.6`.** When `transferStat = validated`, the response carries a fresh `confirmationChallenge` (10-minute TTL); **the prior challenge is invalidated even if its TTL has not elapsed**. The re-issue-on-each-GET pattern means: a partner-app polling every 5 seconds while waiting for the ctomer to tap Pay produces a fresh challenge every poll — only the most-recently-issued challenge is valid. The ctomer's device builds the `/confirm` assertion ing the challenge from the most-recent GET. **Wider ctomer-stat gating per [C4].** Mirrors `/transfers` list — `VALID`, `MONITORED`, `RESTRICTED`, `BLOCKED` permit; only `PENDING` (defensive) and `CLOSED` reject. Read access wider than at money-moving endpoints. **Polling cadence guidance per `§B.14.4`.** State-aware exponential per FM.7 — 1s/2s/4s/8s in `registered` post-`/submit`; 5s steady in `validated`; 30s steady in network-in-flight states; 1s/2s/4s/5s in `NETWORK_CANCELLATION_PENDING`.

Parameters

Responses

POST /v1/core/transfers/{transferId}/submit

Submit recipient + destination + purpose; triggers fast-check.

Transfer submission per `§B.9`. Attaches the ctomer's recipient commitments (beneficiary, payout method, purpose) to the transfer shell created at quote acceptance. Triggers the asynchrono fast-check pipeline per the API specification.1 `§D4`. **Two-step state machine on success.** 202 Accepted; transfer remains `registered` at the response; fast-check transitions asynchronoly to `validated` / `onreview` / `rejected` per `§D4.2`. Partner-app polls `GET /v1/core/transfers/{id}` (`§B.14`) with FM.7 exponential cadence. **Ctomer-stat gating (G5).** `VALID`-only per `§B.9.2.2` — tighter than `/accept` (which allows `VALID` + `MONITORED`). **Payout-method conditional exclion.** Exactly one of `payoutMethod.destinationIdentifier` (fresh method) or `payoutMethod.payoutMethodId` (existing method) MT be supplied. Supplying both rejects with `validation.payoutMethoonflict`; supplying neither rejects with `validation.destinationIdentifierMissing`. **Format-vs-substantive split per `§B.9.2.5`.** Submit-time validation is format-level only (length, character set, structural shape). Substantive validation (IBAN BBAN checksum; Confirmation of Payee name-match; phone-number format check; wallet-address checksum) is part of the asynchrono fast-check pipeline; results surface as state transitions, not synchrono rejections. **Quote-validity-window check at submit.** If `quote.expiresAt < server-time`, the endpoint returns 410 Gone with `transfer.quoteExpired` and the transfer shell transitions to `expired`.

Parameters

Request body

application/json: TransferSubmitRequest

Responses

POST /v1/core/transfers/{transferId}/cancel

Cancel a transfer (consumer-protection floor; cancellable until paid).

Transfer cancellation per `§B.11`. The substantive ctomer-protection commitment of the platform per the API specification.1 `§D9` "cancellable until paid" rule. State-conditional dispatch: - **Pre-funding active states** (`registered`, `onreview`, `validated`, `funding`): **synchrono** 200 OK; transition to `aborted`; `cancellationOutcome: ABORTED_PRE_FUNDING`; no refund (no money moved). - **`funded` state**: **synchrono** 202; transition to `canceled`; `cancellationOutcome: CANCELED_PRE_NETWORK`; PS-side refund flow per the API specification.1 `§D4` initiated asynchronoly. - **`topay` / `reqpay` states**: **asynchrono** 202; `cancellationOutcome: NETWORK_CANCELLATION_PENDING`; principal coordinates with correspondent network per the API specification.4`; final outcome (`NETWORK_CANCELLATION_SUCCESS` / `NETWORK_ALREADY_PAID` / `NETWORK_IN_PROGRESS_RETRY_ALLOWED`) observable via `§B.14` polling with the 1s/2s/4s/5s cadence per `§B.14.4`. - **`spended` state**: outcome resolves per the prior state per the API specification.4`. **Ctomer-stat gating widest among money-moving endpoints (per `§B.11.2.2` carve-out [C2]).** `VALID`, `MONITORED`, `RESTRICTED`, **`BLOCKED`** all permit; only `CLOSED` rejects. The regulatorily-protected cancellation right survives stat changes — the principal cannot retain funds for a transfer the ctomer wants to cancel jt becae the ctomer became BLOCKED post-funding. **Partner kill-switch does NOT block ctomer cancellation** per `§B.11.6` row 1 substantive elaboration — partners in `wind_down` / `blocked` cannot prevent cancellation of pre-existing transfers. **Idempotency.** Same key + same body returns the original response per FM.5. The single exception per `§B.11.2.7` is post-resolution `NETWORK_IN_PROGRESS_RETRY_ALLOWED`, which admits a fresh `/cancel` attempt with a different idempotency key.

Parameters

Request body

application/json: TransferCancelRequest

Responses

POST /v1/core/transfers/{transferId}/confirm

Device-bound release-funds confirmation; promotes validated to funding.

Device-bound transfer confirmation per `§B.12`. The cryptographic gate on the `validated → funding` transition per the API specification.1 `§D2` + matrix v4 `TRF_AUTH_DEVICE_VERIFIED`. The request body carries a single field — a JWS Compact serialization of a device-signed assertion per the API specification.3` — and the principal performs the five-step verification per `§D5.2`. **Cryptographic verification chain.** (1) JWS signature verification against the registered public key for `device_id`; (2) registration-record ctomer-binding equality check; (3) payload-binding verification (`transfer_id`, `amount`, `currency`, `beneficiary_id`); (4) freshness + non-replay (`iat` within 60 seconds; `nonce` single-e); (5) principal-issued challenge consumption (`challenge` matches most-recent `confirmationChallenge` from `§B.14.2.6`). **On success.** Transfer transitions to `funding`; the principal allocates a `fundingSessionId` and `fundingWebviewUrl`; the partner-app opens the URL in an in-app webview per `§B.13`. **This response is the ONLY surface through which the partner-app obtains the funding-webview URL** — there is NO separate `POST /v1/core/transfers/{id}/funding` endpoint per `§B.13.1`. Re- opening a funding session after webview-URL expiry requires a fresh `/confirm` call, which itself requires a fresh device-bound assertion. This is the platform rules substantive defence per `§B.13.9`. **Ctomer-stat gating (G6).** `VALID`-only — mirrors `/submit` per `§B.12.2.2`. **Device-registration pre-conditions.** Ctomer mt have an active registered device per `§A.11`; `device.notRegistered` (412) if not. The `device_id` claim mt correspond to an active device; `device.deactivated` (412) for re-registered ctomers. **Cryptographic discipline.** RS256 + RSA-2048 minimum at v1; ES256 / EdDSA forward-watched at v1.1 per the API specification.0.4`. The Step 23 Appendix B flow B.3 wire-trace `alg: ES256` erratum is superseded by the API specification.3` and the `DeviceAssertion` schema description. **Lockout.** `device.assertionLockout` (429) on exceeding per-ctomer + per-device threshold per the API specification.1 `§D5.3` (15-minute backoff at v1).

Parameters

Request body

application/json: DeviceAssertion

Responses