--- updatedAt: 2026-05-29T13:25:42.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Get a payment by ID # 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": { "EclipsePaymentStatus": { "description": "Status of a payment BUILDING: Not yet submitted as more data needs to be captured, PENDING:Being processed and can no longer be enhanced, SUCCESSFUL: Successfully completed, ERROR_PERM: Failed and wont ever succeed, ERROR_TEMP: Currently having an error but its being retried and may succeed or permanently fail, TIMEOUT: Failed as the process was not finalised in time, CANCELLED: Cancelled prior to SUCCESS or FAILURE, REVERSED: Reversed after success", "type": "string", "enum": [ "BUILDING", "CANCELLED", "ERROR_PERM", "ERROR_TEMP", "PENDING", "REVERSED", "SUCCESSFUL", "TIMEOUT" ] }, "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" ] }, "FieldType": { "description": "Status of a payment NUMERIC: The numeric keyboard is only needed, STRING: The full keyboard is needed", "type": "string", "enum": [ "DROPDOWN", "NUMERIC", "STRING" ] }, "PaymentAdditionalField": { "type": "object", "description": "Some form of additional data required in order for a customer to do a payment", "properties": { "defaultValue": { "type": "string", "description": "The default value to put on the UI which can be changed by the customer" }, "fixed": { "type": "boolean", "description": "This field is required and is fixed and must be the default value. E.g. if there is a fixed tip amount" }, "id": { "type": "string", "description": "Unique identifier for the field to be used when specifying the value on the PUT" }, "regex": { "type": "string", "description": "If provided then the value must match this regex pattern" }, "regexErrorMessage": { "type": "string", "description": "If the regex field is present and the end users value does not match the regex then display this user friendly message" }, "template": { "type": "string", "description": "Information for the input. E.g. if the type is DROPDOWN then this is the comma delimited list of options to put in the dropdown" }, "title": { "type": "string", "description": "The title of the field when asking the customer for the info" }, "type": { "$ref": "#/components/schemas/FieldType", "description": "The field type so the UI knows what keyboard it can use", "type": "string" }, "value": { "type": "string", "description": "The value if supplied" } } }, "PaymentAuthenticationInfo": { "type": "object", "description": "3D-Secure authentication outcome for a card payment. method is SECURE_CODE, AMT, SOV or CNP; the remaining fields are only populated for SECURE_CODE (3DS) transactions.", "properties": { "authIndicator": { "type": "string" }, "dsTransId": { "type": "string" }, "eci": { "type": "string" }, "enrolmentStatus": { "type": "string" }, "mdErrorMsg": { "type": "string" }, "mdStatus": { "type": "string" }, "method": { "type": "string" }, "protocolVersion": { "type": "string" }, "xid": { "type": "string" } } }, "PaymentCardIssuerDetails": { "type": "object", "description": "Card issuer/BIN details: BIN, whether the card is DOMESTIC or INTERNATIONAL, issuer, brand and product type", "properties": { "bin": { "type": "string" }, "brand": { "type": "string" }, "classification": { "type": "string" }, "issuer": { "type": "string" }, "productType": { "type": "string" } } }, "PaymentInstrumentInfo": { "type": "object", "description": "Some form of additional data of payment", "properties": { "cardBin": { "type": "string" }, "cardExpires": { "type": "string" }, "cardIssuer": { "type": "string" }, "cardLast4": { "type": "string" }, "cardName": { "type": "string" }, "cardOnFileId": { "type": "string", "description": "If card on file was created then this will be set with the id that can be used for future payments" }, "cardPhone": { "type": "string" }, "cardType": { "type": "string" }, "externalWalletId": { "type": "string" }, "externalWalletType": { "type": "string" } } }, "PaymentResult": { "type": "object", "description": "Data about a payment being processed or fully processed. Includes fields needed to complete a payment if its still in progress", "properties": { "acceptedCardSchemes": { "type": "array", "items": { "type": "string" }, "description": "If the payment can be made by card then the allowed card schemes that can be used" }, "acceptedPaymentMechanisms": { "type": "array", "items": { "type": "string" }, "description": "The ways that the payment can be made" }, "accountNumber": { "type": "string" }, "accountType": { "type": "string" }, "additionalFields": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAdditionalField" }, "description": "Fields that must be completed by the payer and provided on the PUT to update the payment for processing. Its up to the UI to decide how to lay these out and ask for them but the API and VAS catalog provides details to make it easy to dynamically generate the UI for the payment. For HALO payments one must provide merchantWalletId as an additional field" }, "amount": { "type": "number", "description": "The amount payable. Amounts are in major currency unit" }, "amountOption": { "type": "string", "description": "Contain Json string for purchase amount minimum and maximum. If it is not empty then the purchase amount must be in between of min and max amount specified in this attribute(min and max inclusive) and that amount must be sent on the updated purchase request" }, "associatedPaymentId": { "type": "integer", "format": "int64" }, "authCode": { "type": "string" }, "authentication": { "$ref": "#/components/schemas/PaymentAuthenticationInfo", "description": "3D-Secure authentication outcome for this payment. Only populated for card payments. CAVV, cavvAlgorithm and any raw PARes payload are never exposed here.", "type": "object" }, "bankResponse": { "type": "string" }, "branchCode": { "type": "string" }, "cardIssuerDetails": { "$ref": "#/components/schemas/PaymentCardIssuerDetails", "description": "Card issuer/BIN classification for this payment's card, if known", "type": "object" }, "cardPhone": { "type": "string", "description": "Deprecated. Use phone instead" }, "completionUrl": { "type": "string", "description": "URL to open in an iFrame or browser where customer can securely complete 3DS details if required. Normally this will not be provided until the payment has been posted/updated with sufficient data to be processable. However this is provided for GLOBAL_PAYMENT_LINK payments as these dont require further info from the API caller for the payment to be made" }, "created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the payment was posted" }, "currency": { "type": "string", "description": "The currency of the payment amount - e.g. USD, ZAR, NGN, TSH" }, "customerId": { "type": "integer", "format": "int64" }, "description": { "type": "string", "description": "A description for the payment created from the payment data.E.g. Merchant info and QR description for a QR payment" }, "emvIssuerAuthenticationData": { "type": "string", "description": "Data delivered to the chip card including the ARPC cryptogram for online issuer authentication" }, "errorDescription": { "type": "string", "description": "This will only be populated if there was an error" }, "expires": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the payment must complete by. If not in final state before this time, Eclipse will timeout the payment" }, "externalUniqueId": { "type": "string" }, "extraInfo": { "type": "string", "description": "Loosely typed data resulting from the payment. E.g. could be a voucher id if the payment was for a VAS. The structure depends on what was being paid for." }, "fee": { "type": "number" }, "gatewayTransactionId": { "type": "string", "description": "The transaction identifier for this payment as provided by the gateway itself" }, "lastModified": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the payment was last modified" }, "location": { "type": "string", "description": "Optional. Any location information to add to the payment such as GPS coordinates or branch name etc", "minLength": 0, "maxLength": 200 }, "merchantId": { "type": "string", "description": "The unique identifier for the merchant" }, "merchantName": { "type": "string", "description": "The name of the merchant to whome the payment will go" }, "merchantReference": { "type": "string", "description": "Reference for the merchant" }, "note": { "type": "string" }, "organisationId": { "type": "integer", "format": "int64" }, "otherWalletId": { "type": "integer", "format": "int64", "description": "payment receiver’s wallet ID, if applicable." }, "partialPaymentAllowed": { "type": "boolean", "description": "Will be true if the value allows a partial payment and amount must be sent on the updated purchase request" }, "paymentData": { "type": "string", "description": "Loosely typed data about the payment. Depends on the payment type. E.g. could be a QRCode" }, "paymentId": { "type": "integer", "format": "int64", "description": "Unique identifier for this payment transaction" }, "paymentInstrumentInfo": { "$ref": "#/components/schemas/PaymentInstrumentInfo" }, "paymentReference": { "type": "string" }, "paymentTerminalData": { "$ref": "#/components/schemas/PaymentTerminalData", "description": "Data about the terminal acquiring the payment", "type": "object" }, "paymentType": { "type": "string", "description": "The deduced type of payment being done based on the type and paymentData" }, "phone": { "type": "string" }, "pspId": { "type": "string" }, "retrievalReferenceNumber": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/EclipsePaymentStatus", "description": "If this is provided via a callback then the payment is in a final status, the possibilities are SUCCESSFUL, ERROR_PERM, TIMEOUT, CANCELLED. If provided after updating the payment then it could also be PENDING", "type": "string" }, "tracingContext": { "type": "string", "description": "Tracing data about the payment" }, "walletId": { "type": "integer", "format": "int64" } }, "required": [ "paymentType" ] }, "PaymentTerminalData": { "type": "object", "description": "Data about the acquiring terminal", "properties": { "amountAuthorisedNumeric": { "type": "number" }, "amountOtherNumeric": { "type": "number" }, "applicationUsageControl": { "type": "string" }, "budgetTerm": { "type": "string" }, "cardholderVerificationMethodResults": { "type": "string" }, "cvmList": { "type": "string" }, "cvmResult": { "type": "string" }, "dedicatedFileName": { "type": "string", "description": "EMV Dedicated File Name (tag 84) of the application selected on the terminal" }, "deviceMake": { "type": "string", "description": "Make of the device acquiring the paymentCardData", "minLength": 1, "maxLength": 30 }, "formFactorIndicator": { "type": "string", "description": "Indicates the form factor of the consumer payment device and the type of contactless interface over which the transaction was conducted", "minLength": 1, "maxLength": 100 }, "mti": { "type": "string", "description": "ISO 8583 Message Type Identifier (MTI) that defines the transaction flow. For example: 0100 – Authorization request, 0200 – Financial transaction (e.g., purchase or withdrawal), 0220 – Authorization completion (capture), 0400 – Reversal request, and 0420 – Reversal advice." }, "pointOfServiceEntryMode": { "type": "string" }, "terminalApplicationVersionNumber": { "type": "string" }, "terminalCapabilities": { "type": "string", "description": "The field is used to identify terminal capability, terminal environment and presentation security data. It is used to indicate specific conditions that were present at the time transaction took place at the Point-of-Service", "minLength": 1, "maxLength": 20 }, "terminalCountryCode": { "type": "string" }, "terminalId": { "type": "string", "description": "TerminalId", "minLength": 1, "maxLength": 8 }, "terminalIdentifier": { "type": "string", "description": "Indicates the terminal being used as a mapping to terminals used in Eclipse terminal management - terminalIdentifier" }, "terminalIdentifierType": { "type": "string", "description": "Indicates the terminal being used as a mapping to terminals used in Eclipse terminal management - terminalIdentifierType" }, "terminalSerialNumber": { "type": "string" }, "terminalType": { "type": "string", "description": "The terminal type used for payment acquiring, refer to EMV specs, eg attended vs unattended, online vs offline, etc. typically 1 byte", "minLength": 1, "maxLength": 10 }, "terminalVerificationResult": { "type": "string", "description": "Status of the different functions as seen from the reader/terminal. For EMV mode transactions, all of the bits sent should be set to 0b", "minLength": 1, "maxLength": 10 }, "transactionType": { "type": "string", "description": "Indicates the type of transaction, represented by the values of the first two digits of Processing Code as defined by the payment system. For example: 00 – Purchase, 01 – Cash withdrawal, 09 – Purchase with cashback, 20 – Refund, 30 – Balance inquiry", "minLength": 1, "maxLength": 10 } } } }, "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": "q) Payments", "description": "Manage individual payments: retrieve, update, cancel, process refunds, and obtain proof of payment." } ], "paths": { "/eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId}": { "get": { "summary": "Get a payment by ID", "tags": [ "q) Payments" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResult" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionData" } } } } } }, "security": [ { "JWTBearerAuthorisation": [] } ] } } } } ```