# KYC (https://dev.cosmospay.lat/docs/api/kyc/)

> Receivers, their review and terms of service, and KYC documents.

Base URL: `https://api.cosmospay.lat/cosmos-api`

## List the consumer's receivers

`GET /v1/kyc/receivers`

Reads the local mirror only, newest first, on the fiat partner instance of the key's network. Paginated with `take` (default 100, max 100) and `skip`; answers `{ data, total, take, skip }`, where `total` counts every matching receiver. The stored KYC dossier (tax id, documents, owners) is never returned.

Requires the `kyc:read` scope.

**Query parameters**

- `take` (number, optional): Page size: how many items to return (1 to 100).
- `skip` (number, optional): How many items to skip before this page (offset).

**Responses**

- `200` (`ReceiverListEntity`): OK
  - `data` (ReceiverEntity[], required): The receivers on this page.
  - `total` (number, required): Matching rows, not the page length.
  - `take` (number, required): The page size applied, from the `take` query parameter (default 100).
  - `skip` (number, required): Rows skipped before this page, from the `skip` query parameter (default 0).
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)

## Create a receiver (start KYC/KYB)

`POST /v1/kyc/receivers`

Stores the receiver here and sends nothing to the fiat partner yet: it is created there only by `POST /v1/kyc/receivers/{id}/enable`, after the review and the customer's acceptance of the terms. A body with KYC data (tax id, date of birth, documents, legal name, formation date or owners) starts in `pending_review`, a bare registration in `inactive`. The receiver belongs to the fiat partner instance of the key's network (production for a mainnet key, development otherwise), and the stored dossier is never returned.

Requires the `kyc:write` scope.

**Request body** (`application/json`, required): `CreateReceiverDto`

- `type` (string, required): `individual` for a person (KYC) or `business` for a company (KYB). One of: `individual`, `business`.
- `kyc_type` (string, required): Depth of compliance verification: `light`, `standard` or `enhanced`. One of: `light`, `standard`, `enhanced`.
- `email` (string, required): Receiver's email address, at most 160 characters.
- `country` (string, required): ISO 3166-1 alpha-2 country code, upper case
- `first_name` (string, optional): First name of an individual receiver; with `last_name` it forms the receiver `name`.
- `last_name` (string, optional): Last name of an individual receiver.
- `date_of_birth` (string (date-time), optional): ISO 8601 date-time with an offset (the fiat partner rejects date-only values).
- `tax_id` (string, optional): Receiver's tax id.
- `occupation` (string, optional): Occupation of an individual receiver.
- `id_doc_country` (string, optional): ISO 3166-1 alpha-2 country code, upper case
- `id_doc_type` (string, optional): Type of the identity document (for example `PASSPORT`).
- `id_doc_front_file` (string, optional): file_url from POST /v1/kyc/upload
- `id_doc_back_file` (string, optional): Back of the identity document: a `file_url` from `POST /v1/kyc/upload`.
- `selfie_file` (string, optional): Selfie of the person: a `file_url` from `POST /v1/kyc/upload`.
- `account_purpose` (string, optional): Purpose of the account, as a fiat partner code (for example `receiving_payments`).
- `account_purpose_other` (string, optional): Free-text account purpose, forwarded to the fiat partner with `account_purpose`.
- `source_of_funds_doc_type` (string, optional): Type of the source-of-funds document, as a fiat partner code (for example `employment`).
- `source_of_funds_doc_file` (string, optional): Source-of-funds document: a `file_url` from `POST /v1/kyc/upload`.
- `source_of_wealth` (string, optional): Source of the receiver's wealth, forwarded to the fiat partner.
- `sole_proprietor_doc_type` (string, optional): master_service_agreement | salary_slip | bank_statement
- `proof_of_address_doc_type` (string, optional): Type of the proof-of-address document (for example `UTILITY_BILL`).
- `proof_of_address_doc_file` (string, optional): Proof-of-address document: a `file_url` from `POST /v1/kyc/upload`.
- `recipient_relationship` (string, optional): Relationship to the recipient, as a fiat partner code (for example `self`).
- `purpose_of_transactions` (string, optional): Purpose of the receiver's transactions, as a fiat partner code (for example `business_transactions`); an enhanced KYC field.
- `purpose_of_transactions_explanation` (string, optional): Free-text explanation of `purpose_of_transactions`; an enhanced KYC field.
- `legal_name` (string, optional): Legal name of a business receiver; it becomes the receiver's `name`.
- `alternate_name` (string, optional): Alternate name of a business receiver.
- `business_type` (string, optional): Type of business, as a fiat partner code (for example `cooperative`).
- `business_industry` (string, optional): Industry code of a business receiver, such as the NAICS code `541511`.
- `business_description` (string, optional): What a business receiver does.
- `formation_date` (string (date-time), optional): ISO 8601 date-time with an offset (the fiat partner rejects date-only values).
- `estimated_annual_revenue` (string, optional): Estimated annual revenue band of a business receiver, as a fiat partner code (for example `1000000_4999999`).
- `publicly_traded` (boolean, optional): Whether a business receiver is publicly traded.
- `website` (string, optional): Absolute http(s) URL, without credentials.
- `incorporation_doc_file` (string, optional): Incorporation document of a business receiver: a `file_url` from `POST /v1/kyc/upload`.
- `proof_of_ownership_doc_file` (string, optional): Proof-of-ownership document of a business receiver: a `file_url` from `POST /v1/kyc/upload`.
- `owners` (ReceiverOwnerDto[], optional): Beneficial owners and controlling persons of a business receiver.
- `address_line_1` (string, optional): First line of the receiver's address.
- `address_line_2` (string, optional): Second line of the receiver's address.
- `city` (string, optional): City of the receiver's address.
- `state_province_region` (string, optional): State, province or region of the receiver's address.
- `postal_code` (string, optional): Postal code of the receiver's address.
- `phone_number` (string, optional): Receiver's phone number with its country code.
- `ip_address` (string, optional): Receiver's IP address, forwarded to the fiat partner.
- `external_id` (string, optional): Your own id for this receiver
- `image_url` (string, optional): URL of a display image for the receiver. With `external_id`, the only field a non-admin key may change once the receiver exists at the fiat partner.
- `tos_id` (string, optional): Accepted terms-of-service id (from the redirect of POST /v1/kyc/terms-of-service). Required by the fiat partner to create a receiver.

**Responses**

- `201` (`ReceiverEntity`): Created
  - `id` (string, required): Cosmos Pay id of the receiver, the `{id}` or `{receiverId}` of the receiver routes.
  - `blindpayId` (string, required): The fiat partner's receiver id (`re_...`); a `local_` placeholder until the receiver is enabled.
  - `type` (string, required): `individual` (KYC) or `business` (KYB).
  - `kycType` (object, optional): Depth of compliance verification: `light`, `standard` or `enhanced`.
  - `kycStatus` (object, optional): The fiat partner KYC status (verifying, approved, rejected, ...).
  - `email` (object, optional): Receiver's email address.
  - `name` (object, optional): Display name: a business's legal name, otherwise the person's first and last name.
  - `country` (object, optional): Receiver's country, an ISO 3166-1 alpha-2 code.
  - `externalId` (object, optional): Your own id for the receiver (`external_id`).
  - `disabled` (boolean, required): Owner/admin kill-switch: when true the account is blocked from onramp/offramp.
  - `dossierVersion` (number, required): Version of the submitted KYC data. Bumped on every edit while the receiver is still local. Send it back as `expected_version` when approving, so the approval is pinned to the dossier that was reviewed.
  - `reviewedVersion` (number, optional): The `dossierVersion` an elevated reviewer approved, or null if the receiver has not been approved. Enabling is refused unless it equals `dossierVersion`.
  - `createdAt` (string (date-time), required): When the receiver was created here (ISO 8601 date-time).
  - `updatedAt` (string (date-time), required): When the receiver was last changed here (ISO 8601 date-time).
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Get a receiver (refreshes KYC status from the fiat partner)

`GET /v1/kyc/receivers/{id}`

For a receiver that already exists at the fiat partner, reads it there and updates the local mirror first, so `kycStatus` is the fiat partner's current one; when the fiat partner cannot be reached, the stored row is answered instead of an error. A receiver not yet at the fiat partner (`inactive`, `pending_review`, `pending_user`) is answered from the local row.

Requires the `kyc:read` scope.

**Path parameters**

- `id` (string, required)

**Responses**

- `200` (`ReceiverEntity`): OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Update a receiver (once it is at the fiat partner, identity fields need an elevated key)

`PATCH /v1/kyc/receivers/{id}`

Before the receiver exists at the fiat partner, the patch is merged into the stored registration, any change bumps `dossierVersion`, and editing a `pending_user` receiver (or adding KYC data to an `inactive` one) moves it to `pending_review`. After that the patch is sent to the fiat partner, and a key without the admin role may change only `external_id` and `image_url`. `tos_id` is always ignored: the accepted terms cannot be changed.

Requires the `kyc:write` scope.

**Path parameters**

- `id` (string, required)

**Request body** (`application/json`, required): `UpdateReceiverDto`

- `type` (string, optional): `individual` for a person (KYC) or `business` for a company (KYB). One of: `individual`, `business`.
- `kyc_type` (string, optional): Depth of compliance verification: `light`, `standard` or `enhanced`. One of: `light`, `standard`, `enhanced`.
- `email` (string, optional): Receiver's email address, at most 160 characters.
- `country` (string, optional): ISO 3166-1 alpha-2 country code, upper case
- `first_name` (string, optional): First name of an individual receiver; with `last_name` it forms the receiver `name`.
- `last_name` (string, optional): Last name of an individual receiver.
- `date_of_birth` (string (date-time), optional): ISO 8601 date-time with an offset (the fiat partner rejects date-only values).
- `tax_id` (string, optional): Receiver's tax id.
- `occupation` (string, optional): Occupation of an individual receiver.
- `id_doc_country` (string, optional): ISO 3166-1 alpha-2 country code, upper case
- `id_doc_type` (string, optional): Type of the identity document (for example `PASSPORT`).
- `id_doc_front_file` (string, optional): file_url from POST /v1/kyc/upload
- `id_doc_back_file` (string, optional): Back of the identity document: a `file_url` from `POST /v1/kyc/upload`.
- `selfie_file` (string, optional): Selfie of the person: a `file_url` from `POST /v1/kyc/upload`.
- `account_purpose` (string, optional): Purpose of the account, as a fiat partner code (for example `receiving_payments`).
- `account_purpose_other` (string, optional): Free-text account purpose, forwarded to the fiat partner with `account_purpose`.
- `source_of_funds_doc_type` (string, optional): Type of the source-of-funds document, as a fiat partner code (for example `employment`).
- `source_of_funds_doc_file` (string, optional): Source-of-funds document: a `file_url` from `POST /v1/kyc/upload`.
- `source_of_wealth` (string, optional): Source of the receiver's wealth, forwarded to the fiat partner.
- `sole_proprietor_doc_type` (string, optional): master_service_agreement | salary_slip | bank_statement
- `proof_of_address_doc_type` (string, optional): Type of the proof-of-address document (for example `UTILITY_BILL`).
- `proof_of_address_doc_file` (string, optional): Proof-of-address document: a `file_url` from `POST /v1/kyc/upload`.
- `recipient_relationship` (string, optional): Relationship to the recipient, as a fiat partner code (for example `self`).
- `purpose_of_transactions` (string, optional): Purpose of the receiver's transactions, as a fiat partner code (for example `business_transactions`); an enhanced KYC field.
- `purpose_of_transactions_explanation` (string, optional): Free-text explanation of `purpose_of_transactions`; an enhanced KYC field.
- `legal_name` (string, optional): Legal name of a business receiver; it becomes the receiver's `name`.
- `alternate_name` (string, optional): Alternate name of a business receiver.
- `business_type` (string, optional): Type of business, as a fiat partner code (for example `cooperative`).
- `business_industry` (string, optional): Industry code of a business receiver, such as the NAICS code `541511`.
- `business_description` (string, optional): What a business receiver does.
- `formation_date` (string (date-time), optional): ISO 8601 date-time with an offset (the fiat partner rejects date-only values).
- `estimated_annual_revenue` (string, optional): Estimated annual revenue band of a business receiver, as a fiat partner code (for example `1000000_4999999`).
- `publicly_traded` (boolean, optional): Whether a business receiver is publicly traded.
- `website` (string, optional): Absolute http(s) URL, without credentials.
- `incorporation_doc_file` (string, optional): Incorporation document of a business receiver: a `file_url` from `POST /v1/kyc/upload`.
- `proof_of_ownership_doc_file` (string, optional): Proof-of-ownership document of a business receiver: a `file_url` from `POST /v1/kyc/upload`.
- `owners` (ReceiverOwnerDto[], optional): Beneficial owners and controlling persons of a business receiver.
- `address_line_1` (string, optional): First line of the receiver's address.
- `address_line_2` (string, optional): Second line of the receiver's address.
- `city` (string, optional): City of the receiver's address.
- `state_province_region` (string, optional): State, province or region of the receiver's address.
- `postal_code` (string, optional): Postal code of the receiver's address.
- `phone_number` (string, optional): Receiver's phone number with its country code.
- `ip_address` (string, optional): Receiver's IP address, forwarded to the fiat partner.
- `external_id` (string, optional): Your own id for this receiver
- `image_url` (string, optional): URL of a display image for the receiver. With `external_id`, the only field a non-admin key may change once the receiver exists at the fiat partner.
- `tos_id` (string, optional): Accepted terms-of-service id (from the redirect of POST /v1/kyc/terms-of-service). Required by the fiat partner to create a receiver.

**Responses**

- `200` (`ReceiverEntity`): OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403` (`ApiErrorBodyEntity`): `kyc_review_required`: the receiver already exists at the fiat partner and the patch touches a field other than `external_id` or `image_url`. Only an elevated key (admin role) may rewrite identity at the provider; before enabling, the same edit sends the receiver back to review instead.
  - `statusCode` (number, required): Always the HTTP status of the response itself.
  - `code` (string, required): Stable machine-readable code. Branch on this, never on the message: messages are human-facing and may be reworded; codes are never renamed once published. Each response documents the subset it can return. One of: `insufficient_scope`, `no_authenticated_consumer`, `gateway_required`, `admin_console_only`, `not_found`, `validation_failed`, `payload_too_large`, `idempotency_conflict`, `operation_in_flight`, `invalid_state_transition`, `slippage_exceeded`, `insufficient_balance`, `no_path_found`, `trustline_missing`, `invalid_amount`, `invalid_memo`, `transaction_rejected`, `transaction_already_settled`, `recipient_not_registered`, `payment_transfer_mismatch`, `fee_transfer_mismatch`, `merchant_fee_transfer_mismatch`, `payer_mismatch`, `transaction_not_found`, `expired`, `network_unsupported`, `asset_unsupported`, `merchant_fee_unsupported`, `provider_error`, `provider_unavailable`, `quote_not_found`, `quote_expired`, `kyc_state_invalid`, `kyc_review_required`, `account_disabled`, `payload_expired`, `rate_limited`, `customer_wallet_taken`, `alias_taken`, `alias_name_invalid`, `alias_challenge_invalid`, `alias_signature_invalid`, `alias_recovery_invalid`, `alias_address_conflict`, `wallet_handshake_invalid`, `wallet_verifier_invalid`, `wallet_login_code_invalid`, `wallet_login_code_cooldown`, `wallet_session_invalid`, `wallet_signature_invalid`, `wallet_backup_invalid`, `wallet_backup_limit`, `wallet_account_mismatch`, `wallet_provider_unavailable`, `wallet_return_url_not_allowed`, `wallet_recovery_setup_refused`, `easy_recovery_not_found`, `easy_recovery_already_offered`, `easy_recovery_not_offered`, `easy_recovery_code_invalid`, `easy_recovery_burned`, `plugin_not_installed`, `plugin_consent_mismatch`, `plugin_rejected`, `plugin_quota_exceeded`, `plugin_failed`, `protected_payment_buyer_mismatch`, `protected_payment_signature_invalid`, `misconfigured`, `internal_error`.
  - `error` (string, required): The HTTP reason phrase for `statusCode`.
  - `message` (string | string[], required): Human-readable detail. An array when class-validator rejected the body.
  - `details` (object, optional): Machine-readable facts about this failure, present only on the codes whose example shows it: `easy_recovery_code_invalid` carries `{ "attemptsLeft": 4 }`. Absent everywhere else.
  - `path` (string, required): The path of the request that failed.
  - `timestamp` (string, required): When the envelope was produced, ISO 8601.
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Delete a receiver

`DELETE /v1/kyc/receivers/{id}`

Deletes the receiver at the fiat partner when it was ever created there, then the local row, and records the deletion in the audit log. A receiver that never reached the fiat partner is deleted locally only.

Requires the `kyc:write` scope.

**Path parameters**

- `id` (string, required)

**Responses**

- `200` (`ReceiverDeletedEntity`): OK
  - `id` (string, required): The receiver id from the request path.
  - `deleted` (boolean, required): Always true.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Approve a receiver's KYC review and get its terms-of-service link

`POST /v1/kyc/receivers/{id}/approve`

The review gate before anything reaches the fiat partner: only a key with the admin role may approve (any other key gets 403 `kyc_review_required`), and only a `pending_review` receiver. It requests the fiat partner's hosted terms-of-service link for `redirect_url` (https, on this consumer's allow-list), moves the receiver to `pending_user` and returns the link with the receiver's email; nothing is emailed, the caller delivers it. Send `expected_version` (the `dossierVersion` you reviewed) so an edit made since is a 409 `kyc_state_invalid` instead of an approval of unreviewed data.

Requires the `kyc:write` scope.

**Path parameters**

- `id` (string, required)

**Request body** (`application/json`, required): `ApproveReceiverDto`

- `redirect_url` (string, required): Where the fiat partner redirects the customer after they accept the terms. Must be https and on the consumer allow-list.
- `expected_version` (number, optional): The receiver's `dossierVersion` as you read it. A 409 `kyc_state_invalid` if the KYC data changed since: re-read, review again, approve that version. Omitted approves whatever is stored now.

**Responses**

- `200` (`ReceiverApprovalEntity`): Receiver approved; terms link returned
  - `url` (string, required): The hosted terms-of-service link. This service emails nothing: deliver it to the customer.
  - `email` (string, required): The receiver's email address, to deliver the link to, or null when the receiver has none.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403` (`ApiErrorBodyEntity`): `kyc_review_required`: the API key is not elevated (admin role). A key may submit KYC data or approve it, not both.
- `404`: NotFound (see Shared responses)
- `409` (`ApiErrorBodyEntity`): `kyc_state_invalid`: the receiver is not in 'pending_review', or the KYC data changed after you read it (`expected_version` names a version that is no longer current). Re-read the receiver, review it again, and approve that version.
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Request a terms-of-service link for an approved receiver

`POST /v1/kyc/receivers/{id}/tos`

Only for a `pending_user` receiver (approved, terms not yet accepted); any other status is 400 `kyc_state_invalid`. Requests a fresh hosted link from the fiat partner for `redirect_url` (https, on this consumer's allow-list) and returns it with the receiver's email. `channel: email` sends nothing itself: it records the send, allowed once per 24 hours per receiver (400 `validation_failed` inside that window, 409 `kyc_state_invalid` when two race), and the caller emails the returned link; `channel: code` (the default) has no such limit.

Requires the `kyc:write` scope.

**Path parameters**

- `id` (string, required)

**Request body** (`application/json`, required): `RequestTosDto`

- `channel` (string, optional): 'code' returns the hosted ToS URL to display. 'email' records an email send, allowed once per 24 hours per receiver; it sends nothing itself, so you email the returned link. One of: `code`, `email`.
- `redirect_url` (string, required): Where the fiat partner redirects after acceptance (gets ?tos_id=...). Must be https and on the consumer allow-list.

**Responses**

- `201` (`ReceiverTosEntity`): Created
  - `url` (string, required): The hosted terms-of-service link. This service emails nothing: deliver it to the customer.
  - `email` (string, required): The receiver's email address, to deliver the link to, or null when the receiver has none.
  - `channel` (string, required): `code`: the link to show yourself. `email`: the send was recorded (once per 24 hours per receiver); you email the link. One of: `code`, `email`.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Enable an inactive receiver with an accepted terms-of-service id

`POST /v1/kyc/receivers/{id}/enable`

Creates the receiver at the fiat partner: replays the stored registration with the `tos_id` the customer got by accepting the terms, then replaces the local placeholder id with the fiat partner's and mirrors the fiat partner's KYC status. Only a `pending_user` receiver whose current `dossierVersion` is the approved one; otherwise, or when another enable is running, 409 `kyc_state_invalid`. A receiver already at the fiat partner is not created again: it is refreshed from the fiat partner and returned.

Requires the `kyc:write` scope.

**Path parameters**

- `id` (string, required)

**Request body** (`application/json`, required): `EnableReceiverDto`

- `tos_id` (string, required): Accepted terms-of-service id (the ?tos_id=... from the ToS redirect).

**Responses**

- `200` (`ReceiverEntity`): OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `409` (`ApiErrorBodyEntity`): `kyc_state_invalid`: an invalid KYC status transition (e.g. the receiver is not in 'pending_user').
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Enable or disable a fiat account (admin-only kill-switch for onramp/offramp)

`PATCH /v1/kyc/receivers/{id}/access`

Sets `disabled` on the receiver. While disabled, onramp, offramp and adding wallets, bank accounts or virtual accounts for it are refused with 403 `account_disabled`, whatever its KYC status. Only a key with the admin role may call it (any other key gets 403 `insufficient_scope`), so a tenant cannot lift a switch an operator set. Local only: nothing is sent to the fiat partner.

Requires the `kyc:write` scope.

**Path parameters**

- `id` (string, required)

**Request body** (`application/json`, required): `SetAccessDto`

- `disabled` (boolean, required): true = disable the fiat account, false = enable.

**Responses**

- `200` (`ReceiverEntity`): OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403` (`ApiErrorBodyEntity`): The API key is not elevated (admin role); a tenant key cannot lift a kill-switch an operator applied.
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Upload a KYC document; returns its file_url

`POST /v1/kyc/upload`

Multipart: one `file` part (JPEG, PNG, WebP, HEIC/HEIF or PDF, up to 10 MB, its bytes checked against the declared type) and an optional `bucket` (`onboarding` by default, `avatar` or `limit_increase`). the fiat partner stores the file on the instance of the key's network and nothing is kept here; pass the returned `file_url` in the receiver's `*_file` fields. the fiat partner keeps a stored file even when a later step fails, which is why the route is budgeted per address and per consumer.

Requires the `kyc:write` scope.

**Request body** (`multipart/form-data`, required): `object`

- `file` (string (binary), required)
- `bucket` (string, optional):  One of: `avatar`, `onboarding`, `limit_increase`.

**Responses**

- `201` (`KycUploadEntity`): Created
  - `file_url` (string, required): The provider's URL for the file. Pass it as a document field when creating or updating a receiver.
- `400` (`ApiErrorBodyEntity`): The multipart form was refused (`validation_failed`), before the provider saw anything: more than 4 text fields; a text field longer than 1024 bytes; more than 1 file; a declared content type other than image/jpeg, image/png, image/webp, image/heic, image/heif, application/pdf; file bytes that do not match the declared content type; a missing `file` part; or an unknown `bucket`.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `413` (`ApiErrorBodyEntity`): The file is larger than 10485760 bytes (`payload_too_large`). Multer stops reading at the limit, so nothing reaches the provider.
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Start ToS acceptance; returns the hosted URL (first KYC step)

`POST /v1/kyc/terms-of-service`

Asks the fiat partner for a hosted terms-of-service page and returns its URL; after acceptance the fiat partner redirects to `redirect_url` (https, on this consumer's allow-list) with a `tos_id` query parameter. With `receiver_id` (the fiat partner id of a receiver this consumer owns, otherwise 404) the terms are for that existing receiver. `idempotency_key` is forwarded to the fiat partner and generated when omitted; every call creates a record there, hence the budgets.

Requires the `kyc:write` scope.

**Request body** (`application/json`, required): `InitiateTosDto`

- `redirect_url` (string, required): Where the fiat partner redirects after acceptance (gets ?tos_id=...). Must be https and on the consumer allow-list.
- `receiver_id` (string, optional): Existing receiver to (re)accept updated terms for.
- `idempotency_key` (string, optional): UUID for idempotency. Auto-generated when omitted.

**Responses**

- `201` (`KycTermsOfServiceEntity`): Created
  - `url` (string, required): Open it in a browser; the customer returns to `redirect_url` with a `tos_id`.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Shared responses

- **ValidationFailed** (`ApiErrorBodyEntity`): The body, query or path failed validation. `message` is an array of the individual failures. Routes that reject a *valid* request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
- **Unauthorized** (`ApiErrorBodyEntity`): `no_authenticated_consumer`: The gateway forwarded no API key identity
- **Forbidden** (`ApiErrorBodyEntity`): `insufficient_scope`: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked `x-cosmos-public-key`, with a message saying so; more scopes will not help, the key is the wrong one. `gateway_required`: the request did not arrive through APISIX.
- **InternalError** (`ApiErrorBodyEntity`): Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
- **UpstreamError** (`ApiErrorBodyEntity`): The provider named in `x-cosmos-upstream` refused the request (`provider_error`) or could not be reached at all (`provider_unavailable`). Nothing was charged; retry is safe with the same `Idempotency-Key`.
- **UpstreamUnavailable** (`ApiErrorBodyEntity`): `provider_unavailable`: the provider in `x-cosmos-upstream` is down or unreachable; the message names it. Retry. `misconfigured`: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
- **UpstreamTimeout** (`ApiErrorBodyEntity`): The provider in `x-cosmos-upstream` did not answer in time. Whether it acted on the request is unknown. Retry with the same `Idempotency-Key`, never with a fresh one.
- **NotFound** (`ApiErrorBodyEntity`): No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
- **RateLimited** (`ApiErrorBodyEntity`): The budget in `x-cosmos-rate-limit` is spent for this caller. Honour `Retry-After`. The `ratelimit-*` triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers `503 provider_unavailable`.
