Open Dashboard

Transactions

Split transactions

Move money from several balances to one, or from one balance to several.

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.

A split replaces one side of Create transaction. Send sources instead of source, or destinations instead of destination. A request that sends both is rejected with 400 TXN_VALIDATION_ERROR.

precise_amount, currency, precision, reference, and the other fields below are the same as create. They are listed once. The two sections after that only add the array that replaces the single balance.

Body

precise_amountintegerbody

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

amountfloatbody

The transaction amount as a float. Blnk multiplies amount by precision to store precise_amount. Cannot be negative. The amount field supports up to 15 digits; use precise_amount for larger values. See also: Precision.

currencystringrequiredbody

The currency of the transaction amount is in.

precisionintegerdefault 1requiredbody

Precision for the transaction’s currency. Cannot be negative. 0 means not supplied and is treated as 1. See also: Precision.

referencestringrequiredbody

The unique transaction reference number for the transaction.

descriptionstringrequiredbody

Narration of the transaction.

scheduled_forstringbody

Indicates the date and time of a scheduled transaction.

Always format the date input as ‘YYYY-MM-DDTHH:MM:SS+00:00’ (e.g., 2024-04-22T15:28:03+00:00), where +00:00 specifies the timezone. It is UTC by default.

allow_overdraftbooleandefault falsebody

Specifies whether the transaction should proceed even if the source’s balance is insufficient. If enabled and the source has less than the required amount, the balance will become negative. See also: Overdrafts

overdraft_limitfloatdefault 0body

How far below zero the source balance may go, in the same units as amount. Blnk multiplies it by precision before comparing. 0 with allow_overdraft: true means no cap, and a value above 0 rejects the transaction when the resulting balance would pass that cap (Overdrafts).

inflightbooleandefault falsebody

Specifies that the transaction should be held until certain conditions are met. See also: Create inflight.

inflight_expiry_datestringbody

Specifies the date and time when an inflight transaction should expire. Once expired, the transaction is voided and the amount is rolled back. See Schedule inflight expiry.

Always format the date input as ‘YYYY-MM-DDTHH:MM:SS+00:00’ (e.g., 2024-04-22T15:28:03+00:00), where +00:00 specifies the timezone. It is UTC by default.

inflight_commit_datestringbody

When inflight is true, the date and time when Blnk should automatically commit the inflight transaction (same ledger outcome as Update Inflight with commit). See Schedule a commit.

Always format the date input as ‘YYYY-MM-DDTHH:MM:SS+00:00’ (e.g., 2024-04-22T15:28:03+00:00), where +00:00 specifies the timezone. It is UTC by default.

effective_datestringbody

Specifies the actual date the transaction occurred. Learn more: Backdated transactions.

skip_queuebooleanbody

When true, it bypasses the default transaction queuing system and processes transactions directly. See also: Skip transaction queue.

dry_runbooleandefault falsebody

When true, Blnk projects the transaction without writing anything and returns a preview. See Dry-run a transaction.

atomicbooleandefault falsebody

Controls how Blnk processes split transactions when you use sources or destinations.

When false (default), Blnk applies each leg that can succeed and rejects legs that fail. When true, every leg succeeds together or the entire split fails. If one leg fails, Blnk refunds the legs that already processed so those movements cancel out.

Do not send sources and destinations on the same request. That combination returns 400 TXN_VALIDATION_ERROR. See Atomic processing.

meta_dataobjectbody

Additional metadata of the transaction.

Multiple sources

sourcesarrayrequiredbody

Balances sending the amount, in place of source. destination stays one balance. Each item includes:

Multiple destinations

destinationsarrayrequiredbody

Balances receiving the amount, in place of destination. source stays one balance. Each item uses the same identifier, distribution, and precise_distribution fields as sources.

Response

Fields from the request body mean the same thing in the response.

precise_amountinteger

The amount stored in the ledger in its smallest unit. When you pass amount, Blnk computes this as amount x precision. See Precision.

amount_stringstring

amount as a decimal string, so the value is not rounded. Present after Blnk applies precision. Omitted when empty.

sourcesarray

Present when the request sent sources. Each item includes transaction_id for the leg Blnk created.

destinationsarray

Present when the request sent destinations. Each item includes transaction_id for the leg Blnk created.

transaction_idstring

Unique id of the transaction.

parent_transactionstring

The transaction ID of the parent transaction. A parent transaction is one that impacts the creation of a new transaction, such as an inflight transaction, a scheduled transaction, or similar.

For instance, refunding a sample transaction A creates a new transaction B; therefore A is the parent transaction of B.

statusstring

The status of the transaction. See the following: Transaction statuses.

hashstring

Per-row SHA-256 fingerprint of the transaction’s core details. The optional global hash chain is separate and not returned in API responses. Learn more: Transaction hashing

created_atstring

Indicates the date & time the transaction was created.

meta_dataUser Object

Additional metadata of the transaction.