--- updatedAt: 2026-05-29T13:25:42.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Create a wallet reservation Places a hold on the specified amount in the wallet, reducing available balance until the reservation expires or is consumed by a transfer. # 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" } } }, "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" ] }, "EclipseReservation": { "description": "A lock/hold/reservation of an amount against a wallet. When a reservation is held then this accounts for the difference between current and available balance. Reservations can expire. A reservation can only be removed when a charge or transfer for that same session is applied", "type": "object", "required": [ "reservationId", "walletId" ], "properties": { "amount": { "type": "number", "description": "Amount in the currency of the wallet. Amounts are in major currency unit. Positive for debit reservation, negative for credit reservation" }, "cardId": { "type": "integer", "format": "int64" }, "created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the reservation was created" }, "description": { "type": "string", "description": "Description for the reservation", "pattern": "(?s)^(?:[\\t\\r\\n]|[^\\p{C}<>])*$" }, "expires": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the reservation will automatically be deleted, releasing the amount back to the available balance" }, "externalUniqueId": { "type": "string", "description": "Globally Unique identifier for the reservation" }, "info": { "type": "array", "items": { "$ref": "#/components/schemas/Avp" } }, "payment": { "$ref": "#/components/schemas/PaymentResult", "description": "Associated payment data if payment field data was requested", "type": "object" }, "remittance": { "$ref": "#/components/schemas/WalletRemittanceResult", "description": "Associated remittance data if remittance field data was requested", "type": "object" }, "reservationId": { "type": "integer", "format": "int64", "description": "Unique identifier for the reservation", "exclusiveMinimum": 0 }, "sessionId": { "type": "string", "description": "The identifier of the session holding the reservation" }, "uniqueId": { "type": "string", "description": "Deprecated - use externalUniqueId. Globally Unique identifier for the reservation" }, "walletId": { "type": "integer", "format": "int64", "description": "The wallet the reservation is against", "exclusiveMinimum": 0 }, "withdrawal": { "$ref": "#/components/schemas/WalletWithdrawalResult", "description": "Associated withdrawal data if withdrawal field data was requested", "type": "object" } } }, "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" ] }, "NewEclipseReservation": { "description": "A lock/hold/reservation of an amount against a wallet. When a debit reservation is held then this accounts for the difference between current and available balance. Reservations can expire. Use negative amount to indicate a reservation to credit so that max wallet balance is not exceeded unintentionally due to race conditions A reservation can only be removed when a charge or transfer for that same session is applied", "type": "object", "required": [ "sessionId", "amount", "expires" ], "properties": { "amount": { "type": "number", "description": "Amount in the currency of the wallet. Amounts are in major currency unit. Positive for a reserve to debit, negative for a reserve to credit" }, "avps": { "type": "array", "items": { "$ref": "#/components/schemas/Avp" } }, "cardId": { "type": "integer", "format": "int64" }, "description": { "type": "string", "description": "Description for the reservation", "pattern": "(?s)^(?:[\\t\\r\\n]|[^\\p{C}<>])*$", "minLength": 0, "maxLength": 200 }, "expires": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "ISO 8601 date/time of when the reservation should expire and the amount available back in the wallet" }, "externalUniqueId": { "type": "string", "description": "Globally Unique identifier for the reservation. Duplicates will be rejected", "minLength": 6, "maxLength": 100 }, "onlyCheck": { "type": "boolean", "description": "Optional. If true then the reservation wont actually be done but only validated to see if it could have been done" }, "sessionId": { "type": "string", "description": "The identifier of the session holding the reservation", "minLength": 6, "maxLength": 100 }, "type": { "type": "string", "description": "Optional. The transaction type for the reservation for limit checks" }, "uniqueId": { "type": "string", "description": "Deprecated - use externalUniqueId. Globally Unique identifier for the reservation" } } }, "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 } } }, "RemittanceAdditionalField": { "type": "object", "properties": { "defaultValue": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "identifier": { "type": "string" }, "regex": { "type": "string" }, "regexErrorMessage": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } } }, "WalletRemittanceResult": { "type": "object", "properties": { "additionalFields": { "type": "array", "items": { "$ref": "#/components/schemas/RemittanceAdditionalField" } }, "amount": { "type": "number", "description": "Amount in the major currency unit of the associated wallet e.g. 50.80 for 50 GBP and 80 pence" }, "created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ] }, "currency": { "type": "string", "description": "The currency of the wallet - e.g. USD, ZAR, NGN, TSH" }, "customFraudChecks": { "type": "boolean" }, "description": { "type": "string" }, "destinationAmount": { "type": "number", "description": "Amount in the major currency unit of the associated wallet e.g. 50.80 for 50 GBP and 80 pence being used to buy the destination currency at the exchange rate" }, "destinationCountry": { "type": "string" }, "destinationCurrency": { "type": "string" }, "errorDescription": { "type": "string" }, "exchangeRate": { "type": "number", "description": "The amount to pay in the wallets currency for one major unit of the destination currency. The recipient will get exchangeAmount/exchangeRate in the destination currency" }, "externalUniqueId": { "type": "string" }, "extraInfo": { "type": "string", "description": "Loosely typed data resulting from the remittance payment. E.g. could be a voucher code if the payment was for a VAS. The structure depends on what was being paid for." }, "fee": { "type": "number", "description": "Fee that will be decuted from wallet in wallet currency. walletFeeAmount + walletSendingAmount = walletTotalAmount" }, "gatewayTransactionId": { "type": "string", "description": "The transaction identifier for this remittance as provided by the gateway itself" }, "mtoProvider": { "type": "string" }, "note": { "type": "string" }, "quoteExpires": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ] }, "remittanceId": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/WalletRemittanceStatus", "description": "Status of the remittance", "type": "string" }, "totalSourceAmount": { "type": "number", "description": "If fees are INCLUSIVE this will be same as sourceAmount,if fees are EXCLUSIVE it will be sourceAmount + fee" }, "walletId": { "type": "integer", "format": "int64" } } }, "WalletRemittanceStatus": { "description": "Status of a remittance", "type": "string", "enum": [ "BUILDING", "CANCELLED", "ERROR_PERM", "ERROR_TEMP", "PENDING", "REVERSED", "SUCCESSFUL", "TIMEOUT" ] }, "WalletWithdrawalResult": { "type": "object", "description": "Data which will be posted in a callback/webhook to the tenant when a withdrawal has permanently failed or succeeded", "properties": { "amount": { "type": "number", "description": "Amount in the major currency unit e.g. 50.80 for 50 GBP and 80 pence" }, "created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the withdrawal was created" }, "currency": { "type": "string", "description": "Currency of the transaction. E.g. USD, ZAR, NGN etc" }, "customerId": { "type": "integer", "format": "int64" }, "deliverToPhone": { "type": "string" }, "description": { "type": "string" }, "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 token expires if applicable" }, "externalUniqueId": { "type": "string" }, "extraInfo": { "type": "string", "description": "Extra information about the withdrawal. The structure of the data depends on the withdrawal gateway in use as its often the result in transaction data from the gateway" }, "fee": { "type": "number" }, "finalAmount": { "type": "number" }, "gateway": { "type": "string" }, "gatewayTransactionId": { "type": "string", "description": "The transaction identifier for this withdrawal as provided by the gateway itself" }, "holdUntil": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ] }, "lastModified": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50-04:00" ], "description": "When the withdrawal last modified" }, "location": { "type": "string", "description": "Any location information about the transaction such as IP address or GPS" }, "organisationId": { "type": "integer", "format": "int64" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/WalletWithdrawalStatus", "description": "As the callback will only trigger when the the withdrawal is in a final status, the possibilities are SUCCESSFUL, ERROR, TIMEOUT, CANCELLED", "type": "string" }, "subType": { "type": "string" }, "token": { "type": "string", "description": "The token in case the withdrawal is via a token/identifier given at time of withdrawing and no delivery phone number was provided" }, "tracingContext": { "type": "string", "description": "Tracing data about the withdrawal" }, "type": { "type": "string" }, "walletId": { "type": "integer", "format": "int64" }, "withdrawalId": { "type": "integer", "format": "int64" } } }, "WalletWithdrawalStatus": { "description": "Status of a withdrawal. PENDING:Still being processed, SUCCESSFUL: Successfully completed, ERROR:Failed and wont ever succeed, 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", "HOLD", "PENDING", "REVERSED", "SUCCESSFUL", "TIMEOUT" ] } }, "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": "n) Wallet Reservations", "description": "Manages wallet reservations, which ring-fence a portion of available balance for a pending transaction until it is committed or released." } ], "paths": { "/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/reservations": { "post": { "summary": "Create a wallet reservation", "description": "Places a hold on the specified amount in the wallet, reducing available balance until the reservation expires or is consumed by a transfer.", "tags": [ "n) Wallet Reservations" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "walletId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewEclipseReservation" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EclipseReservation" } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionData" } } } } } }, "security": [ { "JWTBearerAuthorisation": [] } ] } } } } ```