Postilion Management

The Postilion suite by ACI Worldwide provides capabilities across payment switching, transaction processing, and card issuing. Key components include:

Realtime payment switching
Card issuing
ATM and POS driving
Payment acquiring

Eclipse integrates tightly with Postilion to offer a unified platform with hosted services such as:

Instant Card Issuing as a Service
Acquiring and Payment as a Service
SME in-a-box Services, including Terminal Management
Rapid acceleration of Banking-as-a-Service deployments

There are various deployment options including:

Eclipse and Postilion offered as hosted services
Eclipse integrated into an existing Postilion instance

This section outlines the prerequisites and step-by-step configuration for connecting an Eclipse instance to Postilion.

Prerequisites

Before starting configuration, obtain the following from the Postilion operations team:

IP address of the Postilion host
TCP port for the ISO 8583 connection
Number of permitted simultaneous connections (sockets)
ICA number (for card issuing)
Program code(s) for any card programs being issued
HSM service name and connection details (for issuing/PIN management)

Configuration Steps Summary

Add the Postilion connection to the global sd.external.services property (service discovery)
Set the required tenant-level config keys (postilionServiceName, cardManagementSystem, etc.)
Set the postbridge.config global property with issuing/acquiring parameters
Verify connectivity using the Eclipse benchmark or a test card transaction

Service Discovery Configuration

Eclipse uses the sd.external.services global property for service discovery of external TCP connections. Add a new line entry for the Postilion connection.

Entry format:

TCPSOCKET,<serviceName>,<ip>:<port>:<handler>:<connections>, , , ,<timeoutMs>

Field	Description	Example
`TCPSOCKET`	Service type — always `TCPSOCKET` for Postilion	`TCPSOCKET`
`serviceName`	Unique name — format: `PROD` or `TEST` + `_<SystemName>_<Company>_<Country>_<DataCenter>`	`TEST_Postilion_EFTCorp_ZA_Xneelo`
`ip:port`	Postilion host IP and port	`41.87.208.234:7802`
`handler`	Always use the Postbridge handler	`com.ukheshe.eclipse.services.postbridge.transport.PostbridgeTcpsocketHandler`
`connections`	Number of simultaneous TCP connections	`1`
`timeoutMs`	Connection timeout in milliseconds	`6000`

Example sd.external.services entry:

TCPSOCKET,TEST_Postilion_EFTCorp_ZA_Xneelo,41.87.208.234:7802:com.ukheshe.eclipse.services.postbridge.transport.PostbridgeTcpsocketHandler:1, , , ,6000

For production environments, prefix the service name with PROD_ instead of TEST_. Eclipse uses this prefix to apply production-specific behaviour.

If multiple Postilion instances are needed (e.g. different card programs connecting to different hosts), add one line per instance with a unique service name.

Tenant-Level Configurations

Set these as tenant config items for each tenant that uses Postilion:

Config Key	Required	Description	Example Value
`postilionServiceName`	Yes	Service name from `sd.external.services`. Used for all programs unless a program-specific key is set.	`TEST_Postilion_EFTCorp_ZA_Xneelo`
`postilionServiceName.<programName>`	No	Program-specific service name override. Falls back to `postilionServiceName` if not set.	`postilionServiceName.Main=TEST_Postilion_EFTCorp_ZA_Xneelo`
`cardManagementSystem`	Yes (issuing)	Card management system identifier. Must be set to `Postilion` when using Postilion for issuing.	`Postilion`
`isPostilionCardManagementSystem`	Yes	Enables the Postilion card management integration.	`true`
`hsmServiceName`	Yes (issuing)	Service name of the HSM connection (also registered in `sd.external.services`).	`TEST_HSM_EFTCorp_ZW_Netone`
`postbridge.config`	No	Tenant-level override of Postbridge parameters (see Global Property Configurations below). Only set this if the tenant needs values different from the global defaults.	See below
`postilionOutboundProcessor`	No	Processor class for outbound card operations (link, update, read). Can also be set per-program: `OutboundPnPayMsgProcessor.<programname>`
`postilionUpdateNotificationProcessor`	No	Processor for inbound card event notifications from Postilion.

postilionUpdateNotificationProcessor resolution order (first match wins):

postilionUpdateNotificationProcessor.<program name in lowercase> (tenant config)
postilionUpdateNotificationProcessor (tenant config)
postilionUpdateNotificationProcessor.<institution id> (global property)
postilionUpdateNotificationProcessor (global property — default)

Global Property Configurations

The postbridge.config global property sets default Postbridge parameters that apply to all tenants unless overridden at the tenant level. Set this as a global property (not a tenant config).

Parameter	Used For	Description	Example Default
`institutionId`	Issuing	ICA (Interbank Card Association) number assigned by the card scheme	`123456`
`issuerNr`	Issuing	Issuer number within Postilion — typically `1`	`1`
`cardAcceptorTerminalId`	Acquiring	Terminal ID sent in acquiring transactions (8 characters)	`00000008`
`cardAcceptorId`	Acquiring	Card acceptor ID sent in acquiring transactions (15 characters)	`120000000000001`
`cardAcceptorNameLocation`	Acquiring	Merchant name and location string in ISO 8583 field 43	`UKHESHE RESTFUL PRETORIA ZA`
`posDataCode`	Acquiring	POS data code (ISO 8583 field 22 / DE 61)	`060000065000017`

Example postbridge.config global property value:

institutionId=123456
issuerNr=1
cardAcceptorTerminalId=00000008
cardAcceptorId=120000000000001
cardAcceptorNameLocation=UKHESHE RESTFUL PRETORIA ZA
posDataCode=060000065000017

To override any of these for a specific tenant, set the postbridge.config tenant config item with only the parameters that differ from the global defaults.