> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit partner KYC fields (legacy)

> Legacy: submit an External QR Payment's missing KYC fields from your backend.

<Warning>
  Deprecated. New integrations must open the `complete_compliance` URL returned by the Payment and let the Stableyard-hosted page collect the fields.
</Warning>

This legacy server-rendered integration submits the KYC fields an External QR Payment is missing. The `collectionSessionId` comes from the Payment's next action, and the `fields` keys must exactly match the keys returned in `nextAction.fields`. It remains temporarily available for existing backend integrations.


## OpenAPI

````yaml openapi.json POST /v2/partner-kyc/collection-sessions/{collectionSessionId}/fields
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0-staging
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: Backend API for UPAs, Payments, activity, and optional financial products.
  description: >

    Use this API from a trusted partner backend with an app ID and app secret.


    ## Recommended integration


    1. Call `GET /v2/partners/config` to verify credentials and discover enabled
    capabilities.

    2. Create a UPA only when your product needs a persistent Stableyard
    account.

    3. Create a receive or send Payment with `POST /v2/payments`.

    4. Redirect a payer to the returned `paymentUrl` or pass the Payment
    credentials to an official Stableyard interface SDK.

    5. Process signed webhooks and fetch the Payment by ID for reconciliation.


    Checkout execution and account-bound browser endpoints are intentionally
    documented in the separate Interfaces & SDKs reference. Console endpoints
    are dashboard implementation details and are not part of the partner
    integration contract.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Staging
  - url: http://localhost:3001
    description: Local
security: []
tags:
  - name: Authentication
    x-displayName: API authentication
    description: Verify your app ID and app secret before calling UPA APIs.
  - name: Accounts
    x-displayName: UPA Accounts
    description: Create Universal Payment Accounts and manage account settings.
  - name: Deposit Addresses
    description: Create reusable receive addresses and verify inbound deposits.
  - name: Identity & KYC
    description: >-
      Verify the UPA email and run provider-neutral identity verification.
      Managed vaults and fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create Safe/Zodiac controlled stablecoin vaults and manage policy updates
      for accounts.
  - name: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
  - name: Balances & Transactions
    description: >-
      Read Stableyard-posted financial activity. Balances are ledger projections
      of activity Stableyard processed; they are not live balances of externally
      controlled wallets.
paths:
  /v2/partner-kyc/collection-sessions/{collectionSessionId}/fields:
    post:
      tags:
        - Identity & KYC
      summary: Submit partner KYC fields (legacy)
      description: >-
        Legacy server-rendered integration for submitting an External QR
        Payment's missing KYC fields. New integrations must open the
        `complete_compliance` URL returned by the Payment and let the
        Stableyard-hosted page collect the fields. This endpoint remains
        temporarily available for existing backend integrations.
      operationId: submitPartnerKycCollectionFields
      parameters:
        - name: collectionSessionId
          in: path
          required: true
          schema:
            type: string
            pattern: ^info_req_[A-Za-z0-9_-]+$
            example: info_req_123
          description: >-
            Partner KYC collection session returned by an External QR Payment
            next action.
        - name: Stableyard-Version
          in: header
          required: false
          schema:
            type: string
            enum:
              - '2026-09-09'
          description: >-
            Optional contract-version assertion. Omit it to use the app
            environment's pinned version. A different supported version is
            accepted only after that environment is explicitly migrated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerKycSubmitFieldsRequest'
            examples:
              addressState:
                summary: Submit an address field requested by a fiat provider
                value:
                  fields:
                    address.state: Maharashtra
      responses:
        '200':
          description: Partner KYC state
          headers:
            Stableyard-Version:
              description: >-
                Effective date-based Stableyard API contract version for this
                response.
              schema:
                type: string
                enum:
                  - '2026-09-09'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerKycState'
              examples:
                example:
                  summary: Submit partner KYC fields (legacy) 200 response
                  value:
                    status: requires_kyc
                    accountId: acct_123
                    partnerId: external_payout
                    requirementProfileVersion: external_payout@2026-09-02
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      deprecated: true
      security:
        - partnerBasicAuth: []
components:
  schemas:
    PartnerKycSubmitFieldsRequest:
      type: object
      additionalProperties: false
      required:
        - fields
      properties:
        fields:
          type: object
          minProperties: 1
          maxProperties: 32
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 4096
          description: >-
            Field keys must exactly match the keys returned in
            `nextAction.fields`.
    PartnerKycState:
      type: object
      additionalProperties: false
      required:
        - status
        - accountId
        - partnerId
        - requirementProfileVersion
      properties:
        status:
          type: string
          enum:
            - requires_kyc
            - requires_information
            - ready_to_submit
        accountId:
          type: string
          pattern: ^acct_[A-Za-z0-9_-]+$
          example: acct_123
        partnerId:
          type: string
          const: external_payout
          description: Provider-neutral readiness profile identifier.
        requirementProfileVersion:
          type: string
          example: external_payout@2026-09-02
        kycVerification:
          $ref: '#/components/schemas/PartnerKycVerificationSummary'
        partnerSubmission:
          $ref: '#/components/schemas/PartnerKycSubmission'
        collectionSession:
          $ref: '#/components/schemas/PartnerKycCollectionSession'
        missingFields:
          type: array
          items:
            $ref: '#/components/schemas/PartnerKycMissingField'
        requestPayloadHash:
          type: string
        payloadPreview:
          type: object
          additionalProperties: true
        nextAction:
          $ref: '#/components/schemas/CanonicalPaymentNextAction'
    PartnerKycVerificationSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - provider
        - providerSessionId
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: kyc_123
        provider:
          type: string
          enum:
            - didit
          example: didit
        providerSessionId:
          type:
            - string
            - 'null'
          example: didit_session_123
        status:
          type: string
          enum:
            - not_started
            - pending
            - in_progress
            - approved
            - rejected
            - expired
            - requires_review
        completedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PartnerKycSubmission:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - partnerId
        - requirementProfileVersion
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^partner_kyc_[A-Za-z0-9_-]+$
          example: partner_kyc_123
        accountId:
          type: string
          pattern: ^acct_[A-Za-z0-9_-]+$
          example: acct_123
        partnerId:
          type: string
          const: external_payout
          description: Provider-neutral readiness profile identifier.
        kycVerificationId:
          type: string
          example: kyc_123
        collectionSessionId:
          type: string
          example: info_req_123
        requirementProfileVersion:
          type: string
          example: external_payout@2026-09-02
        status:
          type: string
          enum:
            - not_started
            - requires_kyc
            - requires_information
            - ready_to_submit
            - submitted
            - approved
            - rejected
            - requires_more_information
            - failed
            - cancelled
        providerReferenceId:
          type: string
        requestPayloadHash:
          type: string
        submittedAt:
          type: string
          format: date-time
        lastResponseAt:
          type: string
          format: date-time
        failureCode:
          type: string
        failureMessage:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PartnerKycCollectionSession:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - partnerId
        - requirementProfileVersion
        - status
        - missingFields
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^info_req_[A-Za-z0-9_-]+$
          example: info_req_123
        accountId:
          type: string
          pattern: ^acct_[A-Za-z0-9_-]+$
          example: acct_123
        partnerId:
          type: string
          const: external_payout
          description: Provider-neutral readiness profile identifier.
        requirementProfileVersion:
          type: string
          example: external_payout@2026-09-02
        status:
          type: string
          enum:
            - pending_user_input
            - partially_completed
            - completed
            - expired
            - cancelled
        missingFields:
          type: array
          items:
            $ref: '#/components/schemas/PartnerKycMissingField'
        expiresAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PartnerKycMissingField:
      type: object
      additionalProperties: false
      required:
        - key
        - partnerField
        - label
        - type
        - required
        - sources
      properties:
        key:
          type: string
          maxLength: 64
          example: occupation
        partnerField:
          type: string
          maxLength: 64
          example: occupation
        label:
          type: string
          maxLength: 160
          example: Occupation
        type:
          type: string
          enum:
            - string
            - date
            - email
            - phone
            - select
            - image
            - country
            - wallet
        required:
          type: boolean
        sources:
          type: array
          items:
            type: string
            enum:
              - didit
              - account
              - userInput
              - derived
        optionsProfile:
          type: string
          maxLength: 64
        sensitive:
          type: boolean
        reason:
          type: string
          maxLength: 500
    CanonicalPaymentNextAction:
      title: Payment next action
      description: >-
        The exact action the caller must complete. Null means Stableyard needs
        no action from the partner right now.
      oneOf:
        - title: Action required
          type: object
          additionalProperties: false
          required:
            - id
            - type
            - expiresAt
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - transaction
                - managed_authorization
                - payment_method
            expiresAt:
              type:
                - string
                - 'null'
              format: date-time
            depositInstructions:
              $ref: '#/components/schemas/CanonicalPaymentDepositInstructions'
              description: >-
                Present only when type is "transaction" for a collection
                deposit: the exact on-chain payment to make to advance this
                Payment.
        - title: Start account KYC
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: start_kyc_session
        - title: Verify UPA email
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: verify_account_email
        - title: Complete hosted compliance
          description: >-
            Open this Stableyard-hosted URL as a top-level page. The link uses a
            one-time exchange and asks only for information missing from the
            verified account.
          type: object
          additionalProperties: false
          required:
            - type
            - url
            - expiresAt
          properties:
            type:
              type: string
              const: complete_compliance
            url:
              type: string
              format: uri
            expiresAt:
              type: string
              format: date-time
        - title: Wait for partner KYC
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: wait_for_partner_kyc
        - title: Contact support
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: contact_support
        - title: No provider action
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: none
        - title: No action required
          type: 'null'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              minLength: 1
              maxLength: 128
              example: bad_request
            message:
              type: string
              minLength: 1
              maxLength: 1000
              example: The request is invalid
            details: {}
    CanonicalPaymentDepositInstructions:
      type: object
      additionalProperties: false
      required:
        - address
        - chainId
        - tokenAddress
        - assetCode
        - decimals
        - amount
        - amountAtomic
      description: >-
        The exact on-chain deposit to make. Send precisely amountAtomic of
        tokenAddress on chainId to address; anything else will not be recognized
        as this Payment's funding.
      properties:
        address:
          type: string
        chainId:
          type: integer
          minimum: 1
        tokenAddress:
          type: string
        assetCode:
          type: string
        decimals:
          type: integer
          minimum: 0
          maximum: 36
        amount:
          type: string
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
  responses:
    BadRequest:
      description: Bad request
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: BadRequest response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Unauthorized:
      description: Unauthorized
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Unauthorized response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Forbidden:
      description: The app secret does not include the required scope
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Forbidden response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    NotFound:
      description: Not found
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: NotFound response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    Conflict:
      description: Conflict
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Conflict response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    FailedDependency:
      description: Required chain, network, or provider configuration is missing
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: FailedDependency response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    TooManyRequests:
      description: >-
        Rate limit, payment-option limit, selection cooldown, or temporary abuse
        block
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
        Retry-After:
          description: Seconds until the caller should retry.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          description: Quota for the most constrained policy.
          schema:
            type: integer
            minimum: 1
        RateLimit-Remaining:
          description: Requests remaining in that policy window.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: Seconds until that policy window resets.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: TooManyRequests response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
  securitySchemes:
    partnerBasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth. Username is the Stableyard app ID. Password is the app
        secret. The optional Stableyard-Version request header must match the
        environment pin.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.