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

# Créer un remboursement

> Enregistre un remboursement sur une opération.

**Scope requis :** `operations:write`. [Scopes et délégation](/scopes-and-delegation).

**Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre la même mutation, réutiliser la même clé et le même contenu. [Écritures et idempotence](/writes-and-idempotency).



## OpenAPI

````yaml /openapi.json post /operations/{operation_id}/repayments
openapi: 3.1.0
info:
  title: MARKO External Partner API
  version: v1
  description: >-
    Stable external API contract for the live environment.


    Authentication flow for partner integrations:

    1. Generate an API key from the MARKO entity admin API section.

    2. Keep the raw API secret server-side and use it only to sign `POST
    /v1/auth/token`.

    3. Build the canonical message
    `MARKO-EXTERNAL-API-TOKEN-V1\n{key_id}\n{timestamp}\n{nonce}`.

    4. Sign that message with HMAC-SHA256 and send the hex signature with
    `key_id`, `timestamp` and `nonce`.

    5. Use the returned short-lived bearer on business endpoints as
    `Authorization: Bearer <access_token>`.

    The raw API secret must never be sent on business endpoints.


    This public contract intentionally excludes beta endpoints.


    Référence enrichie pour les développeurs et les assistants IA. Exemples
    synthétiques; les champs sont extraits des modèles et sérialiseurs de la
    version indiquée dans x-documentation-provenance.
servers:
  - url: https://partner-api.marko.fr/v1
security:
  - BearerAuth: []
tags:
  - name: auth
    x-group: Authentification
  - name: entity
    x-group: Entité
  - name: portfolio
    x-group: Portefeuille
  - name: deals
    x-group: Deals
  - name: fonds
    x-group: Fonds
  - name: spvs
    x-group: SPV
  - name: operations
    x-group: Opérations
  - name: taxonomies
    x-group: Taxonomies
  - name: import-jobs
    x-group: Imports par lot
  - name: comments
    x-group: Commentaires
  - name: documents
    x-group: Documents
  - name: users
    x-group: Utilisateurs
  - name: settings
    x-group: Paramètres
  - name: rcci
    x-group: Conformité RCCI
  - name: field-definitions
    x-group: Champs métier
  - name: search
    x-group: Recherche
  - name: operateurs
    x-group: Opérateurs
  - name: alerts
    x-group: Alertes
  - name: notifications
    x-group: Notifications
  - name: calendar
    x-group: Calendrier
  - name: enrichment
    x-group: Enrichissement SIREN
  - name: reports
    x-group: Exports
  - name: reporting
    x-group: Templates de reporting
  - name: workflows
    x-group: Workflows et extraction IA
  - name: tasks
    x-group: Tâches
externalDocs:
  description: Download the matching Postman collection.
  url: /v1/postman.json
paths:
  /operations/{operation_id}/repayments:
    post:
      tags:
        - operations
      summary: Créer un remboursement
      description: >-
        Enregistre un remboursement sur une opération.


        **Scope requis :** `operations:write`. [Scopes et
        délégation](/scopes-and-delegation).


        **Idempotence :** header `Idempotency-Key` obligatoire. Pour reprendre
        la même mutation, réutiliser la même clé et le même contenu. [Écritures
        et idempotence](/writes-and-idempotency).
      operationId: operations_repayments_create
      parameters:
        - in: path
          name: operation_id
          required: true
          schema:
            type: string
            format: uuid
            title: Operation Id
          example: 44444444-4444-4444-4444-444444444444
          description: UUID MARKO de l'opération.
        - in: header
          name: X-Request-ID
          required: false
          description: >-
            Partner-generated correlation identifier echoed in logs and error
            payloads.
          schema:
            type: string
          example: marko-operations-repayments-create
        - in: header
          name: Idempotency-Key
          required: true
          description: >-
            Required for every write, including environments where replay
            deduplication is disabled. Reuse the same value when retrying the
            same logical write and use a new value for a different write.
          schema:
            type: string
            maxLength: 255
            pattern: ^[!-~]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepaymentHistoryCreate'
            example:
              date: '2026-03-31'
              principal: '50000.00'
              interest: '4200.00'
              total: '54200.00'
              remaining_balance: '950000.00'
              source: manual
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepaymentHistoryResponse'
              example:
                id: 99999999-9999-9999-9999-999999999999
                operation_id: 44444444-4444-4444-4444-444444444444
                date: '2026-03-31'
                principal: '50000.00'
                interest: '4200.00'
                total: '54200.00'
                remaining_balance: '950000.00'
                source: manual
                created_at: '2026-10-01T10:00:00Z'
                updated_at: '2026-10-01T10:00:00Z'
        '400':
          description: Invalid Idempotency-Key header
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Bad Request
                status: 400
                detail: >-
                  Idempotency-Key must contain at most 255 visible ASCII
                  characters without spaces.
                request_id: req_example_partner_call
        '401':
          description: Authentication required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: A valid bearer token is required.
                request_id: req_example_partner_call
        '403':
          description: Scope, route or IP restriction
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: The API key does not allow this operation.
                request_id: req_example_partner_call
        '409':
          description: Idempotency or write target conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: >-
                  The idempotency key payload, external reference, target, or
                  source conflicts with an existing write.
                request_id: req_example_partner_call
        '422':
          description: Validation failed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unprocessable Content
                status: 422
                detail: The request payload or parameters are invalid.
                request_id: req_example_partner_call
        '428':
          description: Required Idempotency-Key header is missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Precondition Required
                status: 428
                detail: The Idempotency-Key header is required.
                request_id: req_example_partner_call
        '429':
          description: Rate limit or progressive ban
          headers:
            Retry-After:
              description: Cooldown in seconds before retrying the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: The request rate limit was exceeded.
                request_id: req_example_partner_call
        '500':
          description: Unexpected server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: An unexpected server error occurred.
                request_id: req_example_partner_call
      deprecated: false
      security:
        - BearerAuth: []
components:
  schemas:
    RepaymentHistoryCreate:
      properties:
        tranche_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Tranche Id
          description: UUID de la tranche de financement associée au remboursement.
        date:
          type: string
          format: date
          title: Date
          description: >-
            Date métier; le type et le format ci-dessous font autorité pour
            cette route.
        principal:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: >-
                ^(?!^[-+.]*$)[+-]?0*(?:\d{0,18}|(?=[\d.]{1,21}0*$)\d{0,18}\.\d{0,2}0*$)
          title: Principal
          description: Part de capital du remboursement enregistré.
        interest:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: >-
                ^(?!^[-+.]*$)[+-]?0*(?:\d{0,18}|(?=[\d.]{1,21}0*$)\d{0,18}\.\d{0,2}0*$)
          title: Interest
          description: Part d'intérêts du remboursement enregistré.
        total:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: >-
                ^(?!^[-+.]*$)[+-]?0*(?:\d{0,18}|(?=[\d.]{1,21}0*$)\d{0,18}\.\d{0,2}0*$)
          title: Total
          description: >-
            Montant total du remboursement. Doit être exactement égal à
            principal + interest.
        remaining_balance:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: >-
                ^(?!^[-+.]*$)[+-]?0*(?:\d{0,18}|(?=[\d.]{1,21}0*$)\d{0,18}\.\d{0,2}0*$)
          title: Remaining Balance
          description: Capital restant après ce remboursement.
        source:
          type: string
          title: Source
          default: manual
          description: 'Origine du remboursement: manual, extraction ou open_banking.'
      type: object
      required:
        - date
        - principal
        - interest
        - total
        - remaining_balance
      title: RepaymentHistoryCreate
    RepaymentHistoryResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Identifiant MARKO de la ressource.
        operation_id:
          type: string
          format: uuid
          title: Operation Id
          description: UUID MARKO de l'opération.
        tranche_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Tranche Id
          description: UUID de la tranche de financement associée au remboursement.
        date:
          type: string
          format: date
          title: Date
          description: >-
            Date métier; le type et le format ci-dessous font autorité pour
            cette route.
        principal:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Principal
          description: Part de capital du remboursement enregistré.
        interest:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Interest
          description: Part d'intérêts du remboursement enregistré.
        total:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Total
          description: >-
            Montant total du remboursement enregistré, comprenant le capital et
            les intérêts.
        remaining_balance:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Remaining Balance
          description: Capital restant après ce remboursement.
        source:
          type: string
          title: Source
          description: 'Origine du remboursement: manual, extraction ou open_banking.'
        schedule_projection_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Schedule Projection Id
          description: >-
            Identifiant de la projection d'échéancier à laquelle le
            remboursement est rapproché.
        assignment_status:
          type: string
          title: Assignment Status
          default: needs_attachment
          description: État du rapprochement du remboursement avec l'échéancier.
        assignment_label:
          type: string
          title: Assignment Label
          default: À rattacher
          description: Libellé du rapprochement du remboursement avec l'échéancier.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Date de création au format ISO 8601.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Date de dernière modification au format ISO 8601.
      type: object
      required:
        - id
        - operation_id
        - date
        - principal
        - interest
        - total
        - remaining_balance
        - source
        - created_at
        - updated_at
      title: RepaymentHistoryResponse
    ProblemDetails:
      type: object
      required:
        - title
        - status
        - detail
      properties:
        type:
          type: string
          default: about:blank
          description: >-
            URI identifiant le type de problème; about:blank lorsque seul le
            statut HTTP le caractérise.
        title:
          type: string
          description: Titre affiché pour l'événement ou le problème.
        status:
          type: integer
          description: Statut HTTP de la réponse d'erreur.
        detail:
          type: string
          description: Informations détaillées sur le problème ou le dossier.
        request_id:
          type: string
          description: Identifiant de corrélation pour le diagnostic de la requête.
        scope:
          type: string
          description: Scope concerné par le refus d'accès, lorsqu'il est renseigné.
        route_id:
          type: string
          description: Identifiant de la route concernée par le problème.
        reason_code:
          type: string
          description: >-
            Code structuré du motif de refus; préférable au texte du message
            pour le diagnostic.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: MARKO short-lived bearer
      description: >-
        Use the `access_token` returned by `POST /v1/auth/token`. Do not send
        the raw API secret on business endpoints.

````

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