Create bank transaction

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)