Proxy Switch Use Cases

Eclipse enables integration with externally hosted card and switch systems - such as cards or accounts managed on a Postilion platform - through a capability known as Proxy Switch Management. This allows external cards or accounts to be managed via Eclipse's secure and fine-grained API-driven authorization framework. While it does not provide the full suite of Eclipse features like native card issuing or wallet management, it serves as a powerful modernization layer for card management systems and payment switches.

The following Proxy Switch Management functions are currently supported:

Configure and update card limits
Manage card status (e.g., block, unblock)
Link and manage accounts associated with a card
Activate new cards
Perform PIN operations (e.g., change, reset, validate)
Query card transaction history

Card Identifier

When calling these APIs typically a card identifier is required. To prevent exposure of PCI sensitive data in API calls the cardIdentifier is an encrypted field consisting of PAN, expiry and sequence number.

The algorithm for the caller to define this is:

public String encryptCardIdentifier(byte\[] key, String pan, String expiryMMYY, String sequenceNumber) {  
        String dataToEncrypt = pan + "." + (expiryMMYY == null ? "" : expiryMMYY) + "." + (sequenceNumber == null ? "" : sequenceNumber);  
        SecretKeySpec secretKeySpec = new SecretKeySpec(key, "AES");  
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");  
        cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, new GCMParameterSpec(128, new byte[16]));  
        return Base64.getEncoder().encodeToString(cipher.doFinal(dataToEncrypt));  
}

The key to be used is set in tenant config proxy.cards.aesKey and will be shared shared out of the band by the EFT onboarding team.

External System Identifier

The external service to query for the proxy cards, for example the Postilion interface, is determined by the bin of the card identifier. The EFT onboarding team will map the relevant bins to the particular external service in the global mapping property.

Prerequisites:

A valid JWT for API calls
Permission ProxyCard.CREATE/READ/UPDATE/DELETE assigned to the calling user
Tenant config proxy.cards.aesKey defined and shared with the tenant for generating a secure card identifier
Bins mapped to particular external system that is hosting the cards

Manage card program limits

Get limits

Use the get limits by card program endpoint.

Update limits

Use the update limits by card program endpoint.

Manage card limits

Get Limits

Use the get limits by card endpoint.

Update Limits

Use the update limits by card endpoint.

Manage card status

Get card status

Use the get card status endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}
    ?attemptCVV=false
    &masked=true
Authorization: Bearer {jwt}

Query parameter	Type	Default	Description
`attemptCVV`	boolean	`false`	When `true`, the response includes the card CVV retrieved from the external system
`masked`	boolean	`true`	When `false`, the unmasked PAN is returned (requires elevated permissions)

{
  "accountId": "string",
  "cardStatus": "ACTIVE",
  "lifeCycleStatus": "ACTIVATED",
  "pinStatus": "INVALID_PIN"
}

Set card status (block or unblock card)

Use the set card status endpoint.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "cardStatus": "BLOCKED",
  "blockReason": "LOST"
}

Valid cardStatus values: ACTIVE, BLOCKED.

Valid blockReason values: LOST, STOLEN, OTHER. blockReason must not be provided when setting status to ACTIVE.

Manage linked accounts

Get linked accounts

Use the get linked accounts endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts
Authorization: Bearer {jwt}

{
    "accounts": [
        {
            "accountId": "00210104203902013",
            "accountType": "92",
            "currencyCode": "924",
            "ledgerBalance": 0
        }
    ]
}

Link account to card

Use the link account to card endpoint.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "accountId": "12047675344333023",
  "accountType": "92",
  "accountTypeNominated": "92",
  "accountTypeQualifier": "1"
}

Unlink account

Use the unlink account from card endpoint.

DELETE /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts/{accountId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "accountType": "92",
  "accountTypeNominated": "92",
  "accountTypeQualifier": "1"
}

Update account linked to card

Use the update account linked to card endpoint to update the account that a card is linked to.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts/{accountId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "accountType": "92",
  "accountTypeNominated": "92",
  "accountTypeQualifier": "1",
  "updatedAccountId": "00210104203902013"
}

Activate a new card

Use the activate a new card endpoint.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "pin": "4321",
  "pinBlock": "ABC123...",
  "pinBlockFormat": "ISO0"
}

Provide either pin (plaintext, sandbox/testing only) or pinBlock + pinBlockFormat (production). Valid pinBlockFormat values: ISO0, ISO1, ISO2, ISO3, ISO4.

Pin management on a card

Generate a new pin

Use the generate a new pin endpoint.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/pin-sets
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "pin": "4321",
  "pinBlock": "ABC123...",
  "pinBlockFormat": "ISO0"
}

Change or reset pin

Use the change or reset pin endpoint.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/pin-sets
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "pin": "1234",
  "newPin": "9999",
  "pinBlock": "ABC123...",
  "pinBlockFormat": "ISO0"
}

Validate a pin

Use the validate a pin endpoint.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/validate-pins
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "accountId": "12047675344333023",
  "pin": "4321",
  "pinBlock": "ABC123...",
  "pinBlockFormat": "ISO0"
}

Balances and Mini Statements

Get the balance of a given account

Use the get balance of account endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts/{accountId}/balance
    ?accountType=92
    &currencyCode=710
Authorization: Bearer {jwt}

Query parameter	Description
`accountType`	Optional. Filters the balance by account type (e.g., `92` for cheque)
`currencyCode`	Optional. ISO 4217 numeric currency code (e.g., `710` for ZAR)

{
  "availableBalance": 0,
  "currency": "string",
  "ledgerBalance": 0,
  "timestamp": "2022-03-10T12:15:50-04:00"
}

Get the balance of a given card

Use the retrieve balance of proxy card endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/balance
Authorization: Bearer {jwt}

{
  "availableBalance": 0,
  "currency": "string",
  "ledgerBalance": 0,
  "timestamp": "2022-03-10T12:15:50-04:00"
}

Get mini statement of a given account

Use the get mini-statement of account endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts/{accountId}/mini-statement
    ?accountType=92
    &currencyCode=710
Authorization: Bearer {jwt}

Query parameter	Description
`accountType`	Optional. Filters by account type
`currencyCode`	Optional. ISO 4217 numeric currency code

[
  {
    "amount": 0,
    "currency": "string",
    "description": "string",
    "timestamp": "2022-03-10T12:15:50-04:00",
    "transactionId": "string",
    "type": "string"
  }
]

Get mini statement of a given card

Use the retrieve mini-statement of proxy card endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/mini-statement
Authorization: Bearer {jwt}

[
  {
    "amount": 0,
    "currency": "string",
    "description": "string",
    "timestamp": "2022-03-10T12:15:50-04:00",
    "transactionId": "string",
    "type": "string"
  }
]

Transaction Activities

Retrieve the full authorisation history for a proxy card. This endpoint returns a paginated list of card transactions from the external switch, including approval codes, response codes, merchant details, and settlement amounts.

Use the retrieve card activities endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/activities
    ?dateFromIncl=2026-05-01T00:00:00.000Z
    &dateToExcl=2026-05-31T23:59:59.999Z
    &dateFilterOn=transactionDate
    &limit=50
    &offset=0
Authorization: Bearer {jwt}

Query parameter	Description
`dateFromIncl`	Start of date range (inclusive), ISO 8601
`dateToExcl`	End of date range (exclusive), ISO 8601
`dateFilterOn`	`transactionDate` filters on the transaction date; omit to filter on record created date
`messageTypeId`	Filter by ISO 8583 MTI (e.g., `0100`, `0200`)
`cardBin`	Filter by card BIN
`cardLast4Digit`	Filter by last 4 digits of PAN
`transactionType`	Filter by ISO 8583 processing code
`responseCode`	Filter by ISO 8583 response code (e.g., `00` for approved)
`terminalId`	Filter by terminal ID
`merchantId`	Filter by merchant ID
`offset`	Pagination offset (default: `0`)
`limit`	Page size (default: `50`, max: `1000`)

[
  {
    "cardHistoryId": 50001,
    "maskedPan": "512345******9012",
    "mti": "0200",
    "processingCode": "000000",
    "transactionAmount": 299.00,
    "transactionCurrencyCode": "710",
    "settlementAmount": 299.00,
    "settlementCurrencyCode": "710",
    "transactionDate": "2026-05-19T09:45:00.000Z",
    "authCode": "123456",
    "responseCode": "00",
    "rrn": "123456789012",
    "merchantId": "MERCH001",
    "merchantLocation": "TAKEALOT ONLINE ZA",
    "terminalId": "TERM0001",
    "acquiringInstitutionId": "123456",
    "merchantType": "5999"
  }
]

responseCode: "00" indicates an approved transaction. See Application Error Codes for the full list of ISO 8583 response codes.

Proxy Transactions

Initiate a switch-side transaction against a proxy card. This is used for operations such as interbank transfers (ZipIt), internal transfers, and bill payments that are routed through the external card switch rather than the Eclipse wallet layer.

Use the proxy transactions endpoint.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/proxy-transactions
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "sourceAccount": "00210104203902013",
  "destinationAccount": "00210104203902099",
  "amount": 500.00,
  "operationTransactionType": "INTERNAL_TRANSFER"
}

Field	Description
`sourceAccount`	Account ID to debit
`destinationAccount`	Account ID to credit
`amount`	Transaction amount
`operationTransactionType`	Transaction type: `ZIPIT`, `BILL_PAYMENT`, or `INTERNAL_TRANSFER`

Response:

{
  "sourceAccount": "00210104203902013",
  "destinationAccount": "00210104203902099",
  "amount": 500.00,
  "operationType": "INTERNAL_TRANSFER"
}