Proxy Card Use Cases

Eclipse enables integration with externally hosted card systems - such as cards managed on a Postilion platform - through a capability known as Proxy Card Management. This allows external cards 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.

The following Proxy Card 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)

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 toEncrypt = 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} 

{
    "cardStatus": "ACTIVE"
}

Set card status (block or unblock card)

Use the set card status endpoint.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}
{
  "cardStatus": "BLOCKED",
  "blockReason": "LOST"
}

Manage linked accounts

Get linked accounts

Use the get linked accounts endpoint.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/accounts

{
    "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
{
  "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}
{
  "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}
{
  "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}
{
  "pin": "4321"
}

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
{
  "pin": "4321"
}

Change or reset pin

Use the change or reset pin endpoint.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/pin-sets
{
  "newPin": "9999",
  "pin": "1234"
}

Validate a pin

Use the validate a pin endpoint.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/proxy-cards/{cardIdentifier}/validate-pin
{
  "accountId": "12047675344333023",
  "pin": "4321"
}