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

# Create an Outflow Transaction

> Use this endpoint to initiate an outflow transaction, abstracting the process of moving funds from internal ledger accounts to the external world.
<p>Instead of requiring full transaction details, you only need to provide the source accounts. Based on the asset provided, the system automatically includes the corresponding external account in the distribute section of the transaction.</p>




## OpenAPI

````yaml /en/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/outflow
openapi: 3.1.0
info:
  title: Midaz Ledger API
  description: >-
    Complete API reference for Midaz Ledger services including organization
    management, ledger operations, assets, segments, portfolios, accounts,
    account types, transactions, operations, balances, operation routes,
    transaction routes, and metadata indexes.
  version: 3.7.0
servers:
  - url: https://ledger.sandbox.lerian.net
security: []
tags:
  - name: Organizations API
  - name: Ledgers API
  - name: Assets API
  - name: Segments API
  - name: Portfolios API
  - name: Account Types API
  - name: Accounts API
  - name: Balances API
  - name: Transactions API
  - name: Operations API
  - name: Operation Routes API
  - name: Transaction Routes API
  - name: Metadata Indexes API
paths:
  /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/outflow:
    post:
      tags:
        - Transactions API
      summary: Create an Outflow Transaction
      description: >
        Use this endpoint to initiate an outflow transaction, abstracting the
        process of moving funds from internal ledger accounts to the external
        world.

        <p>Instead of requiring full transaction details, you only need to
        provide the source accounts. Based on the asset provided, the system
        automatically includes the corresponding external account in the
        distribute section of the transaction.</p>
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/LedgerId'
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/XIdempotency'
        - $ref: '#/components/parameters/XTTL'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOutflowTransactionRequest'
            example:
              code: OUTFLOW_2025_0007
              pending: false
              description: PIX
              send:
                asset: BRL
                value: '1000'
                source:
                  from:
                    - accountAlias: '@external/BRL'
                      amount:
                        asset: BRL
                        value: '1000'
                      description: Debit pix
                      balanceKey: default
                      metadata:
                        payerDocument: '12345678901'
                        origin: external_account
              metadata:
                referenceId: PIX-OUT-553921
                channel: pix
                purpose: pix_payment
      responses:
        '201':
          description: >-
            Indicates that the resource was successfully created and the
            operation was completed as expected.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the transaction was just processed. If the
            value is true, the response is a replay of a previously processed
            request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTransactionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                Error0073:
                  $ref: '#/components/examples/Error0073'
                Error0050:
                  $ref: '#/components/examples/Error0050'
                Error0051:
                  $ref: '#/components/examples/Error0051'
                Error0094:
                  $ref: '#/components/examples/Error0094'
          headers: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                Error0041:
                  $ref: '#/components/examples/Error0041'
                Error0042:
                  $ref: '#/components/examples/Error0042'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                Error0043:
                  $ref: '#/components/examples/Error0043'
        '409':
          description: >-
            Conflict — the idempotency key is already in use by a request that
            is still being processed.

            The `X-Idempotency-Replayed` header is included in the response and
            set to `false`.

            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                Error0084:
                  $ref: '#/components/examples/Error0084'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                Error0019:
                  $ref: '#/components/examples/Error0019'
                Error0167:
                  $ref: '#/components/examples/Error0167'
                Error0168:
                  $ref: '#/components/examples/Error0168'
          headers: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                Error0046:
                  $ref: '#/components/examples/Error0046'
      security:
        - bearer: []
components:
  parameters:
    OrganizationId:
      name: organization_id
      in: path
      description: The unique identifier of the Organization associated with the Ledger.
      required: true
      example: 019c96a0-0a98-7287-9a31-786e0809c769
      schema:
        type: string
    Authorization:
      name: Authorization
      in: header
      description: >-
        The authorization token. **This header is required if your environment
        has Access Manager enabled**.
      required: false
      schema:
        type: string
    LedgerId:
      name: ledger_id
      in: path
      description: The unique identifier of the associated Ledger.
      required: true
      example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a
      schema:
        type: string
    ContentType:
      name: Content-Type
      in: header
      description: >-
        The type of media of the resource. Recommended value is
        `application/json`.
      required: false
      example: application/json
      schema:
        type: string
    XRequestId:
      name: X-Request-Id
      in: header
      description: A unique identifier used to trace and track each request.
      required: false
      example: 019c96a0-0a98-7287-9a31-786e0809c769
      schema:
        type: string
        format: uuid
    XIdempotency:
      name: X-Idempotency
      in: header
      description: >-
        A unique key that ensures transaction idempotency. If not provided, the
        system automatically generates a SHA-256 hash based on the request body.
        Keys are scoped per organization and ledger.


        Always validate the `X-Idempotency-Replayed` response header to
        distinguish new transactions from cached replays.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        best practices.
      required: false
      example: 019c96a0-10ce-75fc-a273-dc799079a99c
      schema:
        type: string
    XTTL:
      name: X-TTL
      in: header
      description: >-
        The time-to-live for the idempotency key, defined in seconds. Defaults
        to 300 seconds (5 minutes) if not provided. Only the TTL from the first
        request is used; changing it on retries has no effect.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        details.
      required: false
      example: 3600
      schema:
        type: integer
  schemas:
    CreateOutflowTransactionRequest:
      type: object
      properties:
        chartOfAccountsGroupName:
          type: string
          description: >-
            The chart of accounts group name which categorizes this transaction
            under a specific group.
        code:
          type: string
          maxLength: 100
          description: Transaction code for reference.
        pending:
          type: boolean
          description: >-
            Indicates whether the transaction should follow a two-step process:
            authorization followed by execution. When set to **true**, the
            transaction is created in a pending state, reserving funds
            (`on_hold`) without immediately moving them. A subsequent commit is
            required to finalize the transfer.
          default: false
        description:
          type: string
          description: A description for the transaction.
        route:
          type: string
          description: >
            Specifies the Transaction Route associated with the transaction.  
            **Important:** When Transaction Routing validation is enabled for
            your Ledger, this field becomes **mandatory** and must match an
            existing `id` from your configured [Transaction
            Routes](create-transaction-route).   However, when validation is
            disabled (default behavior), this field is **optional** and accepts
            any free-form string.
        routeId:
          type: string
          format: uuid
          description: >-
            The unique identifier (UUID) of the Transaction Route to associate
            with this transaction.
        transactionDate:
          type: string
          description: >-
            The time when the transaction was made. Used to add past
            transactions. **Must be a date in the past**.
        send:
          type: object
          required:
            - asset
            - value
            - source
          description: >-
            An object containing information about the transaction that will be
            sent.
          properties:
            asset:
              type: string
              description: The code that identifies the asset that will be sent.
            value:
              type: string
              description: >-
                The amount that will be sent. **Important:** Use a dot (`.`) as
                the decimal separator — commas are not accepted.
            source:
              type: object
              required:
                - from
              description: An object containing information about the source accounts.
              properties:
                from:
                  type: array
                  description: >-
                    The list of accounts that will be used as source. Each entry
                    in the array must include one of the following fields:
                    `amount`, `share`, or `remaining`. If an entry includes more
                    than one of these fields, an error will occur.
                  items:
                    type: object
                    required:
                      - accountAlias
                      - amount
                    properties:
                      accountAlias:
                        type: string
                        description: The alias for the account used in the operation.
                      balanceKey:
                        type: string
                        description: >-
                          The unique identifier key for the account balance. If
                          omitted, the `default` balance is used. Use a
                          previously [created
                          key](https://docs.lerian.studio/en/reference/create-a-balance)
                          to route funds to a specific balance.
                      route:
                        type: string
                        description: >
                          Specifies the Transaction Route associated with the
                          transaction.   **Important:** When Transaction Routing
                          validation is enabled for your Ledger, this field
                          becomes **mandatory** and must match an existing `id`
                          from your configured [Transaction
                          Routes](create-transaction-route).   However, when
                          validation is disabled (default behavior), this field
                          is **optional** and accepts any free-form string.
                      amount:
                        $ref: '#/components/schemas/SendAmountRequest'
                      share:
                        $ref: '#/components/schemas/SendShareRequest'
                      remaining:
                        type: string
                        description: >-
                          The remaining amount or percentage. **Important:** Use
                          a dot (`.`) as the decimal separator — commas are not
                          accepted.
                      description:
                        type: string
                        description: A description for the transaction.
                      metadata:
                        $ref: '#/components/schemas/Metadata'
                  minItems: 1
        metadata:
          $ref: '#/components/schemas/Metadata'
    CreateTransactionResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the transaction.
          format: uuid
        parentTransactionId:
          type: string
          description: >-
            The unique identifier of the parent/original transaction for
            reversals. This field is populated by the server when a transaction
            is reverted and should be treated as read-only by clients.
          format: uuid
          nullable: true
        organizationId:
          type: string
          format: uuid
          description: The unique identifier of the Organization.
        ledgerId:
          type: string
          description: The unique identifier of the Ledger.
          format: uuid
        description:
          type: string
          description: Description of the transaction.
        route:
          type: string
          description: Specifies the Transaction Route associated with the transaction.
        routeId:
          type: string
          format: uuid
          description: >-
            The unique identifier of the Transaction Route applied to this
            transaction.
        status:
          type: object
          description: The transaction status (pending, completed, reversed).
          properties:
            code:
              type: string
              description: Transaction status code.
            description:
              type: string
              description: Transaction status description.
        amount:
          type: string
          description: The sent amount.
        assetCode:
          type: string
          description: The name of the asset used in the operation.
        chartOfAccountsGroupName:
          type: string
          description: The name of the chart-of-accounts group.
        source:
          type: array
          description: The list of accounts used as source.
          items:
            type: string
        destination:
          type: array
          description: The list of accounts used as destination.
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Timestamp of creation (UTC).
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of last update (UTC).
        deletedAt:
          type: string
          format: date-time
          description: Timestamp of soft deletion, if applicable (UTC).
          nullable: true
        operations:
          type: array
          items:
            $ref: '#/components/schemas/OperationResponse'
        metadata:
          $ref: '#/components/schemas/Metadata'
    ErrorFormat:
      type: object
      description: The response message error.
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
          description: A unique, stable identifier for the error.
        title:
          type: string
          description: A brief summary of the issue.
        message:
          type: string
          description: Detailed guidance for resolving the error.
        fields:
          type: object
          additionalProperties: true
          description: Additional information about the fields that caused the error.
    SendAmountRequest:
      type: object
      required:
        - asset
        - value
      description: >-
        An object containing information about the amount that will be used in
        the operation.
      properties:
        asset:
          type: string
          description: The name of the asset used in the operation.
        value:
          type: string
          description: >-
            The amount that will be sent. **Important:** Use a dot (`.`) as the
            decimal separator — commas are not accepted.
    SendShareRequest:
      type: object
      description: >-
        If different accounts are part of the operation, this object will
        contain the information about the percentage used for each account.
      properties:
        percentage:
          type: string
          description: >-
            The percentage that will be shared. **Important:** Use a dot (`.`)
            as the decimal separator — commas are not accepted.
        percentageOfPercentage:
          type: integer
          description: >-
            The percentage of the percentage that will be shared. **Important:**
            Use a dot (`.`) as the decimal separator — commas are not accepted.
    Metadata:
      type: object
      additionalProperties:
        type: string
      description: >-
        An object containing key-value pairs to add as metadata, where the field
        `name` is the key and the field `value` is the value. For example, to
        add a Cost Center, use 'costCenter': 'BR_11101997'.
    OperationResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the Operation.
          format: uuid
        transactionId:
          type: string
          format: uuid
          description: The unique identifier of the Transaction.
        organizationId:
          type: string
          format: uuid
          description: The unique identifier of the Organization.
        ledgerId:
          type: string
          description: The unique identifier of the Ledger.
          format: uuid
        accountId:
          type: string
          description: The unique identifier of the Account.
          format: uuid
        accountAlias:
          type: string
          description: The alias for the account used in the operation.
        balanceId:
          type: string
          description: The unique identifier of the Balance.
        balanceKey:
          type: string
          description: The key identifier of the Balance.
        description:
          type: string
          description: A description for the operation.
        type:
          type: string
          description: >-
            The type of the operation. `OVERDRAFT` identifies system-generated
            companion operations on the internal `"overdraft"` balance —
            `direction` then carries the lifecycle semantics (`debit` for a
            draw, `credit` for a repayment).
          enum:
            - CREDIT
            - DEBIT
            - ON_HOLD
            - RELEASE
            - OVERDRAFT
        assetCode:
          type: string
          description: The code that identifies the sent asset.
        chartOfAccounts:
          type: string
          description: The name of the Chart-of-Accounts that the operation belongs to.
        route:
          type: string
          deprecated: true
          description: >-
            **Deprecated.** Use `routeId` instead. Will be removed in the next
            major version. The unique ID of the operation route for this
            transaction leg.
        routeId:
          type: string
          format: uuid
          description: >-
            The unique identifier of the operation route associated with this
            operation. Companion overdraft operations inherit this value from
            the primary operation that triggered them.
        routeCode:
          type: string
          maxLength: 100
          description: >-
            A human-readable code for the operation route, useful for audit
            trail and traceability.
        routeDescription:
          type: string
          description: >-
            The description of the operation route associated with this
            operation.
        direction:
          type: string
          enum:
            - debit
            - credit
          description: The direction of the operation in double-entry accounting.
        amount:
          type: object
          description: >-
            An object containing information about the amount used in the
            operation.
          properties:
            value:
              type: string
              description: The amount that will be sent.
        balance:
          type: object
          description: >-
            An object containing information about the balance before the
            operation.
          properties:
            available:
              type: string
              description: Previous available balance.
            onHold:
              type: string
              description: Amount on hold/reserved.
            version:
              type: integer
              description: Balance version, which is updated with each transaction.
            overdraftUsed:
              type: string
              description: >-
                The overdraft consumed by this balance before the operation, as
                a decimal string. `"0"` for operations that do not touch
                overdraft.
        balanceAfter:
          type: object
          description: >-
            An object containing information about the balance after the
            operation.
          properties:
            available:
              type: string
              description: Current available balance.
            onHold:
              type: string
              description: Amount on hold/reserved.
            version:
              type: integer
              description: Balance version, which is updated with each transaction.
            overdraftUsed:
              type: string
              description: >-
                The overdraft consumed by this balance after the operation, as a
                decimal string. `"0"` for operations that do not touch
                overdraft.
        status:
          type: object
          description: The transaction status (pending, completed, reversed).
          properties:
            code:
              type: string
              description: Transaction status code.
            description:
              type: string
              description: Transaction status description.
              nullable: true
        balanceAffected:
          type: boolean
          description: >-
            Indicates whether the operation had an impact on the account
            balance.
        createdAt:
          type: string
          format: date-time
          description: Timestamp of creation (UTC).
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of last update (UTC).
        deletedAt:
          type: string
          format: date-time
          description: Timestamp of soft deletion, if applicable (UTC).
          nullable: true
        metadata:
          $ref: '#/components/schemas/Metadata'
  headers:
    XIdempotencyReplayed:
      description: >-
        Indicates whether the response was replayed from cache (`true`) or is a
        fresh response from a newly processed transaction (`false`). Always
        check this header to avoid processing the same transaction twice on your
        side.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        details.
      schema:
        type: boolean
      example: false
  examples:
    Error0073:
      value:
        code: '0073'
        title: Transaction Value Mismatch
        message: >-
          The values for the source, the destination, or both do not match the
          specified transaction amount. Please verify the values and try again.
      summary: Transaction Value Mismatch
    Error0050:
      value:
        code: '0050'
        title: Invalid Metadata
        message: >-
          One or more metadata entries are invalid. Please ensure metadata keys
          and values follow the allowed format.
      summary: Invalid Metadata
    Error0051:
      value:
        code: '0051'
        title: Invalid Metadata Key
        message: >-
          A metadata key contains unsupported characters or exceeds length
          limits. Please correct the key and try again.
      summary: Invalid Metadata Key
    Error0094:
      value:
        code: '0094'
        title: Invalid Request Body
        message: >-
          The request body is invalid or could not be parsed. Please check JSON
          structure and field types.
      summary: Invalid Request Body
    Error0041:
      summary: Token Missing
      value:
        code: '0041'
        title: Token Missing
        message: >-
          A valid token must be provided in the request header. Please include a
          token and try again.
    Error0042:
      summary: Invalid Token
      value:
        code: '0042'
        title: Invalid Token
        message: >-
          The provided token is expired, invalid or malformed. Please provide a
          valid token and try again.
    Error0043:
      summary: Insufficient Privileges
      value:
        code: '0043'
        title: Insufficient Privileges
        message: >-
          You do not have the necessary permissions to perform this action.
          Please contact your administrator if you believe this is an error.
    Error0084:
      value:
        code: '0084'
        title: Duplicate Idempotency Key
        message: >-
          The idempotency key '{{key}}' is already in use and the original
          request is still being processed. Please retry later using the same
          idempotency key.
      summary: Duplicate Idempotency Key
    Error0019:
      value:
        code: '0019'
        title: Account Ineligibility Error
        message: >-
          One or more accounts listed in the transaction are not eligible to
          participate. Please review the account statuses and try again.
      summary: Account Ineligibility
    Error0167:
      summary: Overdraft Limit Exceeded
      value:
        code: '0167'
        title: Overdraft Limit Exceeded
        message: >-
          The transaction would exceed the balance's configured overdraft limit.
          Reduce the transaction amount or increase the overdraft limit.
    Error0168:
      summary: Direct Operation on Internal Balance
      value:
        code: '0168'
        title: Direct Operation on Internal Balance
        message: >-
          A user-initiated operation targeted a balance with internal scope.
          Internal balances (e.g., overdraft companions) cannot be operated on
          directly.
    Error0046:
      summary: Internal Server Error
      value:
        code: '0046'
        title: Internal Server Error
        message: >-
          The server encountered an unexpected error. Please try again later or
          contact support.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````