Link a ledger account to a virtual account

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 to a ledger account through its Create API via the ledger_account parameter, or its Update API via the ledger_account_id parameter. Alternatively you could also set the ledgerable_id and ledgerable_type fields on a ledger account on create or update.

An internal account can be linked to a ledger account through its Update API via the ledger_account_id parameter, or through setting the ledgerable_id and ledgerable_type fields on a ledger account on create or update.

When a payment moves money between an internal account and 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 moves from the virtual account to the internal account, a credit IPD is created, the virtual account's ledger account will be credited and the internal account's ledger account will be debited.
  • When money moves the internal account to the virtual account, a debit IPD is created, the virtual account's ledger account will be debited and the internal account's ledger account will be credited.

Migrating to the new ledger account parameter

The legacy credit_ledger_account_id and debit_ledger_account_id fields have been deprecated. When it comes to auto-ledgering Incoming Payment Details, the new ledger_account_id on the Virtual Account is equivalent to the legacy credit_ledger_account_id, and the ledger_account_id on the Internal Account is equivalent to the legacy debit_ledger_account_id.

The new ledger account linkages overrides the legacy credit_ledger_account_id and debit_ledger_account_id:

  • If the virtual account's ledger account and the internal account's ledger account both exist, the IPD is auto-ledgered through the linkages;
  • Otherwise if the legacy credit_ledger_account_id and debit_ledger_account_id both exists, the IPD is auto-ledgered through the legacy linkages;
  • Otherwise the IPD is not auto-ledgered.