Payment Processing Blueprint

Process incoming, outgoing, and internal transfer payments with multi-currency support, reference allocation, and automatic reconciliation

   
Feature payment-processing
Category Payment
Version 1.0.0
Tags accounting, payments, reconciliation, multi-currency, erp
YAML Source View on GitHub
JSON API payment-processing.json

Actors

ID Name Type Description
accounts_user Accounts User human Creates and submits payment entries
accounting_system Accounting System system Posts GL entries, updates outstanding balances, and reconciles

Fields

Name Type Required Label Description
payment_type select Yes Payment Type  
party_type select No Party Type  
party text No Party  
paid_from text Yes Paid From Validations: minLength
paid_to text Yes Paid To Validations: minLength
paid_amount number Yes Paid Amount Validations: min
received_amount number Yes Received Amount Validations: min
source_exchange_rate number Yes Source Exchange Rate Validations: min
target_exchange_rate number Yes Target Exchange Rate Validations: min
references json No References  
mode_of_payment select No Mode Of Payment  
status select Yes Status  

States

State field: status

Values:

State Initial Terminal
draft Yes  
submitted    
cancelled   Yes

Transitions:

Name From To Actor Condition
  draft submitted accounts_user  
  submitted cancelled accounts_user  

Rules

  • balanced_entries:
    • description: Total debit must equal total credit in the GL entries generated by the payment.
  • allocation_limit:
    • description: Allocated amount against a reference cannot exceed that reference outstanding amount.
  • reference_validation:
    • description: Referenced documents must be in Submitted status before allocation. Draft or cancelled documents cannot be referenced.
  • exchange_rate_auto:
    • description: Exchange rates are auto-fetched for the posting date when source and target currencies differ.
  • party_required:
    • description: Party type and party are required for Receive and Pay payment types. Internal Transfers do not require a party.
  • internal_transfer_accounts:
    • description: Internal Transfer requires different paid_from and paid_to accounts. Same-account transfers are rejected.
  • unallocated_tracking:
    • description: Unallocated amount is tracked when payment exceeds total allocated references. Can be allocated later.
  • cancellation_reversal:
    • description: Cancellation reverses all GL entries and restores outstanding on referenced documents.

Outcomes

Process_payment (Priority: 10) | Transaction: atomic

Given:

  • payment entry is in Draft status
  • paid_amount gt 0
  • paid_from exists
  • paid_to exists

Then:

  • transition_state field: status from: draft to: submitted
  • create_record target: gl_entries — Create debit and credit GL entries for the payment
  • emit_event event: payment.submitted

Result: Payment is submitted with GL entries posted and referenced document outstanding amounts reduced

Reconcile_payment (Priority: 11)

Given:

  • payment is in Submitted status
  • references exists

Then:

  • set_field target: unallocated_amount — Calculated as paid_amount minus sum of all allocated amounts
  • emit_event event: payment.reconciled

Result: Payment is reconciled against referenced invoices with outstanding amounts updated

Cancel_payment (Priority: 12) | Transaction: atomic

Given:

  • payment is in Submitted status

Then:

  • transition_state field: status from: submitted to: cancelled
  • create_record target: gl_entries — Reverse all GL entries for this payment
  • emit_event event: payment.cancelled

Result: Payment is cancelled, GL entries reversed, and outstanding on referenced documents restored

Errors

Code Status Message Retry
PAYMENT_ALLOCATION_EXCEEDED 400 Allocated amount exceeds outstanding amount on the referenced document. No
PAYMENT_REFERENCE_INVALID 400 Referenced document does not exist or is not in a submitted state. No
PAYMENT_BALANCE_MISMATCH 500 Total debit does not equal total credit in the payment GL entries. No

Events

Event Description Payload
payment.submitted Payment entry transitions from Draft to Submitted payment_id, payment_type, party, paid_amount, received_amount
payment.cancelled Payment entry is cancelled and GL entries reversed payment_id, payment_type, party, paid_amount
payment.reconciled Payment is reconciled against one or more references payment_id, references, unallocated_amount
Feature Relationship Reason
sales-purchase-invoicing required Payments are allocated against sales and purchase invoices
general-ledger required Payment submission creates GL entries
bank-reconciliation recommended Bank statements are matched against payment entries

AGI Readiness

Goals

Reliable Payment Processing

Process incoming, outgoing, and internal transfer payments with multi-currency support, reference allocation, and automatic reconciliation

Success Metrics:

Metric Target Measurement
policy_violation_rate 0% Operations that violate defined policies
audit_completeness 100% All decisions have complete audit trails

Constraints:

  • regulatory (non-negotiable): All operations must be auditable and traceable

Autonomy

Level: supervised

Human Checkpoints:

  • before transitioning to a terminal state

Escalation Triggers:

  • error_rate > 5
  • consecutive_failures > 3

Verification

Invariants:

  • error messages never expose internal system details
  • state transitions follow the defined state machine — no illegal transitions

Tradeoffs

Prefer Over Reason
accuracy speed financial transactions must be precise and auditable

Coordination

Protocol: orchestrated

Consumes:

Capability From Fallback
sales_purchase_invoicing sales-purchase-invoicing fail
general_ledger general-ledger fail

Safety

Action Permission Cooldown Max Auto
process_payment autonomous - -
reconcile_payment autonomous - -
cancel_payment supervised - -
Extensions (framework-specific hints) ```yaml source: repo: https://github.com/frappe/erpnext project: ERPNext tech_stack: Python, Frappe Framework, MariaDB/PostgreSQL ```