{ "feature": "clearing-house-account-management", "version": "1.0.0", "description": "Account management services for payment clearing houses — account mirroring, proxy management, real-time account verification, and check digit verification", "category": "integration", "tags": [ "clearing-house", "proxy", "account-verification", "cdv", "account-mirror", "payments" ], "actors": [ { "id": "partner_system", "name": "Partner System", "type": "system", "description": "Financial institution integrating with payment platform for clearing house services", "role": "api-consumer" }, { "id": "payment_platform", "name": "Payment Orchestration Platform", "type": "external", "description": "Payment orchestration platform — manages clearing house integration layer", "role": "platform" }, { "id": "clearing_house", "name": "Clearing House Operator", "type": "external", "description": "Automated clearing house operator — manages payment schemes and settlement", "role": "scheme-operator" } ], "fields": [ { "name": "account_number", "type": "text", "required": true, "label": "Account Number", "validation": [ { "type": "required", "message": "Account number is required" } ] }, { "name": "account_name", "type": "text", "required": false, "label": "Account Name", "validation": [ { "type": "maxLength", "value": 70, "message": "Account name must not exceed 70 characters" } ] }, { "name": "account_currency", "type": "text", "required": false, "label": "Account Currency" }, { "name": "account_type", "type": "select", "required": false, "label": "Account Type", "options": [ { "value": "CURRENT", "label": "Current" }, { "value": "SAVINGS", "label": "Savings" }, { "value": "TRANSMISSION", "label": "Transmission" }, { "value": "BOND", "label": "Bond" }, { "value": "SUBSCRIPTION_SHARE", "label": "Subscription Share" }, { "value": "OTHER", "label": "Other" } ] }, { "name": "account_status", "type": "select", "required": false, "label": "Account Status", "options": [ { "value": "ENABLED", "label": "Enabled" }, { "value": "DISABLED", "label": "Disabled" }, { "value": "DELETED", "label": "Deleted" } ] }, { "name": "proxy_type", "type": "select", "required": false, "label": "Proxy Type", "options": [ { "value": "mobile_number", "label": "Mobile Number" }, { "value": "email", "label": "Email Address" }, { "value": "id_number", "label": "ID Number" }, { "value": "custom", "label": "Custom Identifier" } ] }, { "name": "proxy_value", "type": "text", "required": true, "label": "Proxy Value", "validation": [ { "type": "required", "message": "Proxy value is required" } ] }, { "name": "proxy_namespace", "type": "text", "required": false, "label": "Proxy Namespace", "validation": [ { "type": "maxLength", "value": 40, "message": "Proxy namespace must not exceed 40 characters" } ] }, { "name": "owner_legal_name", "type": "text", "required": false, "label": "Owner Legal Name", "validation": [ { "type": "maxLength", "value": 140, "message": "Owner legal name must not exceed 140 characters" } ] }, { "name": "owner_known_as_name", "type": "text", "required": false, "label": "Owner Known-As Name", "validation": [ { "type": "maxLength", "value": 140, "message": "Owner known-as name must not exceed 140 characters" } ] }, { "name": "owner_type", "type": "select", "required": false, "label": "Owner Type", "options": [ { "value": "INDIVIDUAL", "label": "Individual" }, { "value": "ORGANISATION", "label": "Organisation" } ] }, { "name": "owner_identification", "type": "text", "required": false, "label": "Owner Identification Number", "validation": [ { "type": "maxLength", "value": 35, "message": "Owner identification must not exceed 35 characters" } ] }, { "name": "owner_identification_scheme", "type": "select", "required": false, "label": "Owner Identification Scheme", "options": [ { "value": "NIDN", "label": "National Identity Number" }, { "value": "CCPT", "label": "Passport Number" }, { "value": "DRLC", "label": "Driver's License" }, { "value": "EMPL", "label": "Employer ID" }, { "value": "SOSE", "label": "Social Security Number" }, { "value": "TXID", "label": "Tax Identification Number" }, { "value": "ARNU", "label": "Alien Registration Number" }, { "value": "CUST", "label": "Customer ID" }, { "value": "TELE", "label": "Telephone Number" }, { "value": "POID", "label": "Point of Interaction Data" } ] }, { "name": "bank_code", "type": "text", "required": false, "label": "Bank Code" }, { "name": "branch_code", "type": "text", "required": false, "label": "Branch Code" }, { "name": "record_identifier", "type": "text", "required": false, "label": "Record Identifier", "validation": [ { "type": "maxLength", "value": 50, "message": "Record identifier must not exceed 50 characters" } ] }, { "name": "iban", "type": "text", "required": false, "label": "IBAN", "validation": [ { "type": "pattern", "value": "^[A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}$", "message": "IBAN must follow ISO 13616 format" } ] }, { "name": "bicfi", "type": "text", "required": false, "label": "BIC/SWIFT Code" } ], "states": { "field": "account_status", "values": [ { "id": "enabled", "label": "Enabled", "initial": true }, { "id": "disabled", "label": "Disabled" }, { "id": "deleted", "label": "Deleted", "terminal": true } ], "transitions": [ { "from": "enabled", "to": "disabled", "actor": "partner_system", "description": "Partner disables account — suspends transaction processing" }, { "from": "disabled", "to": "enabled", "actor": "partner_system", "description": "Partner re-enables a previously disabled account" }, { "from": "enabled", "to": "deleted", "actor": "partner_system", "description": "Partner permanently removes an active account" }, { "from": "disabled", "to": "deleted", "actor": "partner_system", "description": "Partner permanently removes a disabled account" } ] }, "rules": { "account_mirror": { "use_case_a": "Platform as Secondary Store — partner manages proxies, platform mirrors for faster routing", "use_case_b": "Platform as Primary Store — platform manages proxies, partner mirrors for local resolution", "use_case_c": "No Platform Mirror — partner handles all proxy and account resolution directly", "use_case_d": "Platform as Account Mirror — for select institutions", "sync_required": "Account mirror must be kept synchronized with partner's master data", "update_schemas": "Updates sent via AccountUpdateRequest and AccountAdditionalIdUpdateRequest schemas" }, "payshap_proxy": { "uniqueness": "One proxy maps to exactly one account — duplicate registrations are rejected", "resolution_mandatory": "Proxy resolution is mandatory for inbound digital payments", "identifier_determination_inbound": "POST /identifiers/inbound/identifier-determination", "identifier_determination_outbound": "POST /identifiers/outbound/identifier-determination-report" }, "avsr": { "description": "Real-Time Account Verification Service — confirms account can receive funds", "outbound": "Partner sends verification request to platform", "inbound": "Platform sends verification request to partner", "time_limit": "Verification responses must be returned within scheme time limits" }, "cdv": { "description": "Check Digit Verification for bank accounts", "validation_required": "Account numbers must pass check digit validation before payment initiation" }, "account_types": { "standard": "Account types follow clearing house standards: OTHER, CURRENT, SAVINGS, TRANSMISSION, BOND, SUBSCRIPTION_SHARE" }, "identification": { "person_codes": "PersonIdentificationCode enum: ARNU, CCPT, CUST, DRLC, EMPL, NIDN, SOSE, TELE, TXID, POID", "organisation_codes": "OrganisationIdentificationCode enum: BANK, CBID, CHID, CINC, COID, and others per ISO 20022", "address_types": "Supported address types: ADDR, PBOX, HOME, BIZZ, MLTO, DLVY" } }, "errors": [ { "code": "ACCOUNT_BAD_REQUEST", "status": 400, "message": "Invalid account request — check required fields and formats" }, { "code": "ACCOUNT_UNAUTHORIZED", "status": 401, "message": "Authentication failed — invalid or missing credentials" }, { "code": "ACCOUNT_NOT_FOUND", "status": 404, "message": "Account not found in the system" }, { "code": "ACCOUNT_CONFLICT", "status": 409, "message": "Account conflict — duplicate proxy registration or record collision" }, { "code": "ACCOUNT_UNPROCESSABLE", "status": 422, "message": "Account request could not be processed — validation errors" }, { "code": "CDV_VALIDATION_FAILED", "status": 422, "message": "Account number failed check digit verification" }, { "code": "PROXY_NOT_FOUND", "status": 404, "message": "No account found for the given proxy" }, { "code": "PROXY_ALREADY_REGISTERED", "status": 409, "message": "Proxy is already registered to another account" }, { "code": "AVS_VERIFICATION_FAILED", "status": 422, "message": "Account verification failed" } ], "events": [ { "name": "account.mirror.updated", "description": "Account data synchronized to platform mirror", "payload": [ "account_number", "account_status", "record_identifier" ] }, { "name": "account.mirror.deleted", "description": "Account removed from platform mirror", "payload": [ "account_number", "record_identifier" ] }, { "name": "proxy.registered", "description": "New proxy registered for an account", "payload": [ "proxy_type", "proxy_value", "account_number" ] }, { "name": "proxy.deregistered", "description": "Proxy mapping removed from an account", "payload": [ "proxy_type", "proxy_value", "account_number" ] }, { "name": "proxy.resolved", "description": "Proxy successfully resolved to a bank account", "payload": [ "proxy_type", "proxy_value", "account_number", "bank_code" ] }, { "name": "avsr.verification.requested", "description": "AVS-R verification request initiated", "payload": [ "account_number", "bank_code" ] }, { "name": "avsr.verification.completed", "description": "AVS-R verification completed with result", "payload": [ "account_number", "bank_code", "account_status" ] }, { "name": "cdv.validation.requested", "description": "CDV validation request initiated for an account number", "payload": [ "account_number", "bank_code", "branch_code" ] }, { "name": "cdv.validation.completed", "description": "CDV validation completed with result", "payload": [ "account_number", "bank_code" ] } ], "outcomes": { "proxy_resolved": { "priority": 1, "given": [ { "field": "proxy_value", "source": "input", "operator": "exists", "description": "A proxy identifier is provided in the request" }, { "field": "proxy_type", "source": "input", "operator": "in", "value": [ "mobile_number", "email", "id_number", "custom" ], "description": "Proxy type is a valid identifier type" } ], "then": [ { "action": "call_service", "target": "electrum_api.resolve_proxy", "description": "Resolve proxy to its corresponding bank account via platform" }, { "action": "emit_event", "event": "proxy.resolved", "payload": [ "proxy_type", "proxy_value", "account_number", "bank_code" ] } ], "result": "Proxy resolved to bank account — routing information returned for payment processing" }, "proxy_not_found": { "priority": 2, "error": "PROXY_NOT_FOUND", "given": [ { "field": "proxy_value", "source": "input", "operator": "exists", "description": "A proxy identifier is provided" }, { "field": "proxy_value", "source": "db", "operator": "not_exists", "description": "No account mapping exists for the given proxy" } ], "then": [ { "action": "notify", "target": "partner_system", "channel": "system", "description": "Inform partner that proxy could not be resolved" } ], "result": "Proxy resolution failed — no account found for the given identifier" }, "proxy_registered": { "priority": 3, "given": [ { "field": "proxy_value", "source": "input", "operator": "exists", "description": "Proxy identifier provided for registration" }, { "field": "account_number", "source": "input", "operator": "exists", "description": "Target account number provided" }, { "field": "proxy_value", "source": "db", "operator": "not_exists", "description": "Proxy is not already registered to another account" } ], "then": [ { "action": "create_record", "type": "proxy_mapping", "target": "proxy_mapping", "description": "Create proxy-to-account mapping in the proxy registry" }, { "action": "emit_event", "event": "proxy.registered", "payload": [ "proxy_type", "proxy_value", "account_number" ] } ], "result": "New proxy registered — identifier now maps to the specified bank account" }, "proxy_already_registered": { "priority": 3, "error": "PROXY_ALREADY_REGISTERED", "given": [ { "field": "proxy_value", "source": "input", "operator": "exists", "description": "Proxy identifier provided for registration" }, { "field": "proxy_value", "source": "db", "operator": "exists", "description": "Proxy is already registered to another account" } ], "then": [ { "action": "notify", "target": "partner_system", "channel": "system", "description": "Inform partner that proxy is already in use" } ], "result": "Proxy registration rejected — identifier is already mapped to another account" }, "proxy_deregistered": { "priority": 4, "given": [ { "field": "proxy_value", "source": "input", "operator": "exists", "description": "Proxy identifier provided for deregistration" }, { "field": "proxy_value", "source": "db", "operator": "exists", "description": "Proxy mapping exists in the registry" } ], "then": [ { "action": "delete_record", "type": "proxy_mapping", "target": "proxy_mapping", "description": "Remove proxy-to-account mapping from the proxy registry" }, { "action": "emit_event", "event": "proxy.deregistered", "payload": [ "proxy_type", "proxy_value", "account_number" ] } ], "result": "Proxy deregistered — identifier no longer maps to any account" }, "account_mirror_updated": { "priority": 5, "given": [ { "field": "account_number", "source": "input", "operator": "exists", "description": "Account number provided in update request" }, { "field": "account_status", "source": "input", "operator": "in", "value": [ "ENABLED", "DISABLED" ], "description": "Account is in an updatable state" } ], "then": [ { "action": "call_service", "target": "electrum_api.update_account_mirror", "description": "Synchronize account data to platform mirror via AccountUpdateRequest" }, { "action": "emit_event", "event": "account.mirror.updated", "payload": [ "account_number", "account_status", "record_identifier" ] } ], "result": "Account data synchronized to platform mirror — routing information up to date" }, "account_mirror_deleted": { "priority": 6, "given": [ { "field": "account_number", "source": "input", "operator": "exists", "description": "Account number provided for deletion" }, { "field": "account_status", "source": "db", "operator": "in", "value": [ "ENABLED", "DISABLED" ], "description": "Account currently exists in the mirror" } ], "then": [ { "action": "call_service", "target": "electrum_api.delete_account_mirror", "description": "Remove account from platform mirror" }, { "action": "transition_state", "field": "account_status", "from": "enabled", "to": "deleted" }, { "action": "emit_event", "event": "account.mirror.deleted", "payload": [ "account_number", "record_identifier" ] } ], "result": "Account removed from platform mirror — no longer available for routing" }, "avsr_verification_success": { "priority": 7, "given": [ { "field": "account_number", "source": "input", "operator": "exists", "description": "Account number provided for verification" }, { "field": "bank_code", "source": "input", "operator": "exists", "description": "Target bank identified by clearing system member ID" } ], "then": [ { "action": "call_service", "target": "electrum_api.verify_account_avsr", "description": "Submit verification request to clearing house via platform" }, { "action": "emit_event", "event": "avsr.verification.requested", "payload": [ "account_number", "bank_code" ] }, { "action": "emit_event", "event": "avsr.verification.completed", "payload": [ "account_number", "bank_code", "account_status" ] } ], "result": "Account verified — confirmed to exist and able to receive funds" }, "avsr_verification_failed": { "priority": 8, "error": "AVS_VERIFICATION_FAILED", "given": [ { "field": "account_number", "source": "input", "operator": "exists", "description": "Account number provided for verification" }, "AVS-R response indicates account cannot receive funds" ], "then": [ { "action": "emit_event", "event": "avsr.verification.completed", "payload": [ "account_number", "bank_code", "account_status" ] }, { "action": "notify", "target": "partner_system", "channel": "system", "description": "Inform partner that account verification failed" } ], "result": "Account verification failed — account does not exist or cannot receive funds" }, "cdv_validation_passed": { "priority": 9, "given": [ { "field": "account_number", "source": "input", "operator": "exists", "description": "Account number provided for CDV check" }, { "field": "branch_code", "source": "input", "operator": "exists", "description": "Branch code provided for check digit algorithm selection" } ], "then": [ { "action": "call_service", "target": "electrum_api.validate_cdv", "description": "Submit account number for clearing house check digit verification" }, { "action": "emit_event", "event": "cdv.validation.requested", "payload": [ "account_number", "bank_code", "branch_code" ] }, { "action": "emit_event", "event": "cdv.validation.completed", "payload": [ "account_number", "bank_code" ] } ], "result": "Account number passes CDV — format and check digits are valid" }, "cdv_validation_failed": { "priority": 10, "error": "CDV_VALIDATION_FAILED", "given": [ { "field": "account_number", "source": "input", "operator": "exists", "description": "Account number provided for CDV check" }, "Account number fails check digit algorithm validation" ], "then": [ { "action": "emit_event", "event": "cdv.validation.completed", "payload": [ "account_number", "bank_code" ] }, { "action": "notify", "target": "partner_system", "channel": "system", "description": "Inform partner that account number failed CDV" } ], "result": "Account number fails CDV — invalid format or check digits" } }, "related": [ { "feature": "chp-inbound-payments", "type": "required", "reason": "Account validation and proxy resolution required for inbound routing" }, { "feature": "chp-outbound-payments", "type": "required", "reason": "CDV validation before outbound payments" }, { "feature": "chp-request-to-pay", "type": "recommended", "reason": "Proxy resolution for request-to-pay addressing" }, { "feature": "chp-eft", "type": "recommended", "reason": "Account validation for EFT transactions" } ], "agi": { "goals": [ { "id": "reliable_clearing_house_account_management", "description": "Account management services for payment clearing houses — account mirroring, proxy management, real-time account verification, and check digit verification", "success_metrics": [ { "metric": "success_rate", "target": ">= 99.5%", "measurement": "Successful operations divided by total attempts" }, { "metric": "error_recovery_rate", "target": ">= 95%", "measurement": "Errors that auto-recover without manual intervention" } ], "constraints": [ { "type": "availability", "description": "Must degrade gracefully when dependencies are unavailable", "negotiable": false } ] } ], "autonomy": { "level": "supervised", "escalation_triggers": [ "error_rate > 5" ] }, "safety": { "action_permissions": [ { "action": "proxy_resolved", "permission": "autonomous" }, { "action": "proxy_not_found", "permission": "autonomous" }, { "action": "proxy_registered", "permission": "autonomous" }, { "action": "proxy_already_registered", "permission": "autonomous" }, { "action": "proxy_deregistered", "permission": "autonomous" }, { "action": "account_mirror_updated", "permission": "supervised" }, { "action": "account_mirror_deleted", "permission": "human_required" }, { "action": "avsr_verification_success", "permission": "autonomous" }, { "action": "avsr_verification_failed", "permission": "autonomous" }, { "action": "cdv_validation_passed", "permission": "autonomous" }, { "action": "cdv_validation_failed", "permission": "autonomous" } ] }, "tradeoffs": [ { "prefer": "reliability", "over": "throughput", "reason": "integration failures can cascade across systems" } ], "coordination": { "protocol": "orchestrated", "consumes": [ { "capability": "chp_inbound_payments", "from": "chp-inbound-payments", "fallback": "degrade" }, { "capability": "chp_outbound_payments", "from": "chp-outbound-payments", "fallback": "degrade" } ] } }, "extensions": { "api": { "base_url": "https://example.com/path/payments/api/v1", "auth": "OAuth 2.0", "content_type": "application/json" }, "proxy_types": [ { "mobile_number": "Pattern: ^\\+[0-9]{1,3}-[0-9()+\\-]{1,30}$" }, { "generic_account": "1-40 characters with optional scheme and issuer" }, { "iban": "Pattern: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}" }, { "custom": "1-2048 characters with namespace" } ], "cdv": { "description": "Check Digit Verification for bank accounts", "documentation": "https://docs.electrumsoftware.com/chp/public/cdv-overview" }, "avsr": { "description": "Real-Time Account Verification Service", "documentation": "https://docs.electrumsoftware.com/chp/public/avsr-overview" } } }