Terminal Use Cases

Eclipse supports a wide range of terminal card-present payment options. Three main use cases are currently supported:

1. Card Present Payment Processing

In this scenario, the tenant manages its own POS terminals and uses Eclipse purely for card-present payment processingto an acquiring bank.

2. Terminal Driving with Nexo-Supported Devices

Here, terminal management is handled on the EFT platform. Merchants use API calls for Eclipse to trigger card payments to be initiated on POS terminals. Eclipse supports the Nexo interface, where terminals register with Eclipse on power-up and can be triggered to initiate a payment. Payments are processed from the terminal through termApp.ISO to the EFT Postilion platform and sent to the acquiring bank.

This can be useful for unattended terminals where payments are initiated from another device or for any scenario where you would want to initiate a payment from a particular terminal using API calls. Example use cases:

• Initiating payments through unattended POS terminals for scenarios like EV charging or parking payments
• Initiating a payment through a website or teller that then initiates payment completion through a POS terminal

3. Terminal Driving with Terminals Running the EFT Application

This scenario is identical to the Nexo-based terminal driving scenario - the only difference is that the POS application and Eclipse are EFT-controlled. This means that the communication protocol to drive the terminal can be broader and support custom features not necessarily supported in the Nexo standard.

📘

Note

Depending on the terminals and acquiring bank, L3 device certification may be required.

Card Present Payment Processing

Supported Transaction Types

• purchase
• cashback
• pre-auth
• pre-auth-extension
• pre-auth-completion
• refund
• balance-enquiry

Prerequisites

• Valid JWT
• Merchant account configured on the EFT platform and card present link to acquiring bank

To initiate a card-present payment, use the GLOBAL_POS_ACQUIRING payment type. Full EMV card details are included in the paymentCardData field.

{
  "amount": 10,
  "currency": "ZAR",
  "description": "string",
  "destinationWalletId": 0,
  "expires": "2022-03-10T12:15:50-04:00",
  "externalUniqueId": "string",
  "paymentCardData": {
    "accountType": "string",
    "alias": "string",
    "applicationIdentifier": "string",
    "cardSequenceNumber": "string",
    "cardholderName": "string",
    "cardholderVerificationMethodList": "string",
    "cvv": "string",
    "expiry": "mmyy",
    "pan": "stringstring",
    "track2Data": "string"
  },
  "paymentMechanism": "CARD",
  "paymentSecurityData": {
    "applicationInterchangeProfile": "string",
    "applicationTransactionCounter": "string",
    "authorisationRequestCryptogram": "string",
    "cavv": "string",
    "cryptogram": "stringstri",
    "cryptogramInformationData": "string",
    "eciFlag": "st",
    "eciIndicator": "string",
    "encryptedData": "string",
    "errorNo": 0,
    "issuerApplicationData": "string",
    "pinData": "stringstri",
    "pinDataType": "string",
    "rsaPinBlockPublicKeySerial": "string",
    "signatureVerification": "s",
    "unpredictableNumber": "string",
    "xid": "string"
  },
  "paymentTerminalData": {
    "amountOtherNumeric": 0,
    "cardholderVerificationMethodResults": "string",
    "deviceMake": "string",
    "formFactorIndicator": "string",
    "pointOfServiceEntryMode": "string",
    "terminalCapabilities": "string",
    "terminalCountryCode": "string",
    "terminalId": "string",
    "terminalType": "string",
    "terminalVerificationResult": "string",
    "transactionType": "string"
  },
  "reference": "string",
  "replyPolicy": "WHEN_COMPLETE",
  "type": "GLOBAL_POS_ACQUIRING"
}

Example response:

{
  "paymentId": 54726,
  "externalUniqueId": "rhfabcdfggthygfgfgh",
  "status": "PENDING",
  "amount": 6000,
  "description": "EFT Corp Test 2021 : Transaction Details",
  "merchantName": "EFT Corp Test 2021",
  "currency": "ZAR",
  "partialPaymentAllowed": false,
  "additionalFields": [],
  "acceptedCardSchemes": ["MASTER", "VISA", "MAESTRO", "AMEX"],
  "completionUrl": "https://eclipse-java-sandbox.ukheshe.rocks/t/wXYR37",
  "paymentType": "CARD",
  "created": "2023-06-27T09:03:05.000Z",
  "lastModified": "2023-06-27T09:03:07.992Z",
  "paymentData": "6481005932",
  "paymentInstrumentInfo": {
    "cardPhone": "27723891234"
  },
  "fee": 0,
  "customerId": 1901324,
  "gatewayTransactionId": "MP-PR-44134774"
}

📘

Note

The payment endpoint supports both synchronous and asynchronous modes. See Synchronous vs Asynchronous Payment Calls

Terminal Driving and Card Present Payment Processing

When using Eclipse to drive a terminal for card-present payments, the terminal must be configured to register with Eclipse on power-up.

The same GLOBAL_POS_ACQUIRING payment type is used, but no paymentCardData is included—card details are captured directly by the device.

Supported Transaction Types

• purchase
• cashback
• pre-auth
• pre-auth-extension
• pre-auth-completion
• refund
• balance-enquiry

Prerequisites

• Valid JWT
• Merchant account configured on the EFT platform and card present link to acquiring bank
• Terminals added to the EFT payment platform
• Terminals configured to register with Eclipse on startup

To initiate a terminal driving card-present payment, use the GLOBAL_POS_ACQUIRING payment type - the paymentCardData field is not populated which triggers Eclipse to initiate a payment on the terminal to capture the card details and process the payment.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/payments
{
  "paymentTerminalData": {
    "terminalId": "12345"
  },
  "type": "GLOBAL_POS_ACQUIRING",
  "amount": 100,
  "callbackUrl": "www.google.com",
  "currency": "ZAR",
  "destinationWalletId": 1234,
  "externalUniqueId": "2353464576y4567567567"
}

📘

Note:

How Eclipse initiates the payment depends on the terminal type:

• Terminals of type NEXO use the Nexo interface.
• Terminals of type EFT use the EFT interface.

Session Key Management

Eclipse supports the retrieval of session PIN keys for terminals. This requires a Terminal Master Key (TMK) exchange ceremony between the merchant and the EFT platform.

When a merchant calls the session key API for a specific terminal ID:

• Eclipse generates a random HSM key, encrypted under the merchant’s TMK.
• The encrypted key is stored under the terminal on Eclipse.
• When a payment is received for that terminal, Eclipse uses this key to translate the PIN block before sending it to the acquiring bank.

Prerequisites

• Valid JWT
• Terminal created on Eclipse
• TMK exchange ceremony between EFT and merchant

Use the sessionKeys API to request a session key for a terminal:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/session-keys
{
  "mode": "RANDOM_TERMINAL_KEY_UNDER_TMK",
  "terminalId": 123235
}

Example response:

{
  "terminalId": "12345",
  "encryptedSessionKey": "wegtersgtghbdf"
}