openapi: 3.0.0
info:
  title: "API Payment Methods"
  description: ''
  version: '1.0'
servers:
  -
    url: 'https://payments.comgate.cz'
    description: 'Comgate Payment Gateway'
paths:
  /v1.0/create:
    post:
      summary: create
      description: "Access is protected by IP address validation and the integrity of transmitted data is ensured using the HTTPS protocol. The step of creating payments is optional, but it is advisable to implement it in case you require the certainty of secure payment creation. It is possible to skip the implementation of this step if you do not need to identify individual payments in the system, but only require information that someone has paid you a certain amount. This is suitable, for example, when implementing donations or recharging funds to a customer's virtual account, where you are only interested in who recharged what amount, but you do not need to differentiate individual recharges or limit recharges to a minimum amount. However, for a classic e-shop, where you pay for specific goods, it is inappropriate to skip this step. The merchant uses HTTP requests to create payment transaction. Payment attributes including unique payment reference numbers are sent as POST parameters via HTTP protocol. Communication is only between the Merchant’s server and the payment gateway server. It is invisible to payer and the payer cannot change the payment parameters. The payment gateway server responds by sending a unique payment transaction identifier – transaction ID (Comgate system identifier) and URL to which to redirect the payer<br><br>The payment gateway server responds only if the payment is created in a background. All parameters are urlencoded, as in the case of an HTTP request. If the payment is created through redirection (the prepareOnly parameter is 'false'), then the payment gateway server directly redirects the Payer to the appropriate URL or displays an error message.<br><br>**Choice of payment method**<br>Within the shopping process on the e-shop, it's possible to display a selection of payment methods to the payer, and based on their selection, initiate a payment with a specific method. When the payer is presented with the payment gateway, the pre-selected payment method will be automatically displayed. Setting the chosen payment method is possible by filling in the 'method' parameter. Through this parameter, payment methods can also be filtered differently.<br>More here: https://apidoc.comgate.cz/en/metody-platebni-brany<br><br>**Pre-authorization**<br>The payment gateway allows to enter, confirm and cancel pre-authorizations of card payments. The payment is created in the standard way, it is only necessary to specify the parameter preauth = true. After Payer enters data at the payment gateway, the corresponding amount is reserved on his payment card. Depending on the result of this operation, it goes either to the special AUTHORIZED state or, in the case of rejection, to the CANCELLED state. This result is reported in the background according to the usual procedure described above.<br>In order for the money to be actually withdrawn, the e-shop calls the function to confirm the pre-authorization. If the money is to be released (eg it is not possible to meet the conditions of the purchase contract), the e-shop calls the function to cancel the pre-authorization.<br><br><div class='theme-admonition theme-admonition-warning alert alert--warning'><h3 class='cg-alert-title'>ATTENTION</h3><p class='cg-alert-content'>The URL and structure of the payment code may change. Always use the address returned by the API and do not tamper with it. If you want to save the payment code, use the transId parameter. Never parse data from specific positions in the text, they can also change.<br><br><strong>All values containing special characters must be in UTF-8.</strong></p></div>"
      operationId: 87f36741ae33d16a8f205abdbcc834c4
      requestBody:
        description: "Create new payment"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - price
                - curr
                - label
                - refId
                - method
                - email
                - prepareOnly
                - secret
                - phone
                - fullName
              properties:
                merchant:
                  description: "E-shop identifier in the Comgate system - you can find it in the Client Portal in the section e-shop settings - e-shop connection"
                  type: string
                  example: '123456'
                test:
                  description: "A value of 'true' means that the payment will be created as a test, a value of 'false' means a production version. If the parameter is missing, the payment is created as production."
                  type: boolean
                  default: false
                  example: true
                country:
                  description: "Possible values: ALL, AT, BE, CY, CZ, DE, EE, EL, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SI, SK, SE, US. If the parameter is missing, 'CZ' is used automatically. The parameter is used to limit the selection of payment methods at the payment gateway. It is necessary to select the correct combination of 'country' and 'curr' parameters for the given region. For example, to display Czech buttons and pay by card in CZK, choose the combination country = CZ and curr = CZK. For Slovak bank buttons and card payments in EUR, select country = SK and curr = EUR. For Polish bank buttons and card payment in PLN, select country = PL and curr = PLN. For other foreign currencies, you can use the country = ALL parameter or another country code that the payment gateway accepts."
                  type: string
                price:
                  description: "Price for a product in cents or pennies. For currency HUF, you cannot enter the price with decimal places. In this case, the price must always end with 00.<br>Must be in minimum of 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 1 HRK; 0,5 NOK; 0,5 SEK.<br>Maximum 1 000 000 CZK; 40 000 EUR; 170 000 PLN; 12 500 000 HUF; 45 000 USD; 35 000 GBP; 190 000 RON; 400 000 NOK; 390 000 SEK."
                  type: integer
                  format: int32
                  example: 1000
                curr:
                  description: "Currency code according to ISO 4217. Available currencies: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK, SEK."
                  type: string
                  example: CZK
                label:
                  description: "Short description of the product (1-16 characters) - this item enable to filter payments in the Client Portal."
                  type: string
                  example: 'Product 123'
                refId:
                  description: "Parameter suitable for entering a variable symbol or order number on the Client's side (it does not have to be unique, ie it is possible to create more payments with the same refId). In the Client Portal and daily csv. the parameter is marked as Client ID."
                  type: string
                  example: order445566
                method:
                  description: "Payment method from the payment methods table, the value 'ALL' in case the payer should choose the method, or a simple expression with the selection of methods.<br>More here: https://apidoc.comgate.cz/en/metody-platebni-brany"
                  type: string
                  example: ALL
                account:
                  description: "Identifier of the Client's bank account to which Comgate will transfer money. If you do not fill in the parameter, the default Client account will be used. You can find a list of the Client's accounts at https://portal.comgate.cz/."
                  type: string
                email:
                  description: "Payer's contact email. Only one piece of information is required, either an email address or a phone number."
                  type: string
                  example: platce@email.com
                phone:
                  description: "Payer's phone number in international format +420777112233. Only one piece of information is required, either an email address or a phone number."
                  type: string
                fullName:
                  description: "The payer's full name, e.g., Josef Novák."
                  type: string
                  example: 'Jan Novák'
                billingAddrCity:
                  description: "Billing address - city. (e.g., Hradec Králové)."
                  type: string
                billingAddrStreet:
                  description: "Billing address - street. (e.g., Jiráskova 115)."
                  type: string
                billingAddrPostalCode:
                  description: "Billing address - postal code. (e.g., 50304)."
                  type: string
                billingAddrCountry:
                  description: "Billing address - country, in ISO 3166 alpha-2 format (e.g., CZ, SK, US, GB)."
                  type: string
                delivery:
                  description: "Delivery method - one of the available options: HOME_DELIVERY, PICKUP, ELECTRONIC_DELIVERY. The PICKUP option encompasses all pickup locations, pickup boxes, etc."
                  type: string
                  example: HOME_DELIVERY
                homeDeliveryCity:
                  description: "Delivery address - city. Only filled in if delivery=HOME_DELIVERY (e.g., Hradec Králové)."
                  type: string
                homeDeliveryStreet:
                  description: "Delivery address - street. Only filled in if delivery=HOME_DELIVERY (e.g., Štefanikova 421)."
                  type: string
                homeDeliveryPostalCode:
                  description: "Delivery address - postal code. Only filled in if delivery=HOME_DELIVERY (e.g., 50341)."
                  type: string
                homeDeliveryCountry:
                  description: "Delivery address - country, in ISO 3166 alpha-2 format. Only filled in if delivery=HOME_DELIVERY (e.g., CZ, SK, US, GB)."
                  type: string
                category:
                  description: "Product category in the basket - one of the available options that best describes the basket: PHYSICAL_GOODS_ONLY, OTHER. The OTHER option includes gift cards, vouchers, or services."
                  type: string
                  example: PHYSICAL_GOODS_ONLY
                name:
                  description: "Product identifier - this item is located in the client's daily csv under the name Product."
                  type: string
                lang:
                  description: "Language code (ISO 639-1) in which the Payer will be shown instructions for completing the payment, default allowed values ('bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'), if the parameter is missing, 'cs' will be used, in case of request for another language, contact platby-podpora@comgate.cz."
                  type: string
                prepareOnly:
                  description: "In the case of creating payment in the background fill in 'true'. When creating a payment by redirection, fill in either 'false' or do not use the parameter. You can find which payment method is setted up as allowed  in the Client Portal in the Integration section - connection of e-shop."
                  type: boolean
                  default: false
                  example: true
                secret:
                  description: "If you create a background payment, fill in the password for background communication. When creating a payment by redirection, leave the parameter blank or do not use it."
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                preauth:
                  description: "In the case of a request to pre-authorize credit card payments set to 'true'. In the case of a normal payment, fill in 'false' or do not use the parameter. Only for card payments."
                  type: boolean
                initRecurring:
                  description: "Parameter for creating an initial transaction for recurring payments. Only for Clients who have the service enabled."
                  type: boolean
                verification:
                  description: "Verification payment parameter, in case of a request to create a verification payment (value 'true') it is not necessary to send the initRecurring parameter."
                  type: boolean
                expirationTime:
                  description: "If you want to change the expiration date of an individual payment, you can do so by entering this parameter. The allowed value is between 30 minutes and 7 days. The default value is according to the settings in the Client Portal. The value is in the format: ^[1-9][0-9]*(m|h|d)$. For example,: 30m, 3h, 250m, 1d, 5d."
                  type: string
                dynamicExpiration:
                  description: "Enable or disable dynamic expiration. The default state is according to the settings in the Client Portal."
                  type: boolean
                url_paid:
                  description: "Custom settings for single payment. E.g.: 'https://www.example.com/result.php?id=${id}&refId=${refId}'"
                  type: string
                url_cancelled:
                  description: "Custom settings for single payment. E.g.: 'https://www.example.com/result.php?id=${id}&refId=${refId}'"
                  type: string
                url_pending:
                  description: "Custom settings for single payment. E.g.: 'https://www.example.com/result.php?id=${id}&refId=${refId}'"
                  type: string
                chargeUnregulatedCardFees:
                  description: "Using this parameter, you can enable or disable the transfer of fees to the payer when paying with an unregulated card, and at the same time disable the Apple Pay and Google Pay methods (unless overridden by the 'enableApplePayGooglePay' parameter). Allowed values are 'true' or 'false'.<br>Use of this parameter is possible only after approval and activation by Comgate. Not all e-commerce solutions support this parameter.<br><br>More information about surcharge can be found on the <a href='https://help.comgate.cz/docs/en/surcharge' target='_blank'>support page</a>."
                  type: boolean
                enableApplePayGooglePay:
                  description: "Set to 'false' to disable the Apple Pay and Google Pay payment methods for a specific payment, even if these methods are enabled in your account settings.<br>Set to 'true' to enable the Apple Pay and Google Pay payment methods for a specific payment, even if the 'chargeUnregulatedCardFees' parameter is used.<br>If the 'chargeUnregulatedCardFees' parameter is used, then the default value of the 'enableApplePayGooglePay' parameter is 'false'. Otherwise, the default value is 'true'."
                  type: boolean
              type: object
      responses:
        '200':
          description: "Creates a new payment"
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>Method return code and error (value of **message**) description:</strong><br/>0 OK<br/>1100 unknown error<br/>1102 specified language is not supported<br/>1103 method incorrectly specified<br/>1104 unable to load payment<br/>1107 payment price not supported<br/>1200 database error<br/>1301 unknown e-shop<br/>1303 missing link or language<br/>1304 invalid category<br/>1305 product description missing<br/>1306 choose the correct method<br/>1308 chosen payment method is not allowed<br/>1309 wrong amount<br/>1310 unknown currency<br/>1311 Invalid Client's bank account identifier<br/>1316 e-shop does not allow recurring payments<br/>1317 invalid method - does not support recurring payments<br/>1319 payment cannot be set up, problem on the bank's side<br/>1399 unexpected result from database<br/>1400 bad request<br/>1500 unexpected error<br/>", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                  transId: { description: "Unique alphanumeric identifier (code) of the transaction, which will be displayed to the Payer at various stages of payment.", type: string, example: AB12-CD34-EF56 }
                  redirect: { description: "URL of the page where the Payer is to be redirected to make the payment.", type: string, example: 'https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56' }
                type: object
  /v1.0/cancel:
    post:
      summary: cancel
      description: "**Storno of payment**<br>If the order in the e-shop has been cancelled and the transaction is not to be completed by the payer, it is possible to use the storno of payment. Unlike a refund, the payment must be in the pending state.<br>Due to the speed of payment, the payment may already be paid, in which case an error will be displayed and the refund method must be used."
      operationId: 7667d478e251915f2a76980a83977908
      requestBody:
        description: "Cancel payment"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - transId
                - secret
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                transId:
                  description: "unique alphanumeric identifier (code) of the transaction (transactionId)"
                  type: string
                  example: AB12-CD34-EF56
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
              type: object
      responses:
        '200':
          description: "Cancellation status"
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1400 the payment cannot be changed to CANCELLED status (payment not found, payment is not in PENDING status, unauthorized access)", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                type: object
  /v1.0/recurring:
    post:
      summary: recurring
      description: "**Recurring payments, remembering card details**<br>The payment gateway allows you to enter recurring payments, that is, one-click payments. The first (initial) payment takes place through a standard process with redirection to the payment gateway, subsequent payments already take place completely in the background. The system thus allows the payer to pay within a few seconds without having to fill in information about the payment card.<br>This functionality is available on request. In the case of recurring payments at the beginning, we create an initial payment, which is created as a regular payment, only the request contains an additional parameter initRecurring - method create. Subsequent recurring payments are already created using the recurring method and are linked to the Comgate ID of the initiating transaction. This ID must be tied to a specific Payer in the Client's system.<br>After creating a recurring payment, the Payer is not redirected to the payment gateway, because the whole process takes place in the background, the Client is only given the status of the payment, and he then displays this status to the Payer.<br><br>**Subsequent recurring payments**<br>Creating a second and subsequent recurring payment to the payment gateway is only possible in the case of accepting cards for e-shops that have the service enabled.The first (initial) payment is made in the standard way (see Creating a payment). The process of creating a second and each subsequent payment takes place completely in the background, these payments are tied to the initiator via the Comgate ID of the initiation payment. This ID must be in the request in the initRecurringId parameter. The payer is shown the payment status in the e-shop system as a result.<br><br>All parameters are urlencoded, as in the case of an HTTP request to create a standard payment. The answer contains the code parameter, according to which the e-shop determines what result the payer will display. **code = 0** means success, the payment was created and paid, any other code means an error and therefore no payment was created.<br><br>**Recurring payments**<br>Recurring payments with a predefined amount and period (eg monthly, weekly, etc.) can be made using the Recurring Payments service, which is described in the previous paragraphs.<br>Test recurring payments created with the e-mail 'recurring.cancelled@comgate.cz' will have all subsequent payments (apart from the initial one) tagged as CANCELLED (unpaid)"
      operationId: d6dae0a504955877441dbfcea7cffbeb
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - price
                - curr
                - label
                - refId
                - secret
                - initRecurringId
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                test:
                  description: "A value of 'true' means that the payment will be created as a test, a value of 'false' means a production version. If the parameter is missing, the payment is created as production."
                  type: boolean
                  example: true
                price:
                  description: "Price of the product in cents or pennies. Must be min. 10 CZK (incl.), Max. unlimited."
                  type: integer
                  format: int32
                  example: 10000
                curr:
                  description: "Currency code according to ISO 4217, standard 'CZK'."
                  type: string
                  example: CZK
                label:
                  description: "short product description (1-16 characters)"
                  type: string
                refId:
                  description: "Payment reference in the e-shop system (it does not have to be unique, i.e. it is possible to create multiple payments with the same refId)."
                  type: string
                  example: '2010102600'
                account:
                  description: "The identifier of the e-shop bank account to which Comgate will transfer the money. If you do not complete the parameter, the default e-shop account will be used. You can find a list of e-shop accounts at https://portal.comgate.cz/."
                  type: string
                name:
                  description: "Product identifier - this item allows you to navigate to the payment statistics of the Comgate payment system."
                  type: string
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                initRecurringId:
                  description: "Comgate ID of the initial payment"
                  type: string
                  example: AB12-CD34-EF56
              type: object
      responses:
        '200':
          description: Status
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1100 unknown error<br>1102 specified language is not supported<br>1103 method incorrectly specified<br>1104 unable to load payment<br>1200 database error<br>1301 unknown e-shop<br>1303 missing link or language<br>1304 invalid category<br>1305 product description missing<br>1308 selected payment method is not allowed<br>1309 incorrect amount<br>1310 unknown currency<br>1311 invalid e-shop bank account identifier<br>1316 e-shop does not allow recurring payments<br>1317 invalid method - does not support recurring payments<br>1318 initial payment not found<br>1319 can not create a payment, problem with the bank<br>1320 invalid email for recurring<br>1399 unexpected result from database<br>1400 wrong query<br>1500 unexpected error", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                  transId: { description: "a unique alphanumeric transaction identifier (code) that will be displayed to the payer at various stages of payment", type: string }
                type: object
  /v1.0/refund:
    post:
      summary: refund
      description: "**Payment refund**<br>The refund method is intended for payments already created and paid. Payment status must be paid. It is possible to make both a partial (refunded amount is lower than the payment amount) and a full refund (the refund amount is equal to the payment amount). The amount will be transferred back to the payer's account.<br>If the payment has not been completed and is in a pending state, it is possible to use the payment storno method."
      operationId: 4197a39ef55bac2448864b62c3023b1d
      requestBody:
        description: "Payment refund"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - transId
                - secret
                - amount
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                transId:
                  description: "unique alphanumeric transaction identifier (code) (transactionId)"
                  type: string
                  example: AB12-CD34-EF56
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                amount:
                  description: "refund amount - can be the full or partial amount of the transaction. The refund amount is entered in cents or pennies. For the currency HUF, it is not possible to enter an amount with decimal places. In this case, the amount must always end with 00."
                  type: integer
                  format: int32
                  example: 10000
                test:
                  description: "A value of 'true' means that the refund will be created as a test. Refunds and payments will be verified in the standard manner, only the original payment will not be refunded. If 'false' is completed or the parameter is empty, an official refund is created. Test transactions can only be refunded by a test refund."
                  type: boolean
                  example: true
                refId:
                  description: "parameter suitable for entering the refund identification number on the customer's side (it does not have to be unique, i.e. it is possible to create multiple refunds with the same refId); in the Client Portal under refund section and the daily csv for the refund, the parameter is marked as the Client ID. If this parameter is not attached to the refund, the original refId of the created payment will be displayed for the payment."
                  type: string
              type: object
      responses:
        '200':
          description: Status
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1100 unknown error<br>1200 database error<br>1400 wrong query<br>1401 refunded payment is in CANCELLED status<br>1402 refund amount higher than allowed<br>1500 unexpected error", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                type: object
  /v1.0/refundPos:
    post:
      summary: refundPos
      description: "**Terminal payment refund**<br>The refund method is intended for terminal payments already created and paid. Payment status must be paid. It is possible to make both a partial (refunded amount is lower than the payment amount) and a full refund (the refund amount is equal to the payment amount). The amount will be transferred back to the payer's account.<br>If the payment has not been completed and is in a pending state, it is possible to use the payment storno method.The server API may not have a payment record immediately available. Therefore, it is advisable to first call for a refund from the cash desk at the terminal. And the API call can be used if the refund cannot be called from the cash register on the terminal.<br/>To use this method, it is necessary to first set the allowed IP addresses for the given terminal in the section Store settings - Terminals in the Client Portal, from which refunds will be made."
      operationId: 65170de9091a03dad0fb408a647b27c7
      requestBody:
        description: "Terminal payment refund"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - vs
                - amount
                - date
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system - can be found in the Client Portal in the Shop Settings - Terminals section"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                vs:
                  description: "variable payment symbol"
                  type: string
                  example: '7654321'
                amount:
                  description: "refund amount - can be the full or partial amount of the transaction"
                  type: integer
                  format: int32
                  example: 10000
                date:
                  description: "date of execution of the transaction"
                  type: string
                  example: '2000-02-22'
              type: object
      responses:
        '200':
          description: Status
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1100 unknown error<br>1200 database error<br>1400 wrong query<br>1401 refunded payment is in CANCELLED status<br>1402 refund amount higher than allowed<br>1500 unexpected error", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                type: object
  /v1.0/capturePreauth:
    post:
      summary: capturePreauth
      description: "If the e-shop has created a payment with a request to pre-authorize the card payment (using the parameter preauth = true), calling this function will request the debiting of the money that was blocked through pre-authorization. It is possible to perform both the partial debiting of the transaction (the pre-authorized amount is lower than the payment amount) and full debiting (the debited amount is equal to the payment amount). Calls can only be used for payments for which AUTHORIZED status has been reported."
      operationId: d91e7c3202b7c5b6128177e5611c0c8b
      requestBody:
        description: "Confirmation of pre-authorization"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - transId
                - secret
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                transId:
                  description: "unique alphanumeric identifier (code) of the transaction (transactionId)"
                  type: string
                  example: AB12-CD34-EF56
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                amount:
                  description: "the amount of pre-authorization to be debitd from the card - it can be in the full or partial amount of the transaction"
                  type: integer
                  format: int32
                  example: 10000
              type: object
      responses:
        '200':
          description: "Pre-auth status"
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1100 unknown error<br>1104 unable to load payment<br>1200 database error<br>1301 unknown e-shop<br>1303 missing link or language<br>1399 unexpected result from database<br>1400 wrong query<br>1500 unexpected error", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                type: object
  /v1.0/cancelPreauth:
    post:
      summary: cancelPreauth
      description: "If the e-shop has created a payment with a request to pre-authorize the card payment (using the parameter preauth = true), by calling this function the e-shop indicates that it does not want to collect the money that was blocked during pre-authorization and the money can be released to the card again. Calls can only be used for payments for which AUTHORIZED status has been reported."
      operationId: 5fad261dae920bba7880aade214deedb
      requestBody:
        description: "Cancelling pre-authorization"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - transId
                - secret
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                transId:
                  description: "unique alphanumeric identifier (code) of the transaction (transactionId)"
                  type: string
                  example: AB12-CD34-EF56
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
              type: object
      responses:
        '200':
          description: "Pre-auth cancellation status"
          content:
            application/x-www-form-urlencoded:
              schema:
                required:
                  - code
                  - message
                properties:
                  code: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1100 unknow error<br>1104 unable to load payment<br>1200 database error<br>1301 unknown e-shop<br>1303 missing link or language<br>1399 unexpected result from database<br>1400 wrong query<br>1500 unexpected error", type: integer, example: 0 }
                  message: { description: '', type: string, example: OK }
                type: object
  /v1.0/transferList:
    post:
      summary: transferList
      description: "The transferList method is used to obtain information about which transfers were made within a given day."
      operationId: c791f638208a6eef84b677ee5369a1ca
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - date
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                date:
                  description: "indicate the transfer date"
                  type: string
                  example: '2023-03-22'
                test:
                  description: "if the value is 'true', the method returns predefined sample transfer"
                  type: boolean
                  default: false
                  example: false
              type: object
      responses:
        '200':
          description: "Successful operation"
          content:
            application/json:
              schema:
                type: array
                items:
                  properties: { transferId: { type: integer, example: 1234567 }, transferDate: { type: string, format: date, example: '2023-01-25' }, accountCounterparty: { type: string, example: 0/0000 }, accountOutgoing: { type: string, example: 123456789/0000 }, variableSymbol: { type: string, example: '12345678' } }
                  type: object
  /v1.0/singleTransfer:
    post:
      summary: singleTransfer
      description: "The singleTransfer method displays detailed information for a specific bank transfer.<br>The mandatory transferId parameter merchant  obtained by using ttransferList method."
      operationId: b473184f974917ad27377798abad1634
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - transferId
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                transferId:
                  description: "mandatory parameter obtained using the transferList method"
                  type: string
                  example: '1234567'
                test:
                  description: "suitable for testing - returns details to predefined sample transfers"
                  type: boolean
                  default: false
                  example: false
              type: object
      responses:
        '200':
          description: "Successful operation"
          content:
            application/json:
              schema:
                type: array
                items:
                  properties: { typ: { type: integer, example: 1 }, Merchant: { type: string, example: '123456' }, 'Datum založení': { type: string, example: '2023-01-06 14:11:30' }, 'Datum zaplacení': { type: string, example: '2023-01-06 14:21:30' }, 'Datum převodu': { type: string, example: '2023-01-10' }, 'Měsíc fakturace': { type: string, example: null }, 'ID Comgate': { type: string, example: AAAA-BBBB-CCCC }, Metoda: { type: string, example: 'Card payment' }, Produkt: { type: string, example: null }, Popis: { type: string, example: 'description eshop payment' }, 'E-mail plátce': { type: string, example: name.lastname@email.cz }, 'Variabilní symbol platby': { type: string, example: '123456789' }, 'Variabilní symbol převodu': { type: string, example: '123456789' }, 'ID od klienta': { type: string, example: '1234' }, Měna: { type: string, example: EUR }, 'Potvrzená částka': { type: string, example: '10,00' }, 'Převedená částka': { type: string, example: '10,00' }, 'Poplatek celkem': { type: string, example: '0,35' }, 'Poplatek mezibankovní': { type: string, example: '0,25' }, 'Poplatek asociace': { type: string, example: '0,25' }, 'Poplatek zpracovatel': { type: string, example: '-0,15' }, 'Typ karty': { type: string, example: EU_UNREGULATED } }
                  type: object
  /v1.0/csvSingleTransfer:
    post:
      summary: csvSingleTransfer
      description: "Thanks to the csvSingleTransfer method, you can download the daily statement in CSV format for a specific bank transfer."
      operationId: d295851769bb8f5e0c4e21fdcf7dd896
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - transferId
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                transferId:
                  description: "details for a specific bank transfer"
                  type: string
                  example: '5217530'
                download:
                  description: "If not filled in or false, it returns data: file name and its contents; if true, it returns the CSV file directly."
                  type: boolean
                  example: false
                test:
                  description: "returns a sample CSV file for testing purposes"
                  type: boolean
                  default: false
                  example: false
              type: object
      responses:
        '200':
          description: "Successful operation"
          content:
            application/json:
              schema:
                properties:
                  nazev: { description: "File name for the downloaded CSV file", type: string, example: vypis-YYYY-MM-DD.csv }
                  csv: { description: "Base64-encoded CSV file", type: string, example: 'base64 encoded csv' }
                type: object
  /v1.0/aboSingleTransfer:
    post:
      summary: aboSingleTransfer
      description: "Thanks to the aboSingleTransfer method, you can download a daily statement in ABO format."
      operationId: d36a9b048e379b37846200d16e8eb501
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - transferId
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                transferId:
                  description: "details for a specific bank transfer"
                  type: string
                  example: transfer_id
                download:
                  description: "If not filled in or false, it returns data: file name and its contents; if true, it returns the ABO file directly."
                  type: boolean
                  example: true
                type:
                  description: "the 'type' parameter can take the values 'v1' and 'v2'. Under 'v1' you get the ABO version with the fees listed separately for each payment, under 'v2' you get the ABO with the total fee in one line. If the parameter is not filled in, you will automatically receive the type 'v1'."
                  type: string
                  example: v1
                encoding:
                  description: "The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to utf8."
                  type: string
                  default: utf8
                  example: false
                test:
                  description: "Returns a sample ABO file for testing purposes."
                  type: boolean
                  default: false
                  example: false
              type: object
      responses:
        '200':
          description: "Successful operation"
          content:
            application/json:
              schema:
                properties:
                  nazev: { description: "file name", type: string, example: vypis-YYYY-MM-DD.gpc }
                  abo: { description: "base64 encoded abo/gpc file", type: string, example: base64_encoded_abo_file }
                type: object
  /v1.0/csvDownload:
    post:
      summary: csvDownload
      description: "Direct download of CSV files for a specific day using the csvDowload method. The downloaded ZIP file will contain one or more CSV files if there are multiple transactions within a day. It can be used, for example, for calls using wget."
      operationId: e10e8699fce1a4e2b02f3393e8b229ec
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - date
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                date:
                  description: "mandatory for one day only"
                  type: string
                  example: YYYY-MM-DD
                test:
                  description: "For testing purposes, it returns a sample CSV file in ZIP format."
                  type: boolean
                  default: false
                  example: false
              type: object
      responses:
        '200':
          description: "Successful operation"
          content:
            application/zip:
              schema:
                type: string
                format: binary
                example: 'ZIP file containing a CSV of all transfers made on the date specified in the request'
  /v1.0/aboDownload:
    post:
      summary: aboDownload
      description: "Direct download of ABO files for a specific day using the aboDowload method. The downloaded ZIP file will contain one or more ABO files.It can be used, for example, for calls using wget."
      operationId: ddc69daa06e5d32f13ad35c759e1e1a1
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
                - date
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                date:
                  description: "mandatory for one day only"
                  type: string
                  example: YYYY-MM-DD
                type:
                  description: "the 'type' parameter can take the values 'v1' and 'v2'. Under 'v1' you get the ABO version with the fees listed separately for each payment, under 'v2' you get the ABO with the total fee in one line. If the parameter is not filled in, you will automatically receive the type 'v1'."
                  type: string
                encoding:
                  description: "The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to utf8."
                  type: string
                test:
                  description: "For testing purposes, it returns a sample CSV file in ZIP format."
                  type: boolean
                  default: false
                  example: false
              type: object
      responses:
        '200':
          description: "Successful operation"
          content:
            application/zip:
              schema:
                type: string
                format: binary
                example: 'ZIP file contaning ABO for all transfers made on the date specified in the request'
  /v1.0/methods:
    post:
      summary: methods
      description: "**Obtaining allowed methods**<br>Method for obtaining the settings that the e-shop has enabled in the Comgate Payment System. This method can be used to obtain a list of available payment methods for making payments.<br>The response contains XML or JSON, depending on the selected parameter. Both formats have the same level of immersion."
      operationId: 5a06496cc036a6e4b545635883ad1111
      requestBody:
        description: "Get payment methods"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - secret
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
                type:
                  description: "Format of returned data ('xml' or 'json'). If not filled in, 'xml' will be used."
                  type: string
                  example: json
                lang:
                  description: "Select the language in which the method descriptions will be. Allowed values are 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'. If not filled in, 'cs' will be used."
                  type: string
                curr:
                  description: "Filling in the parameter to the values CZK or EUR will return methods that support the specified currency (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK)."
                  type: string
                country:
                  description: "Country code ('AT', 'BE', 'CY', 'CZ', 'DE', 'EE', 'EL', 'ES', 'FI', 'FR', 'GB', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'NO', 'PL', 'PT', 'RO', 'SL', 'SK', 'SE', 'US'), the parameter is used to limit the selection of payment methods for the specified country."
                  type: string
                price:
                  description: "Price for a product in cents or pennies. For currency HUF, you cannot enter the price with decimal places. In this case, the price must always end with 00.<br>Must be in minimum of 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 1 HRK; 0,5 NOK; 0,5 SEK.<br>Maximum 1 000 000 CZK; 40 000 EUR; 170 000 PLN; 12 500 000 HUF; 45 000 USD; 35 000 GBP; 190 000 RON; 400 000 NOK; 390 000 SEK."
                  type: integer
                  format: int32
                initRecurring:
                  description: "Parameter for an initial transaction for recurring payments. Only for Clients who have the service enabled."
                  type: boolean
                  default: false
                verification:
                  description: "Parameter for creating an initial transaction for recurring payments. Only for Clients who have the service enabled."
                  type: boolean
                  default: false
                preauth:
                  description: "In the case of a request to pre-authorize credit card payments set to ‘true’. In the case of a normal payment, fill in ‘false’ or do not use the parameter. Only for card payments."
                  type: boolean
                  default: false
                expirationTime:
                  description: "Length of payment expiration. The allowed value is an integer followed by the letter of the selected time unit: 'm' (minutes), 'h' (hours) or 'd' (days). For example '30m' (30 minutes) or '10h' (10 hours) or '2d' (2 days). Units cannot be combined. The resulting length must be between 30 minutes and 7 days."
                  type: string
                embedded:
                  description: "The 'embedded' parameter is used to filter methods in case the gateway will be displayed in an iframe. Payment methods that cannot be displayed on the payment gateway in the iframe will be filtered out. If you are displaying the payment gateway in an iframe, use 'embedded=true'."
                  type: boolean
                userAgent:
                  description: "The 'userAgent' parameter is used to identify the customer's web browser. Filters out payment methods incompatible with the given device."
                  type: string
                chargeUnregulatedCardFees:
                  description: "Using this parameter, you can enable or disable the transfer of fees to the payer when paying with an unregulated card, and at the same time disable the Apple Pay and Google Pay methods (unless overridden by the 'enableApplePayGooglePay' parameter). Allowed values are 'true' or 'false'.<br>Use of this parameter is possible only after approval and activation by Comgate. Not all e-commerce solutions support this parameter.<br><br>More information about surcharge can be found on the <a href='https://help.comgate.cz/docs/en/surcharge' target='_blank'>support page</a>."
                  type: boolean
                enableApplePayGooglePay:
                  description: "Set to 'false' to disable the Apple Pay and Google Pay payment methods for a specific payment, even if these methods are enabled in your account settings.<br>Set to 'true' to enable the Apple Pay and Google Pay payment methods for a specific payment, even if the 'chargeUnregulatedCardFees' parameter is used.<br>If the 'chargeUnregulatedCardFees' parameter is used, then the default value of the 'enableApplePayGooglePay' parameter is 'false'. Otherwise, the default value is 'true'."
                  type: boolean
              type: object
      responses:
        '200':
          description: "HTTP 200, List of payment methods"
          content:
            application/json:
              schema:
                description: "structure of the returned JSON"
                required:
                  - methods
                properties:
                  methods: { description: "Available methods", type: array, items: { properties: { id: { description: "ID of the method", type: string }, group: { description: "Group of the method", type: string }, groupLabel: { description: "Label of the method group", type: string }, name: { description: "Name of the method", type: string }, name_short: { description: "The short name of the method", type: string }, description: { description: "Description of the method", type: string }, logo: { description: "Logo of the method", type: string }, logo_240: { description: "240px logo of the method", type: string }, cblogo: { description: "Centered bigger logo of the method", type: string }, clogo: { description: "Centered logo of the method", type: string }, sblogo: { description: "Squared bigger logo of the method", type: string }, slogo: { description: "Squared logo of the method", type: string } }, type: object } }
                type: object
        '400':
          description: "HTTP 200, Error occured"
          content:
            application/json:
              schema:
                description: "returns HTTP 200 (OK)!!<br>structure of the returned JSON"
                required:
                  - error
                properties:
                  error: { description: "Error", type: array, items: { properties: { code: { description: '', type: string, example: '1400' }, message: { description: "method return code and error description:<br>0 OK<br>1100 unknown error<br>1200 database error<br>1400 wrong query<br>1500 unexpected error", type: string, example: 'Unauthorized access!' }, extraMessage: { description: "specification of the error message", type: string, example: '' } }, type: object } }
                type: object
  /v1.0/status:
    post:
      summary: status
      description: "**Getting payment status in the background**<br>Analogous function for transmitting the result of payment in the background, only initiated by the Store. However, it does not replace the transfer of the status of the payment in the background, its implementation is still mandatory."
      operationId: 62d0375da5c483677e37da545c688caa
      requestBody:
        description: "Get payment status"
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - merchant
                - transId
                - secret
              properties:
                merchant:
                  description: "e-shop identifier in the Comgate system"
                  type: string
                  example: '123456'
                transId:
                  description: "unique alphanumeric identifier (code) of the transaction (transactionId)"
                  type: string
                  example: AB12-CD34-EF56
                secret:
                  description: "password for background communication"
                  type: string
                  example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
              type: object
      responses:
        '200':
          description: "Obtained payment status"
          content:
            application/x-www-form-urlencoded:
              schema:
                description: "Payment status"
                required:
                  - code
                  - message
                  - merchant
                  - test
                  - price
                  - curr
                  - label
                  - refId
                  - email
                  - transId
                  - secret
                  - status
                properties:
                  code: { description: "Method return code", type: integer, example: 0 }
                  message: { description: "<strong>method return code and error description:</strong><br>0 OK<br>1100 unknown error<br>1200 database error<br>1400 wrong query<br>1500 unexpected error<br><br>in the case of code = 0, the following parameters are in the response", type: string, example: OK }
                  merchant: { description: "e-shop identifier in the Comgate system", type: string, example: '123456' }
                  test: { description: "A value of 'true' means that the payment was created as a test, a value of 'false' means a production version.", type: string, example: false }
                  price: { description: "price of the product in cents or pennies", type: integer, example: 10000 }
                  curr: { description: "currency code according to ISO 4217", type: string, example: CZK }
                  label: { description: "short product description (1-16 characters)", type: string, example: 'Beatles - Help' }
                  refId: { description: "payment references in the e-shop system", type: string, example: '2010102600' }
                  payerId: { description: "payer identifier in the e-shop system", type: string }
                  method: { description: "payment method used, from the table of payment methods", type: string, example: ALL }
                  account: { description: "identifier of the e-shop bank account to which Comgate will transfer the money", type: string }
                  email: { description: "payer's contact e-mail", type: string, example: platce@email.com }
                  name: { description: "product identifier - this item allows you to navigate to the payment statistics of the Comgate payment system", type: string }
                  phone: { description: "Payer's phone number, if available", type: string }
                  transId: { description: "unique alphanumeric transaction identifier (code) (transactionId)", type: string, example: AB12-CD34-EF56 }
                  secret: { description: "password for background communication", type: string, example: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y }
                  status: { description: "current transaction status, values<br>'PENDING' - the payment is created, the final result is not known<br>'PAID' - payment was successfully paid<br>'CANCELLED' - the payment was not completed correctly and is cancelled<br>'AUTHORIZED' - the requested pre-authorization was successful", type: string, example: PAID }
                  payerName: { description: "transmission of the name of the account belonging to the payer", type: string }
                  payerAcc: { description: "transmission of the payer's account number", type: string }
                  fee: { description: "if the e-shop has set up automatic deduction of the payment fee, the transaction fee will be calculated in this field in cents or pennies, otherwise the field will take the value 'unknown'", type: string }
                  vs: { description: "variable payment symbol (may not always be available)", type: string }
                  cardValid: { description: "expiration of the payer's card available for repeated initiation payments except Apple Pay and Google Pay", type: string }
                  cardNumber: { description: "partial payer card number available for recurring initiation payments", type: string }
                  appliedFee: { description: "The surcharge amount applied for unregulated card types.", type: integer }
                  appliedFeeType: { description: "The type of surcharge applied for unregulated card types, such as 'EU_UNREGULATED', 'NON_EU_BUSINESS', 'NON_EU_CONSUMER', or non-surcharge 'EU_CONSUMER'.", type: string }
                  paymentErrorReason: { description: "Reason for payment rejection, if available. In case of multiple attempts by the payer to make a payment, the reason for rejection of the last attempt is returned. Possible values: <br> 'CUSTOMER_CLICK' - Canceled by payer <br> 'FRAUD_SUSPECTED' - Fraud suspected <br> 'ESHOP_CANCELLED' - Canceled by merchant <br> 'PROVIDER_REPORT' - Canceled by provider <br> 'PROVIDER_TIMEOUT' - Provider timeout <br> 'CUSTOMER_TIMEOUT' - Customer timeout <br> 'ACS_TIMEOUT' - The verification time limit has expired <br> 'INVALID_CARDNO_EXPIRY' - Incorrect card number or expiration date <br> 'INVALID_CVC' - Incorrect CVC / CVV code <br> 'LIMIT_EXCEEDED' - Card limit exceeded <br> 'NO_FUNDS' - Insufficient balance in the account <br> 'REJECTED_BY_BANK' - The payment was rejected by the bank <br> '3DS_AUTH_FAIL' - Payment authentication was unsuccessful <br> 'BANK_TIMEOUT' - The payment timeout has expired <br> 'BANK_FORBIDDEN' - The payer did not grant access to their accounts <br> 'TRANSACTION_CANCELLED' - The payer canceled the payment verification  <br> '3RDPART_APP_LIMIT_EXCEEDED' - Third-party transaction limit exceeded <br> 'UNAVAILABLE' - Payment method is temporarily unavailable <br> 'BAD_ACCOUNT_TYPE' - The payer's account type does not support this payment <br> 'NOT_SPECIFIED' - Not specified", type: string }
                type: object
