Transactions

Create transaction

Post a transaction with the TypeScript 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.

const response = await blnk.Transactions.create({
  precise_amount: 125034,
  precision: 100,
  currency: 'USD',
  source: '@WorldUSD',
  destination: '@MyBalance',
  reference: 'ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
  description: 'Customer payment',
  allow_overdraft: false,
  skip_queue: 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.

const response = await blnk.Transactions.create({
  precise_amount: 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,
  inflight_expiry_date: '2025-03-01T00:00:00Z',
  inflight_commit_date: '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.

const response = await blnk.Transactions.create({
  precise_amount: 3000000,
  precision: 100,
  currency: 'USD',
  reference: 'ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
  description: 'Payment to Sarah',
  sources: [
    {
      identifier: 'bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f',
      distribution: '10%',
    },
    {
      identifier: 'bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d',
      precise_distribution: '2000000',
    },
    {
      identifier: 'bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b',
      distribution: 'left',
    },
  ],
  destination: 'bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38',
  atomic: true,
});

const response = await blnk.Transactions.create({
  precise_amount: 3000000,
  precision: 100,
  currency: 'USD',
  reference: 'ref_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30',
  description: 'Payment from Sarah',
  source: 'bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38',
  destinations: [
    {
      identifier: 'bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f',
      distribution: '20%',
    },
    {
      identifier: 'bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d',
      precise_distribution: '1000000',
    },
    {
      identifier: 'bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b',
      distribution: 'left',
    },
  ],
  atomic: true,
});

Field	Type	Description
`sources`	`object[]`	Source legs when debiting more than one balance.
`destinations`	`object[]`	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.

const response = await blnk.Transactions.create({
  precise_amount: 10000000,
  precision: 100,
  currency: 'USD',
  source: 'bln_28edb3e5-c168-4127-a1c4-16274e7a28d3',
  destination: '@fees',
  reference: 'ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
  description: 'Monthly fee',
  scheduled_for: '2024-12-21T01:36:46+01:00',
  meta_data: {
    sender_name: 'John Doe',
    sender_account: '00000000000',
  },
});

Field	Type	Description
`scheduled_for`	`string`	Date and time to post the transaction. ISO 8601 format.
`meta_data`	`Record<string, unknown>`	Optional metadata stored on the scheduled transaction.

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

const response = await blnk.Transactions.create({
  precise_amount: 35890,
  precision: 100,
  currency: 'NGN',
  source: '@source_account',
  destination: '@destination_account',
  reference: 'ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
  description: 'Backdated transaction',
  effective_date: '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.

const preview = await blnk.Transactions.create({
  dry_run: true,
  precise_amount: 12000,
  precision: 100,
  currency: 'USD',
  source: 'bln_source-bal-001',
  destination: 'bln_dest-bal-001',
  reference: 'ref_card_settle_4821',
  description: 'Card settlement',
});

Field	Type	Description
`dry_run`	`true`	Return a `TransactionPreview` without creating a transaction or consuming the reference.

Pass dry_run: true inline, as shown above, to infer the preview response. If the request is declared separately, type it as DryRun<CreateTransactions<T>>.

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,
  "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"
    }
  ]
}

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.