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.
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 |
posted | completed , returned , reversed | completed , returned | completed , returned | reconciled | completed , returned | completed , returned |
archived | denied , failed , cancelled | failed | archived | 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.
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.
Updated 3 months ago