--- updatedAt: 2026-05-29T13:25:42.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Get a card by ID Retrieves a card by ID. To receive an unmasked PAN and CVV (masked=false), the caller must be the cardholder using their own JWT or a valid card access password (CAP). This endpoint must only be called from the cardholder's device when unmasked data is requested. # OpenAPI definition ```json { "servers": [ { "url": "https://eclipse-java-sandbox.ukheshe.rocks", "description": "Eclipse sandbox environment" }, { "url": "https://ukheshe.live", "description": "Eclipse production environment" }, { "url": "https://eclipse-java-develop.ukheshe.rocks", "description": "Eclipse development environment" }, { "url": "https://zw.ukheshe.live", "description": "Zim Eclipse production environment" } ], "openapi": "3.1.0", "components": { "schemas": { "Avp": { "description": "An attribute/value pair for providing weakly typed data on various messages", "type": "object", "required": [ "att", "val" ], "properties": { "att": { "type": "string", "pattern": "\\S" }, "val": { "type": "string" } } }, "CardRules": { "description": "Specific rules on what the card can and cannot do", "type": "object", "properties": { "ecommerceTransactionsEnabled": { "type": "boolean", "description": "eCommerce transactions allowed or not" }, "internationalTransactionsEnabled": { "type": "boolean", "description": "International transactions allowed or not" } } }, "CardStatus": { "description": "Status of the card ACTIVE:Can be used, STOPPED is temporarily blocked from use. CANCELLED is permanently disabled.", "type": "string", "enum": [ "ACTIVE", "CANCELLED", "EXPIRED", "FIRST_TIME_ACTIVATION", "LOST_PICKUP", "NO_SAVING_ACCOUNT", "PIN_TRIES_EXCEEDED", "REPLACED", "RESTRICTED", "STOLEN_PICKUP", "STOPPED" ] }, "EclipseCard": { "description": "A debit/credit card. Can be virtual or physical. If physical it may or may not be manufactured yet. The type and status of a card provides more information on where it is in its lifecycle. Cards that are issued/usable would be linked to a wallet so that credits/debits reflect in the associated wallet", "type": "object", "properties": { "cardHolderName": { "type": "string", "description": "Name of the card holder as printed on the card" }, "cardId": { "type": "integer", "format": "int64", "description": "Unique system generated identifier for a card", "exclusiveMinimum": 0 }, "cardIdentifierType": { "$ref": "#/components/schemas/EclipseCardOperationType", "description": "Type of operation that was specified when creating the card", "type": "string" }, "cardPackId": { "type": "string" }, "cardRules": { "$ref": "#/components/schemas/CardRules", "description": "Detailed rules for the card", "type": "object" }, "cardType": { "$ref": "#/components/schemas/EclipseCardType" }, "created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "ISO 8601 date/time of when the record was first created" }, "customerId": { "type": "integer", "format": "int64", "description": "Customer the card belongs to" }, "cvv": { "type": "string", "description": "CVV/CVC of the card", "minLength": 3, "maxLength": 6 }, "expires": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "ISO 8601 date/time of when the card expires" }, "externalUniqueId": { "type": "string", "description": "External unique identifier for the card" }, "lifeCycleStatus": { "$ref": "#/components/schemas/EclipseCardLifeCycleStatus", "description": "Optional: The lifecycle status of the card can only be ACTIVE or INACTIVE e.g. On Pn the card can be on status ACTIVE with hold response code RESTRICTED", "type": "string" }, "limitConfiguration": { "type": "array", "items": { "$ref": "#/components/schemas/Avp" } }, "pan": { "type": "string", "description": "Primary account number of the card", "minLength": 16, "maxLength": 16 }, "programName": { "type": "string" }, "status": { "$ref": "#/components/schemas/CardStatus", "description": "Current status of the card", "type": "string" }, "statusChangeReason": { "type": "string" }, "walletId": { "type": "integer", "format": "int64", "description": "The wallet the card is mapped to if it only has a single mapping - deprecated use walletIds instead" }, "walletIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "The wallets the card is mapped to. Use this and not walletId" } } }, "EclipseCardLifeCycleStatus": { "type": "string", "enum": [ "ACTIVATED", "INACTIVE" ] }, "EclipseCardOperationType": { "type": "string", "enum": [ "ADDON_CARD", "PRIMARY_CARD", "SUPPLEMENTARY_CARD" ] }, "EclipseCardType": { "description": "Card type either physical or virtual card", "type": "string", "enum": [ "PERSONALISED", "PHYSICAL", "VIRTUAL" ] }, "ExceptionData": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "environment": { "type": "string" }, "info": { "type": "object", "additionalProperties": {} }, "severity": { "$ref": "#/components/schemas/ExceptionSeverity" }, "spanId": { "type": "string" }, "stackTrace": { "type": "string" }, "traceId": { "type": "string" }, "type": { "$ref": "#/components/schemas/ExceptionType" } } }, "ExceptionSeverity": { "type": "string", "enum": [ "CRITICAL", "HIGH", "INFO", "LOW", "MEDIUM" ] }, "ExceptionType": { "type": "string", "enum": [ "BUSINESS", "SYSTEM" ] } }, "securitySchemes": { "JWTBearerAuthorisation": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "info": { "description": "A RESTful API using JSON as the data transfer model, covering all tenant-facing functionality in the Eclipse payments platform.", "title": "Eclipse ReST API", "version": "3.0.0" }, "tags": [ { "name": "i) Card Management", "description": "Manage physical and virtual cards issued to customers. Includes card retrieval, status updates, PIN management, activity history, and issuer token management." } ], "paths": { "/eclipse-conductor/rest/v1/tenants/{tenantId}/cards/{cardId}": { "get": { "summary": "Get a card by ID", "description": "Retrieves a card by ID. To receive an unmasked PAN and CVV (masked=false), the caller must be the cardholder using their own JWT or a valid card access password (CAP). This endpoint must only be called from the cardholder's device when unmasked data is requested.", "tags": [ "i) Card Management" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "cardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "description": "The card access password of the customer. Required if masked=false and no JWT is provided", "name": "cap", "in": "query", "schema": { "type": "string" } }, { "description": "Used to include additional details along with the card information. For example, if a card level limit is required, it can be passed as a field i.e. fields=limits. It supports multiple values using a comma-separated format to include in the response", "name": "fields", "in": "query", "schema": { "type": "string" } }, { "description": "If false then the full PAN and CVV will be returned. An error will be returned if masked=false and the caller is not the card owner or a valid CAP is not provided", "name": "masked", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EclipseCard" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionData" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionData" } } } } } }, "security": [ { "JWTBearerAuthorisation": [] } ] } } } } ```