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

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.

External accounts / Internal accounts

You can link an External Accounts or Internal Accounts to a ledger account.

When a payment order is created with these accounts, a ledger transaction will be automatically generated. This means that the money movement between a ledgerable internal account and a ledgerable external account will be accounted for and automatically ledgered.

When creating an external account in its create API, you could additionally pass in a ledger account parameter, which creates a new ledger account as well as linking it to the external account. An existing external account can also be linked to a Ledger Account in its create API via the ledgerable_id and ledgerable_type fields.

An existing internal account can only be linked to a ledger account on the ledger account creation via the ledgerable_id and ledgerable_type fields.

Note: Ledger transactions are created asynchronously, so the ledger_transaction_id will not be in the payment order response. For this information, please instead listen to the ledger_transaction.created or payment_order.auto_ledgered webhooks.