openapi: 3.2.0 info: title: Silverflow Retrieve POS Charges API version: 1.417.0 contact: name: API Support email: support@silverflow.com license: name: Commercial description: 'Operations tagged Retrieve POS Charges across 2 of this provider''s published API definitions: silverflow-openapi.yml, silverflow-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://eu-west-1.api.silverflow.com/v1 description: Production URL for Europe - Equivalent to https://api.silverflow.co/v1 - url: https://us-east-2.api.silverflow.com/v1 description: Production URL for North America - url: https://eu-west-1.api-sbx.silverflow.com/v1 description: Sandbox URL - Equivalent to https://api-sbx.silverflow.co/v1 security: - ApiKey: [] - BearerToken: [] tags: - name: Retrieve POS Charges description: Retrieve charges for given merchant and with additonal filters. paths: /pos/charges: servers: - url: https://devices.eu-west-1.api.silverflow.com/v1 description: Production environment get: operationId: listPosCharges summary: List Charges [EXPERIMENTAL] security: - MutualTLS: [] description: '> **Notice:** This endpoint has different server URLs and authorization method than the rest of the API. Retrieve charge history for a merchant, optionally filtered by terminal. ' parameters: - $ref: '#/components/parameters/parameters-merchantKey' - $ref: '#/components/parameters/terminalId' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/components-parameters-offsetToken' tags: - Retrieve POS Charges responses: '200': description: A list of POS charges content: application/json: schema: $ref: '#/components/schemas/ChargeListResponse' examples: listCharges: $ref: '#/components/examples/components-examples-Response' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/openapi_components-schemas-InvalidInputErrorDetails' '401': $ref: '#/components/responses/openapi_components-responses-UnauthorizedError' '403': $ref: '#/components/responses/components-responses-ForbiddenError' '500': $ref: '#/components/responses/responses-InternalServerError' '503': $ref: '#/components/responses/responses-ServiceUnavailableError' components: responses: components-responses-ForbiddenError: description: The authenticated client is forbidden to make the request for the resource identified. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorDetails' examples: ForbiddenErrorExample: $ref: '#/components/examples/examples-ForbiddenErrorExample' openapi_components-responses-UnauthorizedError: description: Authentication information is missing or invalid headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorDetails' examples: AuthenticationRequired: $ref: '#/components/examples/examples-AuthenticationRequiredExample' responses-InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorDetails' examples: InternalServerErrorExample: $ref: '#/components/examples/components-examples-InternalServerErrorExample' responses-ServiceUnavailableError: description: Service Unavailable - The service is temporarily unavailable. Please retry. content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableErrorDetails' schemas: ChargeListResponse: type: object required: - itemCount - moreItems - charges properties: itemCount: type: integer format: int32 moreItems: type: boolean offsetToken: $ref: '#/components/schemas/components-schemas-offsetToken' charges: type: array items: $ref: '#/components/schemas/ChargeListItem' maxItems: 100 ChargeListItem: type: object required: - chargeKey - merchantKey - terminalId - created - amount - status - cardMaskedNumber - type properties: chargeKey: $ref: '#/components/schemas/chargeKey' merchantKey: $ref: '#/components/schemas/schemas-merchantKey' terminalId: type: string description: Terminal's ID pattern: ^[a-zA-Z0-9]+$ minLength: 1 maxLength: 8 example: AAFF created: type: string description: The date and time this object was created format: iso-8601-date-time amount: $ref: '#/components/schemas/schemas-ResponseAmount' status: type: string description: Status of the charge example: approved enum: - approved - canceled - refunded cardMaskedNumber: type: string description: Masked card number example: 47613499****1234 type: $ref: '#/components/schemas/schemas-ChargeType' transactionReference: $ref: '#/components/schemas/transactionReference' InternalServerErrorDetails: type: object required: - type - title - status - detail - instance properties: type: allOf: - $ref: '#/components/schemas/errorType' - enum: - /silverflow/problems/internal-server-error title: allOf: - $ref: '#/components/schemas/errorTitle' - enum: - Internal Server Error status: allOf: - $ref: '#/components/schemas/errorStatus' - enum: - 500 detail: $ref: '#/components/schemas/errorDetail' instance: $ref: '#/components/schemas/errorInstance' errorTitle: type: string description: 'A short, human-readable summary of the problem type. It does not change from occurrence to occurrence of the error. ' openapi_components-schemas-InvalidInputErrorDetails: type: object required: - type - title - status - detail - instance - validationErrors properties: type: allOf: - $ref: '#/components/schemas/errorType' - enum: - /silverflow/problems/invalid-input title: allOf: - $ref: '#/components/schemas/errorTitle' - enum: - Invalid Input status: allOf: - $ref: '#/components/schemas/errorStatus' - enum: - 400 detail: $ref: '#/components/schemas/errorDetail' instance: $ref: '#/components/schemas/errorInstance' validationErrors: type: array items: $ref: '#/components/schemas/ValidationError' description: A list of validation errors. components-schemas-cardEntry: description: The method used to capture the card details. type: string enum: - terminal example: terminal schemas-ResponseAmountBreakdown: allOf: - $ref: '#/components/schemas/schemas-BaseAmountBreakdown' - type: object properties: cashback: allOf: - description: 'The cashback amount included in the total transaction `value` in minor units. For example `$12.34` should be encoded as `1234`. ' - $ref: '#/components/schemas/openapi_components-schemas-amountValue' gratuity: allOf: - description: 'The gratuity amount included in the total transaction `value` in minor units. For example `$12.34` should be encoded as `1234`. ' - $ref: '#/components/schemas/openapi_components-schemas-amountValue' schemas-merchantKey: description: Uniquely identifies a merchant. type: string pattern: ^mct-[a-zA-Z0-9]+$ minLength: 5 maxLength: 120 example: mct-1234abcdef123 schemas-sequence: description: 'This property indicates that the cardholder has entered Online PIN, when required by the issuer for a Mastercard Single Tap transaction. ' type: string enum: - subsequent errorInstance: type: string description: 'A reference that identifies the specific occurrence of the error. The instance is unique for every error. ' components-schemas-offsetToken: type: string pattern: ^[a-zA-Z0-9%]+$ minLength: 1 maxLength: 2048 example: LUtyr0s918rNZ5WuWDYh5FNzqAli6HqKHpPDatcfdsaVlibrlO49BKcOdz9YccUOtDSoyLtc4kAiOLkmjSW5zLa8OCnOXXBRja2rDYh5FNzqAli6HqKHpPDatcfdsaVlibrlO49BKcOdz9Yc schemas-ChargeType: description: Describes the kind of POS charge the merchant wants to submit. type: object required: - intent - cardEntry - order - terminalEntryMode properties: intent: $ref: '#/components/schemas/components-schemas-intent' cardEntry: $ref: '#/components/schemas/components-schemas-cardEntry' order: $ref: '#/components/schemas/schemas-order' terminalEntryMode: $ref: '#/components/schemas/schemas-terminalEntryMode' sequence: $ref: '#/components/schemas/schemas-sequence' errorStatus: type: integer format: int32 description: 'The HTTP status code generated by the origin server for this occurrence of the problem. ' schemas-BaseAmountBreakdown: type: object required: - baseAmount description: 'A breakdown of the transaction `value`. All provided amounts must exactly add up to `value`. Providing a breakdown is only required if any other amounts besides the `baseAmount` are included. ' properties: baseAmount: allOf: - description: 'The base transaction value in minor units. For example `$12.34` should be encoded as `1234`. ' - $ref: '#/components/schemas/openapi_components-schemas-amountValue' schemas-ResponseAmount: type: object required: - value - currency additionalProperties: false description: 'The amount encoded as an object with a `value` in minor units and a `currency` code. An optional `breakdown` can be provided to indicate specific sub-amounts. ' properties: value: allOf: - description: 'The full transaction amount in minor units. For example `$12.34` should be encoded as `1234`. If a `breakdown` is provided, it must exactly add up to this `value`. ' - $ref: '#/components/schemas/openapi_components-schemas-amountValue' currency: $ref: '#/components/schemas/openapi_components-schemas-currencyCode-2' breakdown: $ref: '#/components/schemas/schemas-ResponseAmountBreakdown' openapi_components-schemas-currencyCode-2: type: string enum: - AED - AFN - ALL - AMD - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SOS - SRD - SSP - STN - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XCG - XOF - XPF - YER - ZAR - ZMW - ZWL description: An alphabetic ISO-4217 currency code. externalDocs: description: Find more info here url: https://www.iso.org/iso-4217-currency-codes.html example: EUR errorDetail: type: string description: 'A human readable explanation specific to this occurrence of the problem. ' UnauthorizedErrorDetails: type: object required: - type - title - status - detail - instance properties: type: allOf: - $ref: '#/components/schemas/errorType' - enum: - /silverflow/problems/authentication-required title: allOf: - $ref: '#/components/schemas/errorTitle' - enum: - Authentication Required status: allOf: - $ref: '#/components/schemas/errorStatus' - enum: - 401 detail: $ref: '#/components/schemas/errorDetail' instance: $ref: '#/components/schemas/errorInstance' ServiceUnavailableErrorDetails: type: object required: - type - title - status - detail - instance properties: type: allOf: - $ref: '#/components/schemas/errorType' - enum: - silverflow/problems/service-unavailable title: allOf: - $ref: '#/components/schemas/errorTitle' - enum: - Service Unavailable status: allOf: - $ref: '#/components/schemas/errorStatus' - enum: - 503 detail: $ref: '#/components/schemas/errorDetail' instance: $ref: '#/components/schemas/errorInstance' ValidationError: type: object required: - path - message properties: path: type: string description: A relative path to the error location within the request body. errorCode: type: string description: A code that identifies the error. message: type: string description: A brief description of the validation error. schemas-terminalEntryMode: description: 'This field indicates the method used for PAN entry on the terminal to initiate the transaction. ' type: string enum: - contactless - manual-entry - chip - magstripe - magstripe-fallback schemas-order: description: The method used to place the order. type: string enum: - counter openapi_components-schemas-amountValue: type: integer format: int64 minimum: 1 maximum: 999999999999 description: 'An amount in minor units. For example `$12.34` should be encoded as `1234`. ' example: 2599 transactionReference: type: string description: 'Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction. ' pattern: ^[a-zA-Z0-9()+,\-.:=@;$_!*\/?|]+$ minLength: 1 maxLength: 120 example: Dz3dIzE74EfH1HeTInyE components-schemas-intent: description: The intention of the cardholder type: string enum: - purchase - reservation - refund errorType: type: string description: 'A relative URI reference, this property can be used to perform automated error handling. ' chargeKey: description: Uniquely identifies a charge. type: string pattern: ^chg-[a-zA-Z0-9]+$ minLength: 5 maxLength: 120 example: chg-1e1dAHhgstYTUhlphPzZ ForbiddenErrorDetails: type: object required: - type - title - status - detail - instance properties: type: allOf: - $ref: '#/components/schemas/errorType' - enum: - /silverflow/problems/forbidden title: allOf: - $ref: '#/components/schemas/errorTitle' - enum: - Forbidden status: allOf: - $ref: '#/components/schemas/errorStatus' - enum: - 403 detail: $ref: '#/components/schemas/errorDetail' instance: $ref: '#/components/schemas/errorInstance' examples: components-examples-InternalServerErrorExample: value: type: /silverflow/problems/internal-server-error title: Internal Server Error status: 500 detail: The server encountered an unexpected condition. instance: /silverflow/b045229d-f66d-4ef7-9f5d-d48064a2aa39 examples-ForbiddenErrorExample: value: type: /silverflow/problems/forbidden title: Forbidden status: 403 detail: 'Authenticated user ''apk-33GjasQdWl4781OsErvi'' is missing the following permission(s): charges:Create.' instance: /silverflow/b0451a9d-f66d-4ef7-9f5d-d48064a2bb3e components-examples-Response: summary: List charges for a merchant value: itemCount: 2 moreItems: false charges: - chargeKey: chg-3pkSK2b2ES9ZTiYM4GWZ merchantKey: mct-1TQ4EL0rI3Uz06VF2a0f terminalId: 17s2d469 created: '2023-09-20T12:46:05.516Z' amount: value: 2050 currency: EUR status: approved cardMaskedNumber: 52869400****0205 type: intent: purchase cardEntry: terminal order: counter terminalEntryMode: contactless - chargeKey: chg-3pkWfhw0Sc3JlIiWiub2 merchantKey: mct-1TQ4EL0rI3Uz06VF2a0f terminalId: 17s2d469 created: '2023-09-20T12:55:18.216Z' amount: value: 9900 currency: EUR status: approved cardMaskedNumber: 52869400****0205 type: intent: purchase cardEntry: terminal order: counter terminalEntryMode: contactless examples-AuthenticationRequiredExample: value: type: /silverflow/problems/authentication-required title: Authentication Required status: 401 detail: Authentication Required instance: /silverflow/8e445b2e-d745-4b38-a38d-781fc998e442 parameters: components-parameters-offsetToken: name: offsetToken description: The offset token. This token is returned in the response of previous request. in: query required: false schema: $ref: '#/components/schemas/components-schemas-offsetToken' parameters-merchantKey: name: merchantKey description: The merchant identifier to filter charges by. in: query required: true schema: $ref: '#/components/schemas/schemas-merchantKey' terminalId: name: terminalId description: The terminal identifier to filter charges by. When provided, only charges for this specific terminal are returned. in: query required: false schema: type: string minLength: 1 maxLength: 8 pattern: ^[a-zA-Z0-9]+$ limit: name: limit description: The number of items to return in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 10 example: 1 securitySchemes: ApiKey: description: "The primary method of authenticating to the Silverflow API is through API keys.\n\nAPI keys can be created by calling the [createApiKey](#operation/createApiKey) endpoint. You can create up to 40 API keys and also update and delete them, allowing for _credential rotation_.\n\nThe _Agent Activation_ process will generate an initial API Key for you. See [Activate Agent](#section/Getting-Started).\n\nA call to the [createApiKey](#operation/createApiKey) endpoint will return the following structure:\n\n```json\n{\n \"key\": \"apk-1wtRxni5IsPsSpBLWpwr\",\n \"status\": \"active\",\n \"agentKey\": \"cgt-1wtRvFLIjDOyyUR5Q2LB\",\n \"description\": \"Data lake API key\",\n \"permissions\": [\n \"charges:List\",\n \"reports:All\"\n ],\n \"created\": \"2021-06-22T11:21:45.115Z\",\n \"secret\": \"FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ\",\n \"version\": 1\n}\n```\n\n> **Important:** The `secret` is only returned once in the response to the `createApiKey` call.\n\nOnce created, the `key` and `secret` fields from the API key must be used in the HTTP `Authorization` header using the `Basic` scheme.\nThe Basic scheme requires a **username** and **password** to be specified, separated by a `:` (colon) and Base64 encoded.\n\nUse the following values from the API key to construct a Basic authentication header:\n\n| Basic field | API key field | Example |\n| ----------- | ------------- | ------- |\n| username | `key` | `apk-1wtRxni5IsPsSpBLWpwr` |\n| password | `secret` | `FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ` |\n\nIn pseudo-code a valid HTTP Basic Authentication header would be constructed as follows:\n\n```ts\nconst apiKeyId = \"apk-1wtRxni5IsPsSpBLWpwr\";\nconst apiKeySecret = \"FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ\";\nconst authnValue = \"Basic \" + base64Encode(apiKeyId + \":\" + apiKeySecret);\nrequest.setHeader(\"Authorization\", authnValue);\n```\n\nUsing the values from the example a valid HTTP request would look like the following:\n\n```http\nGET /v1/agents/current HTTP/1.1\nAccept: application/json\nAuthorization: Basic YXBrLTF3dFJ4bmk1SXNQc1NwQkxXcHdyOkZXdG5PT0hBamJENnJOeFdXRWVWT0NqN0pYU0VQR0pR\n```\n\nMore information on the Basic scheme can be found in [RFC-7617 - The 'Basic' HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617)." type: http scheme: basic BearerToken: description: 'Bearer tokens are temporary security credentials that can be used to authorize ''third parties'' (bearers) access to the Silverflow API on behalf of the agent. These tokens are created by calling the [createAgentBearerToken](#operation/createAgentBearerToken) endpoint. Once created the `token` field must be used in the HTTP `Authorization` header using the `Bearer` scheme. Here''s an example of an HTTP request with a bearer token: ```http GET /v1/merchants/mct-1hPdFhmgaBzMS191nIbJ HTTP/1.1 Accept: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...40EFOgxf_3I6mPZ16bXqHd5tUyApgl0mNOAXPm5AhnA ``` More information on the Bearer scheme can be found in [RFC-6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750).' type: http scheme: bearer bearerFormat: JWT MutualTLS: type: apiKey in: header name: '-' description: 'The client must set up mTLS connection with a valid X.509 client certificate signed by a customer-provided CA (certificate authority) that is registered to a specific agent. The customer-provided CA certificate must be shared and added to Silverflow''s trust store prior to calling endpoints. Certificate validation happens at the transport layer during TLS handshake. Tenant verification is performed by matching the agent key embedded in the client certificate against the agent key embedded in the trusted CA. ' x-refined-from: - silverflow-openapi.yml - silverflow-openapi.yml x-tagGroups: - name: '' tags: - Introduction - Release Notes - name: Accounts tags: - Agents - API Keys - Bins - Merchants - Merchant Acceptors - Enrollments - Screenings - name: Event Notifications tags: - Event Subscriptions - Charges Events - Disputes Events - Fraud Notification Events - Processor Tokens Events - Network Tokens Events - Report Events - Distribution Events - AMMF Submission Events - Reconciliation Events - Clearing Events - name: 3DS Authentication tags: - 3DS Authentication - name: BEP Authentication tags: - BEP Authentication - name: Tokenization tags: - Processor Tokenization - Network Tokenization - name: Charges tags: - Create Charges - Create Recurring - Retrieve Charges - Charge Actions - name: Terminal-To-Cloud tags: - Create POS Charges - Retrieve POS Charges - POS Charge Actions - name: Card Management tags: - Card Management - name: Disputes tags: - Disputes - Documents - name: Fraud Notifications tags: - Fraud Notifications - name: Card Info tags: - Card Info - name: Currency Conversion Rates tags: - Currency Conversion Rates - name: Fees tags: - Fees - name: Reconciliation tags: - Reconciliation Details - Network Funds Transfers - name: Reports tags: - Reconciliation Reports - Settlement Reports - Card Network Reports - Dispute Reports - Fraud Notifications Reports - Charges Reports - Scheme Fee Reports - Retrieve Reports - Report Scheduling - Distributions - name: Transaction Risk Assessment tags: - Transaction Risk Assessment - name: File Subscriptions tags: - File Subscriptions