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

# Report a settled deposit, a Tradevu repayment, or a confirmed or failed instruction

> The body is the webhook envelope `{event_id, type, created_at, data}`. `type` is
`deposit.settled`, `tradevu.repayment`, `hold.placed`, `payout.confirmed`, `hold.released`,
`refund.paid` or `instruction.failed`; any other type is a 400 with details
`[{"field": "type"}]`. Every 202 carries the loan's current view, the same as
`GET /v1/loans/{loan_id}`. Use the `event_id` as the Idempotency-Key. Repeating an `event_id`, or
a `repayment_id` already posted, answers 202 and posts nothing new. Every object rejects
unknown fields. A 400 names each failing field as `{"field": "data.principal_cents"}`. A `data`
block that does not parse (a missing, unknown or mistyped field) is a 400 with the message
`invalid event` and no details.
A `repayment_id` already posted for a different loan is a 400 with details
`[{"field": "data.repayment_id"}]`.
A `deposit.settled` posts one ledger journal and sends the next deduction instruction. It is
accepted while the loan is current, overdue, delinquent, default, restructured or repaid (a
deposit on a repaid loan is all overpayment, and a refund is queued); any other status is
409 INVALID_STATE. An `instruction_version` above the loan's current version, or a
`ledger_operation_id` already posted for a different loan, is a 400 with details
`[{"field": "data.instruction_version"}]` or `[{"field": "data.ledger_operation_id"}]`.
`payer_name` and `beneficiary_name` are used only to classify the deposit and are not stored.
Final answers are 400 VALIDATION_FAILED, 404, 409 INVALID_STATE, 409 IDEMPOTENCY_KEY_REUSED,
413 PAYLOAD_TOO_LARGE and 422 REPAYMENT_EXCEEDS_LINE: a repeat with the same Idempotency-Key
replays the stored response, so send a corrected event under a new `event_id`. Retry a 5xx,
409 REQUEST_IN_PROGRESS and 429 with the same Idempotency-Key and body. Retry a 401 after
refreshing the token. A 400 IDEMPOTENCY_KEY_REQUIRED or IDEMPOTENCY_KEY_INVALID is not stored:
fix the header and send again.
A `tradevu.repayment` is refused with 409 INVALID_STATE only while the loan is
pending_disbursement or cancelled, and with 422 REPAYMENT_EXCEEDS_LINE when it is above the
loan's outstanding Tradevu line.
`hold.placed`, `payout.confirmed`, `hold.released` and `refund.paid` confirm a
`place_hold`, `pay_out`, `release_hold` or `refund` instruction; `instruction.failed`
reports that any of them could not be done. An unknown `instruction_id`, or another partner's,
is a 404. Field errors are checked next, before the instruction's state, in this order, each a
400 naming its field: `instruction_id` must name an instruction of this loan whose kind matches
the type (`data.instruction_id`), `amount_cents` must equal the instruction's amount,
`reference` is 1 to 128 characters, `done_at` / `failed_at` is no more than 5 minutes ahead of
our clock, and `reason` is one of `insufficient_balance`, `account_blocked`, `other`. Then
the state: resending an identical confirmation (same `reference` and `amount_cents`) or an
identical failure (same `reason`) answers 202 and changes nothing, under any `event_id`; any
other event on an instruction already confirmed or failed is 409 INVALID_STATE. There is no
deadline: a confirmation or failure sent hours later still applies. A `place_hold` is issued
once the bureau check passes. `release_hold` and `refund` are issued within seconds after the
event that causes them, so they are not in that event's answer. A failed `pay_out` is replaced
by a new `pay_out` instruction, up to 3 in all; after the third failure the loan is cancelled
and a `release_hold` is issued. A failed `release_hold` or `refund` is not issued again.




## OpenAPI

````yaml /api-reference/lending-openapi.yaml post /v1/events
openapi: 3.1.0
info:
  title: Cr3dentials Lending API
  version: 1.0.0
  description: >
    The partner API for Cr3dentials lending: applications, money steps,
    repayments and credit profiles. Money is integer USD cents.

    Every POST takes an Idempotency-Key header. Repeating a request with the
    same key and body

    replays the first response. Reusing a key with a different request is a 409.


    Webhooks (see `webhooks`): Cr3dentials POSTs outcomes that happen after a
    response to the partner's

    webhook URL as JSON `{event_id, type, created_at, data}`.

    - Signature: `X-Timestamp` is unix seconds; `X-Signature` is `v1=<lowercase
    hex HMAC-SHA256(secret, "<X-Timestamp>." + raw body)>`.
      The key is the whole `whsec_...` secret string. Verify against the raw body bytes before parsing.
    - The signing secret is shared once, when your webhook URL is registered.
    Rotating it ends the old
      secret at once.
    - Delivery is at least once: deduplicate by `event_id`. Answer 2xx to
    acknowledge. 408, 429, 5xx and
      network errors are retried with backoff for about 3 hours; any other 4xx stops delivery of that event.
    - Order is not guaranteed. `GET /v1/applications/{id}` is the source of
    truth.
servers: []
security:
  - bearerAuth: []
paths:
  /v1/events:
    post:
      summary: >-
        Report a settled deposit, a Tradevu repayment, or a confirmed or failed
        instruction
      description: >
        The body is the webhook envelope `{event_id, type, created_at, data}`.
        `type` is

        `deposit.settled`, `tradevu.repayment`, `hold.placed`,
        `payout.confirmed`, `hold.released`,

        `refund.paid` or `instruction.failed`; any other type is a 400 with
        details

        `[{"field": "type"}]`. Every 202 carries the loan's current view, the
        same as

        `GET /v1/loans/{loan_id}`. Use the `event_id` as the Idempotency-Key.
        Repeating an `event_id`, or

        a `repayment_id` already posted, answers 202 and posts nothing new.
        Every object rejects

        unknown fields. A 400 names each failing field as `{"field":
        "data.principal_cents"}`. A `data`

        block that does not parse (a missing, unknown or mistyped field) is a
        400 with the message

        `invalid event` and no details.

        A `repayment_id` already posted for a different loan is a 400 with
        details

        `[{"field": "data.repayment_id"}]`.

        A `deposit.settled` posts one ledger journal and sends the next
        deduction instruction. It is

        accepted while the loan is current, overdue, delinquent, default,
        restructured or repaid (a

        deposit on a repaid loan is all overpayment, and a refund is queued);
        any other status is

        409 INVALID_STATE. An `instruction_version` above the loan's current
        version, or a

        `ledger_operation_id` already posted for a different loan, is a 400 with
        details

        `[{"field": "data.instruction_version"}]` or `[{"field":
        "data.ledger_operation_id"}]`.

        `payer_name` and `beneficiary_name` are used only to classify the
        deposit and are not stored.

        Final answers are 400 VALIDATION_FAILED, 404, 409 INVALID_STATE, 409
        IDEMPOTENCY_KEY_REUSED,

        413 PAYLOAD_TOO_LARGE and 422 REPAYMENT_EXCEEDS_LINE: a repeat with the
        same Idempotency-Key

        replays the stored response, so send a corrected event under a new
        `event_id`. Retry a 5xx,

        409 REQUEST_IN_PROGRESS and 429 with the same Idempotency-Key and body.
        Retry a 401 after

        refreshing the token. A 400 IDEMPOTENCY_KEY_REQUIRED or
        IDEMPOTENCY_KEY_INVALID is not stored:

        fix the header and send again.

        A `tradevu.repayment` is refused with 409 INVALID_STATE only while the
        loan is

        pending_disbursement or cancelled, and with 422 REPAYMENT_EXCEEDS_LINE
        when it is above the

        loan's outstanding Tradevu line.

        `hold.placed`, `payout.confirmed`, `hold.released` and `refund.paid`
        confirm a

        `place_hold`, `pay_out`, `release_hold` or `refund` instruction;
        `instruction.failed`

        reports that any of them could not be done. An unknown `instruction_id`,
        or another partner's,

        is a 404. Field errors are checked next, before the instruction's state,
        in this order, each a

        400 naming its field: `instruction_id` must name an instruction of this
        loan whose kind matches

        the type (`data.instruction_id`), `amount_cents` must equal the
        instruction's amount,

        `reference` is 1 to 128 characters, `done_at` / `failed_at` is no more
        than 5 minutes ahead of

        our clock, and `reason` is one of `insufficient_balance`,
        `account_blocked`, `other`. Then

        the state: resending an identical confirmation (same `reference` and
        `amount_cents`) or an

        identical failure (same `reason`) answers 202 and changes nothing, under
        any `event_id`; any

        other event on an instruction already confirmed or failed is 409
        INVALID_STATE. There is no

        deadline: a confirmation or failure sent hours later still applies. A
        `place_hold` is issued

        once the bureau check passes. `release_hold` and `refund` are issued
        within seconds after the

        event that causes them, so they are not in that event's answer. A failed
        `pay_out` is replaced

        by a new `pay_out` instruction, up to 3 in all; after the third failure
        the loan is cancelled

        and a `release_hold` is issued. A failed `release_hold` or `refund` is
        not issued again.
      operationId: receiveEvent
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerEvent'
      responses:
        '202':
          description: Processed, or already processed
          content:
            application/json:
              schema:
                type: object
                required:
                  - event_id
                  - loan
                properties:
                  event_id:
                    type: string
                  loan:
                    $ref: '#/components/schemas/LoanView'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: INVALID_STATE, or an idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: PAYLOAD_TOO_LARGE. The body is over 1 MiB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: REPAYMENT_EXCEEDS_LINE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 1 to 255 visible ASCII characters
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    PartnerEvent:
      type: object
      additionalProperties: false
      required:
        - event_id
        - type
        - created_at
        - data
      properties:
        event_id:
          type: string
          minLength: 1
          maxLength: 128
        type:
          type: string
          enum:
            - deposit.settled
            - tradevu.repayment
            - hold.placed
            - payout.confirmed
            - hold.released
            - refund.paid
            - instruction.failed
        created_at:
          type: string
          format: date-time
        data:
          description: >-
            `DepositSettled` for deposit.settled, `TradevuRepayment` for
            tradevu.repayment, `InstructionConfirmation` for hold.placed,
            payout.confirmed, hold.released and refund.paid,
            `InstructionFailure` for instruction.failed
          oneOf:
            - $ref: '#/components/schemas/DepositSettled'
            - $ref: '#/components/schemas/TradevuRepayment'
            - $ref: '#/components/schemas/InstructionConfirmation'
            - $ref: '#/components/schemas/InstructionFailure'
    LoanView:
      type: object
      required:
        - loan_id
        - status
        - currency
        - principal_cents
        - interest_cents
        - hold_cents
        - outstanding_cents
        - installments
        - instructions
        - deduction
      properties:
        loan_id:
          type: string
          format: uuid
        status:
          type: string
        currency:
          type: string
          enum:
            - USD
        principal_cents:
          type: integer
        interest_cents:
          type: integer
        hold_cents:
          type: integer
        outstanding_cents:
          type: integer
          description: >-
            Contractual balance, the sum of amount due less amount paid over the
            current installments. It is 0 while the loan is pending_disbursement
            or cancelled, because nothing is owed until the payout is confirmed;
            each installment's `amount_due_cents` still shows the schedule.
        installments:
          type: array
          items:
            $ref: '#/components/schemas/LoanInstallment'
        instructions:
          type: array
          description: Pending instructions only, oldest first.
          items:
            $ref: '#/components/schemas/Instruction'
        deduction:
          description: >-
            The stored deduction instruction, never recomputed; null until the
            first payout.
          oneOf:
            - $ref: '#/components/schemas/DeductionInstruction'
            - type: 'null'
    Error:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items: {}
        request_id:
          type: string
    DepositSettled:
      type: object
      additionalProperties: false
      required:
        - loan_id
        - partner_account_id
        - instruction_version
        - deposit_id
        - ledger_operation_id
        - deposit_amount_cents
        - deducted_cents
        - settled_at
        - transfer_type
        - from_outside_institution
        - into_own_account
        - payer_name
        - beneficiary_name
      properties:
        loan_id:
          type: string
          format: uuid
        partner_account_id:
          type: string
          description: >-
            Must be the loan's borrower account, otherwise 400 with details
            [{"field": "data.partner_account_id"}]
        instruction_version:
          type: integer
          minimum: 1
          description: Between 1 and the loan's current instruction version
        deposit_id:
          type: string
          minLength: 1
          maxLength: 128
        ledger_operation_id:
          type: string
          minLength: 1
          maxLength: 128
          description: A repeated value is a duplicate and posts nothing new
        deposit_amount_cents:
          type: integer
          exclusiveMinimum: 0
        deducted_cents:
          type: integer
          minimum: 1
          description: At most deposit_amount_cents
        settled_at:
          type: string
          format: date-time
          description: No more than 5 minutes ahead of our clock
        transfer_type:
          type: string
          enum:
            - bank_transfer
            - card
            - internal
            - crypto
            - other
        from_outside_institution:
          type: boolean
        into_own_account:
          type: boolean
        payer_name:
          type:
            - string
            - 'null'
          maxLength: 200
        beneficiary_name:
          type:
            - string
            - 'null'
          maxLength: 200
    TradevuRepayment:
      type: object
      additionalProperties: false
      required:
        - loan_id
        - partner_account_id
        - repayment_id
        - principal_cents
        - repaid_at
      properties:
        loan_id:
          type: string
          format: uuid
        partner_account_id:
          type: string
          description: >-
            Must be the loan's borrower account, otherwise 400 with details
            [{"field": "data.partner_account_id"}]
        repayment_id:
          type: string
          minLength: 1
          maxLength: 128
        principal_cents:
          type: integer
          exclusiveMinimum: 0
        repaid_at:
          type: string
          format: date-time
          description: No more than 5 minutes ahead of our clock
    InstructionConfirmation:
      type: object
      additionalProperties: false
      required:
        - loan_id
        - partner_account_id
        - instruction_id
        - amount_cents
        - reference
        - done_at
      properties:
        loan_id:
          type: string
          format: uuid
        partner_account_id:
          type: string
          description: >-
            Must be the loan's borrower account, otherwise 400 with details
            [{"field": "data.partner_account_id"}]
        instruction_id:
          type: string
          format: uuid
          description: A pending instruction of this loan whose kind matches the event type
        amount_cents:
          type: integer
          description: What you moved; must equal the instruction's amount_cents
        reference:
          type: string
          minLength: 1
          maxLength: 128
          description: Your own id for the movement
        done_at:
          type: string
          format: date-time
          description: No more than 5 minutes ahead of our clock
    InstructionFailure:
      type: object
      additionalProperties: false
      required:
        - loan_id
        - partner_account_id
        - instruction_id
        - reason
        - failed_at
      properties:
        loan_id:
          type: string
          format: uuid
        partner_account_id:
          type: string
          description: >-
            Must be the loan's borrower account, otherwise 400 with details
            [{"field": "data.partner_account_id"}]
        instruction_id:
          type: string
          format: uuid
        reason:
          type: string
          enum:
            - insufficient_balance
            - account_blocked
            - other
        failed_at:
          type: string
          format: date-time
          description: No more than 5 minutes ahead of our clock
    LoanInstallment:
      type: object
      required:
        - seq
        - amount_due_cents
        - principal_due_cents
        - interest_due_cents
        - amount_paid_cents
        - due_date
        - provisional_due_date
        - paid_at
        - status
      properties:
        seq:
          type: integer
        amount_due_cents:
          type: integer
        principal_due_cents:
          type: integer
        interest_due_cents:
          type: integer
        amount_paid_cents:
          type: integer
        due_date:
          type:
            - string
            - 'null'
          format: date
        provisional_due_date:
          type:
            - string
            - 'null'
          format: date
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        status:
          type: string
    Instruction:
      type: object
      required:
        - instruction_id
        - kind
        - amount_cents
        - currency
        - issued_at
      properties:
        instruction_id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - place_hold
            - pay_out
            - release_hold
            - refund
        amount_cents:
          type: integer
        currency:
          const: USD
        issued_at:
          type: string
          format: date-time
    DeductionInstruction:
      type: object
      required:
        - instruction_version
        - status
        - installment_seq
        - amount_cents
        - currency
        - deposit_filter
        - max_deposit_pct
      properties:
        instruction_version:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - active
            - cancelled
        installment_seq:
          type:
            - integer
            - 'null'
        amount_cents:
          type: integer
        currency:
          const: USD
        deposit_filter:
          const: inbound_bank_transfer_from_outside
        max_deposit_pct:
          const: 100
  responses:
    ValidationFailed:
      description: VALIDATION_FAILED
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthenticated:
      description: UNAUTHENTICATED
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: NOT_FOUND, also for another partner's application
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token from POST /v1/oauth/token (client credentials)

````

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