---
title: "Create bank transaction"
method: POST
path: "/v1/banking/bank_transactions"
tags: ["Bank transaction"]
---

# Create bank transaction

`POST /v1/banking/bank_transactions`

Creates a new bank transaction to transfer money between accounts. This endpoint handles both individual transactions and payroll-associated transactions with comprehensive validation and automatic processing.

## Transaction Workflow

### Individual Transactions (without payroll)
1. Transaction is created with status `draft` and transition `enqueue`
2. Automatically enqueued for processing at the bank
3. Bank processes the transaction (approval/decline)
4. Status updates to `approved` or `declined` accordingly

### Payroll Transactions (with bank_payroll_id)
1. Transaction is created with status `draft` and no transition
2. Remains attached to the payroll batch
3. Processed when the entire payroll is authorized
4. Cannot be individually enqueued

## Prerequisites

Before creating a transaction, you need:

1. **Bank Account (sender_id)**: The source account for the transfer
   - Must be an account you have access to through a bank key
   - Find available accounts: `GET /v1/banking/bank_accounts`
   - Account must have sufficient funds

2. **Bank Recipient (recipient_id)**: The destination for the transfer
   - Must be pre-registered and approved (status: `approved`)
   - Find recipients: `GET /v1/banking/bank_recipients?sender_id={account_id}`
   - Recipients with status `draft` or `enrolled` cannot receive individual transactions
   - Recipients with any status can receive payroll transactions

3. **Bank Key (bank_key_id)**: Authentication for the bank operation
   - Must be a valid key associated with the sender account
   - Find available keys: `GET /v1/banking/bank_keys`

## Validation Rules

- **Amount**: Must be a positive integer (in cents)
- **Description**: Required field for transaction reference
- **Recipient Status**: Must be `approved` for individual transactions (unless part of payroll)
- **Payroll Status**: If provided, payroll must be in `draft` status without transition
- **Idempotency**: Optional UUID to prevent duplicate transactions per sender account

## Special Features

### Idempotency Protection
Prevents accidental duplicate transactions by providing a unique `idempotency_id`. The combination of `sender_id` + `idempotency_id` must be unique. Retrying with the same combination will fail with a 422 error.

### Metadata Storage
Store custom data in the `metadata` field for your own tracking purposes (e.g., cost centers, reference numbers, internal codes).

### Payable Associations (Pay Product)
If you have the Pay product activated, you can associate the transaction with invoices/payables using the `payable_transactions` parameter. This links payments to specific invoices for reconciliation.

### LBTR Transfers
For high-value transfers at Banco de Chile and Santander, set `lbtr: true` to bypass amount limits.

## Important Notes

- Regular users can only create transactions from accounts they have access to
- The transaction will be automatically enqueued unless it's part of a payroll
- Email notifications are sent based on company settings
- All amounts are in the smallest currency unit (cents for CLP)
- Comments field is for internal notes (not sent to the bank)

## Parameters

- `#/paths/~1v1~1banking~1bank_keys/get/parameters/0` — unresolved $ref

## Request body

- BankTransactionCreate
  - `sender_id` string, uuid, required — The ID of the source bank account for the transfer. Must be an account you have access to through a bank key. Find available accounts: GET /v1/banking/bank_accounts
  - `recipient_id` string, uuid, required — The ID of the bank recipient who will receive the transfer. Must be pre-registered and approved (status: 'approved') for individual transactions. Find recipients: GET /v1/banking/bank_recipients?sender_id={account_id}
  - `amount` integer, required — Transfer amount in the smallest currency unit (cents for CLP). Must be positive.
  - `description` string, required — Transaction description that will appear in bank statements and notification emails. Used as reference for both sender and recipient.
  - `bank_key_id` string, uuid, required — The ID of the bank key used to authenticate this operation. Must be associated with the sender account. Find available keys: GET /v1/banking/bank_keys
  - `bank_payroll_id` string, uuid, nullable — Optional ID of a payroll batch to associate this transaction with. When provided: - Transaction is created as draft without transition - Transaction is processed when payroll is authorized - Recipient can have any status (not just approved) Find payrolls: GET /v1/banking/bank_payrolls?sender_id={account_id}
  - `idempotency_id` string, uuid, nullable — Optional UUID to prevent duplicate transactions. The combination of sender_id + idempotency_id must be unique. Useful for safely retrying requests without creating duplicates.
  - `metadata` object, nullable — Optional JSON object for storing custom data. Use for internal tracking, cost centers, reference numbers, etc. This data is preserved but not processed by the banking system.
  - `comments` string, nullable — Optional internal notes about the transaction. These comments are stored but not sent to the bank.
  - `lbtr` boolean, nullable — Enable LBTR (Large-value Transfer System) for high-value transfers without amount limits. Only available for Banco de Chile and Santander. Default is false.
  - `payable_transactions` object[], nullable — Optional array to link this transaction to invoices/payables (requires Pay product). Each item associates a portion of the transaction amount with a specific payable for reconciliation.
    - `erp_payouts_payable_id` string, uuid, required — The ID of the payable/invoice to pay
    - `amount` integer, required — Amount to allocate to this payable (in cents)
  - `owner_id` string, uuid, nullable — Deprecated: Use sender_id instead. This field will be removed after March 12, 2025. Currently defaults to sender_id if not provided.

## Response `201`

Transaction created successfully

- object
  - `id` string, uuid, required
  - `owner_id` string, uuid — The id of the bank account that owns the transaction. Same as sender_id if you're sending money.
  - `sender_id` string, uuid, required — The id of the bank account that sends the money. Same as owner_id if you're sending money.
  - `recipient_id` string, uuid, required — The id of the bank recipient that is receiving the money.
  - `bank_payroll_id` string, uuid, nullable
  - `external_id` string — the id assigned to the transaction in the bank systems
  - `holder_id` string, uuid — the id of the company that owns this bank transaction
  - `status` 'draft' | 'enqueued' | 'dequeued' | 'preauthorized' | 'declined' | 'approved', required
  - `transition` 'enqueue' | 'dequeue' | 'authorize' | 'preauthorize' | 'remove', nullable
  - `description` string
  - `lbtr` boolean — This attribute indicates that a transaction does not have an amount limit. Only available at Banco de Chile and Santander
  - `raw_data` string, nullable — the raw data stored from the banks
  - `metadata` unknown
  - `receipt` unknown
  - `amount` integer, required
  - `decline_motive` string
  - `bank_errors` Items[] — unresolved $ref
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `authorized_at` string, date-time
  - `enqueued_at` string, date-time
  - `idempotency_id` string, nullable

## Other responses

- `401` — Unauthorized. Two response shapes are possible on this endpoint: - **Shared auth / `company-id` guard** (missing/invalid `Authorization`, missing `company-id`): **empty body**. Branch on the status code, not the body. - **Action-level guard** (admin-only mutation, company-scope mismatch on `bank_transactions`): JSON body `{"message": "Unauthorized (401)"}`. Parse defensively (treat the body as opaque text and skip `JSON.parse` when empty). See [Errors](https://docs.cardda.com/docs/errors) for the full guard catalogue.
- `422` — Unprocessable Entity - Validation errors

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) · [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardda/banking-api/revisions/ff1aeb3fda8b/schema)