{ "openapi": "3.0.1", "info": { "title": "NetValve Merchant Documentation", "description": "The NetValve merchant documentation provides information on the available APIs. For API authentication use either Basic Auth credentials or an API key.", "version": "1.0.0" }, "servers": [ { "url": "https://payment-api.uat.sandbox-netvalve.com", "description": "UAT / Integration URL" }, { "url": "https://api.netvalve.com", "description": "Production URL" } ], "paths": { "/subscription/update": { "put": { "tags": [ "Recurring Payment Service" ], "operationId": "updateManagedRecurringSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRecurringScheduleUpdateDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UpdateManagedRecurringSubscriptionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } }, "summary": "Update subscription", "description": "Update an existing subscription based off an existing subscriptionId" } }, "/subscription/cancel": { "put": { "tags": [ "Recurring Payment Service" ], "operationId": "cancelManagedRecurringSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRecurringScheduleCancelDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CancelManagedRecurringSubscriptionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } }, "summary": "Cancel subscription", "description": "Cancel a subscription off an existing subscriptionId" } }, "/{walletType}/initializeSession": { "post": { "tags": [ "Payment Service" ], "summary": "Initialize wallet type session", "description": "This api allows merchants to initialize wallet type session before transaction", "operationId": "initializeWalletTypeSession", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "walletType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletInitializeSessionRequestDTO" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WalletInitializeSessionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/subscription/pay": { "post": { "tags": [ "Recurring Payment Service" ], "operationId": "instantRecurringPayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantRecurringPaymentDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RebillTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } }, "summary": "Instant Payment", "description": "Charge an existing subscription based off an existing subscriptionId" } }, "/subscription/create": { "post": { "tags": [ "Recurring Payment Service" ], "operationId": "createManagedRecurringSubscriptionForExistingTransaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRecurringScheduleCreateDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateManagedRecurringSubscriptionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } }, "summary": "Create subscription", "description": "Setup a new subscription based off an existing transactionId" } }, "/sdk/sale": { "post": { "tags": [ "Checkout SDK" ], "summary": "SDK Sale", "description": "Executes a payment from a previously initialized SDK payment session.\nSupports card, wallet, tokenized, and alternative payment method payloads through a single endpoint.\nClient IP is resolved from X-Forwarded-For, then X-Real-IP, then the servlet remote address.\n", "operationId": "sale", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkSaleRequestDTO" } } }, "required": true }, "responses": { "200": { "description": "SDK sale processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseDTO" } } } }, "400": { "description": "Invalid request payload.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } }, "401": { "description": "Authentication failed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TransactionResponseDTO" } } } } } } }, "/sdk/initializeSession": { "post": { "tags": [ "Checkout SDK" ], "summary": "Initialize SDK session", "description": "Creates a hosted SDK payment session for the authenticated merchant.\nThe response contains the payment token, SDK endpoint URLs, script metadata, and initialization configuration needed by the client SDK.\n", "operationId": "initializeSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HppOrderInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "SDK session initialized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkInitializeSessionResponseDTO" } } } }, "400": { "description": "Invalid request payload.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } }, "401": { "description": "Authentication failed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SdkInitializeSessionResponseDTO" } } } } } } }, "/sdk/3ds/payment": { "post": { "tags": [ "Checkout SDK" ], "summary": "Complete SDK 3DS payment", "description": "Completes a SDK payment after a 3DS challenge/result is returned by the authentication provider.\nThe endpoint submits the 3DS transaction data and returns the final gateway transaction response.\n", "operationId": "completeThreeDSPayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkThreeDSPaymentRequestDTO" } } }, "required": true }, "responses": { "200": { "description": "3DS payment completion processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseDTO" } } } }, "400": { "description": "Invalid request payload.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } }, "401": { "description": "Authentication failed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TransactionResponseDTO" } } } } } } }, "/sale": { "post": { "tags": [ "Payment Service" ], "summary": "Sale", "description": "A sale transaction also known as a “Pay” transaction, is a combination of an Authorization (to check the card has sufficient funds and has not been reported lost or stolen) and a Capture, meaning the funds are taken from the cardholder immediately. It is the most common form of card transaction", "operationId": "saleOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AuthAndSaleTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/registerApplePayDomain": { "post": { "tags": [ "Wallet" ], "summary": "Register Apple Pay™ Domain", "description": "This api allows merchants to register apple pay domains", "operationId": "registerApplePayDomain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplePayMerchantRegisterRequestDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ApplePayRegistrationResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/refund": { "post": { "tags": [ "Payment Service" ], "summary": "Refund", "description": "A Refund transaction is the process of returning the funds of a previously settled transaction. A refund amount appears as a credit on the card holder’s statement.", "operationId": "refundOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RefundTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/rebill": { "post": { "tags": [ "Payment Service" ], "summary": "Rebill", "description": "A Rebill transaction is for merchants that are offering subscriptions for their services require a way of billing the same amount on a regular basis.", "operationId": "rebillOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebillInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RebillTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/order": { "get": { "tags": [ "Payment Service" ], "summary": "Get order", "description": "Retrieves a single order for the authenticated merchant.\nProvide at least one lookup key: id, clientOrderId, or transactionId.\nWhen clientOrderId is used without id or transactionId, netvalveMidId is required to disambiguate the merchant account.\n", "operationId": "getOrderById", "parameters": [ { "name": "id", "in": "query", "description": "Internal order identifier.", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 12345 }, { "name": "clientOrderId", "in": "query", "description": "Client-provided order identifier. Requires netvalveMidId when id and transactionId are not supplied.", "required": false, "schema": { "type": "string" }, "example": "ORD-12345-ABC" }, { "name": "netvalveMidId", "in": "query", "description": "Netvalve MID identifier required with clientOrderId-only lookup.", "required": false, "schema": { "type": "string" }, "example": "f8c2c3a9-9d2e-4a7e-9c6b-6b3c0a6e4f21" }, { "name": "transactionId", "in": "query", "description": "Internal transaction identifier linked to the order.", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 987654321 }, { "name": "collectBillingInfo", "in": "query", "description": "Include customer billing information in the order response.", "required": false, "schema": { "type": "string", "default": "false" }, "example": false }, { "name": "collectShippingInfo", "in": "query", "description": "Include customer shipping information in the order response.", "required": false, "schema": { "type": "string", "default": "false" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderOutputDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } }, "post": { "tags": [ "Payment Service" ], "summary": "Create Order", "description": "This api allows merchants to create order to initiate transaction", "operationId": "createOrder", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HppOrderInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateOrderResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/initializeApplePaySession": { "post": { "tags": [ "Wallet" ], "summary": "Initialize Apple Pay™ session", "description": "This api allows merchants to initialize apple pay session before transaction", "operationId": "initializeApplePaySession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplePayInitializeSessionRequestDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ApplePayInitializeSessionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/createToken": { "post": { "tags": [ "Payment Service" ], "summary": "Create token", "description": "The process of creating gateway token", "operationId": "createTokenizedCard", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTokenRequestDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateTokenResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/capture": { "post": { "tags": [ "Payment Service" ], "summary": "Capture", "description": "A Capture transaction is a process that flags an already authorized transaction to be settled in the next settlement period.", "operationId": "captureOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CaptureTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/cancel": { "post": { "tags": [ "Payment Service" ], "summary": "Cancel", "description": "Cancel operation can be done for successfully authorized transactions only. If a transaction is authorized then merchant can either capture or cancel the transaction. In case of cancel on-hold amount will be returned to customer card. The default period of on-hold varies for each card issuers normally it is around 5-30 days.", "operationId": "cancelOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CancelTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/authorize": { "post": { "tags": [ "Payment Service" ], "summary": "Authorize", "description": "The process of checking that the card being used in a transaction contains sufficient funds to cover the amount of the transaction", "operationId": "authorizeOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AuthAndSaleTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/3ds/v2/initialization": { "post": { "tags": [ "Three DS" ], "summary": "3DS Initialization V2", "description": "This endpoint allows merchant to initiate 3DS transaction", "operationId": "initAndAuthOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreeDSInitAndAuthInputDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ThreeDSInitAndAuthResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/3ds/result": { "post": { "tags": [ "Three DS" ], "summary": "3DS Result", "description": "This endpoint allows merchant to retrieve 3DS result", "operationId": "resultOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreeDSResultInputDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ThreeDSResultResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/3ds/authentication": { "post": { "tags": [ "Three DS" ], "summary": "3DS Authentication", "description": "This endpoint allows merchant to Authenticate 3DS transaction", "operationId": "authenticationOperation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreeDSAuthInputDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ThreeDSAuthenticationResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/volt/institutions": { "get": { "tags": [ "Payment Service" ], "summary": "Get Volt Institution List", "description": "This api allows merchants to get Volt Institution List for transaction", "operationId": "getVoltInstitutionsList", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VoltInstitution" } } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/volt/institutions/countries": { "get": { "tags": [ "Payment Service" ], "summary": "Get Volt Institutions Country List", "description": "This api allows merchants to get Volt Institutions Country List for transaction", "operationId": "getVoltInstitutionsCountryList", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VoltInstitutionCountry" } } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/venmo/client-token": { "get": { "tags": [ "Payment Service" ], "summary": "Generate Venmo Client Token", "description": "This api allows merchants to generate Venmo client token for transaction", "operationId": "generateVenmoClientToken", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/transaction": { "get": { "tags": [ "Reconciliation" ], "summary": "Get Transaction", "description": "This api allows merchant to retrieve an transaction by Id.", "operationId": "getTransactionById", "parameters": [ { "name": "id", "in": "query", "description": "Transaction identifier.", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 123456789 }, { "name": "collectBillingInfo", "in": "query", "description": "If true, billing address information is included in the response.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "collectShippingInfo", "in": "query", "description": "If true, shipping address information is included in the response.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionOutputDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/subscriptions": { "get": { "tags": [ "Recurring Payment Service" ], "operationId": "getAllManagedRecurringSubscriptionByFilters", "parameters": [ { "name": "filters", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/RecurringScheduleSearchFilterDTO" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageManagedRecurringSubscriptionDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } }, "summary": "Get subscriptions", "description": "Get all subscriptions" } }, "/subscription": { "get": { "tags": [ "Recurring Payment Service" ], "operationId": "getManagedRecurringSubscription", "parameters": [ { "name": "subscriptionId", "in": "query", "description": "Managed recurring subscription identifier", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 5001 }, { "name": "transactionId", "in": "query", "description": "Original transaction identifier", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 100001 }, { "name": "showRelatedTransactions", "in": "query", "description": "Include related transaction list in response", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedRecurringSubscriptionDTO" } } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } }, "summary": "Get subscription", "description": "Get subscription by subscriptionId or transactionId" } }, "/sdk/pageLayoutSettingsFile": { "get": { "tags": [ "Checkout SDK" ], "summary": "Get SDK page layout settings file", "description": "Returns a page layout asset, such as logo or CSS, when the supplied SDK Bearer token belongs to the layout owner.", "operationId": "getPageLayoutSettingsFile", "parameters": [ { "name": "id", "in": "query", "description": "Page layout file id.", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Page layout file type. Supported values: logo, html, css.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page layout file returned.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } }, "401": { "description": "Authentication failed.", "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "string", "format": "byte" } } } } }, "404": { "description": "File not found or not accessible for the SDK token.", "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "string", "format": "byte" } } } } } } } }, "/sdk/inquiry": { "get": { "tags": [ "Checkout SDK" ], "summary": "Query SDK transaction status", "description": "Retrieves the current status of the transaction bound to the supplied SDK Bearer token.", "operationId": "inquiry", "parameters": [ { "name": "transactionId", "in": "query", "description": "Internal transaction identifier returned by the SDK sale or 3DS payment response. The transaction must belong to the SDK Bearer token client.", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 987654321 }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseDTO" } } } }, "400": { "description": "Invalid transaction id.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } }, "401": { "description": "Authentication failed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TransactionResponseDTO" } } } } } } }, "/report/batchSummary": { "get": { "tags": [ "Reconciliation" ], "summary": "Batch summary", "description": "Retrieves batch summary rows for the authenticated merchant.\nSend filters as query parameters. fromDateTime and toDateTime must use yyyy-MM-dd HH:mm:ss format and are used against the batch created datetime.\nOptional filters are descriptor, midId, currency, cardType, bin, and countryCode. clientId is resolved from authentication.\n", "operationId": "getBatchSummaryData", "parameters": [ { "name": "fromDateTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "toDateTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "descriptor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "midId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchSummaryDataDTO" } } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/report/batchSummaryDetails": { "get": { "tags": [ "Reconciliation" ], "summary": "Batch details", "description": "Retrieves aggregate totals for a single batch ID scoped to the authenticated merchant.", "operationId": "getBatchSummaryDetails", "parameters": [ { "name": "batchId", "in": "query", "description": "Batch summary identifier.", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 12345 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/BatchSummaryDetailsDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/pse/banks": { "get": { "tags": [ "Payment Service" ], "summary": "Get PSE Bank List", "description": "This api allows merchants to get PSE bank list for transaction", "operationId": "getPseBankList", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PseBankList" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/paypal/client-token": { "get": { "tags": [ "Payment Service" ], "summary": "Generate PayPal Client Token", "description": "This api allows merchants to generate PayPal client token for transaction", "operationId": "generatePayPalClientToken", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/orders": { "get": { "tags": [ "Reconciliation" ], "summary": "Export orders by filters", "description": "Retrieves orders for the authenticated merchant using query-string filters and pagination.\nDates must use yyyy-MM-dd HH:mm:ss format, for example fromDateTime=2026-06-01 00:00:00&toDateTime=2026-06-26 23:59:59.\nIf orderId or clientOrderId is supplied, order identifier search takes precedence. If emailAddress is supplied without a complete date range, email search is prioritized.\nWhen fromDateTime/toDateTime are omitted, this endpoint performs a non-date-filtered search; no default date range is applied by this API.\n", "operationId": "exportOrders", "parameters": [ { "name": "filters", "in": "query", "description": "Order export filters. Send fields as query parameters, for example orderStatus=Completed¤cy=USD&ccLastFour=1111.", "required": true, "schema": { "$ref": "#/components/schemas/OrderSearchFilterDTO" } }, { "name": "page", "in": "query", "description": "Zero-based page number.", "required": true, "schema": { "minimum": 0, "type": "integer" }, "example": 0 }, { "name": "pageSize", "in": "query", "description": "Requested page size.", "required": true, "schema": { "minimum": 1, "type": "integer" }, "example": 100 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResultOrderDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/inquiry": { "get": { "tags": [ "Reconciliation" ], "summary": "Query Transaction Status", "description": "Retrieve the status of a previously submitted transaction", "operationId": "inquiry_1", "parameters": [ { "name": "transactionId", "in": "query", "description": "Transaction identifier to query status for.", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 123456789 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/InquiryTransactionResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/hpf/initializeSession": { "get": { "tags": [ "Hosted Payment Fields" ], "summary": "Initialize Session", "description": "The process of initialize Session", "operationId": "initializeSession_1", "parameters": [ { "name": "version", "in": "query", "description": "Hosted payment field script version.", "required": false, "schema": { "type": "string" }, "example": "1.0.0" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/HostedPaymentFieldsResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/export": { "get": { "tags": [ "Reconciliation" ], "summary": "Export transactions by filters", "description": "Retrieves transactions for the authenticated merchant using query-string filters.\nDates must use yyyy-MM-dd HH:mm:ss format, for example fromDateTime=2026-06-01 00:00:00&toDateTime=2026-06-26 23:59:59.\nIf transactionId is supplied, the service searches by that transaction first. Otherwise, an explicit fromDateTime/toDateTime range is used; when dates are omitted, the configured default lookback window is applied.\nThe service enforces the configured maximum export date range and caps pageSize to the configured maximum unless maxLimit is provided.\n", "operationId": "exportTransactions", "parameters": [ { "name": "filters", "in": "query", "description": "Transaction export filters. Send fields as query parameters, for example transactionType=SALE¤cy=USD&ccLastFour=1111.", "required": true, "schema": { "$ref": "#/components/schemas/TransactionSearchFilterDTO" } }, { "name": "page", "in": "query", "description": "Zero-based page number.", "required": true, "schema": { "minimum": 0, "type": "integer" }, "example": 0 }, { "name": "pageSize", "in": "query", "description": "Requested page size. The service caps this to its configured maximum or to maxLimit when supplied in filters.", "required": true, "schema": { "minimum": 1, "type": "integer" }, "example": 100 }, { "name": "collectBillingInfo", "in": "query", "description": "Include customer billing information in each transaction result.", "required": false, "schema": { "type": "string", "default": "false" }, "example": false }, { "name": "collectShippingInfo", "in": "query", "description": "Include customer shipping information in each transaction result.", "required": false, "schema": { "type": "string", "default": "false" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResultTransactionDTO" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidationFieldsResponseDTO" } } } } } } }, "/hpp/order": { "post": { "tags": [ "Hosted Payment Page" ], "summary": "Create Order", "description": "This api allows merchants to create order to initiate transaction", "operationId": "createOrder", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HppOrderInputFieldsDTO" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateOrderResponseDTO" } } } } } } }, "/hpp/volt/institutions": { "get": { "tags": [ "Hosted Payment Page" ], "summary": "Get Volt Institution List", "description": "This api allows merchants to get Volt Institution List for HPP transaction", "operationId": "getVoltInstitutionsList", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VoltInstitution" } } } } } } } }, "/hpp/volt/institutions/countries": { "get": { "tags": [ "Hosted Payment Page" ], "summary": "Get Volt Institutions Country List", "description": "This api allows merchants to get Volt Institutions Country List for HPP transaction", "operationId": "getVoltInstitutionsCountryList", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VoltInstitutionCountry" } } } } } } } }, "/hpp/venmo/client-token": { "get": { "tags": [ "Hosted Payment Page" ], "operationId": "generateVenmoClientToken", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "string" } } } } } } }, "/hpp/pse/banks": { "get": { "tags": [ "Hosted Payment Page" ], "operationId": "getPseBankList", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PseBankList" } } } } } } } }, "components": { "schemas": { "ValidationFieldsResponseDTO": { "type": "object", "properties": { "responseCode": { "type": "string" }, "responseMessage": { "type": "string" }, "responseCodeType": { "type": "string" }, "traceID": { "type": "string" }, "responseTimestamp": { "type": "string", "format": "date-time" } } }, "RecurringScheduleDTO": { "required": [ "recurringAmount", "recurringPeriod", "startDate", "recurringAmount", "recurringPeriod", "startDate" ], "type": "object", "properties": { "subscriptionName": { "type": "string", "description": "Optional name of the subscription or recurring plan. Valid text up to 1000 characters.", "example": "Gold Membership Plan" }, "recurringPeriod": { "maximum": 365, "minimum": 1, "type": "integer", "description": "Recurring interval value. Required on create, optional on update. Allowed range: 1 to 365. Interpreted using recurringType; if recurringType is omitted, DAYS is used.", "format": "int32", "example": 30 }, "startDate": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Start date and time of the recurring schedule. Required on create. Format: yyyy-MM-dd HH:mm:ss. Must not be in the past. Not applied by the managed recurring update endpoint.", "format": "date-time" }, "endDate": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Optional end date and time of the recurring schedule. Format: yyyy-MM-dd HH:mm:ss. If provided, it must not be in the past and must be after the start date.", "format": "date-time" }, "recurringAmount": { "minimum": 0, "type": "number", "description": "Amount to be charged for each recurrence cycle. Required on create. Must be zero or greater, with up to 2 decimal places and up to 8 integer digits.", "example": 499.99 }, "recurringType": { "type": "string", "description": "Type of recurring interval. Optional on create and update. If omitted on create, DAYS is used.", "example": "DAYS", "enum": [ "DAYS", "HOURS", "DAYS", "HOURS" ] }, "status": { "type": "string", "description": "Status to apply to the recurring schedule. Optional and mainly used on update. Create defaults the managed subscription status to ACTIVE.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED", "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "dateNextAttempt": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Timestamp of the next scheduled recurring payment attempt. Optional and mainly used on update. Format: yyyy-MM-dd HH:mm:ss. Must not be in the past, must be after the subscription start date, and must be before the end date when an end date exists.", "format": "date-time" } }, "description": "Recurring schedule configuration. For create requests, recurringPeriod, startDate, and recurringAmount are required. For update requests, recurringSchedule can be omitted to keep the existing subscription unchanged; if supplied, only non-null fields are applied. Date-time fields use yyyy-MM-dd HH:mm:ss." }, "UpdateManagedRecurringSubscriptionRequestDTO": { "required": [ "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "reason": { "type": "string", "description": "Optional reason for update.", "example": "Customer changed schedule preferences" }, "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" } }, "description": "Request payload for updating an existing managed recurring subscription." }, "UpdateManagedRecurringSubscriptionResponseDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "transactionId": { "type": "integer", "description": "Original transaction identifier linked to the subscription.", "format": "int64", "example": 100001 }, "clientId": { "type": "integer", "description": "Client identifier owning this subscription.", "format": "int64", "example": 2001 }, "status": { "type": "string", "description": "Current recurring schedule status.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "createdDatetime": { "type": "string", "description": "Subscription creation timestamp.", "format": "date-time" }, "updatedDatetime": { "type": "string", "description": "Subscription last updated timestamp.", "format": "date-time" }, "nextAttemptDate": { "type": "string", "description": "Next rebill attempt date-time.", "format": "date-time" }, "recurringType": { "type": "string", "description": "Recurring unit type.", "example": "DAYS", "enum": [ "DAYS", "HOURS" ] }, "recurringPeriod": { "type": "integer", "description": "Recurring interval count.", "format": "int32", "example": 30 }, "recurringAmount": { "type": "number", "description": "Amount charged each recurring attempt.", "example": 99.99 }, "failureAttempts": { "type": "integer", "description": "Total failure attempts for this subscription.", "format": "int32", "example": 0 }, "subscriptionName": { "type": "string", "description": "Subscription name.", "example": "Gym Membership" }, "description": { "type": "string", "description": "Subscription description or update reason." }, "recurringTransactionStatus": { "type": "string", "description": "Current recurring transaction status.", "example": "NEW", "enum": [ "NEW", "PROCESSING", "COMPLETED", "FAILED" ] }, "endDate": { "type": "string", "description": "Subscription end date-time, if configured.", "format": "date-time" }, "startDate": { "type": "string", "description": "Subscription start date-time.", "format": "date-time" }, "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Managed recurring subscription updated successfully." } }, "description": "Response payload returned after updating managed recurring subscription." }, "CancelManagedRecurringSubscriptionRequestDTO": { "required": [ "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "reason": { "type": "string", "description": "Reason for cancellation.", "example": "Customer requested cancellation" } }, "description": "Request payload for canceling an existing managed recurring subscription." }, "CancelManagedRecurringSubscriptionResponseDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "transactionId": { "type": "integer", "description": "Original transaction identifier linked to the subscription.", "format": "int64", "example": 100001 }, "clientId": { "type": "integer", "description": "Client identifier owning this subscription.", "format": "int64", "example": 2001 }, "status": { "type": "string", "description": "Recurring schedule status after cancellation.", "example": "INACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "createdDatetime": { "type": "string", "description": "Subscription creation timestamp.", "format": "date-time" }, "updatedDatetime": { "type": "string", "description": "Subscription cancellation timestamp.", "format": "date-time" }, "nextAttemptDate": { "type": "string", "description": "Next rebill attempt date-time, if present.", "format": "date-time" }, "recurringType": { "type": "string", "description": "Recurring unit type.", "example": "DAYS", "enum": [ "DAYS", "HOURS" ] }, "recurringPeriod": { "type": "integer", "description": "Recurring interval count.", "format": "int32", "example": 30 }, "recurringAmount": { "type": "number", "description": "Amount charged each recurring attempt.", "example": 99.99 }, "failureAttempts": { "type": "integer", "description": "Total failure attempts for this subscription.", "format": "int32", "example": 0 }, "subscriptionName": { "type": "string", "description": "Subscription name.", "example": "Gym Membership" }, "description": { "type": "string", "description": "Cancellation reason or subscription description." }, "recurringTransactionStatus": { "type": "string", "description": "Current recurring transaction status.", "example": "NEW", "enum": [ "NEW", "PROCESSING", "COMPLETED", "FAILED" ] }, "endDate": { "type": "string", "description": "Subscription end date-time, if configured.", "format": "date-time" }, "startDate": { "type": "string", "description": "Subscription start date-time.", "format": "date-time" }, "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Managed recurring subscription canceled successfully." } }, "description": "Response payload returned after canceling managed recurring subscription." }, "WalletInitializeSessionRequestDTO": { "type": "object", "properties": { "domainName": { "type": "string" }, "midId": { "type": "integer", "format": "int64" }, "netvalveMidId": { "type": "string" }, "siteId": { "type": "string" }, "clientName": { "type": "string" }, "clientId": { "type": "integer", "format": "int64" }, "walletType": { "type": "string", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "correlationId": { "type": "string" } } }, "WalletInitializeSessionResponseDTO": { "type": "object", "properties": { "status": { "type": "string", "description": "Wallet session status.", "example": "OK" }, "data": { "type": "string", "description": "Wallet session payload represented as JSON string.", "example": "{\"merchantIdentifier\":\"merchant.com.example\",\"merchantName\":\"Example Store\"}" } }, "description": "Wallet-specific session initialization result payload." }, "NetworkTokenStateChangeNotificationDTO": { "type": "object", "properties": { "messageId": { "type": "string" }, "conversationId": { "type": "string" }, "tokenRequestorId": { "type": "string" }, "tokenReferenceId": { "type": "string" }, "requestReason": { "type": "string" }, "requestReasonCode": { "type": "string" }, "previousTokenState": { "type": "string" }, "currentTokenState": { "type": "string" }, "tokenTimestamp": { "type": "string" } } }, "TokenStateChangeDTO": { "type": "object", "properties": { "token": { "type": "string" }, "referenceNumber": { "type": "string" }, "success": { "type": "string" }, "error": { "type": "string" }, "networkTokenStateChangeNotification": { "$ref": "#/components/schemas/NetworkTokenStateChangeNotificationDTO" } } }, "TokenStateChangeResponseDTO": { "type": "object", "properties": { "traceId": { "type": "string" }, "responseTimestamp": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "PENDING", "CANCELLED", "DISABLE", "USED", "SUCCESS", "FAILED", "SUSPEND", "RETRY", "ON_HOLD", "RETIRED" ] } } }, "InstantRecurringPaymentDTO": { "required": [ "amount", "subscriptionId" ], "type": "object", "properties": { "subscriptionId": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "amount": { "type": "number", "description": "Amount to be charged for the instant recurring payment.", "example": 49.99 }, "nextAttemptDate": { "type": "string", "description": "Override for the next recurring attempt date-time.", "format": "date-time" } }, "description": "Request payload for triggering an instant payment against an existing managed recurring subscription." }, "RebillTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for tracing request flow.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp generated by the service.", "format": "date-time", "example": "2026-04-27T11:05:30Z" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 100001 }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "cardType": { "type": "string", "description": "Card brand/type when card data is available.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Transaction identifier returned by bank/acquirer.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code returned by bank/acquirer.", "example": "123456" }, "midId": { "type": "integer", "description": "Merchant identifier used for processing.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External/Netvalve merchant identifier.", "example": "f7e0f1b8-2c6d-4a91-9a5b-3de2c4f8b7a1" }, "processor": { "type": "string", "description": "Payment processor name.", "example": "TSYS" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "transactionType": { "type": "string", "description": "Transaction operation type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "currency": { "type": "string", "description": "Processed transaction currency (ISO 4217).", "example": "USD" }, "clientId": { "type": "integer", "description": "Client identifier associated with the transaction.", "format": "int64", "example": 2001 }, "siteId": { "type": "string", "description": "Site identifier associated with the transaction.", "example": "6001" }, "amount": { "type": "number", "description": "Transaction amount processed for rebill payment.", "example": 49.99 }, "subscriptionId": { "type": "integer", "description": "Managed recurring subscription identifier linked to the payment.", "format": "int64", "example": 5001 }, "subscriptionStatus": { "type": "string", "description": "Subscription status after rebill.", "example": "ACTIVE" } }, "description": "Response payload for recurring rebill or instant recurring payment transaction." }, "CreateManagedRecurringSubscriptionRequestDTO": { "required": [ "recurringSchedule", "transactionId" ], "type": "object", "properties": { "transactionId": { "type": "integer", "description": "Existing transaction identifier for which subscription will be created.", "format": "int64", "example": 100001 }, "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" }, "recurringScheduleStatus": { "type": "string", "description": "Current recurring schedule status.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] } }, "description": "Request payload for creating a managed recurring subscription from an existing transaction." }, "CreateManagedRecurringSubscriptionResponseDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "transactionId": { "type": "integer", "description": "Original transaction identifier linked to the subscription.", "format": "int64", "example": 100001 }, "clientId": { "type": "integer", "description": "Client identifier owning this subscription.", "format": "int64", "example": 2001 }, "status": { "type": "string", "description": "Current recurring schedule status.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "createdDatetime": { "type": "string", "description": "Subscription creation timestamp.", "format": "date-time" }, "updatedDatetime": { "type": "string", "description": "Subscription last updated timestamp.", "format": "date-time" }, "nextAttemptDate": { "type": "string", "description": "Next rebill attempt date-time.", "format": "date-time" }, "recurringType": { "type": "string", "description": "Recurring unit type.", "example": "DAYS", "enum": [ "DAYS", "HOURS" ] }, "recurringPeriod": { "type": "integer", "description": "Recurring interval count.", "format": "int32", "example": 30 }, "recurringAmount": { "type": "number", "description": "Amount charged each recurring attempt.", "example": 99.99 }, "failureAttempts": { "type": "integer", "description": "Total failure attempts for this subscription.", "format": "int32", "example": 0 }, "subscriptionName": { "type": "string", "description": "Subscription name.", "example": "Gym Membership" }, "description": { "type": "string", "description": "Subscription description or reason." }, "recurringTransactionStatus": { "type": "string", "description": "Current recurring transaction status.", "example": "NEW", "enum": [ "NEW", "PROCESSING", "COMPLETED", "FAILED" ] }, "endDate": { "type": "string", "description": "Subscription end date-time, if configured.", "format": "date-time" }, "startDate": { "type": "string", "description": "Subscription start date-time.", "format": "date-time" }, "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Managed recurring subscription created successfully." } }, "description": "Response payload returned after successfully creating managed recurring subscription." }, "AlternativePaymentMethodDTO": { "type": "object", "properties": { "userType": { "type": "string", "description": "Type of user initiating the payment (e.g., Person or Company)." }, "documentType": { "type": "string", "description": "Type of identification document provided by the payer.", "example": "cpf" }, "documentNumber": { "type": "string", "description": "Identification document number of the payer.", "example": "A12345678" }, "rfcPf": { "type": "string", "description": "Mexican Tax Identification Number (RFC) for an individual (Persona Física). Required for SPEI payments when the payer is a natural person.", "example": "SOMH031031C50" }, "socialName": { "type": "string", "description": "Registered or social name of the payer as per official records.", "example": "John Doe" }, "fiscalCountry": { "type": "string", "description": "Country of tax residency.", "example": "Brasil" }, "paymentNonce": { "type": "string", "description": "One-time payment token (nonce) generated by the APM provider to authorize the transaction securely." }, "financialInstitutionCode": { "type": "string", "description": "Code identifying the financial institution involved in the payment." }, "payerEmail": { "type": "string", "description": "Email address of the payer." }, "payerPhone": { "type": "string", "description": "Phone number of the payer." } }, "description": "Alternative payment method customer and payment details." }, "ApplePaySSLDTO": { "type": "object", "properties": { "paymentData": { "$ref": "#/components/schemas/ApplePaymentDataDTO" }, "paymentMethod": { "$ref": "#/components/schemas/ApplePaymentMethodDTO" }, "transactionIdentifier": { "type": "string", "description": "Unique transaction identifier generated by the Apple Pay device." } }, "description": "Apple Pay encrypted payment payload." }, "ApplePaymentDataDTO": { "required": [ "version", "version" ], "type": "object", "properties": { "version": { "type": "string", "description": "Version of Apple Pay payment token format. Typically EC_v1.", "example": "EC_v1" }, "signature": { "type": "string", "description": "Cryptographic signature used to verify the integrity of the payment data." }, "data": { "type": "string", "description": "Base64-encoded encrypted payment data containing tokenized card information." }, "header": { "$ref": "#/components/schemas/HeaderDTO" } }, "description": "Encrypted Apple Pay payment data payload including cryptographic information and tokenized payment details." }, "ApplePaymentMethodDTO": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Human-readable name of the payment method as shown in Apple Pay wallet.", "example": "Visa 4242" }, "network": { "type": "string", "description": "Card network used for the Apple Pay transaction.", "example": "VISA" }, "type": { "type": "string", "description": "Type of payment method used in Apple Pay (e.g., debit, credit, prepaid).", "example": "credit" } }, "description": "Apple Pay payment method details including card network and display information." }, "BillingAddressDTO": { "type": "object", "properties": { "billingAddress": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Billing street address line.", "example": "221B Baker Street" }, "billingZipCode": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Billing ZIP/postal code.", "example": "10001" }, "billingCity": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Billing city.", "example": "New York" }, "billingState": { "maxLength": 30, "minLength": 0, "type": "string", "description": "Billing state/region.", "example": "NY" }, "billingCountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Billing country code in ISO 3166-1 alpha-2 format.", "example": "GB" }, "addressIdentifier": { "type": "string", "description": "Optional identifier for saved/normalized billing address record.", "example": "BILL-ADDR-001" } }, "description": "Billing address details associated with a transaction/order." }, "GoogleIntermediateSigningKeyDTO": { "type": "object", "properties": { "signedKey": { "type": "string", "description": "JSON Web Signature (JWS) signed key used for Google Pay signature verification." }, "signatures": { "type": "array", "description": "Array of signatures corresponding to the intermediate signing key.", "items": { "type": "string", "description": "Array of signatures corresponding to the intermediate signing key." } } }, "description": "Intermediate signing key bundle used to verify Google Pay signature." }, "GooglePaySSLDTO": { "type": "object", "properties": { "protocolVersion": { "type": "string", "description": "Google Pay protocol version for the signed payload.", "example": "ECv2" }, "signature": { "type": "string", "description": "Cryptographic signature returned by Google Pay." }, "intermediateSigningKey": { "$ref": "#/components/schemas/GoogleIntermediateSigningKeyDTO" }, "signedMessage": { "type": "string", "description": "Serialized signed message containing encrypted payment payload and cryptographic metadata." } }, "description": "Google Pay encrypted payment payload." }, "HeaderDTO": { "required": [ "ephemeralPublicKey", "publicKeyHash", "transactionId", "ephemeralPublicKey", "publicKeyHash", "transactionId" ], "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transaction identifier generated on the Apple Pay device." }, "publicKeyHash": { "type": "string", "description": "SHA-256 hash of the merchant’s X.509 public key certificate used for payment encryption." }, "ephemeralPublicKey": { "type": "string", "description": "Ephemeral public key generated for this transaction. Required for EC_v1 encryption." } }, "description": "Apple Pay cryptographic header containing keys and identifiers required for secure payment decryption." }, "HppBrowserInfoDTO": { "type": "object", "properties": { "userAgent": { "type": "string" }, "browserHeader": { "type": "string" }, "browserLanguage": { "type": "string" }, "browserJavaEnabled": { "type": "boolean" }, "browserColorDepth": { "type": "integer", "format": "int32" }, "browserScreenHeight": { "type": "integer", "format": "int32" }, "browserScreenWidth": { "type": "integer", "format": "int32" }, "browserTimeZone": { "type": "integer", "format": "int32" }, "browserIp": { "type": "string" } }, "description": "Browser/device data used for 3DS and risk checks." }, "HppCustomerDetailsDTO": { "type": "object", "properties": { "customerIp": { "type": "string", "description": "Customer IP address (IPv4).", "example": "203.0.113.10" }, "customerEmail": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer email address.", "example": "john.doe@example.com" }, "customerName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer full name.", "example": "John Doe" }, "customerFirstName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer first name.", "nullable": true, "example": "John" }, "customerLastName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer last name.", "example": "Doe" }, "customerAddress": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer address line.", "example": "123 Main Street" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Customer ZIP/postal code.", "example": "10001" }, "customerCity": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer city.", "example": "New York" }, "customerState": { "maxLength": 30, "minLength": 0, "type": "string", "description": "Customer state/region.", "example": "NY" }, "customerCountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Customer country code.", "example": "US" }, "customerPhone": { "maxLength": 20, "minLength": 0, "type": "string", "description": "Customer phone number.", "example": "+15551234567" } }, "description": "Customer details used in HPP create order/payment flows." }, "SdkSaleRequestDTO": { "required": [ "paymentToken" ], "type": "object", "properties": { "siteId": { "type": "string", "description": "Merchant site identifier for the SDK session.", "example": "site-id" }, "paymentToken": { "type": "string", "description": "Payment token returned by the SDK initialize-session endpoint.", "example": "tok_8f34c1d7e9ab42f5" }, "paymentType": { "type": "string", "description": "Payment method type. Defaults to CARD when omitted or invalid.", "example": "CARD" }, "walletType": { "type": "string", "description": "Wallet type for wallet payments.", "example": "APPLE_PAY" }, "applePaySSL": { "$ref": "#/components/schemas/ApplePaySSLDTO" }, "googlePaySSL": { "$ref": "#/components/schemas/GooglePaySSLDTO" }, "tokenizedDTO": { "$ref": "#/components/schemas/TokenizedDTO" }, "apmType": { "type": "string", "description": "Alternative payment method type.", "example": "PAYPAL" }, "alternativePaymentMethod": { "$ref": "#/components/schemas/AlternativePaymentMethodDTO" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Card holder name when card details are collected by the SDK.", "example": "Jane Doe" }, "dfReferenceId": { "type": "string", "description": "Device fingerprint reference identifier for risk and 3DS flows.", "example": "df-ref-123" }, "transID": { "type": "string", "description": "3DS transaction identifier when continuing a 3DS flow.", "example": "3ds-trans-123" }, "customerDetails": { "$ref": "#/components/schemas/HppCustomerDetailsDTO" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "isBillingAndShippingDetailsSame": { "type": "boolean", "description": "Whether billing and shipping details are the same.", "example": false }, "browserData": { "$ref": "#/components/schemas/HppBrowserInfoDTO" } }, "description": "SDK sale request containing the payment token and payment method payload." }, "ShippingAddressDTO": { "type": "object", "properties": { "shippingAddress": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Shipping address line.", "example": "123 Main Street" }, "shippingZipCode": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Shipping ZIP/postal code.", "example": "10001" }, "shippingCity": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Shipping city.", "example": "New York" }, "shippingState": { "maxLength": 30, "minLength": 0, "type": "string", "description": "Shipping state/region.", "example": "NY" }, "shippingCountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Shipping country code (ISO 3166-1 alpha-2).", "example": "US" }, "addressIdentifier": { "type": "string", "description": "Internal identifier for stored shipping address.", "example": "98f46613-9ee7-40a8-a3d6-8f2b7ccb91a2" } }, "description": "Shipping address details associated with a transaction/order." }, "TokenizedDTO": { "type": "object", "properties": { "cardNumber": { "type": "string", "description": "DPAN" }, "cardExpiryMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string", "description": "Card expiry month in MM format.", "example": "09" }, "cardExpiryYear": { "maxLength": 4, "minLength": 4, "type": "string", "description": "Card expiry year in YYYY format.", "example": "2028" }, "cryptogram": { "type": "string" }, "eciIndicator": { "type": "string" }, "authMethod": { "type": "string" }, "paymentToken": { "type": "string" } } }, "APMPaymentInfoDTO": { "type": "object", "properties": { "apmPaymentUrl": { "type": "string", "description": "Redirect/deeplink URL used by the payer to complete APM payment.", "example": "https://pay.provider.com/checkout/abc123" }, "apmPaymentUrlExpiry": { "type": "string", "description": "Expiry timestamp for the APM payment URL.", "format": "date-time", "example": "2026-05-09T18:30:00+05:30" }, "bankAccountNumber": { "type": "string", "description": "Destination bank account number provided for manual transfer based APM flows.", "example": "123456789012" }, "bankName": { "type": "string", "description": "Destination bank name for the payment instructions.", "example": "Banco Example" }, "beneficiaryName": { "type": "string", "description": "Account beneficiary name to be shown to the payer.", "example": "Gateway Payments LLC" }, "dynamicClabe": { "type": "string", "description": "Dynamic CLABE value generated for Mexico bank transfer flows when applicable.", "example": "032180000118359719" }, "referenceNumber": { "type": "string", "description": "Reference number that the payer must include while making payment.", "example": "REF-84736291" }, "qrCode": { "type": "string", "description": "QR payload/content returned for QR-based APM payment flows.", "example": "00020101021226830014br.gov.bcb.pix2561qrcode.provider.com/pix/v2/8f3d2d2a-1d3b-4fc9-8b92-12ab34cd56ef5204000053039865406100.005802BR5913Gateway Store6009Sao Paulo62140510REF123456304B9A1" }, "qrCodeExpiry": { "type": "string", "description": "Expiry timestamp for the QR code content.", "format": "date-time" }, "payerEmail": { "type": "string" }, "apmPaymentDirectUrl": { "type": "string" } }, "description": "Alternative payment method details returned for APM transactions." }, "BinInfo": { "type": "object", "properties": { "cardBin": { "type": "string", "description": "Card BIN/IIN prefix.", "example": "411111" }, "cardBrand": { "type": "string", "description": "Card scheme/brand.", "example": "VISA" }, "cardIssuer": { "type": "string", "description": "Card issuer/bank name.", "example": "Example Bank" }, "cardFundingType": { "type": "string", "description": "Card funding type.", "example": "CREDIT" }, "cardCategoryLevel": { "type": "string", "description": "Issuer product/category level.", "example": "PREPAID" }, "cardIssuerCountry": { "type": "string", "description": "Issuer country code (ISO 3166-1 alpha-2).", "example": "US" }, "cardIssuerPhone": { "type": "string", "description": "Issuer support/contact phone number.", "example": "+18005551234" }, "cardIssuerSite": { "type": "string", "description": "Issuer website URL.", "example": "https://www.examplebank.com" } }, "description": "BIN lookup information derived from the card number." }, "ResultThreeDSTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Trace identifier for request correlation.", "example": "trace-7f3d9e12" }, "responseTimestamp": { "type": "string", "description": "Timestamp when the 3DS response was generated.", "format": "date-time", "example": "2026-05-09T18:30:00Z" }, "transID": { "type": "string", "description": "Internal transaction identifier for the 3DS flow.", "example": "TXN-123456789" }, "referenceId": { "type": "string", "description": "Reference identifier tied to the transaction request.", "example": "REF-987654" }, "errorCode": { "type": "string", "description": "Error code returned when 3DS processing fails.", "example": "3DS_1001" }, "errorMessage": { "type": "string", "description": "Error message returned when 3DS processing fails.", "example": "Challenge initialization failed" }, "threeDs2TransactionId": { "type": "string", "description": "3DS2 provider transaction identifier.", "example": "3DS2-abc-123" }, "eci": { "type": "string", "description": "Electronic Commerce Indicator returned by 3DS.", "example": "05" }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value returned by 3DS.", "example": "AAABBIIFmAAAAAAAAAAAAAAAAAA=" }, "challengeRequired": { "type": "boolean", "description": "Indicates whether a challenge step is required.", "example": true }, "jwt": { "type": "string", "description": "JWT token required for client-side challenge continuation.", "example": "eyJhbGciOi..." }, "redirectUrl": { "type": "string", "description": "URL where client should be redirected for next 3DS step.", "example": "https://acs.example.com/challenge" }, "status": { "type": "string", "description": "Current 3DS status for the transaction.", "example": "CHALLENGE_REQUIRED", "enum": [ "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED", "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED" ] }, "threeDsVersion": { "type": "string", "description": "3DS protocol version used for this transaction.", "example": "2.0.0" }, "providerRedirectUrl": { "type": "string", "description": "Provider-specific redirect URL for completing 3DS.", "example": "https://provider.example.com/redirect/txn123" }, "merchantRedirectUrl": { "type": "string", "description": "Merchant callback/return URL after 3DS flow completes.", "example": "https://merchant.example.com/3ds/callback" }, "provider": { "type": "string", "description": "3DS provider identifier handling the authentication.", "example": "UNICON" }, "providerTransactionId": { "type": "string", "description": "Provider transaction identifier returned by 3DS provider.", "example": "UNI-3DS-443322" }, "netvalveCallBackUrl": { "type": "string", "description": "Callback URL to be used by Netvalve integration, when applicable.", "example": "https://gateway.example.com/netvalve/callback" }, "authType": { "type": "string", "description": "Authentication type returned by provider.", "example": "CHALLENGE" }, "methodPostData": { "type": "string", "description": "Additional form post data required for browser-based challenge steps.", "example": "PaReq=...&MD=...&TermUrl=..." }, "cReq": { "type": "string", "description": "Base64 CReq payload for Mastercard challenge flow.", "example": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6Ii4uLiJ9" } }, "description": "Response payload for 3DS transaction initialization/challenge flows." }, "TokenizationResponseDTO": { "type": "object", "properties": { "tokenizationSuccessful": { "type": "boolean" } } }, "TransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string" }, "responseTimestamp": { "type": "string", "format": "date-time" }, "orderId": { "type": "integer", "format": "int64" }, "transactionID": { "type": "integer", "format": "int64" }, "responseCode": { "type": "string" }, "responseMessage": { "type": "string" }, "responseCodeType": { "type": "string" }, "bankResponseCode": { "type": "string" }, "bankResponseMessage": { "type": "string" }, "orderState": { "type": "string", "enum": [ "CREATED", "READY_TO_PAY", "PENDING", "PAID", "DECLINED", "EXPIRED", "AWAIT_3DS", "CREATED", "READY_TO_PAY", "PENDING", "PAID", "DECLINED", "EXPIRED", "AWAIT_3DS" ] }, "redirectUrl": { "type": "string" }, "merchantName": { "type": "string" }, "clientId": { "type": "integer", "format": "int64" }, "isRetryAllowed": { "type": "boolean" }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ResultThreeDSTransactionResponseDTO" }, "paymentMethod": { "type": "string" }, "cardNumber": { "type": "string" }, "cardExpiryMonth": { "type": "string" }, "cardExpiryYear": { "type": "string" }, "cardType": { "type": "string" }, "bankTransactionId": { "type": "string" }, "authCode": { "type": "string" }, "midId": { "type": "integer", "format": "int64" }, "netvalveMidId": { "type": "string" }, "processor": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "hppIFrameSupported": { "type": "boolean" }, "token": { "type": "string" }, "tokenizationResponseDTO": { "$ref": "#/components/schemas/TokenizationResponseDTO" }, "paymentAttempted": { "type": "boolean" }, "paymentChannelType": { "type": "string", "enum": [ "HPP", "API", "API_3DS", "HPP_3DS", "RETRY_WITH_HPP", "SMART_ROUTING", "RETRY_WITH_SMART_ROUTING", "SERVER_TO_SERVER", "RETRY_WITH_SERVER_TO_SERVER", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "HPP_3DS_CARDS", "HPP_3DS_APPLE_PAY", "HPP_3DS_GOOGLE_PAY", "HPP_3DS_SAMSUNG_PAY", "HPP_APPLE_PAY_CONFIG_NETVALVE_INTEGRATOR", "HPP_APPLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_APPLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_APPLE_PAY_CONFIG_MID_LEVEL", "HPP_GOOGLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_GOOGLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_GOOGLE_PAY_CONFIG_MID_LEVEL", "GATEWAY_TOKEN_SAVING", "GATEWAY_TOKEN_PROCESSING", "NETWORK_TOKEN_SAVING", "NETWORK_TOKEN_PROCESSING", "HOSTED_PAYMENT_FIELDS", "ACCOUNT_UPDATER", "DISABLE_BLACKLIST", "ENABLE_DYNAMIC_DESCRIPTOR", "ENABLE_BIN_INFO_RESPONSE", "ENABLE_DATA_ENRICHMENT", "HPP", "API", "API_3DS", "HPP_3DS", "RETRY_WITH_HPP", "SMART_ROUTING", "RETRY_WITH_SMART_ROUTING", "SERVER_TO_SERVER", "RETRY_WITH_SERVER_TO_SERVER", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "HPP_3DS_CARDS", "HPP_3DS_APPLE_PAY", "HPP_3DS_GOOGLE_PAY", "HPP_3DS_SAMSUNG_PAY", "HPP_APPLE_PAY_CONFIG_NETVALVE_INTEGRATOR", "HPP_APPLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_APPLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_APPLE_PAY_CONFIG_MID_LEVEL", "HPP_GOOGLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_GOOGLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_GOOGLE_PAY_CONFIG_MID_LEVEL", "GATEWAY_TOKEN_SAVING", "GATEWAY_TOKEN_PROCESSING", "NETWORK_TOKEN_SAVING", "NETWORK_TOKEN_PROCESSING", "HOSTED_PAYMENT_FIELDS", "ACCOUNT_UPDATER", "DISABLE_BLACKLIST", "ENABLE_DYNAMIC_DESCRIPTOR", "ENABLE_BIN_INFO_RESPONSE", "ENABLE_DATA_ENRICHMENT" ] }, "siteId": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentTokenType": { "type": "string", "enum": [ "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK", "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK" ] }, "transactionType": { "type": "string", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY", "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "walletInitializeSessionResponseDTO": { "$ref": "#/components/schemas/WalletInitializeSessionResponseDTO" }, "subscriptionId": { "type": "integer", "format": "int64" }, "subscriptionStatus": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED", "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "binInfo": { "$ref": "#/components/schemas/BinInfo" }, "apmType": { "type": "string", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE", "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "apmPaymentInfo": { "$ref": "#/components/schemas/APMPaymentInfoDTO" }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY", "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } } }, "AdditionalTaxDetailsDTO": { "type": "object", "properties": { "taxType": { "type": "string", "description": "Tax type code or label.", "example": "VAT" }, "taxAmount": { "type": "number", "description": "Tax amount for the given tax type.", "example": 10 }, "taxRate": { "type": "number", "description": "Tax rate percentage.", "example": 7.5 }, "taxCategory": { "type": "string", "description": "Tax category/classification.", "example": "STANDARD" } }, "description": "Additional tax details used in Level 3 transaction data." }, "HppOrderInputFieldsDTO": { "required": [ "amount", "cancelUrl", "currency", "failedUrl", "successUrl", "amount", "cancelUrl", "currency", "failedUrl", "successUrl" ], "type": "object", "properties": { "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" }, "mode": { "type": "string", "description": "Transaction mode for create order.", "example": "SALE", "enum": [ "SALE", "AUTHORIZATION" ] }, "amount": { "type": "number", "description": "Order amount.", "example": 49.99 }, "currency": { "type": "string", "description": "Order currency (ISO-4217).", "example": "USD" }, "midId": { "type": "integer", "description": "Internal merchant identifier.", "format": "int64", "example": 3001 }, "netvalveMidId": { "type": "string", "description": "External merchant identifier.", "example": "716a2234-8e24-4a2d-b0d9-aa35d02f370d" }, "siteId": { "type": "string", "description": "Site identifier for routing/layout.", "example": "201" }, "clientOrderId": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Client-provided unique order reference.", "example": "ORD-20260422-001" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string" }, "orderDesc": { "type": "string", "description": "Order description.", "example": "Monthly subscription payment" }, "successUrl": { "type": "string", "description": "Redirect URL for successful payment.", "example": "https://merchant.example/success" }, "cancelUrl": { "type": "string", "description": "Redirect URL for cancelled payment.", "example": "https://merchant.example/cancel" }, "failedUrl": { "type": "string", "description": "Redirect URL for failed payment.", "example": "https://merchant.example/failed" }, "pendingUrl": { "type": "string", "description": "Redirect URL for pending payment status.", "example": "https://merchant.example/pending" }, "slimMode": { "type": "boolean", "description": "If true, opens slim checkout UI.", "example": false }, "isBillingAndShippingDetailsSame": { "type": "boolean", "description": "If true, shipping details are copied from billing details.", "example": false }, "customerDetails": { "$ref": "#/components/schemas/HppCustomerDetailsDTO" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "additionalParameters": { "type": "object", "additionalProperties": { "type": "string", "description": "Additional merchant parameters stored with order.", "example": "{\"source\":\"campaign-a\"}" }, "description": "Additional merchant parameters stored with order.", "example": { "source": "campaign-a" } }, "descriptor": { "pattern": "^.{0,50}$", "type": "string", "description": "Dynamic descriptor (if enabled for merchant).", "example": "MYSHOP*SUBSCRIPTION" }, "language": { "type": "string", "description": "Checkout language code.", "example": "en" }, "level2Data": { "$ref": "#/components/schemas/TransactionInputLevel2DTO" }, "level3Data": { "$ref": "#/components/schemas/TransactionInputLevel3DTO" }, "paymentMode": { "type": "string", "description": "Payment mode. Use DIRECT to execute payment in create-order flow.", "example": "REDIRECT" }, "paymentOption": { "type": "string", "description": "Payment option identifier.", "example": "CARD" }, "alternativePaymentMethod": { "$ref": "#/components/schemas/AlternativePaymentMethodDTO" } }, "description": "Create order request payload for HPP checkout and optional direct payment mode." }, "TransactionInputLevel2DTO": { "type": "object", "properties": { "taxAmount": { "type": "number", "description": "Tax amount applied to the transaction.", "example": 7.5 }, "purchaseOrderNumber": { "type": "string", "description": "Purchase order number associated with the transaction." }, "customerReference": { "type": "string", "description": "Customer reference identifier for reconciliation." }, "merchantTaxId": { "type": "string", "description": "Merchant tax identifier." }, "taxExempt": { "type": "boolean", "description": "Indicates whether the transaction is tax exempt." } }, "description": "Level 2 transaction data used for enhanced corporate/commercial card processing." }, "TransactionInputLevel3DTO": { "type": "object", "properties": { "customerReference": { "type": "string", "description": "Customer reference identifier for Level 3 transaction." }, "purchaseOrderNumber": { "type": "string", "description": "Purchase order number for Level 3 transaction." }, "invoiceNumber": { "type": "string", "description": "Invoice number associated with the transaction." }, "taxAmount": { "type": "number", "description": "Tax amount for Level 3 transaction.", "example": 12.5 }, "taxExempt": { "type": "boolean", "description": "Indicates whether Level 3 transaction is tax exempt." }, "freightAmount": { "type": "number", "description": "Freight amount for shipped goods.", "example": 5 }, "dutyAmount": { "type": "number", "description": "Duty amount applicable to the transaction.", "example": 2 }, "shipFromPostalCode": { "type": "string", "description": "Origin postal code for shipment." }, "destinationPostalCode": { "type": "string", "description": "Destination postal code for shipment." }, "shipToCountry": { "type": "string", "description": "Destination country code for shipment.", "example": "US" }, "merchantTaxId": { "type": "string", "description": "Merchant tax identifier for Level 3 data." }, "additionalTaxDetails": { "$ref": "#/components/schemas/AdditionalTaxDetailsDTO" }, "lineItems": { "type": "array", "description": "Line-item details for Level 3 transaction.", "items": { "$ref": "#/components/schemas/TransactionInputLevel3ItemDTO" } } }, "description": "Level 3 transaction data used for enhanced commercial/corporate card processing." }, "TransactionInputLevel3ItemDTO": { "type": "object", "properties": { "productCode": { "type": "string", "description": "Product code for line item." }, "productName": { "type": "string", "description": "Product name for line item." }, "productSKU": { "type": "string", "description": "Stock keeping unit identifier for line item." }, "quantity": { "type": "integer", "description": "Quantity of product purchased.", "format": "int64", "example": 2 }, "unitPrice": { "type": "number", "description": "Unit price of the product.", "example": 49.99 }, "totalAmount": { "type": "number", "description": "Total amount for line item.", "example": 99.98 }, "taxAmount": { "type": "number", "description": "Tax amount for line item.", "example": 5 }, "alternateTaxIdentifier": { "type": "string", "description": "Alternate tax identifier for line item." }, "taxType": { "type": "string", "description": "Tax type for line item.", "example": "VAT" }, "taxRate": { "type": "number", "description": "Tax rate for line item.", "example": 0.1 }, "unitOfMeasure": { "type": "string", "description": "Unit of measure for quantity.", "example": "EA" }, "discountAmount": { "type": "number", "description": "Discount amount applied to line item.", "example": 2 }, "discountRate": { "type": "number", "description": "Discount rate applied to line item.", "example": 0.05 }, "discountApplied": { "type": "boolean", "description": "Indicates whether discount was applied." }, "commodityCode": { "type": "string", "description": "Commodity code for line item classification." }, "description": { "type": "string", "description": "Detailed line item description." } }, "description": "Line item details for Level 3 transaction processing." }, "PaymentMethodConfigurationDTO": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "fields": { "type": "string" }, "systemFields": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object" } } } } }, "PaymentPageLayoutDTO": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "clientId": { "type": "integer", "format": "int64" }, "siteId": { "type": "integer", "format": "int64" }, "midId": { "type": "integer", "format": "int64" }, "logoId": { "type": "string" }, "title": { "type": "string" }, "bgColor": { "type": "string" }, "cssId": { "type": "string" }, "confirmationMsg": { "type": "string" }, "payButtonText": { "type": "string" }, "collectBillingInfo": { "type": "boolean" }, "collectShippingInfo": { "type": "boolean" }, "collectCustomerInfo": { "type": "boolean" }, "collectZipCode": { "type": "boolean" }, "allowedPaymentOptions": { "type": "array", "items": { "type": "string" } }, "paymentMethodConfigurations": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodConfigurationDTO" } }, "termsAndConditions": { "$ref": "#/components/schemas/TermsAndConditionsDTO" }, "displayFooterInfo": { "type": "boolean" }, "footerFields": { "type": "object", "additionalProperties": { "type": "string" } }, "displayDescriptorInfo": { "type": "boolean" }, "merchantDescriptor": { "type": "string" }, "language": { "type": "string" }, "enableTranslation": { "type": "boolean" } }, "description": "Payment page layout, branding, and allowed payment method configuration." }, "SdkEndpointDTO": { "type": "object", "properties": { "apiBaseUrl": { "type": "string", "description": "Base URL for SDK calls to the Netvalve payment API.", "example": "https://payment-api.dev3.netvalve-dev.com" }, "tokenfieldUrl": { "type": "string", "description": "URL for Netvalve token-field SDK assets.", "example": "https://tokenfield.dev3.netvalve-dev.com/sdk" }, "scriptSrc": { "type": "string", "description": "URL of the SDK script to load.", "example": "https://sdk.dev3.netvalve-dev.com/netvalve-sdk.iife.js" } }, "description": "Endpoint URLs returned to the SDK during session initialization." }, "SdkInitializeSessionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique request trace identifier for observability and troubleshooting.", "example": "trace-7f3d9e12" }, "responseTimestamp": { "type": "string", "description": "Timestamp when the response was generated.", "format": "date-time", "example": "2026-07-03T11:05:30Z" }, "responseCode": { "type": "string", "description": "Gateway response code indicating the operation result.", "example": "GTW_0000" }, "responseMessage": { "type": "string", "description": "Human-readable gateway response message.", "example": "Transaction processed successfully" }, "netvalveScriptSrc": { "type": "string", "description": "URL of the Netvalve SDK JavaScript file to load on the merchant checkout page.", "example": "https://sdk.dev3.netvalve-dev.com/netvalve-sdk.iife.js" }, "version": { "type": "string", "description": "SDK version associated with the initialized session.", "example": "v1" }, "integrity": { "type": "string", "description": "Subresource Integrity hash for validating the SDK script.", "example": "sha384-base64hash" }, "paymentToken": { "type": "string", "description": "Payment token associated with the initialized SDK payment session.", "example": "tok_8f34c1d7e9ab42f5" }, "jwtToken": { "type": "string", "description": "JWT token used by the SDK for session authorization.", "example": "eyJhbGciOiJkaXIi..." }, "endpoints": { "$ref": "#/components/schemas/SdkEndpointDTO" }, "initConfig": { "$ref": "#/components/schemas/SdkSessionInitConfigDTO" } }, "description": "Response payload returned when an SDK payment session is initialized." }, "SdkSessionInitConfigDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique request trace identifier for the initialized session.", "example": "trace-7f3d9e12" }, "responseTimestamp": { "type": "string", "description": "Timestamp when the initialization configuration was generated.", "format": "date-time", "example": "2026-07-03T11:05:30Z" }, "responseCode": { "type": "string", "description": "Gateway response code for the initialization configuration.", "example": "GTW_0000" }, "responseMessage": { "type": "string", "description": "Human-readable response message for the initialization configuration.", "example": "Transaction processed successfully" }, "apiBaseUrl": { "type": "string", "description": "Base API URL used by the SDK.", "example": "https://payment-api.dev3.netvalve-dev.com" }, "orderId": { "type": "integer", "description": "Internal order identifier created for the SDK session.", "format": "int64", "example": 123456 }, "transactionID": { "type": "integer", "description": "Internal transaction identifier created for the SDK session.", "format": "int64", "example": 987654321 }, "orderState": { "type": "string", "description": "Current payment/order state for the SDK session.", "example": "READY_TO_PAY", "enum": [ "CREATED", "READY_TO_PAY", "PENDING", "PAID", "DECLINED", "EXPIRED", "AWAIT_3DS" ] }, "orderDetails": { "$ref": "#/components/schemas/SdkSessionOrderDetailsDTO" }, "collectBillingInfo": { "type": "boolean", "description": "Whether the SDK should collect billing details.", "example": true }, "collectShippingInfo": { "type": "boolean", "description": "Whether the SDK should collect shipping details.", "example": false }, "collectCustomerInfo": { "type": "boolean", "description": "Whether the SDK should collect customer details.", "example": true }, "collectZipCode": { "type": "boolean", "description": "Whether the SDK should collect ZIP/postal code.", "example": true }, "successUrl": { "type": "string", "description": "Merchant URL used after successful payment.", "example": "https://merchant.example.com/success" }, "cancelUrl": { "type": "string", "description": "Merchant URL used when checkout is cancelled.", "example": "https://merchant.example.com/cancel" }, "failedUrl": { "type": "string", "description": "Merchant URL used after failed payment.", "example": "https://merchant.example.com/failed" }, "theme": { "type": "integer", "description": "Payment page layout/theme identifier.", "format": "int64", "example": 99 }, "isIFrameSupported": { "type": "boolean", "description": "Whether iframe integration is supported for this session.", "example": false }, "paymentPageLayout": { "$ref": "#/components/schemas/PaymentPageLayoutDTO" }, "paymentOption": { "type": "string", "description": "Default or selected payment option for the SDK session.", "example": "CARD" }, "alternativePaymentMethod": { "$ref": "#/components/schemas/AlternativePaymentMethodDTO" } }, "description": "SDK initialization configuration used to render checkout and control data collection." }, "SdkSessionOrderDetailsDTO": { "type": "object", "properties": { "clientOrderId": { "type": "string", "description": "Merchant-provided order identifier.", "example": "merchant-order-1001" }, "orderDesc": { "type": "string", "description": "Merchant-provided order description.", "example": "Checkout order" }, "amount": { "type": "number", "description": "Order amount.", "example": 49.99 }, "currency": { "type": "string", "description": "Order currency in ISO 4217 format.", "example": "USD" }, "timeLimit": { "type": "integer", "description": "Payment session time limit in seconds.", "format": "int64", "example": 600 }, "expiryDate": { "type": "string", "description": "Payment session expiry timestamp.", "example": "2026-07-03T11:15:30Z" }, "siteId": { "type": "string", "description": "Merchant site identifier used for the SDK session.", "example": "site-id" } }, "description": "Order details returned as part of SDK session initialization." }, "TermsAndConditionsDTO": { "type": "object", "properties": { "checkboxRequired": { "type": "boolean" }, "termsAndConditionsLabel": { "type": "string" }, "type": { "type": "string", "enum": [ "URL", "TEXT", "URL", "TEXT" ] }, "url": { "type": "string" }, "htmlFileId": { "type": "string" } } }, "SdkThreeDSPaymentRequestDTO": { "type": "object", "properties": { "siteId": { "type": "string", "description": "Merchant site identifier for the SDK session.", "example": "site-id" }, "paymentToken": { "type": "string", "description": "Payment token returned by the SDK initialize-session endpoint.", "example": "tok_8f34c1d7e9ab42f5" }, "transID": { "type": "string", "description": "3DS transaction identifier returned by the authentication provider.", "example": "3ds-trans-123" }, "dfReferenceId": { "type": "string", "description": "Device fingerprint reference identifier for risk and 3DS flows.", "example": "df-ref-123" }, "browserData": { "$ref": "#/components/schemas/HppBrowserInfoDTO" } }, "description": "SDK 3DS completion request containing payment token and 3DS transaction identifiers." }, "AdditionalDataDTO": { "type": "object", "properties": { "industryCode": { "type": "string", "description": "Merchant industry code used to classify the type of business.", "example": "Food/Restaurant" }, "isCardAuthentication": { "type": "boolean", "description": "Indicates whether card authentication was performed.", "default": false }, "isOfflineTransaction": { "type": "boolean", "description": "Indicates whether the transaction was processed in offline mode.", "example": false, "default": false }, "requestTransactionType": { "type": "string", "description": "Type of transaction request (e.g., IN_APP, ECOMMERCE, DIRECT_MARKETING etc.).", "example": "SALE", "enum": [ "IN_APP", "ECOMMERCE", "RECURRING", "DIRECT_MARKETING", "INSTALLMENT" ] }, "isLevel2Transaction": { "type": "boolean", "description": "Indicates whether this is a Level 2 transaction with enhanced data (e.g., tax, customer details).", "example": false, "default": false }, "taxAmount": { "type": "number", "description": "Tax amount associated with the transaction.", "format": "double", "example": 18 }, "settlementAmount": { "type": "number", "description": "Settlement amount to be processed.", "example": 1000.5 }, "isDirectMarketing": { "type": "boolean", "description": "Indicates whether the transaction is related to direct marketing activity.", "example": false, "default": false }, "recurringScheduleType": { "type": "string", "description": "Type of recurring schedule applied to the transaction (e.g., CIT_STANDING_ORDER, CIT_SUBSCRIPTION, MIT_STANDING_ORDER, MIT_UNSCHEDULED_COF etc.).", "example": "MONTHLY" }, "partialAuthorizationIndicator": { "type": "string", "description": "Indicates partial authorization for the transaction." }, "directMarketingTxnMode": { "type": "string", "description": "Direct marketing transaction mode indicator.", "example": "MAIL" }, "cardUsage": { "type": "string", "description": "Indicates intended usage of the card (e.g., COF, INITIAL, INSTALLMENT)." }, "recipientDob": { "type": "string", "description": "Recipient date of birth." }, "recipientAccountNo": { "type": "string", "description": "Recipient account number.", "example": "123456789012" }, "recipientPostalCode": { "type": "string", "description": "Recipient postal/ZIP code.", "example": "440001" }, "recipientSurname": { "type": "string", "description": "Recipient surname/last name.", "example": "Doe" }, "scaExemptionIndicator": { "type": "string", "description": "Strong Customer Authentication (SCA) exemption indicator." }, "credentialOnFileTransaction": { "type": "string", "description": "Indicates whether the transaction is stored as Credential on File (CoF)." }, "recurrenceMode": { "type": "string", "description": "Recurrence mode of the transaction (e.g., INITIAL, REPEATED)." }, "transactionId": { "type": "string", "description": "Unique identifier for the transaction." }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Additional transaction metadata used for enhanced payment processing, including industry classification, recurring settings, Level 2/3 data, fraud indicators, and regulatory flags." }, "BasicInputFieldsDTO": { "required": [ "amount", "currency", "paymentType" ], "type": "object", "properties": { "midId": { "type": "integer", "description": "Merchant identifier internally used by the Netvalve", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "A unique merchant identifier assigned to the account.", "example": "f8c2c3a9-9d2e-4a7e-9c6b-6b3c0a6e4f21" }, "amount": { "type": "number", "description": "The amount of the transaction.", "example": 49.99 }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "Currency code in ISO 4217 format. Must be a valid 3-letter uppercase currency code (e.g., INR, USD, EUR). ", "example": "USD" }, "orderDesc": { "maxLength": 1000, "type": "string", "description": "Optional order description. If provided, must be a valid text string up to 1000 characters.", "example": "Payment for order 12345" }, "clientOrderId": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Optional client-provided order identifier. If provided, must be a valid text value with a maximum length of 100 characters. ", "example": "ORD-12345-ABC" }, "cardSecurityCode": { "maxLength": 4, "minLength": 3, "type": "string", "description": "Optional card security code (CVV/CVC). If provided, must be between 3 and 4 characters in length. ", "example": "123" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Name of the cardholder. Optional field. If provided, must be a valid text value up to 128 characters. ", "example": "John Doe" }, "cardExpireMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string", "description": "Card expiration month. Optional field. If provided, must be in MM format ranging from 01 to 12. ", "example": "09" }, "cardExpireYear": { "maxLength": 4, "minLength": 4, "type": "string", "description": "Card expiration year in YYYY format. Optional field. If provided, must be exactly 4 digits representing a valid year.", "example": "2026" }, "customerName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Full name of the customer. Optional field. If provided, must be a valid text value up to 128 characters.", "example": "John Doe" }, "customerFirstName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer first name. Optional field. Must be valid text up to 128 characters if provided.", "example": "John" }, "customerLastName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer last name. Optional field. Must be valid text up to 128 characters if provided.", "example": "Doe" }, "customerAddress": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer address. Optional field. If provided, must be valid text up to 128 characters.", "example": "221B Baker Street" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Customer ZIP / postal code. Optional field. Must be up to 10 characters if provided.", "example": "440001" }, "customerCity": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer city. Optional field. Must be valid text up to 128 characters if provided.", "example": "Leeds" }, "customerState": { "maxLength": 30, "minLength": 0, "type": "string", "description": "Customer state or region. Optional field. Must be valid text up to 30 characters if provided.", "example": "Massachusetts" }, "customerCountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Customer country code in ISO 3166-1 alpha-2 format. Optional field. If provided, must be a valid 2-letter country code (e.g., IN, US, GB). ", "example": "IN" }, "customerPhone": { "maxLength": 20, "minLength": 0, "type": "string", "description": "Customer phone number. Optional field. If provided, must contain only valid phone characters: digits (0-9), plus sign (+), parentheses (), hyphen (-), dot (.), and spaces. Maximum length is 20 characters. Blank or null values are allowed.", "example": "+91 98765 43210" }, "customerEmail": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer email address. Optional field. If provided, must be a valid email address format. Maximum length is 128 characters.", "example": "john.doe@example.com" }, "customerIp": { "type": "string", "description": "Customer IP address. Optional field. If provided, must be a valid IPv4 or IPv6 address.", "example": "192.168.1.1" }, "paymentType": { "type": "string", "description": "Payment type used for the transaction. Defaults to CARD if not provided.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "walletType": { "type": "string", "description": "Wallet type used for the transaction. Required when paymentType is WALLET. Indicates the digital wallet provider selected by the customer.", "example": "APPLE_PAY", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "ApplePaySSL": { "$ref": "#/components/schemas/ApplePaySSLDTO" }, "GooglePaySSL": { "$ref": "#/components/schemas/GooglePaySSLDTO" }, "SamsungPaySSL": { "$ref": "#/components/schemas/SamsungPaySSLDTO" }, "tokenizedDTO": { "$ref": "#/components/schemas/TokenizedDTO" }, "additionalData": { "$ref": "#/components/schemas/AdditionalDataDTO" }, "additionalParameters": { "type": "object", "additionalProperties": { "type": "string", "description": "Free-form key/value metadata passed along with the payment request.", "example": "{\"promoCode\":\"SPRING10\",\"channel\":\"web\"}" }, "description": "Free-form key/value metadata passed along with the payment request.", "example": { "promoCode": "SPRING10", "channel": "web" } }, "siteId": { "type": "string", "description": "Identifier of the merchant site.", "example": "SITE-001" }, "paymentToken": { "type": "string", "description": "Payment token representing a secure reference to a tokenized payment method. Used to complete transactions without directly exposing card or wallet details.", "example": "tok_8f34c1d7e9ab42f5" }, "descriptor": { "maxLength": 50, "pattern": "^.{0,50}$", "type": "string", "description": "Transaction descriptor used to provide a short description of the payment as it appears on customer statements. Maximum length is 50 characters.", "example": "ONLINE PURCHASE STORE123" }, "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" }, "level2Data": { "$ref": "#/components/schemas/TransactionInputLevel2DTO" }, "level3Data": { "$ref": "#/components/schemas/TransactionInputLevel3DTO" }, "apmType": { "type": "string", "description": "Alternative Payment Method (APM) type used for the transaction. Specifies the external payment network or provider selected by the customer.", "example": "PAYPAL", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "alternativePaymentMethod": { "$ref": "#/components/schemas/AlternativePaymentMethodDTO" }, "cardNumber": { "maxLength": 40, "minLength": 0, "type": "string", "description": "Optional credit card number. If provided, must be a valid credit card number that passes standard validation (including Luhn check). Whitespace characters are ignored during validation. Only numeric digits are validated after removing spaces. Maximum length is 40 characters (including spaces before normalization). ", "example": "4111111111111111" }, "3DS": { "$ref": "#/components/schemas/ThreeDomainsSecureDTO" }, "healthCareData": { "$ref": "#/components/schemas/HealthCareDataDTO" } } }, "Samsung3DSDTO": { "type": "object", "properties": { "data": { "type": "string", "description": "Encrypted Samsung 3DS payload data." }, "type": { "type": "string", "description": "Samsung 3DS payload type." }, "version": { "type": "string", "description": "Samsung 3DS payload version." } }, "description": "Samsung Pay 3DS credential payload." }, "SamsungDetailsDTO": { "type": "object", "properties": { "method": { "type": "string", "description": "Samsung Pay payment method identifier." }, "paymentCredential": { "$ref": "#/components/schemas/SamsungPaymentCredentialDTO" }, "paymentInfo": { "$ref": "#/components/schemas/SamsungPaymentInfoDTO" } }, "description": "Samsung Pay details block containing method, credentials, and payment info." }, "SamsungPaySSLDTO": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique request identifier from Samsung Pay." }, "methodName": { "type": "string", "description": "Samsung Pay method name used for the transaction." }, "details": { "$ref": "#/components/schemas/SamsungDetailsDTO" }, "shippingAddress": { "type": "string", "description": "Shipping address selected in Samsung Pay checkout." }, "shippingOption": { "type": "string", "description": "Shipping option selected in Samsung Pay checkout." }, "payerName": { "type": "string", "description": "Payer full name from Samsung Pay." }, "payerEmail": { "type": "string", "description": "Payer email address from Samsung Pay." }, "payerPhone": { "type": "string", "description": "Payer phone number from Samsung Pay." } }, "description": "Samsung Pay wallet payload containing request, credential, and payer metadata." }, "SamsungPaymentCredentialDTO": { "type": "object", "properties": { "3DS": { "$ref": "#/components/schemas/Samsung3DSDTO" }, "recurring_payment": { "type": "boolean", "description": "Indicates whether this Samsung Pay transaction is for recurring payments." } }, "description": "Samsung Pay payment credential payload." }, "SamsungPaymentInfoDTO": { "type": "object", "properties": { "cardBrand": { "type": "string", "description": "Card brand/network from Samsung Pay.", "example": "VISA" }, "orderNumber": { "type": "string", "description": "Order number associated with Samsung Pay transaction." }, "card_last4digits": { "type": "string", "description": "Last 4 digits of the card used in Samsung Pay.", "example": "1234" } }, "description": "Samsung Pay payment info such as card brand and order number." }, "ThreeDomainsSecureDTO": { "required": [ "cavv", "dsTransactionId", "eci", "cavv", "dsTransactionId", "eci" ], "type": "object", "properties": { "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value (CAVV). Cryptographic value generated during 3D Secure authentication.", "example": "AAABBBCCC1234567890" }, "dsTransactionId": { "type": "string", "description": "Directory Server transaction identifier for the 3DS authentication.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "xid": { "type": "string", "description": "Transaction identifier used in 3D Secure 1.0 authentication (XID).", "example": "MDAwMDAwMDAwMDAwMDAwMzIyNzY=" }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI) representing authentication result. Common values: 05 (fully authenticated), 06 (attempted), 07 (not authenticated).", "example": "05" }, "status": { "type": "string", "description": "3D Secure authentication status. Indicates whether authentication was successful, attempted, or failed." }, "version": { "type": "string", "description": "Version of the 3D Secure protocol used (e.g., 1.0, 2.1, 2.2).", "example": "2.1.0" }, "masterCardDSRP": { "type": "string", "description": "Mastercard Digital Secure Remote Payment (DSRP) data." }, "cavvAlgorithm": { "type": "string", "description": "CAVV algorithm indicator. Possible values: 0 = HMAC, 1 = CVV, 2 = CVV with ATN, 3 = Mastercard SPA.", "example": "2" }, "provider": { "type": "string", "description": "3D Secure provider or authentication service used.", "example": "MASTERCARD" }, "verifyTransactionId": { "type": "string", "description": "Transaction identifier returned during 3DS verification process.", "example": "TXN123456789" }, "isFrictionLess": { "type": "boolean", "description": "Indicates whether the authentication was completed without user interaction (frictionless flow).", "example": true }, "flow": { "type": "string", "description": "3DS authentication flow type. Typically indicates whether the flow was ACS (challenge) or frictionless.", "example": "Frictionless, Challenge" } }, "description": "3DS authentication data captured/returned for a transaction." }, "AuthAndSaleTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for tracing request flow.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp generated by the service.", "format": "date-time", "example": "2026-04-27T11:05:30Z" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 100001 }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "cardType": { "type": "string", "description": "Card brand/type when card data is available.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Transaction identifier returned by bank/acquirer.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code returned by bank/acquirer.", "example": "123456" }, "midId": { "type": "integer", "description": "Merchant identifier used for processing.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External/Netvalve merchant identifier.", "example": "f7e0f1b8-2c6d-4a91-9a5b-3de2c4f8b7a1" }, "processor": { "type": "string", "description": "Payment processor name.", "example": "TSYS" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "transactionType": { "type": "string", "description": "Transaction operation type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "currency": { "type": "string", "description": "Processed transaction currency (ISO 4217).", "example": "USD" }, "clientId": { "type": "integer", "description": "Client identifier associated with the transaction.", "format": "int64", "example": 2001 }, "siteId": { "type": "string", "description": "Site identifier associated with the transaction.", "example": "6001" }, "orderId": { "type": "integer", "format": "int64" }, "cardExpiryMonth": { "type": "string", "description": "Card expiry month in MM format.", "example": "09" }, "cardExpiryYear": { "type": "string", "description": "Card expiry year in YYYY format.", "example": "2028" }, "amount": { "type": "number", "description": "Authorized or captured transaction amount.", "example": 49.99 }, "merchantRegistrationId": { "type": "string", "description": "Merchant registration identifier at processor level.", "example": "MER-778899" }, "apmType": { "type": "string", "description": "Alternative payment method type when paymentMethod is APM.", "example": "PAYPAL", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "qrCode": { "type": "string", "description": "QR payload/content for QR-based payments.", "example": "000201010212...6304ABCD" }, "qrCodeExpiry": { "type": "string", "description": "Expiry time for QR-based payment initiation.", "format": "date-time" }, "subscriptionId": { "type": "integer", "description": "Subscription identifier for recurring transactions.", "format": "int64", "example": 12345 }, "subscriptionStatus": { "type": "string", "description": "Subscription status.", "example": "ACTIVE" }, "paymentToken": { "type": "string", "description": "Payment token reference used for tokenized payment flows.", "example": "tok_8f34c1d7e9ab42f5" }, "paymentTokenType": { "type": "string", "description": "Tokenization type associated with payment token.", "example": "NETWORK_TOKEN", "enum": [ "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK" ] }, "binInfo": { "$ref": "#/components/schemas/BinInfo" }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Response payload for authorize and sale operations." }, "ApplePayMerchantRegisterRequestDTO": { "required": [ "displayName", "domainNames" ], "type": "object", "properties": { "domainNames": { "type": "array", "description": "List of domains to register for Apple Pay.", "example": [ "checkout.dev.sandbox.com" ], "items": { "type": "string", "description": "List of domains to register for Apple Pay.", "example": "[\"checkout.dev.sandbox.com\"]" } }, "displayName": { "type": "string", "description": "Display name shown for the merchant.", "example": "Netvalve Checkout" } }, "description": "Request payload to register Apple Pay domain(s)." }, "ApplePayRegistrationResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Registration Success" }, "merchantRegistrationId": { "type": "string", "description": "Registered merchant identifier returned for successful registration.", "example": "6c6e8d4a-bcb5-46d6-a8f4-6d8e6f1a9809" } }, "description": "Response payload for Apple Pay domain registration." }, "RefundInputFieldsDTO": { "required": [ "transactionID" ], "type": "object", "properties": { "transactionID": { "type": "integer", "description": "Transaction identifier to refund.", "format": "int64", "example": 987654321 }, "amount": { "type": "number", "description": "Partial refund amount. If omitted, full refund is attempted.", "example": 10.5 }, "additionalData": { "$ref": "#/components/schemas/AdditionalDataDTO" } }, "description": "Request payload for refund operation." }, "RefundTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for tracing request flow.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp generated by the service.", "format": "date-time", "example": "2026-04-27T11:05:30Z" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 100001 }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "cardType": { "type": "string", "description": "Card brand/type when card data is available.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Transaction identifier returned by bank/acquirer.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code returned by bank/acquirer.", "example": "123456" }, "midId": { "type": "integer", "description": "Merchant identifier used for processing.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External/Netvalve merchant identifier.", "example": "f7e0f1b8-2c6d-4a91-9a5b-3de2c4f8b7a1" }, "processor": { "type": "string", "description": "Payment processor name.", "example": "TSYS" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "transactionType": { "type": "string", "description": "Transaction operation type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "currency": { "type": "string", "description": "Processed transaction currency (ISO 4217).", "example": "USD" }, "clientId": { "type": "integer", "description": "Client identifier associated with the transaction.", "format": "int64", "example": 2001 }, "amount": { "type": "number", "description": "Refunded amount for full or partial refund.", "example": 19.99 } }, "description": "Response payload for refund operation." }, "RebillInputFieldsDTO": { "required": [ "amount", "transactionID" ], "type": "object", "properties": { "amount": { "type": "number", "description": "Rebill amount.", "example": 19.99 }, "clientOrderId": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Client-provided order identifier for rebill.", "example": "REBILL-ORD-1001" }, "transactionID": { "type": "integer", "description": "Reference transaction identifier used for rebill.", "format": "int64", "example": 987654321 }, "additionalData": { "$ref": "#/components/schemas/AdditionalDataDTO" } }, "description": "Request payload for rebill operation." }, "CreateOrderResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time" }, "orderId": { "type": "integer", "description": "Gateway order identifier.", "format": "int64", "example": 100001 }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 200001 }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "orderState": { "type": "string", "description": "Current order state.", "example": "CREATED", "enum": [ "CREATED", "READY_TO_PAY", "PENDING", "PAID", "DECLINED", "EXPIRED", "AWAIT_3DS", "CREATED", "READY_TO_PAY", "PENDING", "PAID", "DECLINED", "EXPIRED", "AWAIT_3DS" ] }, "redirectUrl": { "type": "string", "description": "Redirect URL for hosted checkout or status callback.", "example": "https://hpp.example.com?paymentToken=opaque_123" }, "isRetryAllowed": { "type": "boolean", "description": "Whether retry is allowed in HPP payment branch.", "example": true }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ResultThreeDSTransactionResponseDTO" }, "midId": { "type": "integer", "description": "Internal merchant identifier.", "format": "int64", "example": 3001 }, "netvalveMidId": { "type": "string", "description": "External merchant identifier.", "example": "MID_ABC_001" }, "processor": { "type": "string", "description": "Processor/acquirer name.", "example": "TRUEVO" }, "amount": { "type": "number", "description": "Transaction amount.", "example": 49.99 }, "currency": { "type": "string", "description": "Transaction currency (ISO-4217).", "example": "USD" }, "paymentMethod": { "type": "string", "description": "Payment method used.", "example": "CARD" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "cardExpiryMonth": { "type": "string", "description": "Card expiry month.", "example": "12" }, "cardExpiryYear": { "type": "string", "description": "Card expiry year.", "example": "2029" }, "cardType": { "type": "string", "description": "Card brand/type.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Bank/acquirer transaction identifier.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Bank/acquirer authorization code.", "example": "123456" }, "bankResponseCode": { "type": "string", "description": "Bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank response message.", "example": "Approved" }, "paymentToken": { "type": "string", "description": "Payment token/customer vault id when tokenization applies.", "example": "cv_9d12ab34" }, "paymentTokenType": { "type": "string", "description": "Token type for payment token.", "example": "GATEWAY_TOKEN", "enum": [ "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK", "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK" ] }, "siteId": { "type": "string", "description": "Site identifier used for processing.", "example": "SITE_US_01" }, "transactionType": { "type": "string", "description": "Processed transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY", "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "subscriptionId": { "type": "integer", "description": "Managed recurring subscription id.", "format": "int64", "example": 5001 }, "subscriptionStatus": { "type": "string", "description": "Managed recurring subscription status.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED", "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "binInfo": { "$ref": "#/components/schemas/BinInfo" }, "apmType": { "type": "string", "description": "APM type when alternative payment method is used.", "example": "BITPACE", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE", "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "apmPaymentUrl": { "type": "string", "description": "APM hosted payment URL.", "example": "https://apm.example.com/pay/abc123" }, "apmPaymentUrlExpiry": { "type": "string", "description": "APM payment URL expiry timestamp.", "format": "date-time" }, "apmPaymentInfo": { "$ref": "#/components/schemas/APMPaymentInfoDTO" }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Create order response containing fields returned across standard, direct and error branches." }, "MultiValueMapStringString": { "type": "object", "properties": { "all": { "type": "object", "additionalProperties": { "type": "string" }, "writeOnly": true }, "empty": { "type": "boolean" } }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "BankConfirmResponseDTO": { "type": "object", "properties": { "responseTimestamp": { "type": "string", "format": "date-time" }, "responseCode": { "type": "string" }, "responseMessage": { "type": "string" }, "responseCodeType": { "type": "string" } } }, "CbAlertRequestDTO": { "type": "object", "properties": { "netvalveTransactionId": { "type": "integer", "format": "int64" }, "cbAlertId": { "type": "string" }, "cbRawData": { "type": "string" }, "cbTransactionType": { "type": "string" }, "sender": { "type": "string" } } }, "CbAlertResponseDTO": { "type": "object", "properties": { "responseTimestamp": { "type": "string", "format": "date-time" }, "chargebackTransactionID": { "type": "integer", "format": "int64" }, "responseCode": { "type": "string" }, "responseMessage": { "type": "string" }, "responseCodeType": { "type": "string" } } }, "GooglePayInitializeSessionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time", "example": "2025-09-17T07:12:17.492Z" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "responseCodeType": { "type": "string", "description": "Derived response type for the response code.", "example": "APPROVED" }, "walletInitializeSessionResponseDTO": { "$ref": "#/components/schemas/WalletInitializeSessionResponseDTO" } }, "description": "Response payload for Google Pay session initialization." }, "ApplePayInitializeSessionRequestDTO": { "required": [ "domainName" ], "type": "object", "properties": { "domainName": { "type": "string", "description": "Merchant domain used for Apple Pay session initialization.", "example": "checkout.dev.sandbox.com" } }, "description": "Request payload to initialize an Apple Pay session." }, "ApplePayInitializeSessionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time", "example": "2025-09-17T07:12:17.492Z" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "responseCodeType": { "type": "string", "description": "Derived response type for the response code.", "example": "APPROVED" }, "walletInitializeSessionResponseDTO": { "$ref": "#/components/schemas/WalletInitializeSessionResponseDTO" } }, "description": "Response payload for Apple Pay session initialization." }, "HostedPaymentFieldsRequestDTO": { "required": [ "fieldName", "fieldValue", "paymentToken" ], "type": "object", "properties": { "paymentToken": { "type": "string" }, "fieldName": { "type": "string" }, "fieldValue": { "type": "string" } } }, "CreateTokenRequestDTO": { "required": [ "cardExpireMonth", "cardExpireYear", "cardNumber" ], "type": "object", "properties": { "amount": { "type": "number", "description": "Transaction amount.", "example": 0 }, "cardExpireMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string", "description": "Card expiry month in MM format.", "example": "12" }, "cardExpireYear": { "maxLength": 4, "minLength": 4, "type": "string", "description": "Card expiry year in YYYY format.", "example": "2030" }, "cardSecurityCode": { "type": "string", "description": "Card security code (CVV/CVC).", "example": "123" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Card holder name.", "example": "John Doe" }, "cardNumber": { "maxLength": 40, "minLength": 0, "type": "string", "description": "Card number (PAN).", "example": "4111111111111111" }, "currency": { "type": "string", "description": "Currency code in ISO-4217 format.", "example": "USD" }, "customerAddress": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer billing address line.", "example": "123 Main St" }, "customerCity": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer city.", "example": "New York" }, "customerCountryCode": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Customer country code in ISO-3166 alpha-2.", "example": "US" }, "customerEmail": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer email address.", "example": "john.doe@example.com" }, "customerIp": { "type": "string", "description": "Customer IPv4/IPv6 address.", "example": "203.0.113.10" }, "customerName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer first name.", "example": "John" }, "customerLastName": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Customer last name.", "example": "Doe" }, "customerPhone": { "maxLength": 20, "minLength": 0, "type": "string", "description": "Customer phone number.", "example": "98725550123" }, "customerState": { "maxLength": 30, "minLength": 0, "type": "string", "description": "Customer state or province.", "example": "NY" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string", "description": "Customer ZIP or postal code.", "example": "10001" }, "midId": { "type": "integer", "description": "Internal merchant identifier (MID).", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "3f16ef23-bc03-4aaa-b632-fbebda462fe5" }, "verify": { "type": "boolean", "description": "If true, performs verification/auth before token save.", "example": false }, "siteId": { "type": "string", "description": "Site identifier used internally." } }, "description": "Request payload for Payment API create token endpoint." }, "CreateTokenResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Request trace identifier used for correlation.", "example": "4f0d3f6e-c84a-4ab3-9a60-58fd3e4b1ce5" }, "responseTimestamp": { "type": "string", "description": "Timestamp at which the response was generated.", "format": "date-time", "example": "2026-04-25T10:15:30Z" }, "transactionID": { "type": "integer", "description": "Internal transaction identifier.", "format": "int64", "example": 123456789 }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction successfully completed" }, "responseCodeType": { "type": "string", "description": "Category of response code.", "example": "approved" }, "paymentMethod": { "type": "string", "description": "Payment method used in transaction processing.", "example": "CARD" }, "paymentToken": { "type": "string", "description": "Gateway payment token/customer vault token.", "example": "3f16ef23-bc03-4aaa-b632-fbebda462fe5" }, "paymentTokenType": { "type": "string", "description": "Token type returned for the payment token.", "enum": [ "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK" ] }, "bankTransactionId": { "type": "string", "description": "Bank transaction identifier.", "example": "BANK_TXN_123456" }, "authCode": { "type": "string", "description": "Authorization code from processor/bank.", "example": "A1B2C3" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "cardExpiryMonth": { "type": "string", "description": "Card expiry month in MM format.", "example": "12" }, "cardExpiryYear": { "type": "string", "description": "Card expiry year in YYYY format.", "example": "2030" }, "cardType": { "type": "string", "description": "Card type/brand.", "example": "VISA" }, "bankResponseCode": { "type": "string", "description": "Raw response code from bank/acquirer.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Raw response message from bank/acquirer.", "example": "Approved" }, "midId": { "type": "integer", "description": "Internal MID identifier.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "3f16ef23-bc03-4aaa-b632-fbebda462fe5" }, "processor": { "type": "string", "description": "Processor/system name.", "example": "TSYS" }, "amount": { "type": "number", "description": "Transaction amount processed.", "example": 0 }, "currency": { "type": "string", "description": "Currency used for processing.", "example": "USD" }, "clientId": { "type": "integer", "description": "Internal client identifier.", "format": "int64", "example": 2001 }, "binInfo": { "$ref": "#/components/schemas/BinInfo" }, "transactionType": { "type": "string", "description": "Transaction type associated with this response.", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "siteId": { "type": "string", "description": "Associated Site id" }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Response payload for Payment API create token endpoint." }, "CaptureInputFieldsDTO": { "required": [ "amount", "transactionID" ], "type": "object", "properties": { "amount": { "type": "number", "description": "Capture amount.", "example": 49.99 }, "transactionID": { "type": "integer", "description": "Transaction identifier to capture against.", "format": "int64", "example": 987654321 }, "additionalData": { "$ref": "#/components/schemas/AdditionalDataDTO" }, "captureOptions": { "$ref": "#/components/schemas/CaptureOptionsDTO" } }, "description": "Request payload for capture operation." }, "CaptureOptionsDTO": { "type": "object", "properties": { "finalCapture": { "type": "boolean", "description": "Marks whether this capture is the final capture for the authorized amount.", "example": true } }, "description": "Optional options for capture operation." }, "CaptureTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for tracing request flow.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp generated by the service.", "format": "date-time", "example": "2026-04-27T11:05:30Z" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 100001 }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "cardType": { "type": "string", "description": "Card brand/type when card data is available.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Transaction identifier returned by bank/acquirer.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code returned by bank/acquirer.", "example": "123456" }, "midId": { "type": "integer", "description": "Merchant identifier used for processing.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External/Netvalve merchant identifier.", "example": "f7e0f1b8-2c6d-4a91-9a5b-3de2c4f8b7a1" }, "processor": { "type": "string", "description": "Payment processor name.", "example": "TSYS" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "transactionType": { "type": "string", "description": "Transaction operation type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "currency": { "type": "string", "description": "Processed transaction currency (ISO 4217).", "example": "USD" }, "clientId": { "type": "integer", "description": "Client identifier associated with the transaction.", "format": "int64", "example": 2001 }, "amount": { "type": "number", "description": "Captured amount.", "example": 49.99 } }, "description": "Response payload for capture operation." }, "CancelInputFieldsDTO": { "required": [ "transactionID" ], "type": "object", "properties": { "transactionID": { "type": "integer", "description": "Transaction identifier to cancel/void.", "format": "int64", "example": 987654321 }, "additionalData": { "$ref": "#/components/schemas/AdditionalDataDTO" } }, "description": "Request payload for cancel operation." }, "CancelTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for tracing request flow.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp generated by the service.", "format": "date-time", "example": "2026-04-27T11:05:30Z" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 100001 }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "cardType": { "type": "string", "description": "Card brand/type when card data is available.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Transaction identifier returned by bank/acquirer.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code returned by bank/acquirer.", "example": "123456" }, "midId": { "type": "integer", "description": "Merchant identifier used for processing.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External/Netvalve merchant identifier.", "example": "f7e0f1b8-2c6d-4a91-9a5b-3de2c4f8b7a1" }, "processor": { "type": "string", "description": "Payment processor name.", "example": "TSYS" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "transactionType": { "type": "string", "description": "Transaction operation type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "currency": { "type": "string", "description": "Processed transaction currency (ISO 4217).", "example": "USD" }, "clientId": { "type": "integer", "description": "Client identifier associated with the transaction.", "format": "int64", "example": 2001 } }, "description": "Response payload for cancel/void operation." }, "ThreeDSInitAndAuthInputDTO": { "required": [ "cardHolderName", "currency", "paymentType" ], "type": "object", "properties": { "midId": { "type": "integer", "format": "int64" }, "netvalveMidId": { "type": "string" }, "cardNumber": { "maxLength": 40, "minLength": 0, "type": "string" }, "cardSecurityCode": { "type": "string" }, "cardExpireMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string" }, "cardExpireYear": { "maxLength": 4, "minLength": 4, "type": "string" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerIp": { "type": "string" }, "customerEmail": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerPhone": { "maxLength": 20, "minLength": 0, "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "merchantRedirectUrl": { "type": "string" }, "siteId": { "type": "string" }, "userAgent": { "type": "string" }, "browserHeader": { "type": "string" }, "browserLanguage": { "type": "string" }, "browserJavaEnabled": { "type": "boolean" }, "browserColorDepth": { "type": "integer", "format": "int32" }, "browserScreenHeight": { "type": "integer", "format": "int32" }, "browserScreenWidth": { "type": "integer", "format": "int32" }, "browserTimeZone": { "type": "integer", "format": "int32" }, "challengeIndicator": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentType": { "type": "string", "description": "Payment type used for the transaction. Defaults to CARD if not provided.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "descriptor": { "pattern": "^.{0,50}$", "type": "string" }, "customerAddress": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string" }, "customerCity": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerState": { "maxLength": 30, "minLength": 0, "type": "string" }, "customerCountryCode": { "maxLength": 2, "minLength": 2, "type": "string" }, "customerName": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerLastName": { "maxLength": 128, "minLength": 0, "type": "string" } } }, "ThreeDSInitAndAuthProviderResponseDTO": { "type": "object", "properties": { "transID": { "type": "string", "description": "3DS transaction identifier.", "example": "1f3b7cc8-95d8-4b57-a969-2340f0d5c3ef" }, "referenceId": { "type": "string", "description": "Provider reference identifier." }, "errorCode": { "type": "string", "description": "Provider error code when request fails." }, "errorMessage": { "type": "string", "description": "Provider error message when request fails." }, "threeDs2TransactionId": { "type": "string", "description": "3DS2 DS transaction identifier." }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI)." }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value (CAVV)." }, "challengeRequired": { "type": "boolean", "description": "Indicates whether challenge flow is required." }, "jwt": { "type": "string", "description": "Provider JWT/token, if applicable." }, "redirectUrl": { "type": "string", "description": "Netvalve redirect URL to continue 3DS flow." }, "status": { "type": "string", "description": "Current 3DS transaction status.", "enum": [ "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED" ] }, "threeDsVersion": { "type": "string", "description": "3DS protocol version.", "example": "2.2.0" }, "providerRedirectUrl": { "type": "string", "description": "Provider redirect URL, if required by provider flow." }, "merchantRedirectUrl": { "type": "string", "description": "Merchant redirect URL supplied at initialization." }, "provider": { "type": "string", "description": "3DS provider name.", "example": "MASTERCARD" }, "providerTransactionId": { "type": "string", "description": "Provider-side transaction identifier." }, "netvalveCallBackUrl": { "type": "string", "description": "Netvalve callback URL used by provider flow." }, "authType": { "type": "string", "description": "Provider-specific authentication type." }, "methodPostData": { "type": "string", "description": "Provider method post data for device data collection/challenge." }, "cReq": { "type": "string", "description": "Challenge request payload (CReq) used for challenge flow." } }, "description": "Provider-specific response for 3DS init+auth v2 endpoint." }, "ThreeDSInitAndAuthResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique trace identifier for request correlation.", "example": "9a37d2f1-6a7c-44a9-9b3d-2cf52f5f2a5e" }, "responseTimestamp": { "type": "string", "description": "Response creation timestamp.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Netvalve response code.", "example": "3DS_1000" }, "responseMessage": { "type": "string", "description": "Human-readable response message.", "example": "3DS request successfully completed" }, "responseCodeType": { "type": "string", "description": "Response code category.", "example": "APPROVED" }, "bankResponseCode": { "type": "string", "description": "Provider or bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Provider or bank response message.", "example": "Success" }, "midId": { "type": "integer", "description": "Internal merchant identifier (MID).", "format": "int64", "example": 101 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "MID_ABC123" }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ThreeDSInitAndAuthProviderResponseDTO" } }, "description": "Response DTO specific to /3ds/v2/initialization endpoint." }, "ThreeDSResultInputDTO": { "required": [ "transID" ], "type": "object", "properties": { "midId": { "type": "integer", "format": "int64" }, "netvalveMidId": { "type": "string" }, "transID": { "type": "string" }, "siteId": { "type": "string" } } }, "ThreeDSResultProviderResponseDTO": { "type": "object", "properties": { "transID": { "type": "string", "description": "3DS transaction identifier.", "example": "1f3b7cc8-95d8-4b57-a969-2340f0d5c3ef" }, "referenceId": { "type": "string", "description": "Provider reference identifier." }, "errorCode": { "type": "string", "description": "Provider error code when request fails." }, "errorMessage": { "type": "string", "description": "Provider error message when request fails." }, "threeDs2TransactionId": { "type": "string", "description": "3DS2 DS transaction identifier." }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI)." }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value (CAVV)." }, "challengeRequired": { "type": "boolean", "description": "Indicates whether challenge flow is required." }, "jwt": { "type": "string", "description": "Provider JWT/token, if applicable." }, "redirectUrl": { "type": "string", "description": "Netvalve redirect URL to continue 3DS flow." }, "status": { "type": "string", "description": "Current 3DS transaction status.", "enum": [ "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED" ] }, "threeDsVersion": { "type": "string", "description": "3DS protocol version.", "example": "2.2.0" }, "providerRedirectUrl": { "type": "string", "description": "Provider redirect URL, if required by provider flow." }, "merchantRedirectUrl": { "type": "string", "description": "Merchant redirect URL supplied at initialization." }, "provider": { "type": "string", "description": "3DS provider name.", "example": "MASTERCARD" }, "providerTransactionId": { "type": "string", "description": "Provider-side transaction identifier." }, "netvalveCallBackUrl": { "type": "string", "description": "Netvalve callback URL used by provider flow." }, "authType": { "type": "string", "description": "Provider-specific authentication type." }, "methodPostData": { "type": "string", "description": "Provider method post data for device data collection/challenge." }, "cReq": { "type": "string", "description": "Challenge request payload (CReq) used for challenge flow." } }, "description": "Provider-specific details for 3DS result response." }, "ThreeDSResultResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique trace identifier for request correlation.", "example": "9a37d2f1-6a7c-44a9-9b3d-2cf52f5f2a5e" }, "responseTimestamp": { "type": "string", "description": "Response creation timestamp.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Netvalve response code.", "example": "3DS_1000" }, "responseMessage": { "type": "string", "description": "Human-readable response message.", "example": "3DS request successfully completed" }, "responseCodeType": { "type": "string", "description": "Response code category.", "example": "APPROVED" }, "bankResponseCode": { "type": "string", "description": "Provider or bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Provider or bank response message.", "example": "Success" }, "midId": { "type": "integer", "description": "Internal merchant identifier (MID).", "format": "int64", "example": 101 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "MID_ABC123" }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ThreeDSResultProviderResponseDTO" } }, "description": "Response payload for 3DS result endpoint." }, "ThreeDSInitInputDTO": { "required": [ "cardHolderName", "currency", "paymentType" ], "type": "object", "properties": { "midId": { "type": "integer", "format": "int64" }, "netvalveMidId": { "type": "string" }, "cardNumber": { "maxLength": 40, "minLength": 0, "type": "string" }, "cardSecurityCode": { "type": "string" }, "cardExpireMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string" }, "cardExpireYear": { "maxLength": 4, "minLength": 4, "type": "string" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "merchantRedirectUrl": { "type": "string" }, "siteId": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentType": { "type": "string", "description": "Payment type used for the transaction. Defaults to CARD if not provided.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "descriptor": { "pattern": "^.{0,50}$", "type": "string" }, "customerAddress": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string" }, "customerCity": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerState": { "maxLength": 30, "minLength": 0, "type": "string" }, "customerCountryCode": { "maxLength": 2, "minLength": 2, "type": "string" }, "customerName": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerLastName": { "maxLength": 128, "minLength": 0, "type": "string" } } }, "ThreeDSInitializationProviderResponseDTO": { "type": "object", "properties": { "transID": { "type": "string", "description": "3DS transaction identifier.", "example": "1f3b7cc8-95d8-4b57-a969-2340f0d5c3ef" }, "referenceId": { "type": "string", "description": "Provider reference identifier." }, "errorCode": { "type": "string", "description": "Provider error code when request fails." }, "errorMessage": { "type": "string", "description": "Provider error message when request fails." }, "threeDs2TransactionId": { "type": "string", "description": "3DS2 DS transaction identifier." }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI)." }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value (CAVV)." }, "challengeRequired": { "type": "boolean", "description": "Indicates whether challenge flow is required." }, "jwt": { "type": "string", "description": "Provider JWT/token, if applicable." }, "redirectUrl": { "type": "string", "description": "Netvalve redirect URL to continue 3DS flow." }, "status": { "type": "string", "description": "Current 3DS transaction status.", "enum": [ "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED" ] }, "threeDsVersion": { "type": "string", "description": "3DS protocol version.", "example": "2.2.0" }, "providerRedirectUrl": { "type": "string", "description": "Provider redirect URL, if required by provider flow." }, "merchantRedirectUrl": { "type": "string", "description": "Merchant redirect URL supplied at initialization." }, "provider": { "type": "string", "description": "3DS provider name.", "example": "MASTERCARD" }, "providerTransactionId": { "type": "string", "description": "Provider-side transaction identifier." }, "netvalveCallBackUrl": { "type": "string", "description": "Netvalve callback URL used by provider flow." }, "authType": { "type": "string", "description": "Provider-specific authentication type." }, "methodPostData": { "type": "string", "description": "Provider method post data for device data collection/challenge." }, "cReq": { "type": "string", "description": "Challenge request payload (CReq) used for challenge flow." } }, "description": "Provider-specific response for /3ds/initialization endpoint." }, "ThreeDSInitializationResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique trace identifier for request correlation.", "example": "9a37d2f1-6a7c-44a9-9b3d-2cf52f5f2a5e" }, "responseTimestamp": { "type": "string", "description": "Response creation timestamp.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Netvalve response code.", "example": "3DS_1000" }, "responseMessage": { "type": "string", "description": "Human-readable response message.", "example": "3DS request successfully completed" }, "responseCodeType": { "type": "string", "description": "Response code category.", "example": "APPROVED" }, "bankResponseCode": { "type": "string", "description": "Provider or bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Provider or bank response message.", "example": "Success" }, "midId": { "type": "integer", "description": "Internal merchant identifier (MID).", "format": "int64", "example": 101 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "MID_ABC123" }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ThreeDSInitializationProviderResponseDTO" } }, "description": "Response payload for /3ds/initialization endpoint." }, "ThreeDSAuthInputDTO": { "required": [ "cardHolderName", "currency", "customerLastName", "customerName", "paymentType", "transID" ], "type": "object", "properties": { "midId": { "type": "integer", "format": "int64" }, "netvalveMidId": { "type": "string" }, "transID": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "cardNumber": { "maxLength": 40, "minLength": 0, "type": "string" }, "cardExpireMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string" }, "cardExpireYear": { "maxLength": 4, "minLength": 4, "type": "string" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string" }, "challengeIndicator": { "type": "string" }, "browserInfo": { "type": "string" }, "customerIp": { "type": "string" }, "customerEmail": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerName": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerLastName": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerAddress": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string" }, "customerCity": { "maxLength": 128, "minLength": 0, "type": "string" }, "customerState": { "maxLength": 30, "minLength": 0, "type": "string" }, "customerCountryCode": { "maxLength": 2, "minLength": 2, "type": "string" }, "customerPhone": { "maxLength": 20, "minLength": 0, "type": "string" }, "dfReferenceId": { "type": "string" }, "acsWindowSize": { "type": "integer", "format": "int32" }, "siteId": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentType": { "type": "string", "description": "Payment type used for the transaction. Defaults to CARD if not provided.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "descriptor": { "pattern": "^.{0,50}$", "type": "string" } } }, "ThreeDSAuthenticationProviderResponseDTO": { "type": "object", "properties": { "transID": { "type": "string", "description": "3DS transaction identifier.", "example": "1f3b7cc8-95d8-4b57-a969-2340f0d5c3ef" }, "referenceId": { "type": "string", "description": "Provider reference identifier." }, "errorCode": { "type": "string", "description": "Provider error code when request fails." }, "errorMessage": { "type": "string", "description": "Provider error message when request fails." }, "threeDs2TransactionId": { "type": "string", "description": "3DS2 DS transaction identifier." }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI)." }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value (CAVV)." }, "challengeRequired": { "type": "boolean", "description": "Indicates whether challenge flow is required." }, "jwt": { "type": "string", "description": "Provider JWT/token, if applicable." }, "redirectUrl": { "type": "string", "description": "Netvalve redirect URL to continue 3DS flow." }, "status": { "type": "string", "description": "Current 3DS transaction status.", "enum": [ "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED" ] }, "threeDsVersion": { "type": "string", "description": "3DS protocol version.", "example": "2.2.0" }, "providerRedirectUrl": { "type": "string", "description": "Provider redirect URL, if required by provider flow." }, "merchantRedirectUrl": { "type": "string", "description": "Merchant redirect URL supplied at initialization." }, "provider": { "type": "string", "description": "3DS provider name.", "example": "MASTERCARD" }, "providerTransactionId": { "type": "string", "description": "Provider-side transaction identifier." }, "netvalveCallBackUrl": { "type": "string", "description": "Netvalve callback URL used by provider flow." }, "authType": { "type": "string", "description": "Provider-specific authentication type." }, "methodPostData": { "type": "string", "description": "Provider method post data for device data collection/challenge." }, "cReq": { "type": "string", "description": "Challenge request payload (CReq) used for challenge flow." } }, "description": "Provider-specific details for 3DS authentication response." }, "ThreeDSAuthenticationResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique trace identifier for request correlation.", "example": "9a37d2f1-6a7c-44a9-9b3d-2cf52f5f2a5e" }, "responseTimestamp": { "type": "string", "description": "Response creation timestamp.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Netvalve response code.", "example": "3DS_1000" }, "responseMessage": { "type": "string", "description": "Human-readable response message.", "example": "3DS request successfully completed" }, "responseCodeType": { "type": "string", "description": "Response code category.", "example": "APPROVED" }, "bankResponseCode": { "type": "string", "description": "Provider or bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Provider or bank response message.", "example": "Success" }, "midId": { "type": "integer", "description": "Internal merchant identifier (MID).", "format": "int64", "example": 101 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "MID_ABC123" }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ThreeDSAuthenticationProviderResponseDTO" } }, "description": "Response payload for 3DS authentication endpoint." }, "VoltAssets": { "type": "object", "properties": { "logo": { "type": "string" }, "icon": { "type": "string" } } }, "VoltBranch": { "type": "object", "properties": { "name": { "type": "string" }, "localName": { "type": "string" } } }, "VoltCapabilities": { "type": "object", "properties": { "payments": { "$ref": "#/components/schemas/VoltPaymentCapability" }, "data": { "$ref": "#/components/schemas/VoltDataCapability" } } }, "VoltCommunication": { "type": "object", "properties": { "appToApp": { "type": "string", "enum": [ "UNKNOWN", "SUPPORTED", "NOT_SUPPORTED", "UNKNOWN", "SUPPORTED", "NOT_SUPPORTED" ] } } }, "VoltDataCapability": { "type": "object", "properties": { "active": { "type": "boolean" }, "accountIdentifiersRequired": { "type": "array", "items": { "type": "string" } }, "additionalDataRequired": { "type": "array", "items": { "type": "string" } }, "communication": { "$ref": "#/components/schemas/VoltCommunication" } } }, "VoltGroup": { "type": "object", "properties": { "name": { "type": "string" }, "localName": { "type": "string" } } }, "VoltInstitution": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" }, "assets": { "$ref": "#/components/schemas/VoltAssets" }, "capabilities": { "$ref": "#/components/schemas/VoltCapabilities" }, "types": { "type": "array", "items": { "type": "string" } }, "supportedCurrencies": { "type": "array", "items": { "type": "string" } }, "alternativeName": { "type": "string" }, "nationalId": { "type": "string" }, "localName": { "type": "string" }, "group": { "$ref": "#/components/schemas/VoltGroup" }, "branch": { "$ref": "#/components/schemas/VoltBranch" } } }, "VoltPaymentCapability": { "type": "object", "properties": { "active": { "type": "boolean" }, "accountIdentifiersRequired": { "type": "array", "items": { "type": "string" } }, "additionalDataRequired": { "type": "array", "items": { "type": "string" } }, "communication": { "$ref": "#/components/schemas/VoltCommunication" } } }, "VoltInstitutionCountry": { "type": "object", "properties": { "country": { "type": "string" } } }, "AVSData": { "type": "object", "properties": { "code": { "type": "string", "description": "AVS verification result code.", "example": "Y" }, "description": { "type": "string", "description": "AVS verification result description.", "example": "Street and ZIP match" } }, "description": "Address Verification Service (AVS) result details." }, "ApiSecurityTypeDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the API security configuration.", "format": "int64", "example": 101 }, "userName": { "type": "string", "description": "Username associated with the API security credentials.", "example": "merchant_user" }, "apiClientId": { "type": "string", "description": "Unique client identifier used for API authentication.", "example": "client_abc123" }, "keyName": { "type": "string", "description": "Name or label of the security key.", "example": "Primary API Key" }, "securityType": { "type": "string", "description": "Type of security mechanism used.", "example": "API_KEY" }, "status": { "type": "string", "description": "Current status of the API security configuration.", "example": "ACTIVE" } }, "description": "API security configuration details." }, "CVVVerificationData": { "type": "object", "properties": { "code": { "type": "string", "description": "CVV verification result code.", "example": "M" }, "description": { "type": "string", "description": "CVV verification result description.", "example": "CVV match" } }, "description": "CVV verification result details." }, "ClientFraudRulesTransactionDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the fraud rule transaction.", "format": "int32", "example": 101 }, "transactionId": { "type": "integer", "description": "Transaction identifier associated with the triggered fraud rule.", "format": "int64", "example": 123456789 }, "clientId": { "type": "integer", "description": "Client identifier related to this fraud transaction.", "format": "int64", "example": 2001 }, "midId": { "type": "integer", "description": "Merchant identifier (MID) linked to this fraud transaction.", "format": "int64", "example": 1001 }, "ruleCode": { "type": "string", "description": "Fraud rule code triggered for this transaction.", "example": "FRAUD_RULE_001" }, "createdDatetime": { "type": "string", "description": "Date and time when this fraud transaction record was created.", "format": "date-time" } }, "description": "Fraud rules transaction details for a client." }, "ResultChargebackDataDTO": { "type": "object", "properties": { "chargebackStatus": { "type": "boolean", "description": "Indicates whether chargeback is present/active for the transaction.", "example": true }, "chargebackTransactionType": { "type": "string", "description": "Chargeback transaction type.", "enum": [ "ETHOCA", "RDR", "VERIFY", "TC40", "INFORM", "FRAUD", "CHARGEBACK" ] }, "chargebackDate": { "type": "string", "description": "Chargeback date and time.", "format": "date-time" }, "chargebackTransactionId": { "type": "integer", "description": "Chargeback transaction identifier.", "format": "int64", "example": 123456789 }, "cbAlertId": { "type": "string", "description": "Chargeback alert identifier.", "example": "CB-ALERT-20260426-001" }, "chargebackData": { "type": "string", "description": "Raw chargeback data payload.", "example": "{\"reasonCode\":\"4837\"}" } }, "description": "Chargeback result details associated with a transaction." }, "SmartRoutingDTO": { "type": "object", "properties": { "siteId": { "type": "string", "description": "Site identifier associated with routing decision.", "example": "SITE_001" }, "siteName": { "type": "string", "description": "Site name associated with routing decision.", "example": "Primary Site" }, "ruleId": { "type": "string", "description": "Smart routing rule identifier.", "example": "RULE_100" }, "primaryMid": { "type": "integer", "description": "Primary internal MID selected by routing.", "format": "int64", "example": 1001 }, "retryMid": { "type": "integer", "description": "Retry internal MID selected by routing.", "format": "int64", "example": 1002 }, "primaryMidId": { "type": "string", "description": "Primary external/netvalve MID identifier.", "example": "MID-PRIMARY-001" }, "primaryMidName": { "type": "string", "description": "Primary MID display/account name.", "example": "Primary Merchant MID" }, "retryMidId": { "type": "string", "description": "Retry external/netvalve MID identifier.", "example": "MID-RETRY-001" }, "retryMidName": { "type": "string", "description": "Retry MID display/account name.", "example": "Retry Merchant MID" }, "transactionProcessingMid": { "type": "string", "description": "MID actually used to process this transaction.", "example": "PRIMARY" }, "ruleDateTime": { "type": "string", "description": "Date and time when routing rule was evaluated/applied.", "format": "date-time" }, "clientId": { "type": "integer", "description": "Client identifier for the routing decision.", "format": "int64", "example": 2001 }, "traceID": { "type": "string", "description": "Trace identifier used for correlation.", "example": "4f0d3f6e-c84a-4ab3-9a60-58fd3e4b1ce5" } }, "description": "Smart routing rule and MID selection details used for transaction processing." }, "TokenDTO": { "type": "object", "properties": { "tokenizedCardId": { "type": "integer", "description": "Internal identifier of the tokenized card.", "format": "int64", "example": 12345 }, "paymentToken": { "type": "string", "description": "Payment token (customer vault identifier).", "example": "tok_3f16ef23bc034aaab632fbebda462fe5" }, "paymentTokenType": { "type": "string", "description": "Payment token type.", "example": "GATEWAY_TOKEN" } }, "description": "Token details returned for tokenized card operations." }, "TransactionOutputDTO": { "type": "object", "properties": { "createdDate": { "type": "string", "description": "Transaction creation timestamp.", "format": "date-time" }, "status": { "type": "string", "description": "Current transaction status.", "example": "APPROVED" }, "settlementStatus": { "type": "string", "description": "Settlement status for transaction.", "example": "SETTLED" }, "issuer": { "type": "string", "description": "Card issuer/bank name.", "example": "JPMORGAN CHASE" }, "cardType": { "type": "string", "description": "Card type/category.", "example": "CREDIT" }, "issuerCountry": { "type": "string", "description": "Card issuer country code.", "example": "US" }, "cardholderName": { "type": "string", "description": "Cardholder full name.", "example": "JOHN DOE" }, "netvalveID": { "type": "string", "description": "Internal gateway identifier." }, "clientOrderId": { "type": "string", "description": "Merchant-side order identifier.", "example": "ORD-10001" }, "customerEmail": { "type": "string", "description": "Customer email address.", "example": "john@example.com" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "brand": { "type": "string", "description": "Card brand/network.", "example": "VISA" }, "userID": { "type": "integer", "description": "Internal user identifier.", "format": "int64", "example": 1001 }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "paymentType": { "type": "string", "description": "Payment type classification.", "example": "OPERATION" }, "ipAddress": { "type": "string", "description": "Client IP address captured for transaction.", "example": "203.0.113.10" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "accountName": { "type": "string", "description": "Processing account name.", "example": "primary-us-account" }, "descriptor": { "type": "string", "description": "Statement descriptor used for charge.", "example": "HITPIXEL*STORE" }, "authCode": { "type": "string", "description": "Authorization code from processor/acquirer.", "example": "123456" }, "bankTransactionId": { "type": "string", "description": "Acquirer/bank transaction identifier.", "example": "BNK123456789" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "transactions": { "type": "array", "description": "Referenced transactions linked to this transaction.", "items": { "$ref": "#/components/schemas/TransactionShortOutputDTO" } }, "amount": { "type": "number", "description": "Transaction amount.", "example": 100 }, "currency": { "type": "string", "description": "Transaction currency (ISO 4217).", "example": "USD" }, "avsData": { "$ref": "#/components/schemas/AVSData" }, "cvvVerificationData": { "$ref": "#/components/schemas/CVVVerificationData" }, "name": { "type": "string", "description": "Customer full name.", "example": "John Doe" }, "firstName": { "type": "string", "description": "Customer first name.", "example": "John" }, "lastName": { "type": "string", "description": "Customer last name.", "example": "Doe" }, "ip": { "type": "string", "description": "Customer IP address.", "example": "203.0.113.10" }, "email": { "type": "string", "description": "Customer email.", "example": "john@example.com" }, "address": { "type": "string", "description": "Customer address line.", "example": "123 Main Street" }, "phone": { "type": "string", "description": "Customer phone number.", "example": "+15551234567" }, "city": { "type": "string", "description": "Customer city.", "example": "New York" }, "state": { "type": "string", "description": "Customer state/region.", "example": "NY" }, "countryCode": { "type": "string", "description": "Customer country code.", "example": "US" }, "zipCode": { "type": "string", "description": "Customer ZIP/postal code.", "example": "10001" }, "successUrl": { "type": "string", "description": "Merchant success redirect URL.", "example": "https://merchant.example/success" }, "cancelUrl": { "type": "string", "description": "Merchant cancel redirect URL.", "example": "https://merchant.example/cancel" }, "failedUrl": { "type": "string", "description": "Merchant failure redirect URL.", "example": "https://merchant.example/failed" }, "pendingUrl": { "type": "string", "description": "Merchant pending redirect URL.", "example": "https://merchant.example/pending" }, "threeDomainsSecureData": { "$ref": "#/components/schemas/ThreeDomainsSecureDTO" }, "smartRouting": { "$ref": "#/components/schemas/SmartRoutingDTO" }, "sourceOfTransaction": { "type": "string", "description": "Transaction source/channel.", "example": "API" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "transactionReferencedList": { "type": "array", "description": "List of referenced transactions.", "items": { "$ref": "#/components/schemas/TransactionShortOutputDTO" } }, "transactionType": { "type": "string", "description": "Transaction type enum.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "allowedActions": { "type": "array", "description": "Actions currently allowed on this transaction.", "example": [ "REFUND", "CAPTURE" ], "items": { "type": "string", "description": "Actions currently allowed on this transaction.", "example": "[\"REFUND\",\"CAPTURE\"]" } }, "transactionReference": { "type": "integer", "description": "Primary referenced transaction ID.", "format": "int64", "example": 1000001 }, "orderId": { "type": "integer", "description": "Internal order identifier.", "format": "int64", "example": 200001 }, "paymentTypeEnum": { "type": "string", "description": "Payment type enum.", "example": "OPERATION", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "walletDataDTO": { "$ref": "#/components/schemas/WalletDataDTO" }, "bankName": { "type": "string", "description": "Processor/acquirer bank name.", "example": "CHASE" }, "refundBalancedAmount": { "type": "number", "description": "Remaining refundable amount.", "example": 35.5 }, "isFraudTransaction": { "type": "boolean", "description": "Indicates whether transaction is marked as fraud.", "example": false }, "clientFraudRulesTransaction": { "$ref": "#/components/schemas/ClientFraudRulesTransactionDTO" }, "chargebackData": { "type": "array", "description": "Chargeback records associated with the transaction.", "items": { "$ref": "#/components/schemas/ResultChargebackDataDTO" } }, "cardExpiryMonth": { "type": "string", "description": "Card expiry month (MM).", "example": "12" }, "cardExpiryYear": { "type": "string", "description": "Card expiry year (YYYY).", "example": "2030" }, "tokenDTO": { "$ref": "#/components/schemas/TokenDTO" }, "level2Data": { "$ref": "#/components/schemas/TransactionInputLevel2DTO" }, "level3Data": { "$ref": "#/components/schemas/TransactionInputLevel3DTO" }, "additionalParameters": { "type": "object", "additionalProperties": { "type": "string", "description": "Additional transaction parameters as key-value pairs." }, "description": "Additional transaction parameters as key-value pairs." }, "backofficeUserName": { "type": "string" }, "apiSecurityType": { "$ref": "#/components/schemas/ApiSecurityTypeDTO" }, "apmType": { "type": "string", "description": "Alternative payment method subtype.", "example": "PSE", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "cryptoProvider": { "type": "string", "description": "Crypto payment provider name.", "example": "BITPACE" }, "callbackData": { "type": "object", "description": "Raw callback payload/object captured from provider." }, "networkTokenPrefix": { "type": "string", "description": "Network token prefix digits.", "example": "520000" }, "networkTokenSuffix": { "type": "string", "description": "Network token suffix digits.", "example": "1234" }, "networkTokenExpiryMonth": { "type": "string", "description": "Network token expiry month (MM).", "example": "08" }, "networkTokenExpiryYear": { "type": "string", "description": "Network token expiry year (YYYY).", "example": "2031" }, "networkTokenPrefixAndSuffix": { "type": "string", "description": "Combined network token masked representation.", "example": "520000******1234" }, "tsysBatchSettlementDTO": { "$ref": "#/components/schemas/TsysBatchSettlementDTO" }, "apmPaymentInfo": { "$ref": "#/components/schemas/APMPaymentInfoDTO" }, "threeDsTransaction": { "type": "boolean" }, "smartRoutingTransaction": { "type": "boolean" }, "isPartialRefund": { "type": "boolean", "description": "Indicates whether this refund is partial.", "example": false }, "isPartialRefundAllowed": { "type": "boolean", "description": "Indicates whether partial refund is allowed.", "example": true }, "isPartialCaptureAllowed": { "type": "boolean", "description": "Indicates whether partial capture is allowed.", "example": true }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Transaction response payload with payment, customer, routing, and post-processing details." }, "TransactionShortOutputDTO": { "type": "object", "properties": { "createdDate": { "type": "string", "description": "Transaction creation date and time.", "format": "date-time" }, "transactionType": { "type": "string", "description": "Transaction type.", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY", "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "amount": { "type": "number", "description": "Transaction amount.", "format": "double", "example": 100.5 }, "status": { "type": "string", "description": "Transaction status.", "example": "APPROVED" }, "settlementStatus": { "type": "string", "description": "Settlement status for transaction.", "example": "SETTLED" }, "transactionId": { "type": "integer", "description": "Transaction identifier.", "format": "int64", "example": 123456789 }, "currency": { "type": "string", "description": "Transaction currency code.", "example": "USD" }, "authCode": { "type": "string", "description": "Authorization code from acquirer/processor.", "example": "123456" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "responseCodeType": { "type": "string", "description": "Response code type/category.", "example": "SUCCESS" }, "bankTransactionId": { "type": "string", "description": "Bank/acquirer transaction identifier.", "example": "BNK123456789" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "allowedActions": { "type": "array", "description": "Allowed actions for this transaction.", "example": [ "REFUND", "CAPTURE", "REFUND", "CAPTURE" ], "items": { "type": "string", "description": "Allowed actions for this transaction.", "example": "[\"REFUND\",\"CAPTURE\"]" } }, "transactionReference": { "type": "integer", "description": "Referenced transaction identifier.", "format": "int64", "example": 1000001 }, "threeDomainsSecureData": { "$ref": "#/components/schemas/ThreeDomainsSecureDTO" }, "smartRoutingData": { "$ref": "#/components/schemas/SmartRoutingDTO" }, "sourceOfTransaction": { "type": "string", "description": "Source/channel of transaction.", "enum": [ "HPP", "API", "API_3DS", "HPP_3DS", "RETRY_WITH_HPP", "SMART_ROUTING", "RETRY_WITH_SMART_ROUTING", "SERVER_TO_SERVER", "RETRY_WITH_SERVER_TO_SERVER", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "HPP_3DS_CARDS", "HPP_3DS_APPLE_PAY", "HPP_3DS_GOOGLE_PAY", "HPP_3DS_SAMSUNG_PAY", "HPP_APPLE_PAY_CONFIG_NETVALVE_INTEGRATOR", "HPP_APPLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_APPLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_APPLE_PAY_CONFIG_MID_LEVEL", "HPP_GOOGLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_GOOGLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_GOOGLE_PAY_CONFIG_MID_LEVEL", "GATEWAY_TOKEN_SAVING", "GATEWAY_TOKEN_PROCESSING", "NETWORK_TOKEN_SAVING", "NETWORK_TOKEN_PROCESSING", "HOSTED_PAYMENT_FIELDS", "ACCOUNT_UPDATER", "DISABLE_BLACKLIST", "ENABLE_DYNAMIC_DESCRIPTOR", "ENABLE_BIN_INFO_RESPONSE", "ENABLE_DATA_ENRICHMENT", "HPP", "API", "API_3DS", "HPP_3DS", "RETRY_WITH_HPP", "SMART_ROUTING", "RETRY_WITH_SMART_ROUTING", "SERVER_TO_SERVER", "RETRY_WITH_SERVER_TO_SERVER", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "HPP_3DS_CARDS", "HPP_3DS_APPLE_PAY", "HPP_3DS_GOOGLE_PAY", "HPP_3DS_SAMSUNG_PAY", "HPP_APPLE_PAY_CONFIG_NETVALVE_INTEGRATOR", "HPP_APPLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_APPLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_APPLE_PAY_CONFIG_MID_LEVEL", "HPP_GOOGLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_GOOGLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_GOOGLE_PAY_CONFIG_MID_LEVEL", "GATEWAY_TOKEN_SAVING", "GATEWAY_TOKEN_PROCESSING", "NETWORK_TOKEN_SAVING", "NETWORK_TOKEN_PROCESSING", "HOSTED_PAYMENT_FIELDS", "ACCOUNT_UPDATER", "DISABLE_BLACKLIST", "ENABLE_DYNAMIC_DESCRIPTOR", "ENABLE_BIN_INFO_RESPONSE", "ENABLE_DATA_ENRICHMENT" ] }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "tokenDTO": { "$ref": "#/components/schemas/TokenDTO" }, "threeDsTransaction": { "type": "boolean" }, "smartRoutingTransaction": { "type": "boolean" } }, "description": "Compact transaction response details." }, "TsysBatchSettlementDTO": { "type": "object", "properties": { "settlementBatchDate": { "type": "string", "description": "Settlement batch date and time.", "format": "date-time" }, "settlementBatchId": { "type": "string", "description": "Settlement batch identifier from TSYS.", "example": "BATCH-20260426-001" } }, "description": "TSYS batch settlement details attached to a transaction response." }, "WalletDataDTO": { "type": "object", "properties": { "mappingId": { "type": "integer", "description": "Wallet mapping identifier.", "format": "int64", "example": 501 }, "transactionId": { "type": "integer", "description": "Associated transaction identifier.", "format": "int64", "example": 123456789 }, "walletType": { "type": "string", "description": "Wallet type.", "example": "APPLE_PAY" }, "pan": { "type": "string", "description": "Primary account number or tokenized PAN value.", "example": "411111******1111" }, "panType": { "type": "string", "description": "PAN type.", "example": "NETWORK_TOKEN" }, "authMethod": { "type": "string", "description": "Authorization method returned by wallet payload.", "example": "3DS" }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI).", "example": "05" }, "cryptogram": { "type": "string", "description": "Wallet cryptogram value.", "example": "AgAAAAAABk4DWZ4C28yUQAAAAAA=" }, "cardSummary": { "type": "string", "description": "Card summary details.", "example": "Visa 1111" }, "service": { "type": "string", "description": "Source service name.", "example": "PAYMENT_SERVICE" }, "createdDatetime": { "type": "string", "description": "Record creation timestamp.", "format": "date-time" } }, "description": "Wallet-specific transaction data captured during processing." }, "RecurringScheduleSearchFilterDTO": { "type": "object", "properties": { "fromDateTime": { "type": "string", "description": "Start date-time (inclusive) for filtering subscriptions.", "format": "date-time" }, "toDateTime": { "type": "string", "description": "End date-time (inclusive) for filtering subscriptions.", "format": "date-time" }, "status": { "type": "string", "description": "Recurring subscription status filter.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "subscriptionId": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "transactionId": { "type": "integer", "description": "Transaction identifier linked to the subscription.", "format": "int64", "example": 100001 }, "clientId": { "type": "integer", "description": "Client identifier owning the subscription.", "format": "int64", "example": 2001 } }, "description": "Filter criteria for querying managed recurring subscriptions." }, "ManagedRecurringSubscriptionDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Managed recurring subscription identifier.", "format": "int64", "example": 5001 }, "transactionId": { "type": "integer", "description": "Original transaction identifier linked to the subscription.", "format": "int64", "example": 100001 }, "clientId": { "type": "integer", "description": "Client identifier owning this subscription.", "format": "int64", "example": 2001 }, "status": { "type": "string", "description": "Current recurring schedule status.", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "INACTIVE", "PAYMENT_PENDING", "PAYMENT_FAILED" ] }, "createdDatetime": { "type": "string", "description": "Subscription creation timestamp.", "format": "date-time" }, "updatedDatetime": { "type": "string", "description": "Subscription last updated timestamp.", "format": "date-time" }, "nextAttemptDate": { "type": "string", "description": "Next recurring payment attempt date-time.", "format": "date-time" }, "recurringType": { "type": "string", "description": "Recurring unit type.", "example": "DAYS", "enum": [ "DAYS", "HOURS" ] }, "recurringPeriod": { "type": "integer", "description": "Recurring interval count based on recurringType.", "format": "int32", "example": 30 }, "recurringAmount": { "type": "number", "description": "Amount charged on each recurring attempt.", "example": 99.99 }, "failureAttempts": { "type": "integer", "description": "Total failed recurring attempts.", "format": "int32", "example": 0 }, "subscriptionName": { "type": "string", "description": "Subscription name.", "example": "Gym Membership" }, "description": { "type": "string", "description": "Subscription description or latest reason." }, "recurringTransactionStatus": { "type": "string", "description": "Current recurring transaction status.", "example": "NEW", "enum": [ "NEW", "PROCESSING", "COMPLETED", "FAILED" ] }, "endDate": { "type": "string", "description": "Subscription end date-time, if configured.", "format": "date-time" }, "startDate": { "type": "string", "description": "Subscription start date-time.", "format": "date-time" }, "traceID": { "type": "string", "description": "Correlation identifier for request tracing.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp in server timezone.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Managed recurring subscription fetched successfully." }, "transactions": { "type": "array", "description": "Related transactions linked to this subscription.", "items": { "$ref": "#/components/schemas/TransactionShortOutputDTO" } } }, "description": "Managed recurring subscription details with schedule, status, and related response metadata." }, "PageManagedRecurringSubscriptionDTO": { "type": "object", "properties": { "totalPages": { "type": "integer", "format": "int32" }, "totalElements": { "type": "integer", "format": "int64" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "numberOfElements": { "type": "integer", "format": "int32" }, "size": { "type": "integer", "format": "int32" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedRecurringSubscriptionDTO" } }, "number": { "type": "integer", "format": "int32" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "empty": { "type": "boolean" } } }, "PageableObject": { "type": "object", "properties": { "paged": { "type": "boolean" }, "unpaged": { "type": "boolean" }, "pageNumber": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int64" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } } } }, "SortObject": { "type": "object", "properties": { "direction": { "type": "string" }, "nullHandling": { "type": "string" }, "ascending": { "type": "boolean" }, "property": { "type": "string" }, "ignoreCase": { "type": "boolean" } } }, "BatchSummarySearchFilterDTO": { "type": "object", "properties": { "fromDateTime": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Start of batch created datetime range.", "example": "2026-06-01 00:00:00" }, "toDateTime": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "End of batch created datetime range.", "example": "2026-06-26 23:59:59" }, "descriptor": { "type": "string", "description": "MID descriptor.", "example": "MYSHOP" }, "midId": { "type": "integer", "description": "Merchant identifier.", "format": "int64", "example": 1001 }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "Transaction currency in ISO 4217 format.", "example": "USD" }, "cardType": { "type": "string", "description": "Card brand/type.", "example": "VISA" }, "bin": { "type": "string", "description": "Card BIN, usually first 6 digits.", "example": "411111" }, "countryCode": { "type": "string", "description": "Customer country code.", "example": "US" }, "clientId": { "type": "integer", "description": "Client identifier. For merchant API calls this is resolved from authentication.", "format": "int64", "example": 2001 } }, "description": "Query filters for batch summary report. Date filters are required by the underlying report query and must be sent in yyyy-MM-dd HH:mm:ss format." }, "BatchSummaryDataDTO": { "type": "object", "properties": { "batchId": { "type": "integer", "description": "Internal batch identifier.", "format": "int64", "example": 1001 }, "batchNumber": { "type": "string", "description": "Processor batch number/reference.", "example": "BATCH-20260426-001" }, "processor": { "type": "string", "description": "Processor/bank name.", "example": "TSYS" }, "createdDatetime": { "type": "string", "description": "Batch creation date and time.", "format": "date-time" }, "updatedDatetime": { "type": "string", "description": "Batch last update date and time.", "format": "date-time" }, "numberOfSales": { "type": "integer", "description": "Number of sale transactions in the batch.", "format": "int32", "example": 120 }, "saleAmount": { "type": "number", "description": "Total amount of sale transactions in the batch.", "example": 15000.75 }, "numberOfRefunds": { "type": "integer", "description": "Number of refund transactions in the batch.", "format": "int32", "example": 8 }, "refundAmount": { "type": "number", "description": "Total amount of refund transactions in the batch.", "example": 850.25 }, "numberOfNetTransactions": { "type": "integer", "description": "Net transaction count (sales - refunds).", "format": "int32", "example": 112 }, "netAmount": { "type": "number", "description": "Net amount (saleAmount - refundAmount).", "example": 14150.5 } }, "description": "Batch-level summary metrics for sales/refunds and net totals." }, "BatchSummaryDetailsDTO": { "type": "object", "properties": { "batchId": { "type": "integer", "description": "Internal batch identifier.", "format": "int64", "example": 1001 }, "batchNumber": { "type": "string", "description": "Processor batch number/reference.", "example": "BATCH-20260426-001" }, "processor": { "type": "string", "description": "Processor/bank name.", "example": "TSYS" }, "createdDateTime": { "type": "string", "description": "Batch creation date and time.", "format": "date-time" }, "updatedDateTime": { "type": "string", "description": "Batch last update date and time.", "format": "date-time" }, "numberOfSales": { "type": "integer", "description": "Number of sale transactions in the batch.", "format": "int32", "example": 120 }, "saleAmount": { "type": "number", "description": "Total sale amount in the batch.", "example": 15000.75 }, "numberOfRefunds": { "type": "integer", "description": "Number of refund transactions in the batch.", "format": "int32", "example": 8 }, "refundAmount": { "type": "number", "description": "Total refund amount in the batch.", "example": 850.25 }, "numberOfNetTransactions": { "type": "integer", "description": "Net transaction count (sales - refunds).", "format": "int32", "example": 112 }, "netAmount": { "type": "number", "description": "Net amount (saleAmount - refundAmount).", "example": 14150.5 }, "batchTransactions": { "type": "array", "description": "Transaction entries included in this batch.", "items": { "$ref": "#/components/schemas/BatchTransactionDTO" } } }, "description": "Detailed batch summary including aggregate values and transaction list." }, "BatchTransactionDTO": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal transaction identifier.", "format": "int64", "example": 987654321 }, "amount": { "type": "number", "description": "Transaction amount.", "example": 49.99 }, "currency": { "type": "string", "description": "Transaction currency (ISO 4217).", "example": "USD" }, "orderId": { "type": "integer", "description": "Order identifier.", "format": "int64", "example": 12345 }, "clientOrderId": { "type": "string", "description": "Client-provided order identifier.", "example": "ORD-12345-ABC" }, "transactionType": { "type": "string", "description": "Transaction type.", "example": "SALE" }, "transactionReference": { "type": "integer", "description": "Reference transaction id for follow-up operations.", "format": "int64", "example": 987650000 }, "datetime": { "type": "string", "description": "Transaction creation timestamp.", "format": "date-time" }, "accountName": { "type": "string", "description": "Merchant account name.", "example": "Acme Merchant" }, "status": { "type": "string", "description": "Transaction status.", "example": "SUCCESS" }, "customerEmail": { "type": "string", "description": "Customer email.", "example": "john.doe@example.com" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_0000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction processed successfully" }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "bankResponseCode": { "type": "string", "description": "Processor/bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Processor/bank response message.", "example": "Approved" }, "bankName": { "type": "string", "description": "Bank/provider name.", "example": "TSYS" }, "bankTransactionId": { "type": "string", "description": "Bank-side transaction identifier.", "example": "BNK-TXN-443322" }, "authCode": { "type": "string", "description": "Authorization code.", "example": "A1B2C3" } }, "description": "Batch transaction summary record." }, "PseBank": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" } } }, "PseBankList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PseBank" } } } }, "OrderSearchFilterDTO": { "type": "object", "properties": { "fromDateTime": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Start of order created datetime range. Used only when both fromDateTime and toDateTime are supplied.", "example": "2026-06-01 00:00:00" }, "toDateTime": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "End of order created datetime range. Used only when both fromDateTime and toDateTime are supplied.", "example": "2026-06-26 23:59:59" }, "emailAddress": { "type": "string", "description": "Customer email address filter. If sent without a complete date range, email search is prioritized.", "example": "customer@example.com" }, "firstName": { "type": "string", "description": "Customer first name.", "example": "John" }, "lastName": { "type": "string", "description": "Customer last name.", "example": "Doe" }, "orderId": { "type": "integer", "description": "Exact internal order identifier. When supplied, order ID search takes precedence over other filters.", "format": "int64", "example": 12345 }, "clientOrderId": { "type": "string", "description": "Client-provided order identifier. When supplied, client order ID search takes precedence over general filters.", "example": "ORD-12345-ABC" }, "orderStatus": { "type": "string", "description": "Order status value stored on the order.", "example": "Completed" }, "descriptor": { "type": "string", "description": "MID descriptor.", "example": "MYSHOP" }, "countryCode": { "type": "string", "description": "Customer country code.", "example": "US" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "Transaction currency in ISO 4217 format.", "example": "USD" }, "transactionId": { "type": "integer", "description": "Exact internal transaction identifier linked to the order.", "format": "int64", "example": 987654321 }, "cardType": { "type": "string", "description": "Card brand/type.", "example": "VISA" }, "bin": { "type": "string", "description": "Card BIN, usually first 6 digits.", "example": "411111" }, "ccFirstSix": { "type": "string", "description": "First six digits of the card number.", "example": "411111" }, "ccLastFour": { "type": "string", "description": "Last four digits of the card number.", "example": "1111" }, "midId": { "type": "integer", "description": "Merchant identifier.", "format": "int64", "example": 1001 }, "bankId": { "type": "integer", "description": "Bank or processor identifier.", "format": "int64", "example": 12 }, "minAmount": { "type": "number", "description": "Minimum order transaction amount, inclusive.", "example": 10 }, "maxAmount": { "type": "number", "description": "Maximum order transaction amount, inclusive.", "example": 100 }, "correlationId": { "type": "string", "description": "Request correlation identifier.", "example": "trace-7f3d9e12" }, "paymentStatus": { "type": "string", "description": "Payment result filter. SUCCESS includes successful attempted payments; FAILED includes failed attempted payments.", "example": "SUCCESS", "enum": [ "SUCCESS", "FAILED" ] }, "includeAllStatuses": { "type": "boolean", "description": "Include all statuses. Defaults to false when omitted.", "example": false, "default": false }, "paymentType": { "type": "string", "description": "Payment type. Value is case-insensitive.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "apmType": { "type": "string", "description": "Alternative payment method type. Value is case-insensitive.", "example": "PAYPAL", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "walletType": { "type": "string", "description": "Wallet type. Value is case-insensitive.", "example": "APPLE_PAY", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "serviceName": { "type": "string", "description": "Service name filter.", "example": "Payment API" }, "withThreeDs": { "type": "boolean", "description": "Filter orders by linked 3DS transaction data. Defaults to false when omitted.", "example": false, "default": false }, "threeDsProviderId": { "type": "integer", "description": "3DS provider identifier.", "format": "int64", "example": 3 }, "clientId": { "type": "integer", "description": "Client identifier. For merchant API calls this is normally resolved from authentication.", "format": "int64", "example": 2001 }, "resellerId": { "type": "integer", "description": "Reseller identifier.", "format": "int64", "example": 3001 }, "paymentTypeEnum": { "type": "string", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "apmTypeEnum": { "type": "string", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "walletTypeEnum": { "type": "string", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] } }, "description": "Query filters for order export. All fields are optional unless noted. Dates must be sent as query parameters in yyyy-MM-dd HH:mm:ss format." }, "PageResultOrderDTO": { "type": "object", "properties": { "totalPages": { "type": "integer", "format": "int32" }, "totalElements": { "type": "integer", "format": "int64" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "numberOfElements": { "type": "integer", "format": "int32" }, "size": { "type": "integer", "format": "int32" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ResultOrderDTO" } }, "number": { "type": "integer", "format": "int32" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "empty": { "type": "boolean" } } }, "ResultOrderDTO": { "type": "object", "properties": { "sourceOfTransaction": { "type": "string", "description": "Channel/source of transaction initiation.", "example": "API", "enum": [ "HPP", "API", "API_3DS", "HPP_3DS", "RETRY_WITH_HPP", "SMART_ROUTING", "RETRY_WITH_SMART_ROUTING", "SERVER_TO_SERVER", "RETRY_WITH_SERVER_TO_SERVER", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "HPP_3DS_CARDS", "HPP_3DS_APPLE_PAY", "HPP_3DS_GOOGLE_PAY", "HPP_3DS_SAMSUNG_PAY", "HPP_APPLE_PAY_CONFIG_NETVALVE_INTEGRATOR", "HPP_APPLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_APPLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_APPLE_PAY_CONFIG_MID_LEVEL", "HPP_GOOGLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_GOOGLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_GOOGLE_PAY_CONFIG_MID_LEVEL", "GATEWAY_TOKEN_SAVING", "GATEWAY_TOKEN_PROCESSING", "NETWORK_TOKEN_SAVING", "NETWORK_TOKEN_PROCESSING", "HOSTED_PAYMENT_FIELDS", "ACCOUNT_UPDATER", "DISABLE_BLACKLIST", "ENABLE_DYNAMIC_DESCRIPTOR", "ENABLE_BIN_INFO_RESPONSE", "ENABLE_DATA_ENRICHMENT" ] }, "id": { "type": "integer", "description": "Order identifier.", "format": "int64", "example": 123456789 }, "amount": { "type": "string", "description": "Order amount.", "example": "100.5" }, "createdDate": { "type": "string", "description": "Order creation date and time.", "format": "date-time" }, "status": { "type": "string", "description": "Order status.", "example": "CREATED" }, "accountName": { "type": "string", "description": "Merchant account name.", "example": "Acme Store" }, "customerEmail": { "type": "string", "description": "Customer email address.", "example": "john@example.com" }, "currency": { "type": "string", "description": "Order currency code.", "example": "USD" }, "bankName": { "type": "string", "description": "Bank/acquirer name.", "example": "TSYS" }, "hppOrderStatus": { "type": "string", "description": "HPP order status derived from payment status.", "example": "CREATED" }, "clientOrderId": { "type": "string", "description": "Client-provided order identifier.", "example": "CLIENT-ORD-20001" }, "traceId": { "type": "string", "description": "Trace identifier used for correlation.", "example": "4f0d3f6e-c84a-4ab3-9a60-58fd3e4b1ce5" }, "paymentType": { "type": "string", "description": "Payment type.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "walletType": { "type": "string", "description": "Wallet type when paymentType is WALLET.", "example": "APPLE_PAY", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "walletData": { "type": "string", "description": "Wallet data payload/details." } }, "description": "Order-level result data used in order listing/search responses." }, "OrderOutputDTO": { "type": "object", "properties": { "createdDate": { "type": "string", "description": "Transaction creation timestamp.", "format": "date-time" }, "status": { "type": "string", "description": "Current order status.", "example": "APPROVED" }, "settlementStatus": { "type": "string", "description": "Settlement status for transaction.", "example": "SETTLED" }, "issuer": { "type": "string", "description": "Card issuer/bank name.", "example": "JPMORGAN CHASE" }, "cardType": { "type": "string", "description": "Card type/category.", "example": "CREDIT" }, "issuerCountry": { "type": "string", "description": "Card issuer country code.", "example": "US" }, "cardholderName": { "type": "string", "description": "Cardholder full name.", "example": "JOHN DOE" }, "netvalveID": { "type": "string", "description": "Internal gateway identifier." }, "clientOrderId": { "type": "string", "description": "Merchant-side order identifier.", "example": "ORD-10001" }, "customerEmail": { "type": "string", "description": "Customer email address.", "example": "john@example.com" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "brand": { "type": "string", "description": "Card brand/network.", "example": "VISA" }, "userID": { "type": "integer", "description": "Internal user identifier.", "format": "int64", "example": 1001 }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "paymentType": { "type": "string", "description": "Payment type classification.", "example": "OPERATION" }, "ipAddress": { "type": "string", "description": "Client IP address captured for transaction.", "example": "203.0.113.10" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "accountName": { "type": "string", "description": "Processing account name.", "example": "primary-us-account" }, "descriptor": { "type": "string", "description": "Statement descriptor used for charge.", "example": "HITPIXEL*STORE" }, "authCode": { "type": "string", "description": "Authorization code from processor/acquirer.", "example": "123456" }, "bankTransactionId": { "type": "string", "description": "Acquirer/bank transaction identifier.", "example": "BNK123456789" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "transactions": { "type": "array", "description": "Referenced transactions linked to this transaction.", "items": { "$ref": "#/components/schemas/TransactionShortOutputDTO" } }, "currency": { "type": "string", "description": "Transaction currency (ISO 4217).", "example": "USD" }, "avsData": { "$ref": "#/components/schemas/AVSData" }, "cvvVerificationData": { "$ref": "#/components/schemas/CVVVerificationData" }, "name": { "type": "string", "description": "Customer full name.", "example": "John Doe" }, "firstName": { "type": "string", "description": "Customer first name.", "example": "John" }, "lastName": { "type": "string", "description": "Customer last name.", "example": "Doe" }, "ip": { "type": "string", "description": "Customer IP address.", "example": "203.0.113.10" }, "email": { "type": "string", "description": "Customer email.", "example": "john@example.com" }, "address": { "type": "string", "description": "Customer address line.", "example": "123 Main Street" }, "phone": { "type": "string", "description": "Customer phone number.", "example": "+15551234567" }, "city": { "type": "string", "description": "Customer city.", "example": "New York" }, "state": { "type": "string", "description": "Customer state/region.", "example": "NY" }, "countryCode": { "type": "string", "description": "Customer country code.", "example": "US" }, "zipCode": { "type": "string", "description": "Customer ZIP/postal code.", "example": "10001" }, "successUrl": { "type": "string", "description": "Merchant success redirect URL.", "example": "https://merchant.example/success" }, "cancelUrl": { "type": "string", "description": "Merchant cancel redirect URL.", "example": "https://merchant.example/cancel" }, "failedUrl": { "type": "string", "description": "Merchant failure redirect URL.", "example": "https://merchant.example/failed" }, "pendingUrl": { "type": "string", "description": "Merchant pending redirect URL.", "example": "https://merchant.example/pending" }, "threeDomainsSecureData": { "$ref": "#/components/schemas/ThreeDomainsSecureDTO" }, "smartRouting": { "$ref": "#/components/schemas/SmartRoutingDTO" }, "sourceOfTransaction": { "type": "string", "description": "Transaction source/channel.", "example": "API" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "transactionReferencedList": { "type": "array", "description": "List of referenced transactions.", "items": { "$ref": "#/components/schemas/TransactionShortOutputDTO" } }, "transactionType": { "type": "string", "description": "Transaction type enum.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "allowedActions": { "type": "array", "description": "Actions currently allowed on this transaction.", "example": [ "REFUND", "CAPTURE" ], "items": { "type": "string", "description": "Actions currently allowed on this transaction.", "example": "[\"REFUND\",\"CAPTURE\"]" } }, "transactionReference": { "type": "integer", "description": "Primary referenced transaction ID.", "format": "int64", "example": 1000001 }, "orderId": { "type": "integer", "description": "Internal order identifier.", "format": "int64", "example": 200001 }, "paymentTypeEnum": { "type": "string", "description": "Payment type enum.", "example": "OPERATION", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "walletDataDTO": { "$ref": "#/components/schemas/WalletDataDTO" }, "bankName": { "type": "string", "description": "Processor/acquirer bank name.", "example": "CHASE" }, "refundBalancedAmount": { "type": "number", "description": "Remaining refundable amount.", "example": 35.5 }, "isFraudTransaction": { "type": "boolean", "description": "Indicates whether transaction is marked as fraud.", "example": false }, "clientFraudRulesTransaction": { "$ref": "#/components/schemas/ClientFraudRulesTransactionDTO" }, "chargebackData": { "type": "array", "description": "Chargeback records associated with the transaction.", "items": { "$ref": "#/components/schemas/ResultChargebackDataDTO" } }, "cardExpiryMonth": { "type": "string", "description": "Card expiry month (MM).", "example": "12" }, "cardExpiryYear": { "type": "string", "description": "Card expiry year (YYYY).", "example": "2030" }, "tokenDTO": { "$ref": "#/components/schemas/TokenDTO" }, "level2Data": { "$ref": "#/components/schemas/TransactionInputLevel2DTO" }, "level3Data": { "$ref": "#/components/schemas/TransactionInputLevel3DTO" }, "additionalParameters": { "type": "object", "additionalProperties": { "type": "string", "description": "Additional order parameters returned as key-value pairs." }, "description": "Additional order parameters returned as key-value pairs." }, "backofficeUserName": { "type": "string" }, "apiSecurityType": { "$ref": "#/components/schemas/ApiSecurityTypeDTO" }, "apmType": { "type": "string", "description": "Alternative payment method subtype.", "example": "PSE", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "cryptoProvider": { "type": "string", "description": "Crypto payment provider name.", "example": "BITPACE" }, "callbackData": { "type": "object", "description": "Raw callback payload/object captured from provider." }, "networkTokenPrefix": { "type": "string", "description": "Network token prefix digits.", "example": "520000" }, "networkTokenSuffix": { "type": "string", "description": "Network token suffix digits.", "example": "1234" }, "networkTokenExpiryMonth": { "type": "string", "description": "Network token expiry month (MM).", "example": "08" }, "networkTokenExpiryYear": { "type": "string", "description": "Network token expiry year (YYYY).", "example": "2031" }, "networkTokenPrefixAndSuffix": { "type": "string", "description": "Combined network token masked representation.", "example": "520000******1234" }, "tsysBatchSettlementDTO": { "$ref": "#/components/schemas/TsysBatchSettlementDTO" }, "apmPaymentInfo": { "$ref": "#/components/schemas/APMPaymentInfoDTO" }, "amountAndCurrency": { "type": "string", "description": "Formatted order amount with currency.", "example": "100.00 USD" }, "orderAmount": { "type": "number", "description": "Order amount value.", "example": 100 }, "lastUpdatedDate": { "type": "string", "description": "Order last updated timestamp.", "format": "date-time" }, "hppOrderStatus": { "type": "string", "description": "Order status, when applicable.", "example": "PENDING" }, "orderDesc": { "type": "string", "description": "Order description provided by merchant.", "example": "Order #12345" }, "threeDsTransaction": { "type": "boolean" }, "smartRoutingTransaction": { "type": "boolean" }, "isPartialRefund": { "type": "boolean", "description": "Indicates whether this refund is partial.", "example": false }, "isPartialRefundAllowed": { "type": "boolean", "description": "Indicates whether partial refund is allowed.", "example": true }, "isPartialCaptureAllowed": { "type": "boolean", "description": "Indicates whether partial capture is allowed.", "example": true } }, "description": "Response model for order details, extending transaction output with order-specific fields." }, "InquiryTransactionResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Correlation identifier for tracing request flow.", "example": "d3cb9f3c-16c3-4d9e-a22f-f8935c1d8f8f" }, "responseTimestamp": { "type": "string", "description": "Response timestamp generated by the service.", "format": "date-time", "example": "2026-04-27T11:05:30Z" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "originalTransactionId": { "type": "integer", "description": "Internal parent transaction identifier.", "format": "int64", "example": 987654321 }, "originalTransactionType": { "type": "string", "description": "Internal parent transaction type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionID": { "type": "integer", "description": "Gateway transaction identifier.", "format": "int64", "example": 100001 }, "responseCodeType": { "type": "string", "description": "Response code category/type.", "example": "SUCCESS" }, "paymentMethod": { "type": "string", "description": "Payment method used for transaction.", "example": "CARD" }, "cardType": { "type": "string", "description": "Card brand/type when card data is available.", "example": "VISA" }, "bankTransactionId": { "type": "string", "description": "Transaction identifier returned by bank/acquirer.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code returned by bank/acquirer.", "example": "123456" }, "midId": { "type": "integer", "description": "Merchant identifier used for processing.", "format": "int64", "example": 1001 }, "netvalveMidId": { "type": "string", "description": "External/Netvalve merchant identifier.", "example": "f7e0f1b8-2c6d-4a91-9a5b-3de2c4f8b7a1" }, "processor": { "type": "string", "description": "Payment processor name.", "example": "TSYS" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "transactionType": { "type": "string", "description": "Transaction operation type.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "currency": { "type": "string", "description": "Processed transaction currency (ISO 4217).", "example": "USD" }, "cardExpiryMonth": { "type": "string", "description": "Card expiry month in MM format.", "example": "12" }, "cardExpiryYear": { "type": "string", "description": "Card expiry year in YYYY format.", "example": "2030" }, "paymentAttempted": { "type": "boolean", "description": "Indicates whether payment was attempted for the transaction.", "example": true }, "paymentChannelType": { "type": "string", "description": "Payment channel used by the transaction.", "example": "HPP" }, "apmType": { "type": "string", "description": "Alternative payment method subtype.", "example": "PSE" }, "apmPaymentUrl": { "type": "string", "description": "APM payment URL returned for redirect-based methods.", "example": "https://provider.example/pay/abc123" }, "apmPaymentUrlExpiry": { "type": "string", "description": "APM payment URL expiry date-time.", "format": "date-time" }, "apmPaymentInfo": { "$ref": "#/components/schemas/APMPaymentInfoDTO" }, "paymentToken": { "type": "string", "description": "Payment token/customer vault id associated with the transaction.", "example": "cust_vault_12345" }, "paymentTokenType": { "type": "string", "description": "Payment token type.", "example": "GATEWAY_TOKEN" }, "siteId": { "type": "string", "description": "Site identifier associated with the transaction.", "example": "site_001" }, "clientId": { "type": "integer", "description": "Client identifier associated with the transaction.", "format": "int64", "example": 2001 }, "binInfo": { "$ref": "#/components/schemas/BinInfo" }, "amount": { "type": "number", "description": "Transaction amount.", "example": 100 }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Response payload for inquiry transaction status endpoint." }, "HostedPaymentFieldsResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Request trace identifier used for correlation.", "example": "4f0d3f6e-c84a-4ab3-9a60-58fd3e4b1ce5" }, "responseTimestamp": { "type": "string", "description": "Timestamp at which the response was generated.", "format": "date-time", "example": "2026-04-26T09:30:00Z" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction successfully completed" }, "netvalveScriptSrc": { "type": "string", "description": "Hosted payment fields JavaScript source URL.", "example": "https://cdn.netvalve.com/hpf/netvalve.min.js" }, "version": { "type": "string", "description": "Hosted payment fields script version.", "example": "1.0.0" }, "integrity": { "type": "string", "description": "Subresource Integrity (SRI) hash for the hosted payment script.", "example": "sha384-abc123xyz" }, "paymentToken": { "type": "string", "description": "Hosted payment tokenization key.", "example": "tok_3f16ef23bc034aaab632fbebda462fe5" }, "jwtToken": { "type": "string", "description": "JWT token used by hosted payment fields.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "description": "Response payload for hosted payment fields initialization." }, "TransactionSearchFilterDTO": { "type": "object", "properties": { "fromDateTime": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Start of transaction datetime range. If omitted with toDateTime, the service applies its configured default lookback window.", "example": "2026-06-01 00:00:00" }, "toDateTime": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "End of transaction datetime range. Must be used with fromDateTime for an explicit date search. The configured maximum export date range is enforced by the service.", "example": "2026-06-26 23:59:59" }, "emailAddress": { "type": "string", "description": "Customer email address filter. Can be used without date filters.", "example": "customer@example.com" }, "transactionId": { "type": "integer", "description": "Exact internal transaction identifier. When supplied, transaction ID search takes precedence over date range search.", "format": "int64", "example": 987654321 }, "transactionStatus": { "type": "string", "description": "Transaction status filter.", "example": "SOLD", "enum": [ "AUTHORIZED", "CAPTURED", "SOLD", "CANCELED", "REFUNDED", "REBILLED", "PENDING", "DECLINED", "RECURRED" ] }, "transactionType": { "type": "string", "description": "Transaction operation type. Value is case-insensitive.", "example": "SALE", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "midId": { "type": "integer", "description": "Merchant identifier.", "format": "int64", "example": 1001 }, "orderId": { "type": "integer", "description": "Internal order identifier.", "format": "int64", "example": 12345 }, "clientOrderId": { "type": "string", "description": "Client-provided order identifier.", "example": "ORD-12345-ABC" }, "descriptor": { "type": "string", "description": "MID descriptor.", "example": "MYSHOP" }, "countryCode": { "type": "string", "description": "Customer country code.", "example": "US" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "Transaction currency in ISO 4217 format.", "example": "USD" }, "cardType": { "type": "string", "description": "Card brand/type.", "example": "VISA" }, "bin": { "type": "string", "description": "Card BIN, usually first 6 digits.", "example": "411111" }, "transactionReferenceId": { "type": "integer", "description": "Transaction reference identifier for linked transactions.", "format": "int64", "example": 987654320 }, "ccFirstSix": { "type": "string", "description": "First six digits of the card number.", "example": "411111" }, "ccLastFour": { "type": "string", "description": "Last four digits of the card number.", "example": "1111" }, "firstName": { "type": "string", "description": "Customer first name.", "example": "John" }, "lastName": { "type": "string", "description": "Customer last name.", "example": "Doe" }, "minAmount": { "type": "number", "description": "Minimum transaction amount, inclusive.", "example": 10 }, "maxAmount": { "type": "number", "description": "Maximum transaction amount, inclusive.", "example": 100 }, "bankId": { "type": "integer", "description": "Bank or processor identifier.", "format": "int64", "example": 12 }, "correlationId": { "type": "string", "description": "Request correlation identifier.", "example": "trace-7f3d9e12" }, "paymentStatus": { "type": "string", "description": "Payment status filter.", "example": "SUCCESS" }, "includeAllStatuses": { "type": "boolean", "description": "Include all statuses. Defaults to false when omitted.", "example": false, "default": false }, "tokenType": { "type": "string", "description": "Tokenization type. Value is case-insensitive.", "example": "GATEWAY_TOKEN", "enum": [ "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF" ] }, "paymentType": { "type": "string", "description": "Payment type. Value is case-insensitive.", "example": "CARD", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "apmType": { "type": "string", "description": "Alternative payment method type. Value is case-insensitive.", "example": "PAYPAL", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "walletType": { "type": "string", "description": "Wallet type. Value is case-insensitive.", "example": "APPLE_PAY", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "serviceName": { "type": "string", "description": "Service name filter.", "example": "Payment API" }, "withThreeDs": { "type": "boolean", "description": "Filter transactions by 3DS usage. Defaults to false when omitted.", "example": false, "default": false }, "threeDsProviderId": { "type": "integer", "description": "3DS provider identifier.", "format": "int64", "example": 3 }, "siteName": { "type": "string", "description": "Site name filter.", "example": "main-site" }, "bankAuthCode": { "type": "string", "description": "Bank authorization code.", "example": "A1B2C3" }, "bankTransactionId": { "type": "string", "description": "Bank-side transaction identifier.", "example": "BNK-TXN-443322" }, "isFraudOnly": { "type": "boolean", "description": "Return fraud-only transactions. Defaults to false when omitted.", "example": false, "default": false }, "isChargebackOnly": { "type": "boolean", "description": "Return chargeback-only transactions. Defaults to false when omitted.", "example": false, "default": false }, "cbTransactionType": { "type": "string", "description": "Chargeback alert transaction type. Use the display value shown in allowable values.", "example": "Ethoca", "enum": [ "Ethoca", "RDR", "Verify", "TC40", "InformAlert", "Fraud", "Chargeback" ] }, "subscriptionId": { "type": "integer", "description": "Subscription identifier.", "format": "int64", "example": 12345 }, "levelOption": { "type": "string", "description": "Level data shortcut. BOTH maps to LEVEL2 and LEVEL3.", "example": "BOTH", "enum": [ "LEVEL2", "LEVEL3", "BOTH", "LEVEL2", "LEVEL3", "BOTH" ] }, "levelFilter": { "type": "array", "description": "Explicit transaction level filter. Can be sent as repeated query params, for example levelFilter=LEVEL2&levelFilter=LEVEL3.", "example": [ "LEVEL2", "LEVEL3" ], "items": { "type": "string", "description": "Explicit transaction level filter. Can be sent as repeated query params, for example levelFilter=LEVEL2&levelFilter=LEVEL3.", "example": "[\"LEVEL2\",\"LEVEL3\"]", "enum": [ "LEVEL1", "LEVEL2", "LEVEL3" ] }, "enum": [ "LEVEL1", "LEVEL2", "LEVEL3" ] }, "networkTokenPrefix": { "type": "string", "description": "Network token prefix.", "example": "411111" }, "networkTokenSuffix": { "type": "string", "description": "Network token suffix.", "example": "1111" }, "settlementFromDate": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "Start of settlement datetime range.", "example": "2026-06-01 00:00:00" }, "settlementToDate": { "pattern": "yyyy-MM-dd HH:mm:ss", "type": "string", "description": "End of settlement datetime range.", "example": "2026-06-26 23:59:59" }, "settlementBatchId": { "type": "string", "description": "Settlement batch identifier.", "example": "BATCH-20260626-001" }, "tsysTransId": { "type": "string", "description": "TSYS transaction identifier.", "example": "TSYS-123456" }, "clientId": { "type": "integer", "description": "Client identifier. For merchant API calls this is normally resolved from authentication.", "format": "int64", "example": 2001 }, "resellerId": { "type": "integer", "description": "Reseller identifier.", "format": "int64", "example": 3001 }, "maxLimit": { "type": "integer", "description": "Maximum page size override. If omitted, the service configured maximum is used; requested pageSize is capped to this value.", "format": "int32", "example": 5000 }, "siteId": { "type": "string", "description": "Site identifier.", "example": "6001" }, "transactionTypeEnum": { "type": "string", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "tokenTypeEnum": { "type": "string", "enum": [ "GATEWAY_TOKEN", "NETWORK_TOKEN", "BANK_TOKEN", "HPF", "SDK" ] }, "paymentTypeEnum": { "type": "string", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "apmTypeEnum": { "type": "string", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "walletTypeEnum": { "type": "string", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "levelFilterEnum": { "type": "array", "items": { "type": "string", "enum": [ "LEVEL1", "LEVEL2", "LEVEL3" ] } } }, "description": "Query filters for transaction export. All fields are optional unless noted. Dates must be sent as query parameters in yyyy-MM-dd HH:mm:ss format." }, "PageResultTransactionDTO": { "type": "object", "properties": { "totalPages": { "type": "integer", "format": "int32" }, "totalElements": { "type": "integer", "format": "int64" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "numberOfElements": { "type": "integer", "format": "int32" }, "size": { "type": "integer", "format": "int32" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ResultTransactionDTO" } }, "number": { "type": "integer", "format": "int32" }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortObject" } }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "empty": { "type": "boolean" } } }, "ResultTransactionDTO": { "type": "object", "properties": { "apmType": { "type": "string", "description": "Alternative payment method subtype.", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "sourceOfTransaction": { "type": "string", "description": "Source/channel of transaction.", "enum": [ "HPP", "API", "API_3DS", "HPP_3DS", "RETRY_WITH_HPP", "SMART_ROUTING", "RETRY_WITH_SMART_ROUTING", "SERVER_TO_SERVER", "RETRY_WITH_SERVER_TO_SERVER", "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY", "HPP_3DS_CARDS", "HPP_3DS_APPLE_PAY", "HPP_3DS_GOOGLE_PAY", "HPP_3DS_SAMSUNG_PAY", "HPP_APPLE_PAY_CONFIG_NETVALVE_INTEGRATOR", "HPP_APPLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_APPLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_APPLE_PAY_CONFIG_MID_LEVEL", "HPP_GOOGLE_PAY_CONFIG_NETVALVE_LEVEL", "HPP_GOOGLE_PAY_CONFIG_CLIENT_LEVEL", "HPP_GOOGLE_PAY_CONFIG_MID_LEVEL", "GATEWAY_TOKEN_SAVING", "GATEWAY_TOKEN_PROCESSING", "NETWORK_TOKEN_SAVING", "NETWORK_TOKEN_PROCESSING", "HOSTED_PAYMENT_FIELDS", "ACCOUNT_UPDATER", "DISABLE_BLACKLIST", "ENABLE_DYNAMIC_DESCRIPTOR", "ENABLE_BIN_INFO_RESPONSE", "ENABLE_DATA_ENRICHMENT" ] }, "id": { "type": "integer", "description": "Transaction identifier.", "format": "int64", "example": 123456789 }, "amount": { "type": "number", "description": "Transaction amount.", "example": 100.5 }, "currency": { "type": "string", "description": "Transaction currency code.", "example": "USD" }, "orderId": { "type": "string", "description": "Internal order identifier.", "example": "ORD-10001" }, "clientOrderId": { "type": "string", "description": "Client-provided order identifier.", "example": "CLIENT-ORD-20001" }, "transactionType": { "type": "string", "description": "Transaction type.", "enum": [ "AUTHORIZATION", "CAPTURE", "SALE", "REFUND", "CANCEL", "REBILL", "INQUIRY" ] }, "transactionReference": { "type": "integer", "description": "Referenced transaction identifier.", "format": "int64", "example": 1000001 }, "datetime": { "type": "string", "description": "Transaction date and time.", "format": "date-time" }, "accountName": { "type": "string", "description": "Merchant account name.", "example": "Acme Store" }, "status": { "type": "string", "description": "Transaction status.", "example": "APPROVED" }, "customerEmail": { "type": "string", "description": "Customer email address.", "example": "john@example.com" }, "responseCode": { "type": "string", "description": "Gateway response code.", "example": "GTW_1000" }, "responseMessage": { "type": "string", "description": "Gateway response message.", "example": "Transaction Approved/ Request Successful." }, "responseCodeType": { "type": "string", "description": "Response code type/category.", "example": "SUCCESS" }, "bankResponseCode": { "type": "string", "description": "Bank/acquirer response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Bank/acquirer response message.", "example": "Approved" }, "bankName": { "type": "string", "description": "Bank/acquirer name.", "example": "TSYS" }, "bankTransactionId": { "type": "string", "description": "Bank/acquirer transaction identifier.", "example": "BNK123456789" }, "authCode": { "type": "string", "description": "Authorization code from acquirer.", "example": "123456" }, "smartRouting": { "$ref": "#/components/schemas/SmartRoutingDTO" }, "traceId": { "type": "string", "description": "Trace identifier used for correlation.", "example": "4f0d3f6e-c84a-4ab3-9a60-58fd3e4b1ce5" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "cardNumber": { "type": "string", "description": "Masked card number.", "example": "411111******1111" }, "cardType": { "type": "string", "description": "Card type/brand.", "example": "VISA" }, "paymentType": { "type": "string", "description": "Payment type.", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "walletType": { "type": "string", "description": "Wallet type.", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "walletData": { "type": "string", "description": "Wallet data payload/details." }, "settlementStatus": { "type": "string", "description": "Settlement status.", "example": "SETTLED" }, "tokenDTO": { "$ref": "#/components/schemas/TokenDTO" }, "chargebackData": { "type": "array", "description": "Chargeback records associated with this transaction.", "items": { "$ref": "#/components/schemas/ResultChargebackDataDTO" } }, "customerIp": { "type": "string", "description": "Customer IP address.", "example": "203.0.113.10" }, "additionalParameters": { "type": "object", "additionalProperties": { "type": "string", "description": "Additional transaction parameters as key-value pairs." }, "description": "Additional transaction parameters as key-value pairs." }, "networkTokenPrefixAndSuffix": { "type": "string", "description": "Network token prefix and suffix representation.", "example": "520000******1234" }, "networkTokenExpiryMonth": { "type": "string", "description": "Network token expiry month (MM).", "example": "08" }, "networkTokenExpiryYear": { "type": "string", "description": "Network token expiry year (YYYY).", "example": "2031" }, "tsysBatchSettlementDTO": { "$ref": "#/components/schemas/TsysBatchSettlementDTO" }, "chargeBackReceived": { "type": "boolean" }, "schemeTransactionLinkIdentifier": { "type": "string", "description": "Mastercard Transaction Link Identifier (TLID). Send it in additionalData when your integration already has the Mastercard TLID; returned when available from the request or processor response.", "example": "mastercard-tlid" } }, "description": "Detailed transaction result data used in search/list responses." }, "ThreeDSInfoProviderResponseDTO": { "type": "object", "properties": { "transID": { "type": "string", "description": "3DS transaction identifier.", "example": "1f3b7cc8-95d8-4b57-a969-2340f0d5c3ef" }, "referenceId": { "type": "string", "description": "Provider reference identifier." }, "errorCode": { "type": "string", "description": "Provider error code when request fails." }, "errorMessage": { "type": "string", "description": "Provider error message when request fails." }, "threeDs2TransactionId": { "type": "string", "description": "3DS2 DS transaction identifier." }, "eci": { "type": "string", "description": "Electronic Commerce Indicator (ECI)." }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value (CAVV)." }, "challengeRequired": { "type": "boolean", "description": "Indicates whether challenge flow is required." }, "jwt": { "type": "string", "description": "Provider JWT/token, if applicable." }, "redirectUrl": { "type": "string", "description": "Netvalve redirect URL to continue 3DS flow." }, "status": { "type": "string", "description": "Current 3DS transaction status.", "enum": [ "INITIALIZED", "INITIALIZATION_FAILED", "AUTHENTICATED", "AUTHENTICATION_FAILED", "DEVICE_DATA_COLLECTED", "ACS_REQUIRED", "ACS_COMPLETED", "ACS_FAILED", "COMPLETED", "RESULT_FAILED" ] }, "threeDsVersion": { "type": "string", "description": "3DS protocol version.", "example": "2.2.0" }, "providerRedirectUrl": { "type": "string", "description": "Provider redirect URL, if required by provider flow." }, "merchantRedirectUrl": { "type": "string", "description": "Merchant redirect URL supplied at initialization." }, "provider": { "type": "string", "description": "3DS provider name.", "example": "MASTERCARD" }, "providerTransactionId": { "type": "string", "description": "Provider-side transaction identifier." }, "netvalveCallBackUrl": { "type": "string", "description": "Netvalve callback URL used by provider flow." }, "authType": { "type": "string", "description": "Provider-specific authentication type." }, "methodPostData": { "type": "string", "description": "Provider method post data for device data collection/challenge." }, "cReq": { "type": "string", "description": "Challenge request payload (CReq) used for challenge flow." } }, "description": "Provider-specific response for /3ds/getThreeDsInfo endpoint." }, "ThreeDSInfoResponseDTO": { "type": "object", "properties": { "traceID": { "type": "string", "description": "Unique trace identifier for request correlation.", "example": "9a37d2f1-6a7c-44a9-9b3d-2cf52f5f2a5e" }, "responseTimestamp": { "type": "string", "description": "Response creation timestamp.", "format": "date-time" }, "responseCode": { "type": "string", "description": "Netvalve response code.", "example": "3DS_1000" }, "responseMessage": { "type": "string", "description": "Human-readable response message.", "example": "3DS request successfully completed" }, "responseCodeType": { "type": "string", "description": "Response code category.", "example": "APPROVED" }, "bankResponseCode": { "type": "string", "description": "Provider or bank response code.", "example": "00" }, "bankResponseMessage": { "type": "string", "description": "Provider or bank response message.", "example": "Success" }, "midId": { "type": "integer", "description": "Internal merchant identifier (MID).", "format": "int64", "example": 101 }, "netvalveMidId": { "type": "string", "description": "External Netvalve MID identifier.", "example": "MID_ABC123" }, "threeDSProviderResponse": { "$ref": "#/components/schemas/ThreeDSInfoProviderResponseDTO" } }, "description": "Response payload for /3ds/getThreeDsInfo endpoint." }, "HppCardDetailsDTO": { "type": "object", "properties": { "cardNumber": { "maxLength": 40, "minLength": 0, "type": "string" }, "cardSecurityCode": { "type": "string" }, "cardHolderName": { "maxLength": 128, "minLength": 0, "type": "string" }, "cardExpireMonth": { "pattern": "^(0[1-9]|1[0-2])$", "type": "string" }, "cardExpireYear": { "maxLength": 4, "minLength": 4, "type": "string" } } }, "HppTransactionInputFieldsDTO": { "required": [ "paymentType" ], "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "CARD", "WALLET", "TOKEN", "APM" ] }, "walletType": { "type": "string", "enum": [ "APPLE_PAY", "GOOGLE_PAY", "SAMSUNG_PAY" ] }, "applePaySSL": { "$ref": "#/components/schemas/ApplePaySSLDTO" }, "googlePaySSL": { "$ref": "#/components/schemas/GooglePaySSLDTO" }, "samsungPaySSL": { "$ref": "#/components/schemas/SamsungPaySSLDTO" }, "tokenizedDTO": { "$ref": "#/components/schemas/TokenizedDTO" }, "cardDetails": { "$ref": "#/components/schemas/HppCardDetailsDTO" }, "customerDetails": { "$ref": "#/components/schemas/HppCustomerDetailsDTO" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "isBillingAndShippingDetailsSame": { "type": "boolean" }, "dfReferenceId": { "type": "string" }, "transID": { "type": "string" }, "orderId": { "type": "integer", "format": "int64" }, "threeDSTransactionType": { "type": "string", "enum": [ "INITIALIZATION_3DS", "AUTHENTICATION_3DS", "RESULT_3DS", "GET_INFO_3DS" ] }, "browserData": { "$ref": "#/components/schemas/HppBrowserInfoDTO" }, "customerZipCode": { "maxLength": 10, "minLength": 0, "type": "string" }, "descriptor": { "pattern": "^.{0,50}$", "type": "string" }, "level2Data": { "$ref": "#/components/schemas/TransactionInputLevel2DTO" }, "level3Data": { "$ref": "#/components/schemas/TransactionInputLevel3DTO" }, "apmType": { "type": "string", "enum": [ "PIX", "PAYPAL", "BITPACE", "PSE", "VENMO", "SPEI", "VOLT", "SEZZLE" ] }, "alternativePaymentMethod": { "$ref": "#/components/schemas/AlternativePaymentMethodDTO" } } }, "HppOrderDetailsDTO": { "type": "object", "properties": { "clientOrderId": { "type": "string" }, "orderDesc": { "type": "string" }, "merchantName": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "netvalveMidId": { "type": "string" }, "timeLimit": { "type": "integer", "format": "int64" }, "expiryDate": { "type": "string", "format": "date-time" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionShortOutputDTO" } }, "additionalParameters": { "type": "object", "additionalProperties": { "type": "string" } }, "siteId": { "type": "string" }, "midId": { "type": "integer", "format": "int64" } } }, "HppOrderOutputFieldsDTO": { "type": "object", "properties": { "traceID": { "type": "string" }, "responseTimestamp": { "type": "string", "format": "date-time" }, "orderId": { "type": "integer", "format": "int64" }, "transactionID": { "type": "integer", "format": "int64" }, "responseCode": { "type": "string" }, "responseMessage": { "type": "string" }, "orderState": { "type": "string", "enum": [ "CREATED", "READY_TO_PAY", "PENDING", "PAID", "DECLINED", "EXPIRED", "AWAIT_3DS" ] }, "csrfToken": { "type": "string" }, "orderDetails": { "$ref": "#/components/schemas/HppOrderDetailsDTO" }, "customerDetails": { "$ref": "#/components/schemas/HppCustomerDetailsDTO" }, "billingDetails": { "$ref": "#/components/schemas/BillingAddressDTO" }, "shippingDetails": { "$ref": "#/components/schemas/ShippingAddressDTO" }, "collectBillingInfo": { "type": "boolean" }, "collectShippingInfo": { "type": "boolean" }, "collectCustomerInfo": { "type": "boolean" }, "collectZipCode": { "type": "boolean" }, "isBillingAndShippingDetailsSame": { "type": "boolean" }, "successUrl": { "type": "string" }, "cancelUrl": { "type": "string" }, "failedUrl": { "type": "string" }, "pendingUrl": { "type": "string" }, "theme": { "type": "integer", "format": "int64" }, "isIFrameSupported": { "type": "boolean" }, "siteId": { "type": "string" }, "paymentPageLayout": { "$ref": "#/components/schemas/PaymentPageLayoutDTO" }, "paymentOption": { "type": "string" }, "alternativePaymentMethod": { "$ref": "#/components/schemas/AlternativePaymentMethodDTO" } } }, "RecurringScheduleCreateDTO": { "type": "object", "required": [ "transactionId" ], "properties": { "transactionId": { "type": "integer", "format": "int64" }, "reason": { "type": "string" }, "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" } } }, "TransactionRecurringScheduleCreateDTO": { "type": "object", "required": [ "transactionId" ], "properties": { "transactionId": { "type": "integer", "format": "int64" }, "reason": { "type": "string" }, "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" } } }, "TransactionRecurringScheduleUpdateDTO": { "type": "object", "required": [ "subscriptionId" ], "properties": { "subscriptionId": { "type": "integer", "format": "int64" }, "reason": { "type": "string" }, "recurringSchedule": { "$ref": "#/components/schemas/RecurringScheduleDTO" } } }, "TransactionRecurringScheduleCancelDTO": { "type": "object", "required": [ "subscriptionId" ], "properties": { "subscriptionId": { "type": "integer", "format": "int64" }, "reason": { "type": "string" } } }, "HealthCareDataDTO": { "type": "object", "description": "Healthcare transaction data for eligible HSA/FSA Visa or Mastercard Auth and Sale payments. The merchant's MID must have the ENABLE_FSA_HSA_HEALTHCARE_DATA payment channel enabled. For non-zero transactions, the healthcare amounts must be non-negative, at least one must be positive, and their sum must equal the transaction amount exactly. isQualifiedIIAS is required when any healthcare amount is positive.", "properties": { "healthCareAccountType": { "type": "string", "description": "Healthcare account type used for the transaction.", "enum": [ "HSA", "FSA" ], "example": "HSA" }, "prescriptionAmount": { "type": "number", "format": "double", "description": "Prescription or Rx amount included in the transaction.", "example": 0 }, "visionAmount": { "type": "number", "format": "double", "description": "Vision care amount included in the transaction.", "example": 0 }, "dentalAmount": { "type": "number", "format": "double", "description": "Dental care amount included in the transaction.", "example": 0 }, "clinicAmount": { "type": "number", "format": "double", "description": "Clinic or medical care amount included in the transaction.", "example": 12 }, "isQualifiedIIAS": { "type": "string", "description": "Indicates whether the transaction is qualified under the Inventory Information Approval System. Required when any healthcare amount is greater than zero.", "enum": [ "YES", "NO", "EXEMPTED" ], "example": "NO" }, "prescriptionNumber": { "type": "string", "maxLength": 64, "description": "Prescription/Rx number associated with the healthcare transaction, when applicable. Redacted in gateway logs.", "example": "00001" } } } }, "securitySchemes": { "netvalve-client-id": { "type": "apiKey", "name": "netvalve-client-id", "in": "header", "description": "Your NetValve Client ID" }, "netvalve-api-key": { "type": "apiKey", "name": "netvalve-api-key", "in": "header", "description": "Your NetValve API Key" } } }, "security": [ { "netvalve-client-id": [], "netvalve-api-key": [] } ], "tags": [ { "name": "Payment Service" }, { "name": "Hosted Payment Page" }, { "name": "Three DS" }, { "name": "Recurring Payment Service" }, { "name": "Wallet" }, { "name": "Hosted Payment Fields" }, { "name": "Reconciliation" } ] }