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

# Push payees

> Persist a batch of payees under a submission.

<Note>
  Each payee carries your own `clientPayeeId`, echoed back in the result. It is the only key you use to attach payments and to update or delete the payee later, and it must be unique within the submission. Send the optional `Idempotency-Key` header to make a retried batch safe.
</Note>


## OpenAPI

````yaml post /reports/cesop/v1/submissions/{submissionId}/payees
openapi: 3.1.0
info:
  title: CESOP REST API
  description: >
    <p>REST API for reporting CESOP(The Central Electronic System of Payment
    information). Create a submission, send payees

    and payments under its id, then submit it to the regulatory authority.</p>


    <p><strong>Filtering is the reporting company's responsibility.</strong>
    This API reports the data you send as-is, and it does not decide which
    payments are reportable. Apply the CESOP filtering rules before sending.</p>


    <p><strong>European Commission's official reporting guideline:</strong>

    <a href="docs/cesop-guidelines-v1.2.pdf">CESOP Guidelines for the reporting
    of payment data v1.2 (PDF)</a></p>


    <p><strong>CESOP filtering rules, PSP's implementation guide:</strong>

    <a href="docs/cesop-filtering-rules.html">open the guide</a>. This is a
    quick reference only, it may not cover every case. For accurate handling of
    specific cases, refer to the regulation and official CESOP
    documentation.</p>


    <p><strong>Regulation:</strong>

    <a href="https://eur-lex.europa.eu/eli/dir/2020/284/oj">Council Directive
    (EU) 2020/284</a>

    &middot;

    <a
    href="https://taxation-customs.ec.europa.eu/taxation-1/central-electronic-system-payment-information-cesop_en">CESOP
    — European Commission</a></p>
  version: 0.0.1
servers:
  - url: https://api.rrc.dev.finventi.com
    description: Development
  - url: https://api.rrc.finventi.com
    description: Production
security:
  - bearer-jwt: []
tags:
  - name: CESOP Filtering Support
    description: >-
      Helper endpoints supporting CESOP filtering decisions. This is not part of
      the submission flow.Use them to prepare your data before sending it via
      the CESOP Submission API.
  - name: CESOP REST API
    description: >-
      REST API for submitting and correcting CESOP payee and payment data.
      Create a submission, push payees and payments under its id, then submit it
      to the regulatory authority.
paths:
  /reports/cesop/v1/submissions/{submissionId}/payees:
    post:
      tags:
        - CESOP REST API
      summary: Push payees
      description: >-
        Persists a batch of payees under the submission and echoes back each
        payee's clientPayeeId, which you use to attach payments and to update or
        delete the payee later. Available for both submission and correction
        submissions.
      operationId: postPayees
      parameters:
        - name: Idempotency-Key
          in: header
          description: Client-provided idempotency key.
          schema:
            type: string
            maxLength: 255
        - name: submissionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CesopPayee'
        required: true
      responses:
        '201':
          description: All payees created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeResult'
        '207':
          description: Partial success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeResult'
        '400':
          description: All failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeResult'
components:
  schemas:
    CesopPayee:
      type: object
      description: A payee to report.
      properties:
        clientPayeeId:
          type: string
          description: >-
            Your own id for this payee. Required and echoed back in the result
            to correlate it.
          maxLength: 100
          minLength: 0
        names:
          type: array
          items:
            $ref: '#/components/schemas/CesopName'
          maxItems: 2147483647
          minItems: 1
        countryCode:
          type: string
          example: DE
          minLength: 1
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/CesopAddress'
        emails:
          type: array
          items:
            type: string
        webPages:
          type: array
          items:
            type: string
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/CesopTaxId'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/CesopAccount'
        representative:
          $ref: '#/components/schemas/CesopRepresentative'
      required:
        - accounts
        - addresses
        - clientPayeeId
        - countryCode
        - emails
        - names
        - taxes
        - webPages
    PayeeResult:
      type: object
      description: Result of creating/updating a single payee
      properties:
        status:
          $ref: '#/components/schemas/Status'
        clientPayeeId:
          type: string
          description: >-
            Your clientPayeeId echoed back, to correlate this result with your
            record
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
      required:
        - errors
        - status
    CesopName:
      type: object
      description: Payee name
      properties:
        value:
          type: string
          maxLength: 200
          minLength: 0
        type:
          type: string
          enum:
            - PERSON
            - TRADE
            - LEGAL
            - BUSINESS
            - OTHER
        specification:
          type: string
          description: Specification when type = OTHER
          maxLength: 200
          minLength: 0
      required:
        - type
        - value
    CesopAddress:
      type: object
      description: Payee address, as free text.
      properties:
        countryCode:
          type: string
          example: DE
        addressFree:
          type: string
          maxLength: 1000
          minLength: 0
        type:
          type: string
          enum:
            - RESIDENTIAL_OR_BUSINESS
            - RESIDENTIAL
            - BUSINESS
            - REGISTERED_OFFICE
            - OTHER
    CesopTaxId:
      type: object
      description: Tax identifier
      properties:
        number:
          type: string
          maxLength: 20
          minLength: 0
        issuedBy:
          type: string
          description: Issuing country
          example: DE
          minLength: 1
        type:
          type: string
          enum:
            - VAT
            - UNCONFIRMED_VAT
            - TIN
            - IOSS
            - VOES
            - OTHER
        specification:
          type: string
          description: Specification when type = OTHER
          maxLength: 200
          minLength: 0
      required:
        - issuedBy
        - number
        - type
    CesopAccount:
      type: object
      description: Payee account
      properties:
        number:
          type: string
          example: DE89370400440532013000
          maxLength: 200
          minLength: 0
        type:
          type: string
          enum:
            - IBAN
            - OBAN
            - BIC
            - OTHER
        countryCode:
          type: string
          example: DE
          minLength: 1
        specification:
          type: string
          description: Specification when type = OTHER
          maxLength: 200
          minLength: 0
      required:
        - countryCode
        - number
        - type
    CesopRepresentative:
      type: object
      description: Payee representative (optional)
      properties:
        representativeId:
          type: string
          description: Representative PSP id (e.g. a BIC)
          maxLength: 200
          minLength: 0
        type:
          type: string
          enum:
            - BIC
            - OTHER
        specification:
          type: string
          description: Specification when type = OTHER
          maxLength: 200
          minLength: 0
        names:
          type: array
          items:
            $ref: '#/components/schemas/CesopName'
      required:
        - names
        - representativeId
        - type
    Status:
      type: string
      enum:
        - SUCCESS
        - FAILED
    FieldError:
      type: object
      description: Per-item validation/processing error
      properties:
        code:
          type: string
          description: >-
            Validation error code returned by the regulatory authority; only
            present for records that failed authority validation
          example: 51
        fields:
          type: array
          description: >-
            Fields that caused the error; may be empty for errors not tied to a
            single field (e.g. cross-field validation)
          example:
            - iban
          items:
            type: string
        message:
          type: string
          description: Human-readable error message
      required:
        - fields
  securitySchemes:
    bearer-jwt:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth.sandbox.finventi.com/realms/sti-connector/protocol/openid-connect/token
          scopes: {}

````