Link Ledger Transaction to Payments


Ledger Transactions often represent payments in other systems. In these cases, the Ledger Transaction should reflect the amount and status of the external payment.

Payments Outside Modern Treasury

If a payment is executed in another system outside Modern Treasury, you can use a Ledger Transaction to represent this payment.

When the payment is updated, executed, or cancelled in the external system, your system can use the Update Ledger Transaction endpoint to update, post, or archive the underlying Ledger Transaction.

Metadata fields can be used to attach external system IDs and other references to the Ledger Transaction.

Payments in Modern Treasury

Payment objects in Modern Treasury can also be recorded in your internal ledger. For example, you may want a Payment to a user to decrement their in-app funds represented in the ledger.

If you link a Modern Treasury payment to a Ledger Transaction, Modern Treasury will handle reflecting any changes in the payment lifecycle on the Ledger Transaction.

Linking After Payment Object Creation

Ledger Transactions can be linked to other Modern Treasury objects using the fields ledgerable_type and ledgerable_id.

ledgerable_type can be one of payment_order, incoming_payment_detail, expected_payment, return, reversal, or paper_item. You can link an object to a ledger transaction if it is within the same environment as the ledger transaction and it is not already tied to a different ledger transaction.

Linked Statuses

After a payment object is created, you can create a new ledger transaction linked to that object by specifying ledgerable_type and ledgerable_id.

If a ledger transaction is linked to another object, we will automatically update the ledger transaction's status based on the status of the linked object. The table below shows how different object statuses correspond to ledger transaction statuses.

Ledger transaction statusPayment order statusReturn statusIncoming payment detail statusExpected payment statusReversal statusPaper item status
pendingneeds approval, approved, processing, sentpending, processing, sentpending, returnedunreconciledpending, processing, sentpending
postedcompleted, returned, reversedcompleted, returnedcompleted, returnedreconciledcompleted, returnedcompleted, returned
archiveddenied, failed, cancelledfailedarchivedfailed

After you link a ledger transaction to another object, you will no longer be able to manually update the ledger transaction's status.