Sign in
Bank transaction

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)
post/v1/banking/bank_transactions

Parameters

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

Request body

sender_idstring 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_idstring 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}

amountinteger required

Transfer amount in the smallest currency unit (cents for CLP). Must be positive.

descriptionstring required

Transaction description that will appear in bank statements and notification emails. Used as reference for both sender and recipient.

bank_key_idstring 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_idstring 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_idstring 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.

metadataobject 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.

commentsstring nullable

Optional internal notes about the transaction. These comments are stored but not sent to the bank.

lbtrboolean 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.

owner_idstring uuid nullable

Deprecated: Use sender_id instead. This field will be removed after March 12, 2025. Currently defaults to sender_id if not provided.

Example request

{
  "sender_id": "694eefdb-b45f-45a7-9aac-d2ab3c0582c4",
  "recipient_id": "8e668a4e-8485-4248-86cc-a7a2201cf8c3",
  "amount": 150000,
  "description": "Payment for services - Invoice #1234",
  "bank_key_id": "47b93e3d-36a6-423a-acbe-c23b5484c3ed",
  "bank_payroll_id": "9f8e7d6c-5b4a-3c2d-1e9f-8a7b6c5d4e3f",
  "idempotency_id": "bbbbc3af-b3db-40c0-98c9-5e6b4c05f734",
  "metadata": {
    "cost_center": "operations",
    "invoice_number": "INV-2025-001",
    "department": "finance"
  },
  "comments": "Approved by CFO on 2025-01-15",
  "payable_transactions": [
    {
      "erp_payouts_payable_id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 50000
    },
    {
      "erp_payouts_payable_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "amount": 50000
    }
  ],
  "owner_id": "694eefdb-b45f-45a7-9aac-d2ab3c0582c4"
}

Response

Transaction created successfully

idstring uuid required
owner_idstring uuid

The id of the bank account that owns the transaction. Same as sender_id if you're sending money.

sender_idstring uuid required

The id of the bank account that sends the money. Same as owner_id if you're sending money.

recipient_idstring uuid required

The id of the bank recipient that is receiving the money.

bank_payroll_idstring uuid nullable
external_idstring

the id assigned to the transaction in the bank systems

holder_idstring 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
descriptionstring
lbtrboolean

This attribute indicates that a transaction does not have an amount limit. Only available at Banco de Chile and Santander

raw_datastring nullable

the raw data stored from the banks

{"stackTrail":"paths:/v1/banking/bank_transactions:post:responses:201:content:application/json:schema:properties:metadata","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/v1/banking/bank_transactions:post:responses:201:content:application/json:schema:properties:receipt","oasType":"schema","type":"unknown"}
amountinteger required
decline_motivestring
bank_errorsItems[] — unresolved $ref
created_atstring date-time
updated_atstring date-time
authorized_atstring date-time
enqueued_atstring date-time
idempotency_idstring nullable

Changes

No recorded changes to this endpoint across all 1 revision of this API.