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

# Submit payment data.

> Upsert by `orderUuid` (one payment record per order).



## OpenAPI

````yaml /openapi-integration-v1.yaml post /partners/{sellerId}/orders/{uuid}/payment
openapi: 3.1.0
info:
  title: Novatrade24 Integration API
  version: 1.0.0-draft
  summary: Customer-facing integration API for the Novatrade24 compliance platform.
  description: >
    The Novatrade24 Integration API lets marketplaces, dealers, and financial

    partners embed EU VAT-compliant cross-border vehicle transactions into

    their own systems.


    The API is organized around the end-to-end compliance workflow:


    1. **Buyer (KYC)** — create or sync a buyer, run VIES, upload KYC documents,
       optionally trigger NT24-led verification.
    2. **Order** — register a VIN-based transaction linked to a buyer.

    3. **Invoice** — submit preliminary and final invoice data and documents.

    4. **Payment** — submit proof-of-payment and trigger pickup readiness.

    5. **Transport** — confirm pickup and delivery with CMR / declarations.

    6. **Compliance rollup** — poll workflow status or subscribe to webhooks.

    7. **Finalization** — download the generated Export File.


    **Status:** Draft — no production endpoint yet. Specification published for

    integration planning. Hosted mock available at
    `https://mock.api.novatrade24.com`.
  termsOfService: https://novatrade24.com/terms
  contact:
    name: Novatrade24 Integration Support
    email: integration-support@novatrade24.com
    url: https://developers.novatrade24.com
  license:
    name: Proprietary
    url: https://novatrade24.com/terms
servers:
  - url: https://api.novatrade24.com/v1
    description: Production (Phase 1 pilot — restricted access)
  - url: https://api.stage.novatrade24.com/v1
    description: Staging environment
  - url: https://mock.api.novatrade24.com
    description: Hosted mock server (Prism) — spec-driven stub responses
security:
  - oauth2ClientCredentials: []
tags:
  - name: Discovery
    description: Organization + capability discovery.
  - name: Buyers
    description: |
      Manage buyer (trade partner) records and KYC lifecycle.
      Buyers are upserted by `(sellerId, vatNumber)`.
  - name: KYC
    description: KYC documents, VIES checks, Mode B verification, profile.
  - name: Self-service invitations
    description: |
      Orchestrate buyer-facing self-service links for KYC submission
      and prospect onboarding.
  - name: Orders
    description: |
      Register vehicle transactions. Orders may contain one or more VINs;
      Phase 1 Santander pilot uses single-VIN orders.
  - name: Invoice
    description: Buyer's VAT-compliance invoice (preliminary or final).
  - name: Payment
    description: Proof-of-payment data and documents; pickup readiness trigger.
  - name: Transport
    description: Pickup + delivery milestones and documents (CMR, declarations).
  - name: Compliance
    description: End-to-end compliance rollup per order.
  - name: Finalization
    description: Final invoice submission and Export File download.
  - name: Prospects
    description: Public prospect submission flow.
  - name: Documents
    description: Typed document download.
  - name: Webhooks
    description: Webhook endpoint registration, delivery history, test-fire.
paths:
  /partners/{sellerId}/orders/{uuid}/payment:
    parameters:
      - $ref: '#/components/parameters/SellerIdPath'
      - $ref: '#/components/parameters/OrderUuidPath'
    post:
      tags:
        - Payment
      summary: Submit payment data.
      description: Upsert by `orderUuid` (one payment record per order).
      operationId: upsertPayment
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '201':
          description: Payment stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        4XX:
          $ref: '#/components/responses/Problem'
        5XX:
          $ref: '#/components/responses/Problem'
components:
  parameters:
    SellerIdPath:
      name: sellerId
      in: path
      required: true
      description: UUID of the seller trade partner (must be in caller's authorized list).
      schema:
        type: string
        format: uuid
    OrderUuidPath:
      name: uuid
      in: path
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        Client-generated unique key (UUID recommended) for this write operation.
        Identical key + identical body within 24h returns the cached response.
        Identical key + different body returns `422`.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    PaymentRequest:
      type: object
      required:
        - paymentDate
        - bankAmount
        - cashAmount
      properties:
        paymentDate:
          type: string
          format: date
        bankAmount:
          $ref: '#/components/schemas/Money'
        cashAmount:
          $ref: '#/components/schemas/Money'
        sourceIban:
          type: string
          example: DE89370400440532013000
    PaymentResponse:
      allOf:
        - $ref: '#/components/schemas/PaymentRequest'
        - type: object
          properties:
            status:
              $ref: '#/components/schemas/PaymentStatus'
            amountMatchesInvoice:
              type: boolean
            ibanConsistent:
              type: boolean
            readyForPickup:
              type: boolean
            version:
              type: integer
            updatedAt:
              type: string
              format: date-time
    Money:
      type: object
      required:
        - value
        - currency
      properties:
        value:
          type: integer
          format: int64
          description: Amount in minor units (e.g. 7900 = €79.00).
          example: 7900
        currency:
          type: string
          description: ISO 4217 currency code.
          example: EUR
    PaymentStatus:
      type: string
      enum:
        - DRAFT
        - SUBMITTED
        - VALID
        - INVALID
    Problem:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        traceId:
          type: string
  responses:
    Problem:
      description: |
        RFC 7807 problem detail. Default fallback for any status not explicitly
        enumerated on the operation. Concrete status is in `status` field.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: |
        OAuth 2.0 client_credentials grant via Keycloak service account.
        Clients are provisioned per `IntegrationOrganization` in the
        `nt24-idp` realm.
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token
          scopes: {}

````