openapi: 3.0.0
info:
  x-logo:
    url: getfile/przelewy24-logo_mini.png
    altText: LogoP24
  contact:
    name: Przelewy24 Support
    url: https://www.przelewy24.pl/support
  title: Ekspres Przelewy24 REST API Documentation Additional API functionality API
  version: 1.0.6
  description: "\n\n\n# Ekspres Przelewy24\n\nPrzelewy24 provides an authorisation and clearing system and provides payment services as a Domestic Payment Institution. <br><br/>\n<b><b>Ekspres-Przelewy24</b> service allows to quickly and effortlessly send money between accounts from different banks.</b><br/><br/>\nBelow documentation describes the process of information exchange in the course of ordering a transfer via Ekspres Przelewy24 with the use of REST API.<br/><br/>\nIn order to be able to access Ekspres API Przelewy24, first you need to [create an account](https://ekspres.przelewy24.pl/kontakt/index) in Ekspres P24 Administration Panel.\n<br/>\n# Basic notions\nThe following notions will be used for describing the operation of Ekspres Przelewy24:<br/><br/> **WWW system** – access to Ekspres Przelewy24 in the WWW version through the following websites:<ul>\n    <li>[https://ekspres.przelewy24.pl](https://ekspres.przelewy24.pl) – production version,</li>\n    <li>[https://testekspres.przelewy24.pl](https://testekspres.przelewy24.pl) – sandbox version.</li></ul>\n**API** – access to Ekspres Przelewy24 via REST API. <br/> **Partner** – a person / entity owning the system and submitting transfer orders to Ekspres.<br/> **Client** – a person using Ekspres services (payer or recipient of payment from Ekspres).\n\n# Modes and transfer processing\nEkspres Przelewy24 offers 3 modes of transfer processing:<ul> <li><b>Wallet</b> - transfers are processed using the funds previously paid into the wallet,</li> <li><b>P24</b> i <b>P24mobile</b> - transfers are processed only after the client has made the payment in [przelewy24.pl](https://www.przelewy24.pl),</li> Each of these modes allows the client to monitor the progress of the transfer by providing them with a dedicated URL address (available upon transfer registration).\n\n## Transfer processing in Wallet\n<b>Wallet</b> is characterized by quick processing of transfers to the client. Thanks to the funds accrued in the wallet, it is possible to effect immediate processing of a transfer registered by the Partner.<br/><br/>\n\n<img src=\"getfile/eng_wallet.png\" alt=\"Transfer w trybie Wallet\" class=\"center smallImg\">\n\n\n## Transfer processing in P24 and P24mobile\n<b>P24</b> and <b>P24mobile</b> processes payments based on the funds paid in by the Client through [przelewy24.pl](https://www.przelewy24.pl). Using this mode, the partner registers the transfer in API and, subsequently, sends a payment link to the client (alternatively, the payment link may also be sent automatically via email). Once the transaction is paid by the client in [przelewy24.pl](https://www.przelewy24.pl), the transfer registered by the partner is sent for processing.<br/><br/>\n<b>NOTE: P24mobile is analogous to P24 in that it is designed to operate with a mobile library.</b><br/><br/>\n\n<img src=\"getfile/eng_p24_p24mobile.png\" alt=\"Transfer w trybie P24 i P24mobile\" class=\"center smallImg\">\n\n\n# Codes of responses and erros\n## HTTP response codes\nEkspres Przelewy24 REST API uses response codes in HTTP headers to communicate the result of a query, potential problems and errors. <br/><br/> An inventory of possible response codes and their meanings are explained in the appropriate subchapters describing the specific methods.<br/><br/> <b>Always take note of the response code in order to react adequately to potential problems idempotent replies, etc.</b><br/><br/>\n<b>Possible response codes for all methods:</b>\n\n  | Kod   |      Opis      |  Znaczenie |\n  |--------------|:--------------|:------------|\n  | 401  |   Authorization Required   | No access, check the key and the password, check if the key and the password are active and valid for this method. The code is also used to signal temporary failures. |\n  | 403 |  Forbidden  | No access to a given method. The API key and the password are correct. Contact our staff in order to get access.  |\n  | 404 | Not Found | Method not found, check the URL address called. |\n  | 405 | Method Not Allowed | The method used exists, but under a different http call. Check the calls for this method (GET/POST/etc.).|\n  | 415 | Unsupported Media Type | The „Content-Type” value used is not allowed or a required header is missing. Inventory of allowed values available at <a href=\"#section/General-structures-of-queries-and-responses/General-query-format\"><b>General query format</b></a>. |\n  | 500 | Internal Server Error | Server error, if the error recurs, contact our staff and provide the whole query processed, as well as your API key. |\n  | 503 | Service Unavailable | Service temporarily unavailable due to a failure or planned upgrade.   |\n\n\n## Error codes\nError codes appear in the output object of a query that ended with an error and, if it’s possible, indicate its cause. This allows to precisely establish the cause of the error and triggers an automatic reaction / error notification. <br/><br/>\nError codes are divided into the following groups:<ul> <li><b>1xxx</b> – input parameter validation error (the query contains an error),</li> <li><b>2xxx, 3xxx</b> – transfer registration error (the query is correct, but the transfer cannot be processed, e.g. due to insufficient funds),</b> <li><b>9xxx</b> – external services error (API failure caused by unavailability of a related service necessary to process the transfer, e.g. currency exchange),</li> <li><b>10000</b> – internal error (failure of Ekspres Przelewy24 REST API).</li></ul>\n<b>NOTE! When implementing API error service, in order to identify the error, rely solely on the codes, as the “description” parameter may change and constitutes additional information only!</b><br/><br/>\nThe table below presents error codes <b>input parameter validation:</b>\n\n  | Error code   |      Description      |\n  |--------------|:--------------|\n  | 1001  | The value of parameter <b>parameter_name</b> contains illicict characters |\n  | 1002  | Parameter <b>parameter_name</b> value must not be empty |\n  | 1003  | Passwords are not identical |\n  | 1004  | The password must consist of at least 8 characters and contain small and capital letters and digits |\n  | 1005  | Incorrect email address |\n  | 1006  | Incorrect postal code |\n  | 1007  | Incorrect country code |\n  | 1008  | Incorrect amount |\n  | 1009  | The <b>parameter</b> value submitted is not a correct integer |\n  | 1010  | Incorrect currency |\n  | 1011  | Incorrect account number |\n  | 1012  | Incorrect URL address |\n  | 1013  | Transaction type not serviced |\n  | 1014  | Incorrect field value |\n  | 1015  | Current transfer status prevents this operation, or incorrect transfer object |\n  | 1016  | Incorrect date format / incorrect date |\n  | 1017  | Incorrect query signature |\n  | 1018  | Parameter value too long |\n  | 1019  | IBAN number submitted has been blocked |\n\n<br/>The table below presents <b>transfer registration error codes:</b>\n\n  | Error code   |      Description   |\n  |--------------|:--------------|\n  |  2001\t| Bank unavailable |\n  |  2002 |\tInsufficient funds in wallet |\n  |  2003\t| Limit for a single transfer has been exceeded |\n  |  2004\t|\tDaily limit on the amount of transfers paid has been exceeded |\n  |  2005\t| Transfer ID not recognised |\n  |  2006\t| Refund amount provided exceeds the transfer value available |\n  |  2007\t| Access denied |\n  |  2008\t| Incorrect transfer ID |\n  |  2009\t| Transfer limit exceeded |\n  |  2010\t| Transfer already returned in P24 mode |\n  |  3000\t| Incorrect ID query |\n  |  3001\t| Unknown sessionId in P24 mode |\n\n<br/>The table below presents <b>error codes for external services:</b>\n\n  | Error code   |      Description      |\n  |--------------|:--------------|\n  | 9001 |\tTransfer processing error. Contact the customer service department and provide the query ID |\n  | 9002 |\tCurrency exchange error. Please, try again |\n\n<br/>The table below presents the <b>remaining error codes:</b>\n\n  | Error code   |      Description      |\n  |--------------|:--------------|\n  | 10000 |\tInternal error. Please, contact the customer service department and provide the query ID |\n\n\n\n# General structures of queries and responses\n## General query format\n\n  API queries may be processed using any library that allows HTTPS protocol-based communication. Allowed Content-Type values:<ul>\n  <li><b>application/json</b> – queries sent in JSON format,</li>\n  <li><b>application/x-www-form-urlencoded</b> – queries sent as POST (urlencoded).</li></ul>\n\n  <b>Required coding to UTF-8.</b><br/>\n\n  Sample PHP code with the use of cURL\n  ```php\n      <?php\n      $process = curl_init('https://endpoint/ekspres/v1/balance');\n      // Content-Type header required\n      curl_setopt(\n        $process,\n        CURLOPT_HTTPHEADER,\n        array('Content-Type: application/json')\n      );\n      // Basic Auth authentication\n      curl_setopt($process, CURLOPT_USERPWD, 'api-key' . \":\" . 'api-pass');\n      curl_setopt($process, CURLOPT_RETURNTRANSFER, true);\n      $return = json_decode(curl_exec($process));\n      echo json_encode($return, JSON_PRETTY_PRINT) . \"n\";\n      curl_close($process);\n  ```\n\n## General response format\nA correct method call in Ekspres Przelewy24 REST API will generate a response in the form of a JSON object, in the format dependent on the method called.<br/> <p style=\"border:1.5px; border-style:dashed; border-color:#FF0000; padding: 1em;\"> <b>NOTE!</b><br/><br/> All the responses returned by API are <b>UTF-8-coded JSON objects without “slash” sign filters and unicode characters!</b><br/><br/> All the responses are returned using the following method:<br/> json_encode($response, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)<br/><br/> For more information see [PHP documentation](https://www.php.net/manual/en/json.constants.php). </p><br/>\nIn the case of some errors, e.g. internal error 500 or authorisation error 401, the same http code will be returned without additional information in the body. These are the cases when the system does not have any more information on the error or does not want to make it available (for instance, due to lack of authorisation). <br/><br/>\n\n When most errors are generated, GeneralErrorObject is returned (in addition to the relevant http code) with additional details:<br/>\n\n  <b>GeneralErrorObject:</b>\n\n  | Field name   |      Type    |  Description |\n  |--------------|:--------------:|:------------|\n  | code  |     int   | General <a href=\"#section/Codes-of-responses-and-erros/Error-codes\"><b>error code</b></a>  |\n  | description |  string  | Error details   |\n\n  <p style=\"color:darkblue; font-size:17px\"><b>Przykład odpowiedzi z obiektem GeneralErrorObject:</b></p>\n\n    ```html\n        HTTP/1.1 400 Bad Request\n          Content-Type: application/json\n\n          {\n            „error”: {\n              „code”: 1011,\n              „description”: „Given IBAN value ”iban” is not valid”\n            }\n          }\n    ```\n\n\n# Environments\n## Production environment\nEvery request is differentiated by its own unique request URL. This way Ekspres P24 knows which API-function you want to access. Combined with the base URL for either the production- or test-environment, you will get the complete API-URL.\n\nBase URL production system:<br/> https://secure.przelewy24.pl/express/v1\n\n## Test environment\nDuring implementation of the mechanisms in merchant’s system, it is recommended to use test environment. Test environment allows to reproduce system functionalities without making actual payments. <br><br>\nTest environment endpoint:<br> https://sandbox.przelewy24.pl/express/v1 <br><br>\n**<u>The test version does not effect transfers and requires separate login keys.</u>**\n\n# IP server addresses\nWe recommend script protection against suspicious calls using address filtering for incoming connections. IP server ranges for the P24 servers: <br><br> <font class = \"right\"><b>5.252.202.255 , 5.252.202.254</b></font><br> <font class = \"right\"><b>20.215.81.124</b></font><br> <font class = \"right\"><b>193.178.213.0/24</b></font><br> <font class = \"right\"><b>91.220.177.0/24</b></font><br> <font class = \"right\"><b>20.215.183.48/28</b></font><br> <font class = \"right\"><b>134.112.88.8/29</b></font><br>\n\n\n# API Access\nAuthentication is effected with the Basic Auth mechanism, which uses a REST API key (as a login) and the password assigned to it. Generating the API key is possible upon logging on to one’s account in the  <a href=\"#section/Basic-notions\"><b>WWW System</b></a> (left-hand menu, tab “API Users” -> “REST User List”). A single user may possess a few API access keys.\n# Authentication\n<!-- Redoc-Inject: <security-definitions> -->\n"
servers:
- url: https://sandbox.przelewy24.pl
  description: Sandbox server (uses test data)
- url: https://secure.przelewy24.pl
  description: Production server (uses live data)
tags:
- name: Additional API functionality
  x-displayName: Additional API functionality
paths:
  /api/v1/testAccess:
    get:
      tags:
      - Additional API functionality
      summary: Test Access
      description: Test connection. REST uses  <a href="#section/Authentication"><b>"basicAuth"</b></a> authorisation standard, where login and password are, respectively, account ID in P24 and the API key obtained from the “My data” section (“API and configuration data” subsection).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionTestAccess200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputData'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
      security:
      - basicAuth: []
  /api/v1/payment/methods/{lang}?amount=150&subgroup=1&currency=PLN:
    get:
      tags:
      - Additional API functionality
      summary: Payment Methods
      description: Method returns a list of payment methods.
      parameters:
      - name: lang
        in: path
        description: 'A language code. One of these: pl , en'
        required: true
        schema:
          type: string
          enum:
          - pl
          - en
      - in: query
        name: amount
        schema:
          type: integer
        description: Value of the amount.<br>It gives the possibility of clarifying whether a given form of payment is available for a specific amount.
        required: false
      - in: query
        name: currency
        schema:
          type: string
          default: PLN
        description: Currency compatible with ISO, e.g. PLN
        required: false
      - in: query
        name: subgroup
        schema:
          type: integer
          enum:
          - 1
          - 0
        description: Condition if the subgroup value should be visible in the response. Default 0 (NO). Optional 1 (YES).
        required: false
      responses:
        '200':
          description: List of payment methods
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    description: List of methods
                    items:
                      $ref: '#/components/schemas/PaymentMethodsResponseMethod'
                  agreements:
                    type: array
                    description: List of agreements
                  responseCode:
                    type: string
                    default: ''
                type: object
        '403':
          description: Not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Payment methods not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
      security:
      - basicAuth: []
  /api/v1/transaction/refund:
    post:
      tags:
      - Additional API functionality
      summary: Refund transaction
      description: Create refund for one or more transactions.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRefundJsonRequestBody'
        description: Parameter 'refunds' may contain multiple refunds.
        required: true
      responses:
        '201':
          description: Created. Parameter 'data' contains all refunds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRefund201'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputDataRefund'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRefund409'
        '500':
          description: Unknown error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund500Response'
      security:
      - basicAuth: []
  /api/v1/transaction/registerOffline:
    post:
      description: This method allows you to register offline payments. To use the method, you must first register standard payment transaction with <a href="#tag/Transaction-service-API/paths/~1api~1v1~1transaction~1register/post"><b>register transaction</b></a> method.<br><br>Additionally, you can control which bank use for payment by using the method parameter.
      tags:
      - Additional API functionality
      summary: Register offline transaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRegisterOfflineRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TransactionRegisterOfflineRequest'
        description: Input parameters.
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRegistrationOffline200'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputData'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRegistrationOffline409'
        '500':
          description: Undefined error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCodeResponse'
      security:
      - basicAuth: []
  /api/v1/transaction/register/ttl:
    post:
      description: Transaction registration and defining the lifespan of the transaction at the same time. The <b>ttl</b> paramter is required.
      tags:
      - Additional API functionality
      summary: Transaction Registration with ttl
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRegisterTtl'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRegistrationResponse'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputData'
        '401':
          description: not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
      security:
      - basicAuth: []
  /api/v1/transaction/register/splitpayment:
    post:
      description: Split Payments are charged using previously registered token in a process analogous to  <a href="#tag/Transaction-service-API/paths/~1api~1v1~1transaction~1register/post"><b>transaction/register</b></a>. When registering the token, you must add the <b>splitPaymentDetails</b> object characteristic for this form of transaction execution.
      tags:
      - Additional API functionality
      summary: Split Payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranstactionSplitPayment'
        description: Array
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRegistrationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputData'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
      security:
      - basicAuth: []
  /api/v1/refund/by/orderId/{orderId}:
    get:
      tags:
      - Additional API functionality
      summary: Refund by OrderID
      description: Get refund details for given Order Id
      consumes:
      - application/json
      - application/x-www-form-urlencoded
      parameters:
      - name: orderId
        in: path
        description: existing refund Order Id
        required: true
        type: integer
        format: int64
      responses:
        '200':
          description: Request has been processed successful. Parameter 'data' contains refund info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRefundsInfoResponse'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Refund with given Order Id not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionNotFoundResponse'
        '500':
          description: Undefined error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCodeResponse'
      security:
      - basicAuth: []
  /api/v1/transaction/by/sessionId/{sessionId}:
    get:
      tags:
      - Additional API functionality
      summary: Get transaction by sessionID
      description: Method returns transaction information by sessionId
      consumes:
      - application/json
      - application/x-www-form-urlencoded
      parameters:
      - name: sessionId
        in: path
        description: Transaction ID assigned by Merchant
        required: true
        type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionBySessionIdSuccessResponse'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidInputData'
        '401':
          description: Incorrect authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Transaction not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionNotFoundResponse'
      security:
      - basicAuth: []
  /api/v1/payment/methods/{lang}?amount=150&currency=PLN:
    get:
      tags:
      - Additional API functionality
      summary: Payment Methods
      description: Method returns a list of payment methods.
      parameters:
      - name: lang
        in: path
        description: 'A language code. One of these: pl , en'
        required: true
        schema:
          type: string
          enum:
          - pl
          - en
      - in: query
        name: amount
        schema:
          type: integer
        description: Value of the amount.<br>It gives the possibility of clarifying whether a given form of payment is available for a specific amount.
        required: false
      - in: query
        name: currency
        schema:
          type: string
          default: PLN
        description: Currency compatible with ISO, e.g. PLN
        required: false
      responses:
        '200':
          description: List of payment methods
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    description: List of methods
                    items:
                      $ref: '#/components/schemas/PaymentMethodsResponseMethod_2'
                  agreements:
                    type: array
                    description: List of agreements
                  responseCode:
                    type: string
                    default: ''
                type: object
        '403':
          description: Not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Payment methods not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponse'
      security:
      - basicAuth: []
components:
  schemas:
    TransactionRegisterOfflineRequest:
      properties:
        token:
          type: string
    TransactionRefundsInfoResponse:
      properties:
        data:
          $ref: '#/components/schemas/TransactionWithRefundsResponse'
        responseCode:
          type: number
          example: 0
    TranstactionSplitPayment:
      required:
      - merchantId
      - posId
      - sessionId
      - amount
      - currency
      - description
      - email
      - country
      - language
      - urlReturn
      - sign
      - splitPaymentDetails
      - description
      properties:
        merchantId:
          name: merchantId
          in: formData
          description: Merchant identification number
          type: integer
        posId:
          name: posId
          in: formData
          description: Shop identification number (defaults to merchant ID)
          type: integer
        sessionId:
          name: sessionId
          in: formData
          description: Unique identifier from merchant's system
          type: string
          maxLength: 100
        amount:
          name: amount
          in: formData
          description: Transaction amount expressed in lowest currency unit, e.g. 1.23 PLN = 123
          type: integer
        currency:
          name: currency
          in: formData
          description: Currency compatible with ISO, e.g. PLN
          type: string
          maxLength: 3
          default: PLN
        description:
          name: description
          in: formData
          description: Transaction description
          type: string
          maxLength: 1024
        email:
          name: email
          in: formData
          description: Customer's e-mail
          type: string
          maxLength: 50
        client:
          name: client
          in: formData
          description: Customer's first name and surname
          type: string
          maxLength: 40
        address:
          name: address
          in: formData
          description: Customer's address
          type: string
          maxLength: 80
        zip:
          name: zip
          in: formData
          description: Customer's postal code
          type: string
          maxLength: 10
        city:
          name: city
          in: formData
          description: Customer's city
          type: string
          maxLength: 50
        country:
          name: country
          in: formData
          description: Country codes compatible with  ISO, e.g. PL, DE, etc.
          type: string
          maxLength: 2
          default: PL
        phone:
          name: phone
          in: formData
          description: 'Customer''s telephone in the following format:  481321132123'
          type: string
          maxLength: 12
        language:
          name: language
          in: formData
          description: 'One of following language codes according to ISO 639-1: bg, cs, de, en, es, fr, hr, hu, it, nl, pl, pt, se, sk, ro'
          type: string
          default: pl
          maxLength: 2
        method:
          name: method
          in: formData
          description: Payment method ID. List of payment methods provided in the panel or available through API
          type: integer
        urlReturn:
          name: urlReturn
          in: formData
          description: URL address to which customer will be redirected when transaction is complete
          type: string
          maxLength: 250
        urlStatus:
          name: urlStatus
          in: formData
          description: URL address to which transaction status will be send
          type: string
          maxLength: 250
        timeLimit:
          name: timeLimit
          in: formData
          description: Time limit for transaction process, 0 - no limit, max. 99 (in minutes)
          type: integer
        channel:
          name: channel
          in: formData
          description: ' 1 - card + ApplePay + GooglePay, 2 - transfer, 4 - traditional transfer, 8 - N/A, 16 - all 24/7 – makes available all payment methods, 32 - use pre-payment, 64 – only pay-by-link methods, 128 – instalment payment forms, 256 – wallets, 4096 - card, 8192 - blik, 16384 - all methods except blik

            <p>To activate the specific channels, their values should be summed up.

            <p>Example:

            transfer and traditional transfer: channel=6'
          type: integer
          enum:
          - '1'
          - '2'
          - '4'
          - '8'
          - '16'
          - '32'
          - '64'
          - '128'
          - '256'
          - '4096'
          - '8192'
          - '16384'
        shipping:
          name: shipping
          in: formData
          description: Delivery cost
          type: integer
        transferLabel:
          name: transferLabel
          in: formData
          description: Description forwarded to transfer's description (not in every payment methods). A parameter can contain values only ​​in a range [a-z A-Z 0-9 ęółśążźćńĘÓŁŚĄŻŹĆŃ . / :- ]
          type: string
          maxLength: 20
        sdkVersion:
          name: sdkVersion
          in: formData
          description: Version of mobile library. Determines if transaction is mobile.
          type: string
          maxLength: 10
        sign:
          name: sign
          in: formData
          type: string
          maxLength: 100
          description: <br>Checksum of parameters:<br> {<font color = "brown">"sessionId":</font>"string",<font color = "brown">"merchantId":</font>int,<font color = "brown">"amount":</font>int,<font color = "brown">"currency":</font>"string",<font color = "brown">"crc":</font>"string"} <br><br>calculated with the use of sha384<br><br> <b><font color = "#DB2053">IMPORTANT!:</font></b><br>  in case json_encode function is used, the following attributes should be added <br> "JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES"
        encoding:
          name: encoding
          in: formData
          description: 'Coding system for characters sent: ISO-8859-2, UTF-8, Windows-1250'
          type: string
          maxLength: 15
        cart:
          description: cart
          items:
            $ref: '#/components/schemas/CartParameters'
        methodRefId:
          name: methodRefId
          in: formData
          description: Special parameter for some payment flows e.g. BLIK and Card one-click.
          type: string
          maxLength: 250
        splitPaymentDetails:
          type: object
          properties:
            vatAmount:
              type: integer
              description: Kwota podatku VAT
            invoiceNumber:
              type: string
              description: Numer faktury
            nip:
              type: string
              description: Numer identyfikacji podatkowej
            iban:
              type: string
              description: Międzynarodowy numer rachunku bankowego IBAN (international bank account number)
          required:
          - vatAmount
          - invoiceNumber
          - nip
    BasicResponse:
      properties:
        data:
          type: array
          default: Payment methods not found
          items:
            type: string
            default: Payment methods not found
        responseCode:
          default: 404
          type: number
    availabilityHours:
      type: object
      description: An object containing information about the method's availability hours (methods with ID 177, 178 return bool true/false information)
      properties:
        mondayToFriday:
          type: string
        saturday:
          type: string
        sunday:
          type: string
    TransactionRegistrationOffline409:
      properties:
        error:
          type: string
          default: Unable to create offline transaction
          example: Unable to create offline transaction
        code:
          type: number
          example: 409
    RefundRequestArrayDataBasic:
      properties:
        orderId:
          type: integer
          format: int64
          description: Transaction order ID from Przelewy24
        sessionId:
          type: string
          description: Transaction session ID from the Partner’s system
        amount:
          type: integer
          description: Amount of refund
        description:
          type: string
          description: Refund description visible in transfer details
          maxLength: 35
      type: object
      required:
      - orderId
      - sessionId
      - amount
    RefundsCollection:
      properties:
        batchId:
          type: integer
        requestId:
          type: string
        date:
          type: string
        login:
          type: string
        description:
          type: string
        status:
          type: integer
          example: 3
          default: 3
          description: 1 - completed,<br/>2 - pending,<br/>3 - awaiting P24's acceptance,<br/>4 - rejected
        amount:
          type: integer
      type: object
    TransactionRefund201Item:
      properties:
        orderId:
          type: integer
          format: int64
          description: Transaction order ID from Przelewy24
        sessionId:
          type: string
          description: Transaction session ID from the Partner’s system
        amount:
          type: integer
          description: Amount of refund
        description:
          type: string
          description: Transaction description
        status:
          type: boolean
          example: true
          description: Was refund attempt successful?
        message:
          type: string
          example: success
          description: Text description of successful refund
    ErrorCodeResponse:
      properties:
        error:
          type: string
          example: Undefined error
          default: Undefined error
        code:
          type: integer
          example: 500
          default: 500
      type: object
    TransactionRegisterTtl:
      required:
      - merchantId
      - posId
      - sessionId
      - amount
      - currency
      - description
      - email
      - country
      - language
      - urlReturn
      - sign
      - ttl
      properties:
        merchantId:
          description: Merchant identification number
          type: integer
        posId:
          description: Shop identification number (defaults to merchant ID)
          type: integer
        sessionId:
          description: Unique identifier from merchant's system
          type: string
        amount:
          description: Transaction amount expressed in lowest currency unit, e.g. 1.23 PLN = 123
          type: integer
        currency:
          description: Currency compatible with ISO, e.g. PLN
          default: PLN
          type: string
          maxLength: 3
        description:
          description: Transaction description
          type: string
          maxLength: 1024
        email:
          description: Customer's e-mail
          type: string
          maxLength: 50
        client:
          description: Customer's first name and surname
          type: string
          maxLength: 50
        address:
          description: Customer's address
          type: string
          maxLength: 80
        zip:
          description: Customer's postal code
          type: string
          maxLength: 10
        city:
          description: Customer's city
          type: string
          maxLength: 50
        country:
          description: Country codes compatible with ISO, e.g. PL, DE, etc.
          type: string
          default: PL
          maxLength: 2
        phone:
          description: 'Customer''s telephone in the following format : 481321132123'
          type: string
          maxLength: 2
        language:
          description: 'One of following language codes according to ISO 639-1: bg, cs, de, en, es, fr, hr, hu, it, nl, pl, pt, se, sk, ro'
          type: string
          default: pl
        method:
          description: Payment method ID. List of payment methods provided in the panel or available through API
          type: integer
          maxLength: 2
        urlReturn:
          description: URL address to which customer will be redirected when transaction is complete
          type: string
          maxLength: 250
        urlStatus:
          description: URL address to which transaction status will be send
          type: string
          maxLength: 250
        urlNotify:
          description: URL address to which notify message will be send
          type: string
          maxLength: 250
        timeLimit:
          description: Time limit for transaction process 0 - no limit max. 99 (in minutes)
          type: integer
        ttl:
          description: Time limit for transaction token 0 = max 31 days max. 44640 (in minutes)
          type: integer
        channel:
          description: ' 1 - card + ApplePay + GooglePay, 2 - transfer, 4 - traditional transfer, 8 - N/A, 16 - all 24/7 – makes available all payment methods, 32 - use pre-payment, 64 – only pay-by-link methods, 128 – instalment payment forms, 256 – wallets, 4096 - card, 8192 - blik, 16384 - all methods except blik

            <p>To activate the specific channels, their values should be summed up.

            <p>Example: transfer and traditional transfer: channel=6'
          type: integer
          enum:
          - 1
          - 2
          - 4
          - 8
          - 16
          - 32
          - 64
          - 128
          - 256
          - 4096
          - 8192
          - 16384
        shipping:
          description: Delivery cost
          type: integer
        transferLabel:
          description: Description forwarded to transfer's description (not in every payment methods). A parameter can contain values only ​​in a range [a-z A-Z 0-9 ęółśążźćńĘÓŁŚĄŻŹĆŃ . / :- ]
          type: string
          maxLength: 20
        sdkVersion:
          description: Version of mobile library. Determines if transaction is mobile
          type: string
        sign:
          description: <br>Checksum of parameters:<br> {<font color = "brown">"sessionId":</font>"str",<font color = "brown">"merchantId":</font>int,<font color = "brown">"amount":</font>int,<font color = "brown">"currency":</font>"str",<font color = "brown">"crc":</font>"str"} <br><br>calculated with the use of sha384<br><br> <b><font color = "#DB2053">IMPORTANT!:</font></b><br>  in case json_encode function is used, the following attributes should be added <br> "JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES"
          type: string
        encoding:
          description: 'Coding system for characters sent: ISO-8859-2, UTF-8, Windows-1250'
          type: string
        cart:
          description: cart
          type: array
          items: null
          $ref: '#/components/schemas/CartParameters'
        methodRefId:
          description: Special parameter for some payment flows e.g. BLIK and Card one-click.
          type: string
    TransactionBySessionIdSuccessResponse:
      properties:
        data:
          $ref: '#/components/schemas/TransactionBySessionIdResponse'
        responseCode:
          type: number
          default: 0
      type: object
    TransactionWithRefundsResponse:
      properties:
        orderId:
          type: integer
          format: int64
        sessionId:
          type: string
        amount:
          type: integer
        currency:
          type: string
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/RefundsCollection'
      type: object
    InvalidInputData:
      properties:
        error:
          type: string
          default: Invalid input data
          example: Invalid input data
        code:
          type: number
          default: 400
          example: 400
    UnauthorizedResponse:
      properties:
        error:
          type: string
          default: Incorrect authentication
          example: Incorrect authentication
        code:
          type: number
          default: 401
          example: 401
    TransactionBySessionIdResponse:
      properties:
        statement:
          type: string
          description: Transfer title
        orderId:
          type: integer
          format: int64
          description: Transaction ID
        sessionId:
          type: string
          description: Transaction ID assigned by Merchant
        status:
          type: integer
          description: Transaction status. 0 - no payment, 1 - advance payment, 2 - payment made, 3 - payment returned
        amount:
          type: integer
          description: Transaction amount
        currency:
          type: string
          default: PLN
          description: Transaction currency
        date:
          type: string
          description: Transaction registration date
        dateOfTransaction:
          type: string
          description: Date of payment
        clientEmail:
          type: string
          description: Customer's e-mail
        accountMD5:
          type: string
          description: Customer's hashed bank account number
        paymentMethod:
          type: integer
          description: Payment method ID
        description:
          type: string
          description: Transaction description
        clientName:
          type: string
          description: Customer's first name and surname
        clientAddress:
          type: string
          description: Customer's address
        clientCity:
          type: string
          description: Customer's city
        clientPostcode:
          type: string
          description: Customer's zip code
        batchId:
          type: integer
          description: Batch number in which the transaction was paid
        fee:
          type: string
          description: Commission
    TransactionNotFoundResponse:
      properties:
        error:
          type: string
          default: Transaction not found
          example: Transaction not found
        responseCode:
          type: number
          default: 0
          example: 0
    Refund500Response:
      properties:
        error:
          type: string
          example: Unknown error
          description: Error message
        code:
          type: integer
          example: 500
          default: 500
    CartParameters:
      description: Cart Parameters
      type: object
      required:
      - sellerId
      - sellerCategory
      properties:
        sellerId:
          type: string
          description: Shop ID on the part of Partner
        sellerCategory:
          type: string
          description: Shop category
        name:
          type: string
          description: Product name<br/><br/><font color="red">Required for PayPal payment method</font>
        description:
          type: string
          description: Product description<br/><br/><font color="red">Required for PayPal payment method</font>
        quantity:
          type: integer
          description: Product quantity<br/><br/><font color="red">Required for PayPal payment method</font>
        price:
          type: integer
          description: Product price<br/><br/><font color="red">Required for PayPal payment method</font>
        number:
          type: string
          description: Product number<br/><br/><font color="red">Required for PayPal payment method</font>
    TransactionRefund201:
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRefund201Item'
        responseCode:
          type: number
    TransactionRegistrationOffline200:
      properties:
        data:
          properties:
            orderId:
              type: integer
              format: int64
              description: Unique transaction ID assigned by P24
            sessionId:
              type: string
              description: Unique ID assigned by the merchant’s system
            amount:
              type: integer
              description: Transaction amount
            statement:
              type: string
              description: Full payment title
            iban:
              type: string
              description: Number of account for payment
            ibanOwner:
              type: string
              description: Name of payment recipient
            ibanOwnerAddress:
              type: string
              description: Address of payment recipient
          type: object
        responseCode:
          type: number
          example: 0
    TransactionRefundJsonRequestBody:
      properties:
        requestId:
          type: string
          description: Individual request ID
          maxLength: 45
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/RefundRequestArrayDataBasic'
        refundsUuid:
          type: string
          description: Individual ID for a correct refund request in the merchant’s system
          maxLength: 35
        urlStatus:
          type: string
          description: Notification address for the refund batch transferred
      required:
      - requestId
      - refunds
      - refundsUuid
    TransactionRegistrationResponse:
      properties:
        data:
          properties:
            token:
              type: string
          type: object
        responseCode:
          type: number
          default: 0
    PaymentMethodsResponseMethod_2:
      properties:
        name:
          type: string
          description: Name of payment method
        id:
          type: integer
          description: Payment method ID
        group:
          type: string
          description: 'Possible values: FastTransfers, Blik, eTransfer, Credit Card, Installments, Wallet, Foreign, PrePayment, TraditionalTransfer, Another. SplitPayment'
        subgroup:
          type: string
          description: 'Possible values: FastTransfers, Blik, eTransfer, Credit Card, Installments, Wallet, Foreign, PrePayment, TraditionalTransfer, Another. SplitPayment'
        status:
          type: boolean
          example: true
          description: Specifies whether a given method is active
        imgUrl:
          type: string
          description: Link to graphics
        mobileImgUrl:
          type: string
          description: Link to mobile graphics
        mobile:
          type: boolean
          example: true
          description: Is the payment mobile method available?
        availabilityHours:
          $ref: '#/components/schemas/availabilityHours'
    TransactionRefund409:
      properties:
        error:
          type: array
          items:
            $ref: '#/components/schemas/TransactionRefund409Item'
        code:
          type: integer
          example: 409
    TransactionTestAccess200:
      properties:
        data:
          type: boolean
          default: true
        error:
          type: string
    TransactionRefund409Item:
      properties:
        orderId:
          type: integer
          format: int64
          description: Transaction order ID from Przelewy24
        sessionId:
          type: string
          description: Transaction session ID from the Partner’s system
        amount:
          type: integer
          description: Amount of refund
        description:
          type: string
          description: Refund description
        status:
          type: boolean
          example: false
          description: Was refund attempt successful?
        message:
          type: string
          example: The amount of refund exceeds available amount for the transaction
          description: Error message. Possible values:<br/><br/>"Transaction not found" - in case the transaction is not found, <br/><br/>"Transaction in wrong status - cannot refund" - in case the transaction is in wrong status, therefore the refundis not possible, <br/><br/>"Insufficient funds available" - in case there are not enough funds to execute the refund, <br/><br/>"The amount of refund exceeds available amount for the transaction" - in case the amount of the refund request exceeds available amount for the transaction
    InvalidInputDataRefund:
      properties:
        error:
          type: string
          description: Error message. Possbile values:<br/><br/>"Invalid input parameters" - in case incorrect parameters or their values,<br/><br/> "Request already exists" - in case the refund was already created,<br/><br/> "Concurrent call" - in case the  refund is multiplied.
        code:
          type: number
          default: 400
          example: 400
    PaymentMethodsResponseMethod:
      properties:
        name:
          type: string
          description: Name of payment method
        id:
          type: integer
          description: Payment method ID
        group:
          type: string
          description: 'Possible values: FastTransfers, Blik, eTransfer, Credit Card, Installments, Wallet, Foreign, PrePayment, TraditionalTransfer, Another. SplitPayment'
        subgroup:
          type: string
          description: 'Possible values: PBL, Blik, BlikWhiteLabel, eTransfer, Credit Card, Installments, Wallet, Foreign, PrePayment, TraditionalTransfer, Another, SplitPayment, PIS'
        status:
          type: boolean
          example: true
          description: Specifies whether a given method is active
        imgUrl:
          type: string
          description: Link to graphics
        mobileImgUrl:
          type: string
          description: Link to mobile graphics
        mobile:
          type: boolean
          example: true
          description: Is the payment mobile method available?
        availabilityHours:
          $ref: '#/components/schemas/availabilityHours'
  securitySchemes:
    basicAuth:
      description: This is the default authentication method. User login is API REST key the password assigned to it.
      type: http
      scheme: basic
x-tagGroups:
- name: Methods available in API
  tags:
  - Ekspres P24 API
- name: Sign parameter
  tags:
  - Calculation of sign parameter
- name: Transfer
  tags:
  - Notifications on transfer status
  - Table of transfer statuses
  - Transfer scenarios