Skip to main content
POST
Create a Transaction using the v2 block model

Authorizations

​
Authorization
string
header
required

JWT bearer token issued by the identity provider.

Headers

​
X-Idempotency
string

Idempotency key to safely retry the create; an identical retry returns the original transaction, a different request under the same key answers 409 (0084)

​
X-TTL
string

Idempotency slot TTL in seconds (default 300)

Body

application/json

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.

​
amount
string
required
​
asset
string
required
​
credits
object[]
required
Required array length: 1 - 500 elements
​
debits
object[]
required
Required array length: 1 - 500 elements
​
accountBlockExceptionId
string<uuid>

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.

Example:

"00000000-0000-0000-0000-000000000000"

​
code
string
​
description
string
​
metadata
object
​
operationRouteId
string<uuid>
Example:

"00000000-0000-0000-0000-000000000000"

​
routeId
string<uuid>
Example:

"00000000-0000-0000-0000-000000000000"

​
skip
object

Response

Created

​
amount
string | null
required
Example:

"1500"

​
assetCode
string
required
Required string length: 2 - 10
Example:

"BRL"

​
createdAt
string<date-time>
required
Example:

"2021-01-01T00:00:00Z"

​
credit
string[] | null
required
Example:
​
debit
string[] | null
required
Example:
​
deletedAt
string<date-time> | null
required
Example:

"2021-01-01T00:00:00Z"

​
description
string
required
Maximum string length: 256
Example:

"Transaction description"

​
feesSkipped
boolean
required
Example:

false

​
id
string<uuid>
required
Example:

"00000000-0000-0000-0000-000000000000"

​
ledgerId
string<uuid>
required
Example:

"00000000-0000-0000-0000-000000000000"

​
operations
object[] | null
required
​
organizationId
string<uuid>
required
Example:

"00000000-0000-0000-0000-000000000000"

​
status
object
required
​
tracerSkipped
boolean
required
Example:

false

​
updatedAt
string<date-time>
required
Example:

"2021-01-01T00:00:00Z"

​
groupId
string<uuid>
Example:

"00000000-0000-0000-0000-000000000000"

​
metadata
object

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, and absent when a package matched but priced nothing, for instance because the amount fell outside its bounds; 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; a transaction recorded before v4.1.1 may carry feeExemption as that object itself instead of the string, so a reader must accept both shapes; 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.

​
parentTransactionId
string<uuid>
Example:

"00000000-0000-0000-0000-000000000000"

​
routeId
string<uuid>
Example:

"00000000-0000-0000-0000-000000000000"