Ledger account transactions webhooks

Ledger account transactions

When a new ledger account transaction is created a webhook event will be sent to a specified URL with the transaction details and its origin context. This allows clients to receive real-time updates on ledger movements within their subaccounts.

Event types

ledger_account_transaction_created: This event is triggered when a new ledger account transaction is recorded for a subaccount. It includes the transaction details and the origin entity that caused the transaction.

Details by origin

The details field contains the origin entity that caused the ledger transaction. Its structure varies depending on the origin value:

Origin	Description
`subaccount_operation`	A subaccount operation (topup, withdrawal, account-to-account transfer, etc.).
`payout`	A payout to an external bank account.
`card_transaction`	A card transaction (purchase, ATM withdrawal, etc.).
`card_presentment_payment`	Final settlement of an international card transaction.
`fee`	A fee charge.
`synced_bank_transaction`	A synced bank transaction from an external bank.

When the origin is unknown, details will be null.

Nullable fields

The following fields can be null depending on the transaction:

reverts_id: null when the transaction does not revert another transaction.
reverted_by_id: null when the transaction has not been reverted.
details: null when the origin entity is unknown or not available.

Payload example

Subaccount operation (credit):

{
    "event": {
        "data": {
            "id": "ltx_5tgliBmzjZ6mpQPRbQjfKj",
            "operation_type": "credit",
            "origin": "subaccount_operation",
            "id_in_origin": "sao_3RJ9CbZLYq7r1MxH8vAm7Y",
            "amount": {
                "amount": 150000000,
                "currency": "COP"
            },
            "transaction_at": "2025-01-15T14:30:00.000000Z",
            "origin_transaction_at": "2025-01-15T14:29:55.000000Z",
            "description": "Transfer to savings account",
            "reverts_id": null,
            "reverted_by_id": null,
            "details": {
                "id": "sao_3RJ9CbZLYq7r1MxH8vAm7Y",
                "state": "successful",
                "state_reason": null,
                "operation_type": "topup",
                "origin_account_id": "lac_7MkWDrqvfosB8fzHhb1Eql",
                "destination_account_id": null,
                "amount": {
                    "amount": 150000000,
                    "currency": "COP"
                },
                "source_amount": {
                    "amount": 150000000,
                    "currency": "COP"
                },
                "target_amount": null,
                "fx_rate": null,
                "external_id": "ext-transfer-12345",
                "description": "Transfer to savings account",
                "reference": "REF-2025-001",
                "metadata": {},
                "calculated_fees": []
            }
        },
        "type": "ledger_account_transaction_created"
    },
    "timestamp": "2025-01-15T14:30:05.000000Z"
}

Payout (debit):

{
    "event": {
        "data": {
            "id": "ltx_2PVWOx9dZKJMBZw7opjrrs",
            "operation_type": "debit",
            "origin": "payout",
            "id_in_origin": "pay_5NYRqKnE17nE0MswylZzq1",
            "amount": {
                "amount": 50000000,
                "currency": "COP"
            },
            "transaction_at": "2025-01-15T16:00:00.000000Z",
            "origin_transaction_at": "2025-01-15T15:59:50.000000Z",
            "description": "Payout to external bank",
            "reverts_id": null,
            "reverted_by_id": null,
            "details": {
                "id": "pay_5NYRqKnE17nE0MswylZzq1",
                "account_id": "lac_7MkWDrqvfosB8fzHhb1Eql",
                "external_id": "ext-payout-789",
                "state": "approved",
                "state_reason": null,
                "method": "co_ach",
                "method_params": null,
                "source_amount": {
                    "amount": 50000000,
                    "currency": "COP"
                },
                "target_amount": {
                    "amount": 50000000,
                    "currency": "COP"
                },
                "description": "Payout to external bank",
                "reference": "PAY-2025-001",
                "metadata": {},
                "target": {
                    "kind": "co_bank_account",
                    "country": "CO",
                    "currency": "COP",
                    "account_type": "savings_account",
                    "account_number": "12345678901",
                    "bank_code": "007",
                    "payee": {
                        "name": "Juan Pérez",
                        "document_type": "CC",
                        "document_number": "1234567890"
                    }
                },
                "calculated_fees": [],
                "inserted_at": "2025-01-15T15:59:50.000000Z",
                "updated_at": "2025-01-15T16:00:00.000000Z"
            }
        },
        "type": "ledger_account_transaction_created"
    },
    "timestamp": "2025-01-15T16:00:05.000000Z"
}

Card transaction (debit):

{
    "event": {
        "data": {
            "id": "ltx_4kRtaBmzjZ6mpQPRbQjfKj",
            "operation_type": "debit",
            "origin": "card_transaction",
            "id_in_origin": "ctx_6WnYqKnE17nE0MswylZzq1",
            "amount": {
                "amount": 25000000,
                "currency": "COP"
            },
            "transaction_at": "2025-01-15T18:00:00.000000Z",
            "origin_transaction_at": "2025-01-15T17:59:45.000000Z",
            "description": "Card purchase",
            "reverts_id": null,
            "reverted_by_id": null,
            "details": {
                "id": "ctx_6WnYqKnE17nE0MswylZzq1",
                "type": "authorization_approved",
                "state": "approved",
                "amount": {
                    "amount": 25000000,
                    "currency": "COP"
                },
                "merchant_amount": {
                    "amount": 6250,
                    "currency": "USD"
                },
                "declination_reason": null,
                "transaction_at": "2025-01-15T17:59:45.000000Z",
                "card_id": "car_5tgliBmzjZ6mpQPRbQjfKj",
                "merchant_name": "Almacenes Exito",
                "merchant": {
                    "id": "merchant_789012345",
                    "name": "Almacenes Exito",
                    "mcc": "5411",
                    "country": "COL"
                },
                "card": {
                    "id": "car_5tgliBmzjZ6mpQPRbQjfKj",
                    "last_four": "4952"
                }
            }
        },
        "type": "ledger_account_transaction_created"
    },
    "timestamp": "2025-01-15T18:00:05.000000Z"
}

Card presentment payment (debit):

{
    "event": {
        "data": {
            "id": "ltx_8rTsaBmzjZ6mpQPRbQjfKj",
            "operation_type": "debit",
            "origin": "card_presentment_payment",
            "id_in_origin": "cpp_3WnYqKnE17nE0MswylZzq1",
            "amount": {
                "amount": 25000000,
                "currency": "COP"
            },
            "transaction_at": "2025-01-16T10:00:00.000000Z",
            "origin_transaction_at": "2025-01-15T18:00:00.000000Z",
            "description": "Card presentment settlement",
            "reverts_id": null,
            "reverted_by_id": null,
            "details": {
                "id": "cpp_3WnYqKnE17nE0MswylZzq1",
                "fx_rate": "4000.00",
                "paid_at": "2025-01-16T10:00:00.000000Z"
            }
        },
        "type": "ledger_account_transaction_created"
    },
    "timestamp": "2025-01-16T10:00:05.000000Z"
}

Fee (debit):

{
    "event": {
        "data": {
            "id": "ltx_7pQWOx9dZKJMBZw7opjrrs",
            "operation_type": "debit",
            "origin": "fee",
            "id_in_origin": "fee_2DpSchlriwoCuyGMOoIuwp",
            "amount": {
                "amount": 1500000,
                "currency": "COP"
            },
            "transaction_at": "2025-01-15T18:00:01.000000Z",
            "origin_transaction_at": "2025-01-15T18:00:00.000000Z",
            "description": "Transaction fee",
            "reverts_id": null,
            "reverted_by_id": null,
            "details": {
                "id": "fee_2DpSchlriwoCuyGMOoIuwp",
                "type": "transaction",
                "amount": {
                    "amount": 1500000,
                    "currency": "COP"
                },
                "processing_type": "card",
                "processing_subtype": "authorization",
                "tx_description": "Transaction fee",
                "state": "successful",
                "transaction_at": "2025-01-15T18:00:00.000000Z",
                "origin": "card_transaction",
                "id_in_origin": "ctx_6WnYqKnE17nE0MswylZzq1"
            }
        },
        "type": "ledger_account_transaction_created"
    },
    "timestamp": "2025-01-15T18:00:05.000000Z"
}

Synced bank transaction (credit):

{
    "event": {
        "data": {
            "id": "ltx_6kRtaBmzjZ6mpQPRbQjfKj",
            "operation_type": "credit",
            "origin": "synced_bank_transaction",
            "id_in_origin": "sbt_4NYRqKnE17nE0MswylZzq1",
            "amount": {
                "amount": 200000000,
                "currency": "COP"
            },
            "transaction_at": "2025-01-15T20:00:00.000000Z",
            "origin_transaction_at": "2025-01-15T19:55:00.000000Z",
            "description": "External bank deposit",
            "reverts_id": null,
            "reverted_by_id": null,
            "details": {
                "id": "sbt_4NYRqKnE17nE0MswylZzq1"
            }
        },
        "type": "ledger_account_transaction_created"
    },
    "timestamp": "2025-01-15T20:00:05.000000Z"
}