{ "swagger": "2.0", "info": { "version": "3.1", "title": "Connect REST API" }, "host": "your-host-here.test.connect.paymentsense.cloud", "basePath": "/", "schemes": [ "https" ], "consumes": [ "application/connect.v1+json" ], "produces": [ "application/connect.v1+json" ], "securityDefinitions": { "connectBasicAuth": { "type": "basic" } }, "security": [ { "connectBasicAuth": [] } ], "paths": { "/pac/terminals": { "get": { "description": "Gets a list of all card terminals that are currently connected. This can be filtered by currency, capabilities and status.", "tags": [ "PAC Terminals" ], "operationId": "RetailTerminals", "parameters": [ { "name": "status", "in": "query", "required": false, "type": "string", "description": "Filter the response to only available or only busy terminals.", "enum": [ "AVAILABLE", "BUSY" ] }, { "name": "capabilities", "in": "query", "required": false, "type": "string", "description": "Filter the response to only terminals with particular capabilities. This should be a comma separated list of values." }, { "name": "currency", "in": "query", "required": false, "type": "string", "description": "Filter the response to only terminals in a particular currency.", "enum": [ "GBP", "EUR" ] } ], "responses": { "200": { "description": "Returns a list of terminals", "schema": { "$ref": "#/definitions/terminalWrapper" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pac/terminals/{tpi}": { "get": { "description": "Gets details for a specific terminal.", "tags": [ "PAC Terminals" ], "operationId": "RetailTerminalsByTPI", "parameters": [ { "$ref": "#/parameters/tpiParam" } ], "responses": { "200": { "description": "Returns information about the requested terminal", "schema": { "$ref": "#/definitions/terminal" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Unavailable terminal or no data available for terminal." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pac/terminals/{tpi}/transactions": { "post": { "description": "Starts a transaction on the terminal with the given TPI.", "tags": [ "PAC Transactions" ], "operationId": "TransactionOnTPI", "parameters": [ { "$ref": "#/parameters/tpiParam" }, { "name": "TransactionRequest", "in": "body", "required": true, "schema": { "$ref": "#/definitions/transactionRequest" } } ], "responses": { "201": { "description": "Transaction has successfully started. Returns the transaction requestId and the location of an endpoint for further details.", "schema": { "$ref": "#/definitions/requestLocationResponse" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Unavailable terminal or no data available for terminal." }, "422 ": { "description": "Incorrect JSON received." }, "422": { "description": "The card machine is busy." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pac/terminals/{tpi}/transactions/{requestId}": { "get": { "description": "Gets data for the transaction with the given requestId.", "tags": [ "PAC Transactions" ], "operationId": "GetTransactionWithRequestId", "parameters": [ { "$ref": "#/parameters/tpiParam" }, { "$ref": "#/parameters/requestIdParam" } ], "responses": { "200": { "description": "Transaction details have been successfully returned. \nProperties marked with an * are always returned. Other properties are only returned following a completed transaction (e.g. most recent notification is \"TRANSACTION_FINISHED\"), however their values may be empty.", "schema": { "$ref": "#/definitions/transaction" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404": { "description": "Unavailable terminal or no data available for terminal." }, "404 ": { "description": "The requestId could not be found." }, "500 ": { "description": "An internal Connect error has occurred." } } }, "delete": { "description": "Attempts to cancel the transaction with the given requestId.", "tags": [ "PAC Transactions" ], "operationId": "CancelTransactionWithRequestId", "parameters": [ { "$ref": "#/parameters/tpiParam" }, { "$ref": "#/parameters/requestIdParam" } ], "responses": { "204": { "description": "Transaction associated to the requestId has been cancelled.", "schema": { } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "The requestId could not be found." }, "422 ": { "description": "Transaction could not be cancelled." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pac/terminals/{tpi}/transactions/{requestId}/signature": { "put": { "description": "Attempts to apply signature verification on the transaction with the given requestId. If the signature is declined, the card terminal will attempt to reverse the transaction.", "tags": [ "PAC Transactions" ], "operationId": "VerifySignature", "parameters": [ { "$ref": "#/parameters/tpiParam" }, { "$ref": "#/parameters/requestIdParam" }, { "name": "SignatureRequest", "in": "body", "required": true, "schema": { "$ref": "#/definitions/signatureRequest" } } ], "responses": { "202": { "description": "Signature status has been successfully accepted.", "schema": { "$ref": "#/definitions/verifySignatureResponse" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Unavailable terminal or no data available for terminal." }, "404 ": { "description": "The requestId could not be found." }, "422 ": { "description": "Incorrect JSON received." }, "422 ": { "description": "Unable to action the signature check. When required, signatures must be verified within 80 seconds." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pac/terminals/{tpi}/reports": { "post": { "description": "Starts a report on the terminal with the given TPI.", "tags": [ "PAC Reports" ], "operationId": "RetailReportRequest", "parameters": [ { "$ref": "#/parameters/tpiParam" }, { "name": "reportRequest", "in": "body", "required": true, "schema": { "$ref": "#/definitions/reportRequest" } } ], "responses": { "201": { "description": "Report has successfully started. Returns the report requestId and the location of an endpoint for further details.", "schema": { "$ref": "#/definitions/requestLocationResponse" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "422 ": { "description": "Incorrect JSON received." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pac/terminals/{tpi}/reports/{requestId}": { "get": { "description": "Gets data for the report with the given requestId.", "tags": [ "PAC Reports" ], "operationId": "RetailReportDetails", "parameters": [ { "$ref": "#/parameters/tpiParam" }, { "$ref": "#/parameters/requestIdParam" } ], "responses": { "200": { "description": "Report details have been successfully returned. \nProperties marked with an * are always returned. Other properties are only returned following a completed report (e.g. most recent notification is \"REPORT_FINISHED\"), however their values may be empty.", "schema": { "$ref": "#/definitions/reportResponsePAC" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404": { "description": "Unavailable terminal or no data available for terminal." }, "404 ": { "description": "The requestId could not be found." }, "500": { "description": "An internal Connect error has occurred." } } } }, "/pat/tables": { "get": { "description": "Gets a list of all tables. This can be filtered by locked state, fully paid state and currency.", "tags": [ "PAT Tables" ], "operationId": "Tables", "parameters": [ { "name": "locked", "in": "query", "required": false, "type": "boolean", "description": "Filters the response to show only locked or only unlocked tables" }, { "name": "currency", "in": "query", "required": false, "type": "string", "description": "Filters the response to show only tables with an amount for this currency", "enum": [ "GBP", "EUR" ] } ], "responses": { "200": { "description": "List of tables has been successfully returned.", "schema": { "$ref": "#/definitions/tableListWrapper" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "500 ": { "description": "An internal Connect error has occurred." } } }, "put": { "description": "Creates/Opens a table", "tags": [ "PAT Tables" ], "operationId": "OpenTable", "parameters": [ { "name": "tableCreation", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tableCreation" } } ], "responses": { "201": { "description": "Table has been successfully created.", "schema": { "$ref": "#/definitions/tableCreationResponse" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "409 ": { "description": "Table already exists." }, "422 ": { "description": "Incorrect JSON received." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/tables/{tableName}": { "get": { "description": "Gets details for a specific table", "tags": [ "PAT Tables" ], "operationId": "Table", "parameters": [ { "name": "tableName", "in": "path", "required": true, "type": "string", "description": "Name of the table" }, { "name": "receipt", "in": "query", "required": false, "type": "boolean", "description": "Whether or not the response should contain the receipt stored on this table." } ], "responses": { "200": { "description": "Table details have been successfully returned", "schema": { "$ref": "#/definitions/table" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Table could not be found." }, "500 ": { "description": "An internal Connect error has occurred." } } }, "delete": { "description": "Deletes/Closes a table. This removes the table from Connect and means it is no longer accessible from any endpoints. It is intended for use when a table is fully paid and closed on the EPoS and allows the same tableName to be reused. The lastKnownAmount and lastKnownPaidAmount must be passed in to ensure that deletions only take place when the EPoS has the latest table data. This is to help avoid scenarios where a table has been updated by a card terminal and the update has not yet been picked up by the EPoS.", "tags": [ "PAT Tables" ], "operationId": "DeleteTable", "parameters": [ { "name": "tableName", "in": "path", "required": true, "type": "string" }, { "name": "tableDeletion", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tableDeletion" } } ], "responses": { "204": { "description": "Table has been successfully deleted.", "schema": { } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Table could not be found." }, "422 ": { "description": "Incorrect JSON received." }, "422 ": { "description": "lastKnownAmount does not match the stored amount." }, "422 ": { "description": "lastKnownPaidAmount does not match the stored amount." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/tables/{tableName}/amount": { "put": { "description": "Updates the amount on a table. The lastKnownAmount and lastKnownPaidAmount must be passed in to ensure that updates only take place when the EPoS has the latest table data. This is to help avoid scenarios where a table has been updated by a card terminal and the update has not yet been picked up by the EPoS.", "tags": [ "PAT Tables" ], "operationId": "TableAmount", "parameters": [ { "name": "tableName", "in": "path", "required": true, "type": "string" }, { "name": "tableAmountUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tableAmountUpdate" } } ], "responses": { "204": { "description": "Table amount has been successfully updated.", "schema": { } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Table could not be found." }, "422 ": { "description": "Incorrect JSON received." }, "422 ": { "description": "lastKnownAmount does not match the stored amount." }, "422 ": { "description": "lastKnownPaidAmount does not match the stored amount." }, "423 ": { "description": "Table is currently locked and cannot be updated." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/tables/{tableName}/lock": { "put": { "description": "Updates the lock on a table. The lastKnownAmount and lastKnownPaidAmount must be passed in to ensure that updates only take place when the EPoS has the latest table data. This is to help avoid scenarios where a table has been updated by a card terminal and the update has not yet been picked up by the EPoS.", "tags": [ "PAT Tables" ], "operationId": "TableLock", "parameters": [ { "name": "tableName", "in": "path", "required": true, "type": "string" }, { "name": "tableLockUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tableLockUpdate" } } ], "responses": { "204": { "description": "Table lock has been successfully updated.", "schema": { } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Table could not be found." }, "422 ": { "description": "Incorrect JSON received." }, "422 ": { "description": "lastKnownAmount does not match the stored amount." }, "422 ": { "description": "lastKnownPaidAmount does not match the stored amount." }, "423 ": { "description": "Table is currently locked and cannot be updated." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/tables/{tableName}/receipt": { "put": { "description": "Updates the receipt on a table. The lastKnownAmount and lastKnownPaidAmount must be passed in to ensure that updates only take place when the EPoS has the latest table data. This is to help avoid scenarios where a table has been updated by a card terminal and the update has not yet been picked up by the EPoS.", "tags": [ "PAT Tables" ], "operationId": "TableReceipt", "parameters": [ { "name": "tableName", "in": "path", "required": true, "type": "string" }, { "name": "tableReceiptUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tableReceiptUpdate" } } ], "responses": { "204": { "description": "Table receipt has been successfully updated.", "schema": { } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Table could not be found." }, "422 ": { "description": "Incorrect JSON received." }, "422 ": { "description": "lastKnownAmount does not match the stored amount." }, "422 ": { "description": "lastKnownPaidAmount does not match the stored amount." }, "423 ": { "description": "Table is currently locked and cannot be updated." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/tables/{tableName}/waiterids": { "put": { "description": "Updates the waiter ids on a table. The lastKnownAmount and lastKnownPaidAmount must be passed in to ensure that updates only take place when the EPoS has the latest table data. This is to help avoid scenarios where a table has been updated by a card terminal and the update has not yet been picked up by the EPoS.", "tags": [ "PAT Tables" ], "operationId": "TableWaiterIds", "parameters": [ { "name": "tableName", "in": "path", "required": true, "type": "string" }, { "name": "tableWaiterIdsUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tableWaiterIdsUpdate" } } ], "responses": { "204": { "description": "Table waiter ids have been successfully updated.", "schema": { } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Table could not be found." }, "422 ": { "description": "Incorrect JSON received." }, "422 ": { "description": "lastKnownAmount does not match the stored amount." }, "422 ": { "description": "lastKnownPaidAmount does not match the stored amount." }, "423 ": { "description": "Table is currently locked and cannot be updated." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/reports": { "get": { "description": "Get a list of all reports from the last 3 days", "tags": [ "PAT Reports" ], "operationId": "PATReports", "parameters": [ { "$ref": "#/parameters/tpiParam" } ], "responses": { "200": { "description": "List of reports has been successfully returned.", "schema": { "$ref": "#/definitions/reportListResponse" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "500 ": { "description": "An internal Connect error has occurred." } } } }, "/pat/reports/{reportId}": { "get": { "description": "Gets details for a specific report", "tags": [ "PAT Reports" ], "operationId": "PATReport", "parameters": [ { "name": "reportId", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Report details have been successfully returned.", "schema": { "$ref": "#/definitions/reportResponsePAT" } }, "401": { "description": "Authorization credentials must be provided in the request headers." }, "401 ": { "description": "The provided authorization credentials were not correct." }, "404 ": { "description": "Report could not be found." }, "500 ": { "description": "An internal Connect error has occurred." } } } } }, "parameters": { "tpiParam": { "name": "tpi", "description": "Terminal Public Identifier (unique identifier assigned to a terminal) of the terminal to use in this request.", "in": "path", "required": true, "type": "string" }, "requestIdParam": { "name": "requestId", "description": "Request Id (UUID assigned to a terminal request) of the terminal request to use in this request.", "in": "path", "required": true, "type": "string" } }, "definitions": { "capabilities": { "type": "string", "enum": [ "SALE", "REFUND", "DUPLICATE", "CANCEL_TRANSACTION", "REPORT_END_OF_DAY", "REPORT_BANKING", "REPORT_X_BALANCE", "REPORT_Z_BALANCE", "TERMINAL_STATUS" ] }, "currency": { "description": "Currency of the request. The textual representation from ISO 4217 is used.", "type": "string", "enum": [ "GBP", "EUR" ], "example": "GBP" }, "format": { "type": "string", "enum": [ "BOLD", "DOUBLE_HEIGHT", "DOUBLE_WIDTH" ] }, "issuerTotals": { "type": "object", "description": "A dictionary of totals split by issuer. {issuerName} is an example key.", "properties": { "{issuerName}": { "$ref": "#/definitions/totalsBreakdown" } } }, "messageList": { "type": "array", "items": { "type": "string" } }, "reportResultsPAT": { "type": "string", "enum": [ "COMPLETE" ] }, "notifications": { "type": "string", "enum": [ "APPROVED", "BAD_SWIPE", "CARD_ERROR", "CARD_EXPIRED", "CARD_NOT_SUPPORTED", "CONNECTING", "CONNECTION_MADE", "DECLINED", "DECLINED_BY_CARD", "INSERT_CARD", "PIN_ENTRY", "PLEASE_WAIT", "PRESENT_CARD", "PRESENT_ONLY_ONE_CARD", "PROCESSING_ERROR", "REMOVE_CARD", "RETRYING", "REQUEST_SENT", "RE_PRESENT_CARD", "SIGNATURE_VERIFICATION", "SIGNATURE_VERIFICATION_PROCESS_COMPLETED", "SIGNATURE_VERIFICATION_PROCESS_COULD_NOT_BE_COMPLETED", "SIGNATURE_VERIFICATION_IN_PROGRESS", "SIGNATURE_VERIFICATION_TIMEOUT", "TRANSACTION_FINISHED", "TRANSACTION_STARTED" ] }, "paymentMethod": { "type": "string", "example": "ICC_CHIP", "enum": [ "UNKNOWN", "KEYED", "SWIPED", "ICC_CHIP", "CONTACTLESS" ] }, "receiptLine": { "type": "object", "required": [ "value" ], "properties": { "format": { "description": "Defines any special formatting applied to this line.", "type": "array", "items": { "$ref": "#/definitions/format" }, "example": [ "BOLD" ] }, "type": { "description": "The type of the content contained in the value field.", "type": "string", "enum": [ "TEXT", "BOX_DECLINE", "BOX_VOID", "CARRIAGE_RETURN", "LINE_SEPARATOR_SINGLE", "LINE_SEPARATOR_DOUBLE", "TICKET_FEED" ], "example": "TEXT" }, "value": { "description": "Raw content of the line.", "type": "string", "example": "John's Shop" } } }, "receiptLine ": { "type": "object", "required": [ "value" ], "properties": { "format": { "description": "Defines any special formatting applied to this line.", "type": "array", "items": { "$ref": "#/definitions/format" }, "example": [ "BOLD" ] }, "type": { "type": "string", "enum": [ "TEXT", "IMAGE_LOGO", "CARRIAGE_RETURN", "LINE_SEPARATOR_SINGLE", "LINE_SEPARATOR_DOUBLE", "TICKET_FEED", "BARCODE_CODE25", "BARCODE_CODE39", "BARCODE_CODE128" ] }, "value": { "type": "string" } } }, "receiptLineList": { "type": "array", "items": { "$ref": "#/definitions/receiptLine" } }, "reportBalances": { "description": "Local totals for the current terminal session. Only contained in X_BALANCE, Z_BALANCE and END_OF_DAY.", "type": "object", "required": [ "currency", "issuerTotals", "totalAmount", "totalCashbackAmount", "totalCashbackCount", "totalGratuityAmount", "totalGratuityCount", "totalRefundsAmount", "totalRefundsCount", "totalSalesAmount", "totalSalesCount", "totalsSince", "waiterTotals" ], "properties": { "currency": { "$ref": "#/definitions/currency" }, "issuerTotals": { "$ref": "#/definitions/issuerTotals" }, "totalAmount": { "description": "Total amount that has been taken in the current session.", "type": "integer", "example": "1000" }, "totalCashbackAmount": { "description": "Total amount of cashback (in pence) that has been taken in the current session.", "type": "integer", "example": "100" }, "totalCashbackCount": { "description": "Total number of transactions with cashback that have taken place in the current session.", "type": "integer", "example": "2" }, "totalGratuityAmount": { "description": "Total amount of gratuity (in pence) that has been taken in the current session.", "type": "integer", "example": "100" }, "totalGratuityCount": { "description": "Total number of transactions with gratuity that have taken place in the current session.", "type": "integer", "example": "3" }, "totalRefundsAmount": { "description": "Total amount of refunds (in pence) that have been taken in the current session.", "type": "integer", "example": "400" }, "totalRefundsCount": { "description": "Total number of refunds that have taken place in the current session.", "type": "integer", "example": "9" }, "totalSalesAmount": { "description": "Total amount of sales (in pence) that have been taken in the current session.", "type": "integer", "example": "1200" }, "totalSalesCount": { "description": "Total number of sales that have taken place in the current session.", "type": "integer", "example": "14" }, "totalsSince": { "description": "Time at which the terminal totals were last reset.", "type": "string", "example": "INSTALLATION" }, "waiterTotals": { "$ref": "#/definitions/waiterTotals" } } }, "reportBanking": { "type": "object", "required": [ "currency", "currentSessionIssuerTotals", "previousSessionIssuerTotals", "currentSessionTotals", "previousSessionTotals", "currentSessionTransactionNumbers", "previousSessionTransactionNumbers" ], "properties": { "currency": { "$ref": "#/definitions/currency" }, "currentSessionIssuerTotals": { "$ref": "#/definitions/issuerTotals" }, "previousSessionIssuerTotals": { "$ref": "#/definitions/issuerTotals" }, "currentSessionTotals": { "$ref": "#/definitions/totalsBreakdown" }, "previousSessionTotals": { "$ref": "#/definitions/totalsBreakdown" }, "currentSessionTransactionNumbers": { "description": "Range of transaction numbers within the current terminal session.", "type": "array", "items": { "type": "string" }, "example": [ "0076", "0123" ] }, "previousSessionTransactionNumbers": { "description": "Range of transaction numbers within the previous terminal session.", "type": "array", "items": { "type": "string" }, "example": [ "0000", "0075" ] } } }, "reportList": { "type": "array", "items": { "$ref": "#/definitions/reportResponsePAT" } }, "reportListResponse": { "type": "object", "properties": { "reports": { "$ref": "#/definitions/reportList" } } }, "reportRequest": { "type": "object", "properties": { "reportType": { "$ref": "#/definitions/reportType" } } }, "reportResponsePAC": { "type": "object", "required": [ "requestId", "location", "notifications" ], "properties": { "balances": { "$ref": "#/definitions/reportBalances" }, "banking": { "$ref": "#/definitions/reportsBanking" }, "reportLines": { "$ref": "#/definitions/receiptLineList" }, "reportTime": { "description": "Time at which the report took place.", "type": "string", "format": "YYYY-MM-DDThh:mm:ss", "example": "2019-03-04T16:12:00" }, "reportType": { "description": "Type of the report.", "type": "string", "enum": [ "END_OF_DAY", "BANKING", "X_BALANCE", "Z_BALANCE" ], "example": "END_OF_DAY" }, "reportResult": { "description": "Outcome of the report.", "type": "string", "enum": [ "TIMED_OUT", "COMPLETE" ], "example": "COMPLETE" }, "tpi": { "description": "Terminal Public Identifier (unique identifier assigned to a terminal) of the terminal used in this request.", "type": "string", "example": "12345678" }, "requestId": { "description": "UUID for this request, which can be used in other endpoints.", "type": "string", "example": "d19912ad-11a3-4af3-86e0-d6eb2ebea63c" }, "location": { "description": "URI where information about this report can be found.", "type": "string", "format": "URI", "example": "https://your-host-here.test.connect.paymentsense.cloud/terminals/{tpi}/report/{requestId}" }, "notifications": { "description": "Notifications indicating the progress of the report.", "type": "array", "items": { "type": "string", "enum": [ "REPORT_FINISHED", "REPORT_STARTED" ], "example": [ "REPORT_FINISHED", "REPORT_STARTED" ] } } } }, "reportResponsePAT": { "type": "object", "required": [ "balances", "banking", "reportLines", "reportTime", "reportType", "reportResult", "tpi", "requestId", "location" ], "properties": { "balances": { "$ref": "#/definitions/reportBalances" }, "banking": { "$ref": "#/definitions/reportsBanking" }, "reportLines": { "$ref": "#/definitions/receiptLineList" }, "reportTime": { "type": "string", "format": "date-time" }, "reportType": { "$ref": "#/definitions/reportType" }, "reportResult": { "type": "string", "$ref": "#/definitions/reportResultsPAT" }, "tpi": { "type": "string" }, "reportId": { "type": "string" }, "location": { "type": "string", "description": "The URI where the information about this particular report can be found." } } }, "reportsBanking": { "type": "object", "description": "Banking totals for the current terminal session (these are reset in line with the banking window). Only contained in BANKING and END_OF_DAY. Consists of a dictionary of reports keyed by acquirer name. '{acquirerName}' is an example key", "properties": { "{acquirerName}": { "$ref": "#/definitions/reportBanking" } } }, "reportType": { "description": "Type of the report.", "type": "string", "enum": [ "END_OF_DAY", "BANKING", "X_BALANCE", "Z_BALANCE" ], "example": "END_OF_DAY" }, "requestLocationResponse": { "type": "object", "properties": { "requestId": { "description": "UUID for this request, which can be used in other endpoints.", "type": "string", "example": "d19912ad-11a3-4af3-86e0-d6eb2ebea63c" }, "location": { "description": "URI where information about this request can be found.", "type": "string", "format": "URI", "example": "https://your-host-here.test.connect.paymentsense.cloud/terminals/{tpi}/{requestType}/{requestId}" } } }, "signatureRequest": { "type": "object", "required": [ "accepted" ], "properties": { "accepted": { "description": "Indicates whether the signature has been accepted.", "type": "boolean", "example": true } } }, "table": { "type": "object", "required": [ "tableName", "amount", "amountCashback", "amountGratuity", "amountPaid", "payments", "locked", "lockedBy", "waiterIds" ], "properties": { "tableName": { "type": "string" }, "amount": { "type": "integer" }, "amountCashback": { "type": "integer" }, "amountGratuity": { "type": "integer" }, "amountPaid": { "type": "integer" }, "payments": { "$ref": "#/definitions/tablePaymentList" }, "receipt": { "$ref": "#/definitions/receiptLineList" }, "locked": { "type": "boolean" }, "lockedBy": { "type": "string" }, "waiterIds": { "type": "array", "items": { "type": "string" } } } }, "table ": { "type": "object", "required": [ "tableName", "amount", "amountCashback", "amountGratuity", "amountPaid", "payments", "locked", "lockedBy", "waiterIds" ], "properties": { "tableName": { "type": "string" }, "amount": { "type": "integer" }, "amountCashback": { "type": "integer" }, "amountGratuity": { "type": "integer" }, "amountPaid": { "type": "integer" }, "payments": { "$ref": "#/definitions/tablePaymentList" }, "locked": { "type": "boolean" }, "lockedBy": { "type": "string" }, "waiterIds": { "type": "array", "items": { "type": "string" } } } }, "tableAmountUpdate": { "type": "object", "required": [ "lastKnownAmount", "lastKnownPaidAmount", "newAmount" ], "properties": { "lastKnownAmount": { "type": "integer" }, "lastKnownPaidAmount": { "type": "integer" }, "newAmount": { "type": "integer" } } }, "tableCreation": { "type": "object", "required": [ "tableName", "amount", "currency" ], "properties": { "tableName": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "$ref": "#/definitions/currency" }, "receipt": { "$ref": "#/definitions/receiptLineList" }, "waiterIds": { "type": "array", "items": { "type": "string" } } } }, "tableCreationResponse": { "type": "object", "required": [ "location", "tableName" ], "properties": { "location": { "type": "string", "description": "The URI where the information about this particular table can be found." }, "tableName": { "type": "string" } } }, "tableDeletion": { "type": "object", "required": [ "lastKnownAmount", "lastKnownPaidAmount" ], "properties": { "lastKnownAmount": { "type": "integer" }, "lastKnownPaidAmount": { "type": "integer" } } }, "tableList": { "type": "array", "items": { "$ref": "#/definitions/table " } }, "tableListWrapper": { "type": "object", "properties": { "tables": { "$ref": "#/definitions/tableList" } }, "required": ["tables"] }, "tableLockUpdate": { "type": "object", "required": [ "lastKnownAmount", "lastKnownPaidAmount", "locked" ], "properties": { "lastKnownAmount": { "type": "integer" }, "lastKnownPaidAmount": { "type": "integer" }, "locked": { "type": "boolean" }, "lockedBy": { "type": "string", "description": "Used to denote which EPoS/User has locked a table. This will default to 'EPoS' if not set." }, "override": { "type": "boolean", "description": "Used to override an existing table lock. This should be used with caution when a terminal or EPoS has malfunctioned while holding a lock." } } }, "tablePayment": { "type": "object", "required": [ "amountPaid", "amountCashback", "amountGratuity", "authCode", "currency", "cardSchemeName", "paymentId", "paymentMethod", "time" ], "properties": { "amountPaid": { "type": "integer" }, "amountCashback": { "type": "integer" }, "amountGratuity": { "type": "integer" }, "authCode": { "type": "string" }, "currency": { "type": "string", "$ref": "#/definitions/currency" }, "cardSchemeName": { "type": "string" }, "paymentId": { "type": "string" }, "paymentMethod": { "type": "string", "$ref": "#/definitions/paymentMethod" }, "time": { "type": "string", "format": "date-time" } } }, "tablePaymentList": { "type": "array", "items": { "$ref": "#/definitions/tablePayment" } }, "tableReceiptUpdate": { "type": "object", "required": [ "lastKnownAmount", "lastKnownPaidAmount", "newReceipt" ], "properties": { "lastKnownAmount": { "type": "integer" }, "lastKnownPaidAmount": { "type": "integer" }, "newReceipt": { "$ref": "#/definitions/receiptLineList" } } }, "tableWaiterIdsUpdate": { "type": "object", "required": [ "lastKnownAmount", "lastKnownPaidAmount", "newWaiterIds" ], "properties": { "lastKnownAmount": { "type": "integer" }, "lastKnownPaidAmount": { "type": "integer" }, "newWaiterIds": { "type": "array", "items": { "type": "string" } } } }, "terminal": { "title": "Terminal", "type": "object", "required": [ "tpi", "status", "currency", "capabilities", "location" ], "properties": { "tpi": { "description": "Terminal Public Identifier, a unique identifier assigned to this terminal.", "type": "string", "example": "12345678" }, "status": { "description": "Current status of the terminal, indicating whether it is ready to accept requests.", "type": "string", "enum": [ "AVAILABLE", "BUSY" ], "example": "AVAILABLE" }, "currency": { "description": "Currency in which the terminal is setup. The textual representation from ISO 4217 is used.", "type": "string", "enum": [ "GBP", "EUR" ], "example": "GBP" }, "capabilities": { "description": "Defines the actions that this terminal is capable of performing. This field is due to be deprecated in the next API version (v2).", "type": "array", "items": { "type": "string", "enum": [ "SALE", "REFUND", "DUPLICATE", "CANCEL_TRANSACTION", "REPORT_END_OF_DAY", "REPORT_BANKING", "REPORT_X_BALANCE", "REPORT_Z_BALANCE", "TERMINAL_STATUS" ] }, "example": [ "SALE", "REFUND" ] }, "location": { "description": "URI where information about this terminal can be found.", "type": "string", "format": "URI", "example": "https://your-host-here.test.connect.paymentsense.cloud/terminals/{tpi}" } } }, "terminalList": { "type": "array", "items": { "$ref": "#/definitions/terminal" } }, "terminalWrapper": { "type": "object", "properties": { "terminals": { "$ref": "#/definitions/terminalList" } } }, "totalsBreakdown": { "type": "object", "required": [ "currency", "totalAmount", "totalRefundsAmount", "totalRefundsCount", "totalSalesAmount", "totalSalesCount" ], "properties": { "currency": { "$ref": "#/definitions/currency" }, "totalAmount": { "description": "Total amount that has been taken in the current session.", "type": "integer" }, "totalRefundsAmount": { "description": "Total amount of refunds (in pence) that have been taken in the current session.", "type": "integer" }, "totalRefundsCount": { "description": "Total number of refunds that have taken place in the current session.", "type": "integer" }, "totalSalesAmount": { "description": "Total amount of sales (in pence) that have been taken in the current session.", "type": "integer" }, "totalSalesCount": { "description": "Total number of sales that have taken place in the current session.", "type": "integer" } } }, "transaction": { "type": "object", "properties": { "amountBase": { "description": "Base amount of the transaction (in pence), without cashback or gratuity.", "type": "integer", "format": "int32", "example": "100" }, "amountCashback": { "description": "Amount of cashback (in pence) added to the transaction.", "type": "integer", "format": "int32", "example": "30" }, "amountGratuity": { "description": "Amount of gratuity (in pence) added to the transaction.", "type": "integer", "format": "int32", "example": "20" }, "amountTotal": { "description": "Sum of amountBase, amountCashback and amountGratuity (in pence).", "type": "integer", "format": "int32", "example": "150" }, "applicationId": { "description": "Identifier of the application in the card used in the transaction.", "type": "string", "example": "A0000000031010" }, "applicationLabel": { "description": "Name of the application in the card used in the transaction.", "type": "string", "example": "VISA" }, "authCode": { "description": "Authorisation code provided by the bank to approve the transaction.", "type": "string", "example": "78YT6RS0" }, "cardSchemeName": { "description": "Scheme of the card used in the transaction. The scheme controls the operation of payment transactions.", "type": "string", "example": "VISA" }, "cardHolderVerificationMethod": { "description": "Method used to verify that the person presenting the card is the legitimate cardholder.", "type": "string", "enum": [ "NONE", "PIN", "SIGNATURE", "DEVICE" ], "example": "PIN" }, "currency": { "description": "Currency in which the transaction took place. The textual representation from ISO 4217 is used.", "type": "string", "enum": [ "GBP", "EUR" ], "example": "GBP" }, "dateOfExpiry": { "description": "Expiry date of the card used in the transaction.", "type": "string", "format": "MM/YY", "example": "01/25" }, "dateOfStart": { "description": "Start date of the card used in the transaction.", "type": "string", "format": "MM/YY", "example": "01/19" }, "location": { "description": "URI where information about this transaction can be found.", "type": "string", "format": "URI", "example": "https://your-host-here.test.connect.paymentsense.cloud/terminals/{tpi}/transactions/{requestId}" }, "notifications": { "description": "Notifications indicating the progress of the transaction.", "type": "array", "items": { "$ref": "#/definitions/notifications" }, "example": [ "TRANSACTION_FINISHED", "APPROVED", "CONNECTION_MADE", "CONNECTING", "PIN_ENTRY", "PLEASE_WAIT", "PRESENT_CARD", "TRANSACTION_STARTED" ] }, "paymentMethod": { "description": "Method by which the card details have been read from the payment medium.", "type": "string", "example": "ICC_CHIP", "enum": [ "UNKNOWN", "KEYED", "SWIPED", "ICC_CHIP", "CONTACTLESS" ] }, "primaryAccountNumber": { "description": "PAN (Primary Account Number) of the card used in the transaction. Only the last 4 digits of the number are provided.", "type": "string", "example": "************1234" }, "primaryAccountNumberSequence": { "description": "Sequence number of the PAN of the card used in the transaction. Used to differentiate cards with the same PAN.", "type": "string", "example": "01" }, "receiptLines": { "description": "Card machine receipt(s) for the transaction.", "type": "object", "properties": { "MERCHANT": { "$ref": "#/definitions/receiptLineList" }, "CUSTOMER": { "$ref": "#/definitions/receiptLineList" } } }, "requestId": { "description": "UUID for this request, which can be used in other endpoints.", "type": "string", "example": "d19912ad-11a3-4af3-86e0-d6eb2ebea63c" }, "transactionId": { "description": "Used by the terminal to identify this transaction.", "type": "string", "example": "1234567" }, "transactionNumber": { "description": "Number of the transaction within the current terminal session.", "type": "string", "example": "0012" }, "transactionResult": { "description": "Outcome of the transaction.", "type": "string", "enum": [ "SUCCESSFUL", "DECLINED", "VOID", "UNSUCCESSFUL", "CANCELLED", "TIMED_OUT" ], "example": "SUCCESSFUL" }, "transactionTime": { "description": "Time at which the transaction took place.", "type": "string", "format": "YYYY-MM-DDThh:mm:ss", "example": "2019-03-04T16:12:00" }, "transactionType": { "description": "Type of the transaction.", "type": "string", "enum": [ "LOGON", "REFUND", "REFUND_REVERSAL", "SALE", "SALE_REVERSAL" ], "example": "SALE" } }, "required": ["location", "notifications"] }, "transactionList": { "type": "array", "items": { "$ref": "#/definitions/transaction" } }, "transactionListWrapper": { "type": "object", "properties": { "transactions": { "$ref": "#/definitions/transactionList" } } }, "transactionRequest": { "type": "object", "properties": { "transactionType": { "$ref": "#/definitions/transactionType" }, "amount": { "description": "Base amount of the transaction (in pence).", "type": "integer", "example": 1234 }, "currency": { "$ref": "#/definitions/currency" } } }, "transactionType": { "description": "Type of the transaction.", "type": "string", "enum": [ "SALE", "REFUND", "DUPLICATE" ], "example": "SALE" }, "verifySignature": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string" }, "example": "Signature verification in progress." } } }, "verifySignatureResponse": { "type": "object", "properties": { "messages": { "$ref": "#/definitions/verifySignature" } } }, "waiterTotals": { "type": "object", "description": "A dictionary of totals split by waiter. {waiterId} is an example key.", "properties": { "{waiterId}": { "$ref": "#/definitions/totalsBreakdown" } } } } }