Skip to main content
POST
/
transactions
curl -X POST https://api.blnkfinance.com/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 100.50,
    "reference": "order-12345",
    "currency": "USD",
    "description": "Payment for order #12345",
    "source": "bln_src123",
    "destination": "bln_dst456",
    "precision": 100
  }'

{
  "transaction_id": "txn_a1b2c3d4e5f6",
  "source": "bln_src123",
  "destination": "bln_dst456",
  "reference": "order-12345",
  "amount": 100.50,
  "precise_amount": "10050",
  "precision": 100,
  "currency": "USD",
  "description": "Payment for order #12345",
  "status": "APPLIED",
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2024-01-15T10:30:00Z",
  "meta_data": {
    "customer_id": "cust_123"
  }
}
Create and record a new transaction to move funds between balances. This endpoint supports simple transfers, multi-destination distributions, inflight transactions, and scheduled transactions.

​
Request Body

​
amount
number
Transaction amount in major currency units (e.g., 100.50 for $100.50). Either amount or precise_amount must be provided, but not both.Note: For amounts with more than 15 significant digits, use precise_amount to avoid rounding errors.
​
precise_amount
string
Transaction amount in minor units as a string representing a big integer (e.g., “10050” for $100.50 with precision 100).Use this field for:
  • High precision amounts (>15 significant digits)
  • Avoiding floating-point rounding errors
  • Cryptocurrency transactions with large precision values
​
reference
string
required
Unique reference identifier for this transaction. Used for idempotency - duplicate references will be rejected.
​
currency
string
required
Three-letter ISO currency code (e.g., “USD”, “EUR”, “BTC”).
​
description
string
required
Human-readable description of the transaction.
​
source
string
Source balance ID from which funds will be debited. Either source or sources must be provided, but not both.Special Indicators:
  • Prefix with @ to use balance indicators (e.g., @world for external funds)
  • @world balances are automatically created if they don’t exist
​
destination
string
Destination balance ID to which funds will be credited. Either destination or destinations must be provided, but not both.
​
sources
array
Array of source distributions for splitting debits across multiple balances. See Distribution Structure.
​
destinations
array
Array of destination distributions for splitting credits across multiple balances. See Distribution Structure.
​
precision
integer
Precision multiplier for amount calculations (e.g., 100 for 2 decimal places, 1000 for 3 decimal places). Must be an integer value.If not provided, uses the balance’s currency multiplier.
​
rate
number
default:"1.0"
Exchange rate for currency conversion transactions.
​
allow_overdraft
boolean
default:"false"
Whether to allow the source balance to go negative.
​
overdraft_limit
number
Maximum allowed negative balance when allow_overdraft is true.
​
inflight
boolean
default:"false"
Create as an inflight (pending) transaction. Inflight transactions reserve funds but don’t finalize the transfer until committed.Use cases:
  • Card authorizations
  • Pending payments
  • Multi-stage transactions
​
inflight_expiry_date
string
ISO 8601 timestamp when the inflight transaction should expire (e.g., “2024-04-22T15:28:03+00:00”).
​
scheduled_for
string
ISO 8601 timestamp for when the transaction should be processed (e.g., “2024-04-22T15:28:03+00:00”).Scheduled transactions remain in SCHEDULED status until processed.
​
skip_queue
boolean
default:"false"
Process transaction synchronously without queuing. Use for high-priority transactions that need immediate processing.
​
atomic
boolean
default:"false"
Ensure all related transactions (e.g., distributions) succeed or fail together.
​
effective_date
string
ISO 8601 timestamp for the transaction’s effective date for accounting purposes.
​
meta_data
object
Custom key-value pairs for storing additional transaction information.

​
Distribution Structure

For multi-destination transactions, use the sources or destinations array with Distribution objects: 
{
  "identifier": "bal_abc123",
  "distribution": "50%",  // or "100" for fixed amount, or "left" for remainder
  "precise_distribution": "1000"  // Optional: fixed amount in minor units
}
​
distribution.identifier
string
required
Balance ID to debit/credit in this distribution.
​
distribution.distribution
string
required
Distribution method:
  • Percentage: "50%" - percentage of total amount
  • Fixed amount: "100" - fixed amount in major units
  • Remainder: "left" - receives remaining amount after other distributions
​
distribution.precise_distribution
string
Fixed distribution amount in minor units. Takes precedence over distribution for fixed amounts.

​
Response

​
transaction_id
string
Unique identifier for the created transaction.
​
parent_transaction
string
ID of parent transaction if this is part of a distribution.
​
source
string
Source balance ID.
​
destination
string
Destination balance ID.
​
reference
string
Transaction reference.
​
amount
number
Transaction amount in major units.
​
precise_amount
string
Transaction amount in minor units (big integer).
​
amount_string
string
String representation of the amount for display purposes.
​
precision
number
Precision multiplier used for this transaction.
​
rate
number
Exchange rate applied.
​
currency
string
Currency code.
​
description
string
Transaction description.
​
status
string
Transaction status:
  • QUEUED - Pending processing
  • APPLIED - Successfully processed
  • SCHEDULED - Scheduled for future processing
  • INFLIGHT - Pending commitment
  • REJECTED - Failed validation or processing
​
hash
string
Cryptographic hash of the transaction for integrity verification.
​
allow_overdraft
boolean
Whether overdraft was allowed.
​
overdraft_limit
number
Overdraft limit applied.
​
inflight
boolean
Whether this is an inflight transaction.
​
inflight_expiry_date
string
ISO 8601 timestamp when inflight transaction expires.
​
sources
array
Source distributions with assigned transaction IDs.
​
destinations
array
Destination distributions with assigned transaction IDs.
​
created_at
string
ISO 8601 timestamp when transaction was created.
​
scheduled_for
string
ISO 8601 timestamp for scheduled processing.
​
effective_date
string
ISO 8601 timestamp of effective date.
​
meta_data
object
Custom metadata.
{
  "transaction_id": "txn_a1b2c3d4e5f6",
  "source": "bln_src123",
  "destination": "bln_dst456",
  "reference": "order-12345",
  "amount": 100.50,
  "precise_amount": "10050",
  "precision": 100,
  "currency": "USD",
  "description": "Payment for order #12345",
  "status": "APPLIED",
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2024-01-15T10:30:00Z",
  "meta_data": {
    "customer_id": "cust_123"
  }
}

curl -X POST https://api.blnkfinance.com/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 100.50,
    "reference": "order-12345",
    "currency": "USD",
    "description": "Payment for order #12345",
    "source": "bln_src123",
    "destination": "bln_dst456",
    "precision": 100
  }'

​
Precision Handling

Blnk uses big.Int internally for all amount calculations to ensure precise arithmetic without floating-point errors.

​
Amount vs PreciseAmount

  • amount: Floating-point number in major units (e.g., 100.50)
    • Converted internally: precise_amount = amount × precision
    • Limited to ~15 significant digits due to float64 precision
    • Suitable for most fiat currency transactions
  • precise_amount: String representing exact minor units (e.g., "10050")
    • No conversion needed - used directly as big.Int
    • Supports unlimited precision
    • Required for cryptocurrency and high-precision scenarios

​
Example

For $100.50 with precision 100:
  • Using amount: {"amount": 100.50, "precision": 100} → precise_amount = "10050"
  • Using precise_amount: {"precise_amount": "10050", "precision": 100} → Direct use

​
Transaction Lifecycle

​
Regular Transactions

  1. QUEUED → Transaction created and queued for processing
  2. APPLIED → Transaction successfully processed and balances updated

​
Scheduled Transactions

  1. SCHEDULED → Transaction created with future scheduled_for date
  2. QUEUED → Transaction becomes due and queued for processing
  3. APPLIED → Transaction processed

​
Inflight Transactions

  1. INFLIGHT → Transaction created with funds reserved
  2. APPLIED → Transaction committed (see Update Inflight)
  3. VOID → Transaction voided and funds released

​
Error Responses

​
error
string
Error message describing what went wrong.
​
errors
string
Validation errors from request body.

​
Common Errors

  • 400 Bad Request - Invalid request body or validation failure
    • Duplicate reference
    • Missing required fields
    • Invalid precision (must be integer)
    • Both amount and precise_amount provided
    • Neither amount nor precise_amount provided
    • Amount has >15 significant digits without using precise_amount
    • Both source and sources provided
    • Neither source nor sources provided
  • 400 Bad Request - Business logic errors
    • Insufficient balance
    • Source/destination balance not found
    • Invalid distribution (total >100% or >amount)
    • Overdraft not allowed

Build docs developers (and LLMs) love

Get started for freeTalk to us