Dry-run a Transaction

POST

transactions

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_00000000-0000-0000-0000-000000000000' not found",
  "error_detail": {
    "code": "TXN_NOT_FOUND",
    "message": "Balance with ID 'bln_00000000-0000-0000-0000-000000000000' not found",
    "details": {}
  }
}

If you’re using the auto-provisioned Enterprise Core instance included with your Production License deployment, set the base URL to: https://ENTERPRISE_PUBLIC_URL/core.If you’re connecting to a different Core instance, use the publicly accessible base URL for that instance instead.

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: Scoped API keys and Secure your Blnk server.

Available in version 0.15.3 and later.

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

boolean

required

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.

integer

The transaction amount in its smallest unit (recommended). Include the corresponding precision value. See Precision.

Either precise_amount or amount should be provided, not both.

float

The transaction amount as a float. Blnk multiplies amount by precision to store precise_amount.

string

required

The currency of the transaction amount.

integer

default:"1"

required

Precision for the transaction’s currency. See Precision.

string

required

Unique transaction reference. A dry run does not consume it.

string

required

Balance sending the amount. @ prefix indicates an internal balance.

string

required

Balance receiving the amount. @ prefix indicates an internal balance.

string

Narration of the transaction.

boolean

default:"false"

Whether the source can go negative. See Overdrafts.

boolean

default:"false"

When true, the preview uses INFLIGHT status and projects inflight balances. See Create inflight.

boolean

default:"false"

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.

array

Multiple sources instead of source. See Multiple sources.

array

Multiple destinations instead of destination. See Multiple destinations.

Response

boolean

required

Always true. This is a preview, not a recorded transaction.

boolean

required

Whether a real post of this payload would be accepted against balances as they stand now.

object

Present when would_apply is false. code is the same catalog code a real post would return.

Show Rejection properties

string

Stable error code, such as TXN_INSUFFICIENT_FUNDS or TXN_DUPLICATE_REFERENCE. See API error codes.

string

Short category for the rejection.

string

Human-readable rejection message.

string

Status the real transaction would carry (APPLIED, or INFLIGHT if you sent inflight: true). Omitted when would_apply is false.

string

The reference you sent. It is still unused after a dry run.

string

Currency of the projected movement.

float

Display amount of the projected movement.

string

Movement in minor units, returned as a string so nothing is rounded.

float

Precision used to convert precise_amount.

string

Present on inflight previews only: commit or void.

array

required

Before and after state for each participating balance. Amounts are minor-unit strings.

Show Balance projection

string

Balance ID, or the @indicator when the balance is virtual.

string

source or destination.

string

Currency of the balance.

boolean

true when the @indicator does not exist yet. The preview uses a zeroed stand-in and does not create the balance.

string

Net balance before the projected movement.

string

Spendable funds before the movement (balance minus inflight and queued debits).

string

Credit balance before the movement.

string

Debit balance before the movement.

string

Inflight debit before the movement.

string

Inflight credit before the movement.

string

Net balance after the projected movement. Matches current_balance when would_apply is false.

string

Spendable funds after the movement.

string

Credit balance after the movement.

string

Debit balance after the movement.

string

Inflight debit after the movement.

string

Inflight credit after the movement.

array

One entry per split that would apply on a multiple-source or multiple-destination transaction.

Show Leg projection

string

Source or destination balance for this leg.

string

source or destination.

string

Leg amount in minor units.

float

Display amount for the leg.

array

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_00000000-0000-0000-0000-000000000000' not found",
  "error_detail": {
    "code": "TXN_NOT_FOUND",
    "message": "Balance with ID 'bln_00000000-0000-0000-0000-000000000000' not found",
    "details": {}
  }
}

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

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_00000000-0000-0000-0000-000000000000' not found",
  "error_detail": {
    "code": "TXN_NOT_FOUND",
    "message": "Balance with ID 'bln_00000000-0000-0000-0000-000000000000' not found",
    "details": {}
  }
}

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Transaction hooks

API keys

System

Authorization

Body

Response

Need help?

​Authorization

​Body

​Response

​Need help?

Authorization

Body

Response

Need help?