Transactions

Create transaction

Post a transaction with the Java SDK.

POST/transactions

Use blnk.transactions().create to post a transaction between a source and destination balance.

Call the method

Move money from one source balance to one destination in a single call.

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(125034)
        .precision(100)
        .currency("USD")
        .source("@WorldUSD")
        .destination("@MyBalance")
        .reference("ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .description("Customer payment")
        .allowOverdraft(false)
        .skipQueue(false));

Field	Type	Description
`precise_amount`	`Number`	Amount in minor units. Use with `precision`.
`amount`	`Number`	Float amount. Blnk applies `precision`. Use one of `amount` or `precise_amount`.
`precision`	`Number`	Precision for the currency (for example `100` for cents).
`currency`	`String`	Currency of the transaction.
`reference`	`String`	Unique reference for the transaction.
`source`	`String`	Balance sending the amount. Prefix `@` for an internal balance.
`destination`	`String`	Balance receiving the amount.
`description`	`String`	Narration of the transaction.
`allow_overdraft`	`boolean`	Allow the source balance to go negative. See Overdrafts.
`skip_queue`	`boolean`	Bypass the transaction queue and process directly.

Reserve funds without settling until you commit or void the transaction. See Create inflight.

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(10000)
        .precision(100)
        .currency("USD")
        .source("bln_28edb3e5-c168-4127-a1c4-16274e7a28d3")
        .destination("bln_ebcd230f-6265-4d4a-a4ca-45974c47f746")
        .reference("ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .description("For vacation")
        .inflight(true)
        .inflightExpiryDate("2025-03-01T00:00:00Z")
        .inflightCommitDate("2025-02-28T12:00:00Z"));

Field	Type	Description
`inflight`	`boolean`	Hold the transaction until you commit or void it.
`inflight_expiry_date`	`String`	When the inflight transaction expires and rolls back. ISO 8601 format.
`inflight_commit_date`	`String`	When Core auto-commits the inflight transaction. ISO 8601 format.

See Update inflight to commit or void.

Debit multiple sources or credit multiple destinations in one transaction. See Multiple sources and Multiple destinations.

MultipleSourcesT partnerShare = MultipleSourcesT.create()
    .identifier("bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f")
    .distribution("10%");

MultipleSourcesT fixedAmount = MultipleSourcesT.create()
    .identifier("bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d")
    .preciseDistribution("2000000");

MultipleSourcesT remainder = MultipleSourcesT.create()
    .identifier("bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b")
    .distribution("left");

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(3000000)
        .precision(100)
        .currency("USD")
        .reference("ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .description("Payment to Sarah")
        .sources(List.of(partnerShare, fixedAmount, remainder))
        .destination("bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38")
        .atomic(true));

MultipleSourcesT partnerShare = MultipleSourcesT.create()
    .identifier("bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f")
    .distribution("20%");

MultipleSourcesT fixedAmount = MultipleSourcesT.create()
    .identifier("bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d")
    .preciseDistribution("1000000");

MultipleSourcesT remainder = MultipleSourcesT.create()
    .identifier("bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b")
    .distribution("left");

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(3000000)
        .precision(100)
        .currency("USD")
        .reference("ref_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30")
        .description("Payment from Sarah")
        .source("bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38")
        .destinations(List.of(partnerShare, fixedAmount, remainder))
        .atomic(true));

Field	Type	Description
`sources`	`List`	Source legs when debiting more than one balance.
`destinations`	`List`	Destination legs when crediting more than one balance.
`sources.` `[].identifier`	`String`	Balance ID or `@` internal name for a source leg.
`destinations.` `[].identifier`	`String`	Balance ID or `@` internal name for a destination leg.
`distribution`	`String`	Percentage, fixed amount, or `left` for a split leg.
`precise_distribution`	`String`	Fixed split-leg amount in minor units.
`atomic`	`boolean`	When `true`, every leg succeeds together or the entire split fails.

Post the transaction at a future date and time. See Scheduling.

Map<String, Object> meta = Map.of(
    "sender_name", "John Doe",
    "sender_account", "00000000000");

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(10000000)
        .precision(100)
        .currency("USD")
        .source("bln_28edb3e5-c168-4127-a1c4-16274e7a28d3")
        .destination("@fees")
        .reference("ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .description("Monthly fee")
        .scheduledFor("2024-12-21T01:36:46+01:00")
        .metaData(meta));

Field	Type	Description
`scheduled_for`	`String`	Date and time to post the transaction. ISO 8601 format.
`meta_data`	`JsonNode`	Optional metadata stored on the scheduled transaction.

Record a transaction with a financial date in the past. See Backdated transactions.

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(35890)
        .precision(100)
        .currency("NGN")
        .source("@source_account")
        .destination("@destination_account")
        .reference("ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
        .description("Backdated transaction")
        .effectiveDate("2025-02-15T10:30:00Z"));

Field	Type	Description
`effective_date`	`String`	Actual date the transaction occurred. ISO 8601 format.

Preview whether a transaction would apply and how it would change balances without writing anything. See Dry-run transactions.

ApiResponse<JsonNode> preview = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(12000)
        .precision(100)
        .currency("USD")
        .source("bln_source-bal-001")
        .destination("bln_dest-bal-001")
        .reference("ref_card_settle_4821")
        .description("Card settlement")
        .dryRun(true));

Field	Type	Description
`dryRun(true)`	`boolean`	Return a preview without creating a transaction or consuming the reference.

Response

{
  "amount": 1250.34,
  "precision": 100,
  "precise_amount": 125034,
  "transaction_id": "txn_c4e70eb8-e4d6-4e04-a2e2-92a43b969e0c",
  "parent_transaction": "",
  "source": "bln_f344b673-e855-4bda-b769-3e94a02c1941",
  "destination": "bln_d5cbde84-d20a-485b-8ce8-6677d782c3a1",
  "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "currency": "USD",
  "description": "Customer payment",
  "status": "QUEUED",
  "hash": "0b9c25fb5b00d6c71cb4ca87026bf6dc316e63353d3330deb588bd0b3d74dcc0",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2024-11-26T09:33:35.265582042Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z"
}

{
  "amount": 100,
  "precision": 100,
  "precise_amount": 10000,
  "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "parent_transaction": "",
  "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
  "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
  "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "currency": "USD",
  "description": "For vacation",
  "status": "INFLIGHT",
  "hash": "8cfdc0f2562ce30c3728ef624dc29fbd0e4207c77df9220df0c699d45de0eef",
  "allow_overdraft": false,
  "inflight": true,
  "created_at": "2024-12-21T01:36:46.997063436Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "2025-03-01T00:00:00Z",
  "inflight_commit_date": "2025-02-28T12:00:00Z"
}

{
  "precise_amount": 3000000,
  "amount": 30000,
  "precision": 100,
  "transaction_id": "txn_0b59f6e6-6c4a-4efa-915c-526f77ef61ab",
  "parent_transaction": "",
  "source": "",
  "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "currency": "USD",
  "description": "Payment to Sarah",
  "status": "QUEUED",
  "hash": "8cfdc0f2562ce30c3728ef624dc29fbd0e4207c77df9220df0c699d45de0eef",
  "allow_overdraft": false,
  "inflight": false,
  "atomic": true,
  "sources": [
    {
      "identifier": "bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f",
      "distribution": "10%",
      "transaction_id": "txn_59347177-aa7e-d8ad-9f4f-d09628b32ec3"
    },
    {
      "identifier": "bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d",
      "distribution": "2000000",
      "transaction_id": "txn_7ddc8d4f-3b77-4b7d-a37f-240216ab074c"
    },
    {
      "identifier": "bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b",
      "distribution": "left",
      "transaction_id": "txn_5aad04dd-ed53-4f77-9f01-4916d31fac5f"
    }
  ],
  "destination": "bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38",
  "created_at": "2025-09-18T01:26:30.648049042Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z"
}

{
  "precise_amount": 3000000,
  "amount": 30000,
  "precision": 100,
  "transaction_id": "txn_8a3c1f2e-9d4b-4e5a-b6c7-1d2e3f4a5b6c",
  "parent_transaction": "",
  "source": "bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38",
  "reference": "ref_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
  "currency": "USD",
  "description": "Payment from Sarah",
  "status": "QUEUED",
  "hash": "8cfdc0f2562ce30c3728ef624dc29fbd0e4207c77df9220df0c699d45de0eef",
  "allow_overdraft": false,
  "inflight": false,
  "atomic": true,
  "destinations": [
    {
      "identifier": "bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f",
      "distribution": "20%",
      "transaction_id": "txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94"
    },
    {
      "identifier": "bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d",
      "distribution": "1000000",
      "transaction_id": "txn_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30"
    },
    {
      "identifier": "bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b",
      "distribution": "left",
      "transaction_id": "txn_a1b2c3d4-6e2d-4f89-a17b-3d5e8f2a1c94"
    }
  ],
  "created_at": "2025-09-18T01:26:30.648049042Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z"
}

{
  "amount": 100000,
  "precision": 100,
  "precise_amount": 10000000,
  "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "parent_transaction": "",
  "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
  "destination": "bln_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "currency": "USD",
  "description": "Monthly fee",
  "status": "QUEUED",
  "hash": "0b9c25fb5b00d6c71cb4ca87026bf6dc316e63353d3330deb588bd0b3d74dcc0",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2024-12-21T01:36:46.997063436Z",
  "scheduled_for": "2024-12-21T01:36:46+01:00",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z",
  "meta_data": {
    "sender_name": "John Doe",
    "sender_account": "00000000000"
  }
}

{
  "amount": 358.9,
  "precision": 100,
  "precise_amount": 35890,
  "transaction_id": "txn_c62f200b-905f-4983-a349-cadd279234aa",
  "parent_transaction": "",
  "source": "bln_a03ef6af-1e5d-46a8-86a9-5fb1f2286f66",
  "destination": "bln_68be0aed-383c-4d27-87db-fb0650093686",
  "reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "currency": "NGN",
  "description": "Backdated transaction",
  "status": "APPLIED",
  "hash": "0b9c25fb5b00d6c71cb4ca87026bf6dc316e63353d3330deb588bd0b3d74dcc0",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2025-03-02T15:30:45Z",
  "effective_date": "2025-02-15T10:30:00Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z"
}

{
  "dry_run": true,
  "would_apply": true,
  "status": "APPLIED",
  "reference": "ref_card_settle_4821",
  "currency": "USD",
  "amount": 120,
  "precise_amount": "12000",
  "precision": 100
}

Field	Type	Description
`transaction_id`	`String`	Unique ID for the transaction.
`status`	`String`	Transaction status (for example `QUEUED`, `APPLIED`).
`precise_amount`	`Number`	`amount` × `precision`.
`source`	`String`	Resolved source balance.
`destination`	`String`	Resolved destination balance.
`hash`	`String`	Hash of the transaction details.
`created_at`	`String`	Date and time the transaction was created.