Transactions
Dry-run a transaction Preview a transaction without writing it to the ledger.
POST /transactions
Authorization
If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>.
Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code.
See also: Core API key .
Send the same body as Record a transaction and set dry_run to true. Blnk returns a projection instead of a recorded transaction.
The preview always answers synchronously with HTTP 200. dry_run takes precedence over skip_queue. A projected rejection is 200 with would_apply: false, not an HTTP error.
dry_run also works on bulk create , refund , and update inflight . See Dry-run transactions .
Body
dry_runboolean required body Set true to project the transaction without writing anything. No transaction row, balance change, queue entry, webhook, or hook is created, and the reference is not consumed.
precise_amountinteger body The transaction amount in its smallest unit (recommended). Include the corresponding precision value. See Precision .
amountfloat body The transaction amount as a float. Blnk multiplies amount by precision to store precise_amount.
currencystring required body The currency of the transaction amount.
precisioninteger default 1 required body Precision for the transaction’s currency. See Precision .
referencestring required body Unique transaction reference. A dry run does not consume it.
sourcestring required body destinationstring required body descriptionstring body Narration of the transaction.
allow_overdraftboolean default false body Whether the source can go negative. See Overdrafts .
inflightboolean default false body When true, the preview uses INFLIGHT status and projects inflight balances. See Create inflight .
skip_queueboolean default false body Ignored for a single-transaction dry run. The preview always answers now. For bulk and splits, this flag selects cumulative vs independent projection. See Bulk and split transactions .
sourcesarray body destinationsarray body Response
dry_runboolean required Always true. This is a preview, not a recorded transaction.
would_applyboolean required Whether a real post of this payload would be accepted against balances as they stand now.
rejectionobject Present when would_apply is false. code is the same catalog code a real post would return.
Rejection properties codestring Stable error code, such as TXN_INSUFFICIENT_FUNDS or TXN_DUPLICATE_REFERENCE. See API error codes .
reasonstring Short category for the rejection.
messagestring Human-readable rejection message.
statusstring Status the real transaction would carry (APPLIED, or INFLIGHT if you sent inflight: true). Omitted when would_apply is false.
referencestring The reference you sent. It is still unused after a dry run.
currencystring Currency of the projected movement.
amountfloat Display amount of the projected movement.
precise_amountstring Movement in minor units, returned as a string so nothing is rounded.
precisionfloat Precision used to convert precise_amount.
operationstring Present on inflight previews only: commit or void.
balancesarray required Before and after state for each participating balance. Amounts are minor-unit strings.
Balance projection balance_idstring Balance ID, or the @indicator when the balance is virtual.
rolestring currencystring virtualboolean true when the @indicator does not exist yet. The preview uses a zeroed stand-in and does not create the balance.
current_balancestring Net balance before the projected movement.
current_availablestring Spendable funds before the movement (balance minus inflight and queued debits).
current_credit_balancestring Credit balance before the movement.
current_debit_balancestring Debit balance before the movement.
current_inflight_debit_balancestring Inflight debit before the movement.
current_inflight_credit_balancestring Inflight credit before the movement.
resulting_balancestring Net balance after the projected movement. Matches current_balance when would_apply is false.
resulting_availablestring Spendable funds after the movement.
resulting_credit_balancestring Credit balance after the movement.
resulting_debit_balancestring Debit balance after the movement.
resulting_inflight_debit_balancestring Inflight debit after the movement.
resulting_inflight_credit_balancestring Inflight credit after the movement.
legsarray One entry per split that would apply on a multiple-source or multiple-destination transaction.
Leg projection identifierstring Source or destination balance for this leg.
rolestring precise_amountstring Leg amount in minor units.
amountfloat Display amount for the leg.
notesarray Advisory messages that are not rejections, such as a currency mismatch or a scheduled_for date being ignored.
curl -X POST "http://localhost:5001/transactions" \ -H "X-blnk-key: <api-key>" \ -H "Content-Type: application/json" \ -d '{ "dry_run": true, "precise_amount": 12000, "precision": 100, "reference": "ref_card_settle_4821", "currency": "USD", "source": "bln_source-bal-001", "destination": "bln_dest-bal-001", "description": "Card settlement" }' { "dry_run" : true , "would_apply" : true , "status" : "APPLIED" , "reference" : "ref_card_settle_4821" , "currency" : "USD" , "amount" : 120 , "precise_amount" : "12000" , "precision" : 100 , "balances" : [ { "balance_id" : "bln_source-bal-001" , "role" : "source" , "currency" : "USD" , "current_balance" : "50000" , "current_available" : "50000" , "current_credit_balance" : "50000" , "current_debit_balance" : "0" , "current_inflight_debit_balance" : "0" , "current_inflight_credit_balance" : "0" , "resulting_balance" : "38000" , "resulting_available" : "38000" , "resulting_credit_balance" : "50000" , "resulting_debit_balance" : "12000" , "resulting_inflight_debit_balance" : "0" , "resulting_inflight_credit_balance" : "0" }, { "balance_id" : "bln_dest-bal-001" , "role" : "destination" , "currency" : "USD" , "current_balance" : "0" , "current_available" : "0" , "current_credit_balance" : "0" , "current_debit_balance" : "0" , "current_inflight_debit_balance" : "0" , "current_inflight_credit_balance" : "0" , "resulting_balance" : "12000" , "resulting_available" : "12000" , "resulting_credit_balance" : "12000" , "resulting_debit_balance" : "0" , "resulting_inflight_debit_balance" : "0" , "resulting_inflight_credit_balance" : "0" } ] } { "dry_run" : true , "would_apply" : false , "rejection" : { "code" : "TXN_INSUFFICIENT_FUNDS" , "reason" : "insufficient_funds" , "message" : "insufficient funds in source balance" }, "reference" : "ref_card_settle_4821" , "currency" : "USD" , "amount" : 120 , "precise_amount" : "12000" , "precision" : 100 , "balances" : [ { "balance_id" : "bln_source-bal-001" , "role" : "source" , "currency" : "USD" , "current_balance" : "5000" , "current_available" : "5000" , "current_credit_balance" : "5000" , "current_debit_balance" : "0" , "current_inflight_debit_balance" : "0" , "current_inflight_credit_balance" : "0" , "resulting_balance" : "5000" , "resulting_available" : "5000" , "resulting_credit_balance" : "5000" , "resulting_debit_balance" : "0" , "resulting_inflight_debit_balance" : "0" , "resulting_inflight_credit_balance" : "0" }, { "balance_id" : "bln_dest-bal-001" , "role" : "destination" , "currency" : "USD" , "current_balance" : "0" , "current_available" : "0" , "current_credit_balance" : "0" , "current_debit_balance" : "0" , "current_inflight_debit_balance" : "0" , "current_inflight_credit_balance" : "0" , "resulting_balance" : "0" , "resulting_available" : "0" , "resulting_credit_balance" : "0" , "resulting_debit_balance" : "0" , "resulting_inflight_debit_balance" : "0" , "resulting_inflight_credit_balance" : "0" } ] } { "errors" : "amount: either amount or precise_amount is required." , "error_detail" : { "code" : "TXN_VALIDATION_ERROR" , "message" : "amount: either amount or precise_amount is required." } } { "error" : "Balance with ID 'bln_c8e4f1a2-3b5d-4e7a-9c1f-2d6a8b0e4f73' not found" , "error_detail" : { "code" : "BAL_NOT_FOUND" , "message" : "Balance with ID 'bln_c8e4f1a2-3b5d-4e7a-9c1f-2d6a8b0e4f73' not found" , "details" : {} } } Related pages 
