--- updatedAt: 2026-05-29T13:25:42.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Initiate a new payment Starts a payment. The flow depends on the payment type — it may be a single fire-and-forget call or a multi-step process requiring customer interaction. # 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": { "EclipseAdditionalMerchantData": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "merchantCategoryCode": { "type": "string" }, "paymentFacilitatorData": { "$ref": "#/components/schemas/EclipsePaymentFacilitatorData" }, "phoneNumber": { "type": "string" }, "subMerchantId": { "type": "string" }, "subMerchantName": { "type": "string" }, "website": { "type": "string" } } }, "EclipsePaymentFacilitatorData": { "type": "object", "properties": { "amex": { "type": "string" }, "diners": { "type": "string" }, "discover": { "type": "string" }, "maestro": { "type": "string" }, "mastercard": { "type": "string" }, "visa": { "type": "string" } } }, "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" ] }, "EncryptedPaymentCardData": { "description": "Card data for a customer adding a card on file or paying by card. Never to be called by a Non PCI Compliant environment backend", "type": "object", "properties": { "base64EncryptedPayload": { "type": "string", "minLength": 4, "maxLength": 10000 }, "type": { "$ref": "#/components/schemas/EncryptedPaymentCardDataType" } } }, "EncryptedPaymentCardDataType": { "type": "string", "enum": [ "APPLE_PAY", "CTP_MASTERCARD", "CTP_VISA", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "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" ] }, "NewEclipsePayment": { "description": "Data to initiate a payment by someone that is not a customer on Eclipse. The payment could be to a QRCode or another supported payment destination.", "type": "object", "required": [ "externalUniqueId", "type" ], "properties": { "accountNumber": { "type": "string", "description": "Account number ", "minLength": 8, "maxLength": 80 }, "additionalFields": { "type": "array", "items": { "$ref": "#/components/schemas/SuppliedPaymentAdditionalField" }, "description": "Additional fields captured by the customer be submitted for processing. These fields relate to additionalFields requested when the payment was initiated or in the VAS catalog" }, "additionalMerchantData": { "$ref": "#/components/schemas/EclipseAdditionalMerchantData" }, "amount": { "type": "number", "description": "The amount for the payment. Optional depending on the payment type. Amounts are in major currency unit. Note that this is the total amount of the payment. If the payment has a tip portion then the amount should reflect this. E.g. QRCode is 100, tip decided by customer is 10, the amount should be set as 110", "minimum": 0 }, "branchCode": { "type": "string", "description": "Branch code", "minLength": 2, "maxLength": 20 }, "callbackUrl": { "type": "string", "description": "The URL Eclipse must post the PaymentResult to. Optional as one can always do a GET to get the result instead of using callbacks. This will be a system-system call", "pattern": "^http(s)?:\\/\\/.*\\..*$", "minLength": 10, "maxLength": 2000 }, "cardOnFileId": { "type": "string", "description": "Optional. Card on file id for pre-enrolled cards to use for the payment if applicable. Negates the need to provide actual card data E.g. PAN etc" }, "currency": { "type": "string", "description": "The currency of the payment amount - e.g. USD, ZAR, NGN, TSH. Must be provided if the amount is provided. Otherwise do not provide", "minLength": 3, "maxLength": 3 }, "customFraudChecks": { "type": "boolean", "description": "By default this value is false. If User wants to enable fraud rule checks then need to pass true" }, "description": { "type": "string", "description": "A description for the payment if being initiated from Eclipse", "pattern": "(?s)^(?:[\\t\\r\\n]|[^\\p{C}<>])*$", "minLength": 0, "maxLength": 200 }, "destinationWalletId": { "type": "integer", "format": "int64", "description": "Used to indicate where the funds must be paid to for payment types GLOBAL_PAYMENT_LINK, GLOBAL_REUSABLE_PAYMENT_LINK, GLOBAL_TOG, GLOBAL_TOG_VAC, GLOBAL_WALLET, KE_DTB_AIRTEL_PROMPT, KE_DTB_MPESA_PROMPT, KE_DTB_STK_PUSH, ZA_HALO, ZA_OZOW, ZA_PNP_CASH" }, "encryptedPaymentCardData": { "$ref": "#/components/schemas/EncryptedPaymentCardData", "description": "If the payment mechanism uses a card and its not a card on file (i.e. cardOnFileId not provided) and PaymentCardData is not provided then this field provides the encrypted card data to use for the payment. supported type(GooglePay)", "type": "object" }, "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", "description": "Provide a GUID for the payment to prevent replays/duplicates", "minLength": 6, "maxLength": 100 }, "externalWalletId": { "type": "string", "description": "Optional. If the payment mechanism is via some proprietary (non-card based) interface such as an external wallet or bank account then this field can be used to identity the payers wallet id, account number, profile id etc." }, "externalWalletType": { "type": "string", "description": "Optional. If the payment mechanism is via some proprietary (non-card based) interface such as an external wallet or bank account then this field can be used to identify what wallet type this is." }, "landingUrl": { "type": "string", "description": "Where the customers iFrame/Browser should be navigated to after the payment has completed (applicable to payments that use 3DS). If the URL contains <paymentId> then it will be replaced with the paymentId before the redirect.", "minLength": 10, "maxLength": 2000 }, "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 }, "maxAmount": { "type": "number", "description": "This field specifies the maximum amount to make the partial payment" }, "minAmount": { "type": "number", "description": "This field specifies the minimum amount to make the partial payment" }, "note": { "type": "string", "description": "Optional. User defined extra note related to payment in any format free text or JSON formatted text.", "minLength": 0, "maxLength": 200 }, "paymentCardData": { "$ref": "#/components/schemas/PaymentCardData", "description": "If the payment mechanism uses a card and its not a card on file (i.e. cardOnFileId not provided) then this field provides the card data to use for the payment", "type": "object" }, "paymentData": { "type": "string", "description": "Loosely typed data about the payment. Depends on the payment type. E.g. could be a QRCode or a VAS partnerId, productId combination (For VAS the paymentData must consist of the partnerId and productId of a product in the VAS catalog separated with an _ e.g. 2_ABC123.) )For payment links and payments destined to an Eclipse wallet, it must be populated with the destination wallet Id)" }, "paymentMechanism": { "$ref": "#/components/schemas/PaymentMechanism", "description": "The mechanism with which to make the payment. Determines if paymentCardData, paymentSecurity data etc are required. If not passed then the requests data like walletId, paymentCardData, paymentSecurityData etc will be used to work out the inferred mechanism", "type": "string" }, "paymentSecurityData": { "$ref": "#/components/schemas/PaymentSecurityData", "description": "Security data related to the payment in order to prove that the payer has authorised the transaction or that the issuer authorises the transaction on behalf of the payer (and hence accepts liability for the payment). Not required if COMPLETION_URL is used as the payment mechanism as the security data will be generated by Eclipse in concert with the issuing bank via an iFrame with the card holder", "type": "object" }, "paymentTerminalData": { "$ref": "#/components/schemas/PaymentTerminalData", "description": "Data about the terminal acquiring the payment", "type": "object" }, "phone": { "type": "string", "description": "Users primary mobile phone number. Optional/Required depending on the payment type", "pattern": "^[0-9]{8,16}$" }, "reference": { "type": "string" }, "storeCardOnFile": { "type": "boolean", "description": "Optional. If the payment mechanism is to pay with a card and card details are provided then this indicates whether to store the card on file" }, "templateId": { "type": "string", "description": "Optional. If provided then card ui will be rendered based on the provided templateId else fallback to default tenant template." }, "type": { "type": "string", "description": "The type of payment being done. Indicates how Eclipse should process/parse the payment data as the payment data field is a loosely typed and could be a QRCode, JSON or any other data that Eclipse can pay. The type indicates what is being paid, not the payment mechanism." }, "unattended": { "type": "boolean", "description": "Optional. Indicates that the customer is not present for the payment and interactive authentication must not happen (e.g. 3DS)" }, "walletId": { "type": "integer", "format": "int64", "description": "Optional. If the payment mechanism is to pay with an Eclipse wallet, then the Eclipse walletId can be provided in this field", "exclusiveMinimum": 0 } } }, "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" } } }, "PaymentCardData": { "type": "object", "description": "Card data for a customer adding a card on file or paying by card. Never to be called by a Non PCI Compliant environment backend", "properties": { "accountType": { "type": "string", "description": "Account Type - will default to 00 if not provided" }, "alias": { "type": "string", "description": "Alias (some friendly name e.g. HSBC Gold Card). If provided then the card will be stored as a card on file for later reuse", "minLength": 1, "maxLength": 50 }, "applicationIdentifier": { "type": "string", "description": "Identifies the application as described in ISO 7816-5", "minLength": 1, "maxLength": 100 }, "cardSequenceNumber": { "type": "string", "description": "Number distinguishing between separate cards with the same primary account number or primary account number extended, usually 3 numerics", "minLength": 1, "maxLength": 10 }, "cardholderName": { "type": "string", "description": "Name of the card holder as printed on the card", "minLength": 3, "maxLength": 50 }, "cardholderVerificationMethodList": { "type": "string" }, "cvv": { "type": "string", "description": "Cards CVV" }, "deleteAt": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "Optional. If provided then the card will only remain on file up till this date after which it will be deleted permanently (hard delete). Ignored if alias is not provided as the card will not be store." }, "dob": { "type": "string", "description": "Cardholders DOB CCYYMMDD ", "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$", "minLength": 8, "maxLength": 8 }, "encryptedApplicationIdentifier": { "type": "string", "description": "SRED encoded appId blob containing the ecrypted app identifier as described in ISO 7816-5", "minLength": 1, "maxLength": 100 }, "encryptedCardSequenceNumber": { "type": "string", "description": "SRED encoded card sequence number blob containing the ecrypted card sequence number, usually 3 numerics", "minLength": 1, "maxLength": 100 }, "encryptedCardholderName": { "type": "string", "description": "SRED encoded cardholder blob containing the ecrypted card holder as printed on the card", "minLength": 0, "maxLength": 200 }, "encryptedExpiry": { "type": "string", "description": "SRED encoded Expiry blob containing the ecrypted card expiry date in format MMYY", "minLength": 4, "maxLength": 100 }, "encryptedPan": { "type": "string", "description": "SRED encoded PAN blob containing the ecrypted Card number. 16 numeric digits", "minLength": 12, "maxLength": 100 }, "encryptedTrack2Data": { "type": "string", "description": "RED encoded track2 blob containing the ecrypted track2 information as per ISO/IEC 7813", "minLength": 1, "maxLength": 255 }, "expiry": { "type": "string", "description": "Card expiry date in format MMYY", "minLength": 4, "maxLength": 4 }, "pan": { "type": "string", "description": "Card number. 16 numeric digits", "minLength": 12, "maxLength": 20 }, "track2Data": { "type": "string", "description": "Optional track2 information as per ISO/IEC 7813", "minLength": 1, "maxLength": 255 } } }, "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" } } }, "PaymentMechanism": { "description": "Payment mechanism. CARD: Credit/Debit/Prepaid card will be used with eitherthe card data provided, card on file ID, or by a lightbox the customer can capture the card details in, CARD_PRESENT: specifica use case of card present acquiring, typically used with pos estate or tap on glass integrations, WALLET: The debit should be done on an Eclipse walletId provided, EXTERNAL_WALLET: Pay with the externalWalletId and externalWalletIdType", "type": "string", "enum": [ "CARD", "CARD_PRESENT", "EFT", "EXTERNAL_WALLET", "WALLET" ] }, "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" ] }, "PaymentSecurityData": { "type": "object", "description": "Data to prove acceptance or deemed acceptance for the payment. Depends on the payment mechanism", "properties": { "applicationInterchangeProfile": { "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": 10 }, "applicationTransactionCounter": { "type": "string", "description": "Contains proprietary application data for transmission to the issuer in an online transaction", "minLength": 1, "maxLength": 10 }, "authorisationRequestCryptogram": { "type": "string", "description": "Authorisation request cyrptogram to be sent to the issuer, will result in an authorization response cryptogram being returned", "minLength": 1, "maxLength": 100 }, "cavv": { "type": "string", "description": "The Cardholder Authentication Verification Value that will be sent to the issuing bank for authentication. Visa AAV / Mastercard UCAF", "minLength": 4, "maxLength": 48 }, "cryptogram": { "type": "string", "minLength": 10, "maxLength": 5000 }, "cryptogramInformationData": { "type": "string", "description": "Contains information about the crytpgram (authorisationRequestCryptogram)", "minLength": 1, "maxLength": 100 }, "eciFlag": { "type": "string", "description": "", "minLength": 2, "maxLength": 2 }, "eciIndicator": { "type": "string" }, "encryptedData": { "type": "string", "description": "JWE encypted object with all the EMV SCD - the model to be encrypted is the same as the paymentCardData JSON model", "minLength": 1, "maxLength": 5000 }, "errorNo": { "type": "integer", "format": "int32", "description": "An application error number returned on the ACS interface for the 3D-Secure call" }, "isXPayTokenSecurityDataProvided": { "type": "boolean", "description": "Pass true if the card contains token data" }, "issuerApplicationData": { "type": "string", "description": "Indicates the capabilities of the card to support specific functions in the application", "minLength": 1, "maxLength": 100 }, "jwt": { "type": "string", "minLength": 10, "maxLength": 5000 }, "paRes": { "type": "string", "minLength": 10, "maxLength": 2000 }, "paResStatus": { "type": "string", "description": "The transaction status result identifier as returned on the ACS interface for the 3D-Secure call. Can be Y, N, U, A", "minLength": 1, "maxLength": 2 }, "pinData": { "type": "string", "description": "- A string value of the encrypted pin payload (e.g. pinblock)", "minLength": 10, "maxLength": 2000 }, "pinDataType": { "type": "string", "description": "A string value idenifying the format of the encrypted pin data - eg ISO1)", "minLength": 1, "maxLength": 5000 }, "rsaPinBlockPublicKeySerial": { "type": "string", "description": "serial number for the certificate used for encrypting pinblock", "minLength": 1, "maxLength": 5000 }, "signatureVerification": { "type": "string", "description": "The transaction signature status identifier as returned on the ACS interface for the 3D-Secure call. Can be Y or N", "minLength": 1, "maxLength": 1 }, "threeDSecureCryptogram": { "type": "string" }, "token": { "type": "string", "minLength": 10, "maxLength": 5000 }, "tokenExpiry": { "type": "string", "minLength": 10, "maxLength": 5000 }, "tokenisationType": { "type": "string" }, "unpredictableNumber": { "type": "string", "description": "Contains the card unpredictable number generated by the card and signed for fast dynamic authenitcation data (fDDA)", "minLength": 1, "maxLength": 15 }, "xid": { "type": "string", "description": "The transaction identifier used for 3D-Secure authentication", "minLength": 4, "maxLength": 40 } } }, "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 } } }, "SuppliedPaymentAdditionalField": { "type": "object", "description": "Supplied data required in order for a customer to do a payment", "properties": { "id": { "type": "string" }, "value": { "type": "string" } } } }, "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": { "post": { "summary": "Initiate a new payment", "description": "Starts a payment. The flow depends on the payment type — it may be a single fire-and-forget call or a multi-step process requiring customer interaction.", "tags": [ "q) Payments" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewEclipsePayment" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResult" } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionData" } } } } } }, "security": [ { "JWTBearerAuthorisation": [] } ] } } } } ```