> ## 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 a Transaction using the v2 hold model ## OpenAPI ````yaml /pt/openapi/v3-current/ledger.yaml post /v2/transactions/hold openapi: 3.1.0 info: title: Midaz Ledger API version: 4.0.0 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Account Block Exceptions (v2) - name: Account Plan Assignments (v2) - name: Account Plans (v2) - name: Account Types (v1) - name: Account Types (v2) - name: Accounts (v1) - name: Accounts (v2) - name: Asset Rates (v1) - name: Assets (v1) - name: Assets (v2) - name: Balances (v1) - name: Balances (v2) - name: Billing Calculate (v2) - name: Billing Packages (v2) - name: Composition (v2) - name: Dashboard (v1) - name: Dashboard (v2) - name: Encryption (v2) - name: Fee Charges (v2) - name: Fee Debts (v2) - name: Fees (v2) - name: Holders (v2) - name: Instruments (v2) - name: Ledgers (v1) - name: Ledgers (v2) - name: Metadata Indexes (v1) - name: Metadata Indexes (v2) - name: Operation Routes (v1) - name: Operation Routes (v2) - name: Operations (v1) - name: Operations (v2) - name: Organizations (v1) - name: Organizations (v2) - name: Packages (v2) - name: Portfolios (v1) - name: Portfolios (v2) - name: Protection (v2) - name: Segments (v1) - name: Segments (v2) - name: Transaction Routes (v1) - name: Transaction Routes (v2) - name: Transactions (v1) - name: Transactions (v2) paths: /v2/transactions/hold: post: tags: - Transactions (v2) summary: Create a Transaction using the v2 hold model operationId: createTransactionHoldV2 parameters: - description: >- Idempotency key to safely retry the create; an identical retry returns the original transaction, a different request under the same key answers 409 (0084) in: header name: X-Idempotency schema: description: >- Idempotency key to safely retry the create; an identical retry returns the original transaction, a different request under the same key answers 409 (0084) type: string - description: Idempotency slot TTL in seconds (default 300) in: header name: X-TTL schema: description: Idempotency slot TTL in seconds (default 300) type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTransactionV2Input' required: true responses: '201': content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreatedTransactionV2' - $ref: '#/components/schemas/CrossLedgerTransactionGroupV2' description: Created headers: X-Idempotency-Replayed: schema: type: string '422': content: application/problem+json: schema: $ref: '#/components/schemas/Error' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Error' description: Error security: - BearerAuth: [] components: schemas: CreateTransactionV2Input: additionalProperties: false description: >- Transaction request body. `debits` and `credits` are the two required, non-empty leg arrays of the transaction; one debit paired with many credits, or the reverse, is a valid request. Every leg names the `organizationId` and `ledgerId` its account belongs to. The direct and hold actions accept multiple enabled ledgers and return an atomic group; block and unblock still require every leg to name the same pair. `asset`, `amount`, `description`, `code`, `routeId`, `operationRouteId` and `metadata` sit alongside the two leg arrays, and `amount` is the transaction total that the legs' `share` expressions divide. Each leg array holds at most 500 legs. properties: accountBlockExceptionId: description: >- Single-use account-block exception identifier. Authorizes one debit of an exact amount out of a blocked source account, and is consumed on use. Rejected on the hold action. examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string amount: type: string asset: type: string code: type: string credits: items: $ref: '#/components/schemas/V2LegInput' maxItems: 500 minItems: 1 type: array debits: items: $ref: '#/components/schemas/V2LegInput' maxItems: 500 minItems: 1 type: array description: type: string metadata: additionalProperties: {} type: object operationRouteId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string scheme: description: >- Optional payment scheme of the transaction, for example PIX, WIRE, CARD or CRYPTO. Any value of up to 50 letters, digits, underscores or hyphens is accepted; it is trimmed and upper-cased. CARD covers any card payment and is never the card brand. examples: - PIX maxLength: 50 type: string skip: $ref: '#/components/schemas/TransactionSkip' required: - asset - amount - debits - credits type: object CreatedTransactionV2: additionalProperties: false properties: accountPlanFees: description: >- Account plan outcome of each source account of the transaction with an active account plan assignment: the matched fee, whether the unit was free (quota), charged or matched no fee (no_match), its ordinal in the period and the fee charged. Absent when no source account has an assignment. items: $ref: '#/components/schemas/FeeAccountPlanFeeOutcome' type: - array - 'null' amount: examples: - '1500' minimum: 0 type: - string - 'null' assetCode: examples: - BRL maxLength: 10 minLength: 2 type: string createdAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string credit: examples: - - '@person2' items: type: string type: - array - 'null' debit: examples: - - '@person1' items: type: string type: - array - 'null' deletedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: - string - 'null' description: examples: - Transaction description maxLength: 256 type: string feesSkipped: examples: - false type: boolean groupId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string id: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string metadata: additionalProperties: {} description: >- Additional custom attributes. The ledger writes six fee keys on this field itself and reserves them: feeApplied is the string true when the fee engine actually charged this transaction; packageAppliedID is the identifier of the fee package the engine applied, written when that package charged a fee or recorded an exemption (including a package that priced the transaction at zero), and absent when no package applied, which includes a route whose packages all exclude the amount by their bounds, or when the applied package's fees only rounded down to zero; feeExemption is a string holding a JSON object with exempt, reason and message, present when every account on one side of the transaction is exempt from fees, which is how a caller tells an exemption apart from no package having matched; feeExemption is also present, with reason cross_ledger_bridge, when the only account on one side that would have paid a fee is the @external/ bridge closing a part of a cross-ledger group, because that bridge never pays a fee; feeExemption is also present, with reason zero_fee_amount, when the package priced the transaction at zero, for instance a band configured with no fee, so no fee leg was posted and feeApplied is absent; a transaction recorded before v4.1.1 stored feeExemption as that object itself, and a read returns it as the string too; feeDebtOpenings and feeDebtSettlements are strings holding a JSON array, in the order the ledger applied them, of the fee debts this transaction opened because its payer could not fund a deferrable fee (debtId, debtorRef, creditRef, opened, seq) and of the fee debts it settled (debtId, debtorRef, creditRef, amount, opened, seq), each absent when there is none; feeDebtCollection is the string true on a standalone fee-debt collection, whose amount is what it settled and which cannot be reverted. A request body carrying feeApplied, packageAppliedID, feeExemption, feeDebtOpenings, feeDebtSettlements, feeDebtCollection or feeDeferPair is refused with 400 naming the offending key, on every body that carries transaction metadata: a create, a metadata update and a fee estimate. A metadata update, including one that clears the metadata, never changes them. So a value present here is always the ledger's own word about the charge and never one a caller supplied. feeLeg and feeDeferPair, on operation metadata, are reserved the same way. Transaction-level metadata is additive, so caller-supplied keys on this field are preserved alongside the ledger keys. type: object operations: items: $ref: '#/components/schemas/OperationV2' type: - array - 'null' organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string parentTransactionId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string scheme: description: >- Payment scheme the transaction declared, normalized to upper case; absent when none. examples: - PIX maxLength: 50 type: string status: $ref: '#/components/schemas/TransactionStatus' tracerSkipped: examples: - false type: boolean updatedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string required: - id - description - status - amount - assetCode - debit - credit - ledgerId - organizationId - feesSkipped - tracerSkipped - createdAt - updatedAt - deletedAt - operations type: object CrossLedgerTransactionGroupV2: additionalProperties: false properties: groupId: format: uuid type: string revertedGroupId: description: >- Original group reversed by this group. Present only on grouped revert responses. format: uuid type: string transactions: description: >- Created per-ledger transactions in deterministic decomposition order. items: $ref: '#/components/schemas/AtomicTransactionBatchV2Transaction' type: array required: - groupId - transactions type: object Error: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object V2LegInput: additionalProperties: false description: >- One leg of a transaction side. Fill EXACTLY ONE value expression per leg: `amount` for an explicit value, or `share` for a percentage of the transaction total. A leg carrying both, or neither, is rejected. `balanceKey` optionally selects one of the account's balances; when omitted, the `default` balance is used. properties: alias: description: >- The leg's account alias. Accepts letters, digits and the characters @ : _ and -, or an external account alias spelled @external/ followed by the uppercase asset code. Any other spelling is refused with 400 before the transaction is calculated. examples: - '@person1' type: string amount: type: string balanceKey: description: >- Optional balance key for this leg. When omitted, the transaction uses the account's default balance. examples: - food maxLength: 100 type: string description: maxLength: 256 type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string operationRouteId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string share: $ref: '#/components/schemas/V2ShareInput' required: - alias - organizationId - ledgerId type: object TransactionSkip: additionalProperties: false properties: fees: examples: - false type: boolean tracer: examples: - false type: boolean type: object FeeAccountPlanFeeOutcome: additionalProperties: false properties: accountAlias: examples: - '@cliente_x' type: string accountId: examples: - 00000000-0000-0000-0000-000000000000 type: string accountPlanId: examples: - 00000000-0000-0000-0000-000000000000 type: string accountPlanVersion: examples: - 1 format: int64 type: integer amount: description: Fee charged; 0 unless outcome is charged. examples: - '7.9' type: string feeKey: description: Key of the matched fee; empty when outcome is no_match. examples: - tedEnviada type: string freeQuota: examples: - 10 format: int64 type: integer outcome: enum: - quota - charged - no_match - not_covered examples: - charged type: string unit: description: >- Ordinal of the consumed unit in the period; 0 when outcome is no_match. examples: - 11 format: int64 type: integer required: - accountId - accountAlias - accountPlanId - accountPlanVersion - feeKey - outcome - unit - freeQuota - amount type: object OperationV2: additionalProperties: false properties: accountAlias: examples: - '@person1' maxLength: 256 type: string accountId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string amount: $ref: '#/components/schemas/OperationAmount' assetCode: examples: - BRL maxLength: 10 minLength: 2 type: string balance: $ref: '#/components/schemas/OperationBalance' balanceAffected: examples: - true format: boolean type: boolean balanceAfter: $ref: '#/components/schemas/OperationBalance' balanceId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string balanceKey: examples: - asset-freeze maxLength: 100 type: string createdAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string deletedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: - string - 'null' description: examples: - Credit card operation maxLength: 256 type: string direction: examples: - debit maxLength: 50 type: string id: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string metadata: additionalProperties: {} description: >- Additional custom attributes. The ledger reserves the feeLeg and feeDeferPair keys on this field and writes them itself: feeLeg is the string true on every operation the fee engine created, and never appears on an operation the caller authored, because a request body that carries either key is refused rather than silently stripped; feeDeferPair carries the same token on the payer and fee operations of one deferrable fee. So a client names a fee movement from the ledger mark instead of inferring one from account names or from the caller metadata. Caller-supplied keys on an operation are returned as sent on a transaction no fee package was applied to; once a package is applied the engine rebuilds every movement of both sides, including when it prices the transaction at zero because every account is exempt, and the rebuilt movements carry only the ledger keys, so do not rely on a per-movement caller reference surviving a payment a fee package was applied to. type: object organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string routeCode: examples: - ROUTE-001 maxLength: 100 type: string routeDescription: examples: - Settlement route for service charges maxLength: 250 type: string routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string status: $ref: '#/components/schemas/OperationStatus' transactionId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string type: examples: - DEBIT maxLength: 50 type: string updatedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string required: - id - transactionId - description - type - assetCode - amount - balance - balanceAfter - status - accountId - accountAlias - balanceKey - balanceId - organizationId - ledgerId - balanceAffected - createdAt - updatedAt - deletedAt - metadata type: object TransactionStatus: additionalProperties: false properties: code: examples: - ACTIVE maxLength: 100 type: string description: examples: - Active status maxLength: 256 type: - string - 'null' required: - code - description type: object AtomicTransactionBatchV2Transaction: additionalProperties: false properties: accountPlanFees: description: >- Account plan outcome of each source account of the transaction with an active account plan assignment: the matched fee, whether the unit was free (quota), charged or matched no fee (no_match), its ordinal in the period and the fee charged. Absent when no source account has an assignment, and on every response other than a create. items: $ref: '#/components/schemas/FeeAccountPlanFeeOutcome' type: - array - 'null' amount: examples: - '1500' minimum: 0 type: - string - 'null' assetCode: examples: - BRL maxLength: 10 minLength: 2 type: string createdAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string credit: examples: - - '@person2' items: type: string type: - array - 'null' debit: examples: - - '@person1' items: type: string type: - array - 'null' deletedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: - string - 'null' description: examples: - Transaction description maxLength: 256 type: string feesSkipped: examples: - false type: boolean groupId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string id: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string metadata: additionalProperties: {} description: >- Additional custom attributes. The ledger writes six fee keys on this field itself and reserves them: feeApplied is the string true when the fee engine actually charged this transaction; packageAppliedID is the identifier of the fee package the engine applied, written when that package charged a fee or recorded an exemption (including a package that priced the transaction at zero), and absent when no package applied, which includes a route whose packages all exclude the amount by their bounds, or when the applied package's fees only rounded down to zero; feeExemption is a string holding a JSON object with exempt, reason and message, present when every account on one side of the transaction is exempt from fees, which is how a caller tells an exemption apart from no package having matched; feeExemption is also present, with reason cross_ledger_bridge, when the only account on one side that would have paid a fee is the @external/ bridge closing a part of a cross-ledger group, because that bridge never pays a fee; feeExemption is also present, with reason zero_fee_amount, when the package priced the transaction at zero, for instance a band configured with no fee, so no fee leg was posted and feeApplied is absent; a transaction recorded before v4.1.1 stored feeExemption as that object itself, and a read returns it as the string too; feeDebtOpenings and feeDebtSettlements are strings holding a JSON array, in the order the ledger applied them, of the fee debts this transaction opened because its payer could not fund a deferrable fee (debtId, debtorRef, creditRef, opened, seq) and of the fee debts it settled (debtId, debtorRef, creditRef, amount, opened, seq), each absent when there is none; feeDebtCollection is the string true on a standalone fee-debt collection, whose amount is what it settled and which cannot be reverted. A request body carrying feeApplied, packageAppliedID, feeExemption, feeDebtOpenings, feeDebtSettlements, feeDebtCollection or feeDeferPair is refused with 400 naming the offending key, on every body that carries transaction metadata: a create, a metadata update and a fee estimate. A metadata update, including one that clears the metadata, never changes them. So a value present here is always the ledger's own word about the charge and never one a caller supplied. feeLeg and feeDeferPair, on operation metadata, are reserved the same way. Transaction-level metadata is additive, so caller-supplied keys on this field are preserved alongside the ledger keys. type: object operations: items: $ref: '#/components/schemas/OperationV2' type: - array - 'null' order: description: Logical order used to execute this transaction. format: int64 minimum: 1 type: integer organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string parentTransactionId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string scheme: description: >- Payment scheme the transaction declared, normalized to upper case; absent when none. examples: - PIX maxLength: 50 type: string status: $ref: '#/components/schemas/TransactionStatus' tracerSkipped: examples: - false type: boolean updatedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string required: - order - id - description - status - amount - assetCode - debit - credit - ledgerId - organizationId - feesSkipped - tracerSkipped - createdAt - updatedAt - deletedAt - operations type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object V2ShareInput: additionalProperties: false properties: percentage: examples: - 60 format: int64 maximum: 100 minimum: 1 type: integer percentageOfPercentage: examples: - 50 format: int64 maximum: 100 minimum: 0 type: integer required: - percentage type: object OperationAmount: additionalProperties: false properties: value: examples: - '1500' minimum: 0 type: - string - 'null' required: - value type: object OperationBalance: additionalProperties: false properties: available: examples: - '1500' minimum: 0 type: - string - 'null' onHold: examples: - '500' minimum: 0 type: - string - 'null' overdraftUsed: examples: - '130' minimum: 0 type: string version: examples: - 2 format: int64 minimum: 0 type: - integer - 'null' required: - available - onHold - version - overdraftUsed type: object OperationStatus: additionalProperties: false properties: code: examples: - ACTIVE maxLength: 100 type: string description: examples: - Active status maxLength: 256 type: - string - 'null' required: - code - description type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.