Domain GL Posting

Domain-driven GL posting is not the same as immediate GL posting.

When a domain procedure calls post_domain_transaction_to_gl_v2, the call can end in one of several GL outcomes:

• POSTED
• PENDING_APPROVAL
• SCHEDULED_FUTURE_POST
• REJECTED
• FAILED

The domain must treat only POSTED as a final accounting outcome.

Core Rule

Do not apply irreversible domain effects just because post_domain_transaction_to_gl_v2 returned successfully.

Success only means the GL orchestration call itself completed.

The actual GL outcome is exposed through:

• @post_domain_transaction_to_gl_v2_draft_status
• @post_domain_transaction_to_gl_v2_draft_batch_id
• @post_domain_transaction_to_gl_v2_gl_batch_id
• @post_domain_transaction_to_gl_v2_should_apply_domain_effects_now

Recommended Pattern

1. Create the domain transaction first in a pending domain state.
2. Call post_domain_transaction_to_gl_v2.
3. Read @post_domain_transaction_to_gl_v2_draft_status.
4. Branch by outcome:
   • POSTED: either apply domain effects immediately, or let a registered on_posted callback do it
   • PENDING_APPROVAL: keep the domain transaction pending and wait
   • SCHEDULED_FUTURE_POST: keep the domain transaction pending and wait for the future date
   • REJECTED: mark the domain transaction rejected or failed
   • FAILED: roll back or keep the domain transaction failed, based on domain policy

Callback Model

The GL engine now supports optional domain callbacks stored with the idempotency record.

Pass them in the submit payload:

{
  "callbacks": {
    "on_posted_callback_id": "my_domain_finalize_after_gl_post_v2",
    "on_rejected_callback_id": "my_domain_reject_after_gl_reject_v2",
    "payload": {
      "domain_transaction_id": 123,
      "domain_entity": "MY_DOMAIN_TXN"
    }
  }
}

Both callback procedures must accept a single JSON parameter.

The engine invokes:

• on_posted_callback_id when the batch finally reaches POSTED
• on_rejected_callback_id when an approval-routed batch is rejected

That includes:

• immediate domain posts
• post-after-approval
• scheduled future posting when the due date arrives

Callback Payload

The callback receives the original callbacks.payload merged with GL metadata such as:

• source_system
• source_module
• source_txn_id
• draft_batch_id
• gl_batch_id
• gl_outcome
• gl_status
• actioned_by
• business_unit_id
• comment

Use that payload to finalize the domain safely.

When To Use Callbacks

Use callbacks when the domain has side effects that must happen only after final GL success, for example:

• crediting or debiting a deposit account
• changing account balances or lifecycle state
• releasing or consuming a facility limit
• writing settlement links or downstream artifacts

Do not perform those effects directly after a PENDING_APPROVAL or SCHEDULED_FUTURE_POST outcome.

Domain Approval vs GL Approval

Some domains already have their own approval.

Recommended order:

1. Domain approval first
2. Domain action becomes ready for accounting
3. Call post_domain_transaction_to_gl_v2
4. If GL also requires approval, wait for the GL callback outcome

Do not mix unfinished domain approval and unfinished GL approval in one half-posted transaction.

Loan / Deposit Example

Unsafe pattern:

• loan disbursement calls GL
• GL returns PENDING_APPROVAL
• procedure immediately credits deposit account and marks loan POSTED

Safe pattern:

• loan transaction stays PENDING
• GL batch goes to PENDING_APPROVAL
• no deposit credit happens yet
• after final GL post, on_posted callback credits the deposit account and marks the loan transaction POSTED
• if GL is rejected, on_rejected callback marks the loan transaction FAILED

Procedure Registry

For governance, register reusable callback procedures in the system procedure registry as approved system or utility procedures.

Recommended metadata:

• proc_type: SYSTEM or UTILITY
• domain: the owning domain, such as LOANS or DEPOSITS
• tags including GL_DOMAIN_CALLBACK

Practical Guidance

• Keep the main domain procedure responsible for validation and domain transaction creation.
• Keep final side effects in callback procedures.
• Make callbacks idempotent.
• Make rejection callbacks safe when no domain side effects were applied yet.
• Prefer one domain transaction ID in the callback payload rather than many loosely related keys.

Related Pages

• GL Posting Approval
• Posting Dates and Periods
• Back-Office Posting