Linking to other Modern Treasury objects

Overview

Payment objects in Modern Treasury represent transfers of funds at your bank. Often, in addition to transferring these funds you will want to record these transfers in your internal ledger. For example, you may want an incoming payment from a user to increment their in-app funds available, represented in the ledger.

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 has the same dollar amount on it as the ledger transaction, 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 status

Payment order status

Return status

Incoming payment detail status

Expected payment status

Reversal status

Paper item status

pending

needs approval, approved, processing, sent

pending, processing, sent

pending, returned

unreconciled

pending, processing, sent

pending, returned

posted

completed, returned

completed

completed, returned

reconciled

completed

completed, returned

archived

denied, failed, cancelled

failed

failed

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

Payment orders

There are two ways to link a ledger transaction to a payment order. As described above, you can create a new ledger transaction linked to an existing Payment Order.

Alternatively, you can create both a payment order and ledger transaction in a single API call. You can do so by using the Create Payment Order endpoint and using the ledger_transaction field.

If you link a payment order to a ledger transaction and the payment order status changes to returned, we will create a new ledger transaction tied to the corresponding Return object and reversing the entries of the original transaction.

If you link a payment order to a ledger transaction and then redraft the payment order, we will create a new ledger transaction linked to the redrafted payment order.

Expected payments

You can link an Expected Payment to a ledger transaction only if the expected payment has an exact amount (i.e. amount_upper_bound is equal to amount_lower_bound).

If a linked expected payment changes from reconciled to unreconciled, we will automatically create two new Ledger Transactions: one posted transaction reversing the entries of the original transaction, and one pending transaction linked to the now unreconciled expected payment.

Virtual accounts

If you are using Virtual Accounts, you can link any virtual account to two Ledger Accounts.

Suppose you offer a digital wallet product allowing users to deposit and withdraw money. To keep track of which users are depositing funds into your Internal Account, you would create a separate virtual account for each user. You can then tie this virtual account to two ledger accounts: one debit normal account representing your internal account balance and one credit normal account representing the user's wallet balance. If a specific user sends money to their virtual account, both of these balances will automatically increase.

A virtual account can be linked on creation to ledger accounts using the debit_ledger_account_id and credit_ledger_account_id fields. Both fields must be passed together. When a payment moves money into a virtual account, we create an incoming_payment_detail as well as a ledger_transaction referring to the incoming_payment_detail via the ledgerable_type and ledgerable_id fields.

When money enters the virtual account, the ledger account referred to by debit_ledger_account_id will be debited and the ledger account referred to be credit_ledger_account_id will be credited.


Did this page help you?