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 can be one of
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.
After a payment object is created, you can create a new ledger transaction linked to that object by specifying
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|
After you link a ledger transaction to another object, you will no longer be able to manually update the ledger transaction's status.
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
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.
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
If a linked expected payment changes from
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.
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
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
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.
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
An existing internal account can only be linked to a ledger account on the ledger account creation via the
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
Updated 3 months ago