Przelewy24 Additional services Mass Payments Transactions API

openapi: 3.2.0
info:
  x-logo:
    url: getfile/przelewy24-logo_mini.png
    altText: LogoP24
  contact:
    name: Przelewy24 Support
    url: https://www.przelewy24.pl/support
  title: Przelewy24 REST API Documentation Additional services Mass…
  description: '# Payment system


    Przelewy24 provides an authorisation and clearing system and provides payment services as a Domestic Payment Institution.'
  version: 1.0.0.
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 services Mass Payments Transactions
  x-displayName: Mass Payments Transactions
  description: Mass Payment Identification System is an easy way for a payer to make a payment to an individual bank account created. For a payer wishing to make a traditional transfer, an individual bank account is generated to which he makes the payment.
paths:
  /api/v1.1/transaction/register/simp:
    post:
      tags:
      - Additional services Mass Payments Transactions
      summary: Mass payments transaction register
      description: 'Before sending a transaction request, save its data to the Partner''s local database. In particular, the session ID and transaction amount information should be saved.


        The request takes analogous values to the request transaction/register, except for two additional parameters used when requesting transaction/register/simp czyli simpCountryCode and simpClientId.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRegistrationSIMPBody'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMPTransactionRegistrationResponse'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMPResponse400'
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMPConflict'
        '500':
          description: Undefined error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCodeResponse'
      security:
      - basicAuth: []
      operationId: postApiV11TransactionRegisterSimp
      x-operation-id-source: derived
  /api/v2/transaction/by/sessionId/{sessionId}:
    get:
      tags:
      - Additional services Mass Payments Transactions
      summary: Data about transaction via sessionID
      description: The method returns transaction information based on the sessionId field. For a single sessionId within a SIMP payment, multiple payments can be made on the IBAN, hence the API can return multiple objects.
      parameters:
      - in: path
        name: sessionId
        schema:
          type: string
        required: true
        description: SessionId of the transaction given during transaction registration
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMPGetTransactionBySessionId200'
        '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'
        '500':
          description: Undefined error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCodeResponse'
      security:
      - basicAuth: []
      operationId: getApiV2TransactionBySessionIdBySessionId
      x-operation-id-source: derived
components:
  schemas:
    InvalidInputData:
      properties:
        error:
          type: string
          default: Invalid input data
          example: Invalid input data
        code:
          type: number
          default: 400
          example: 400
    cardData:
      type: object
      description: <b><font color = "#DB2053">IN PREPARATION!</font></b> An object containing card data
      discriminator:
        propertyName: transactionType
        mapping:
          recurring: '#/components/schemas/recurring'
          standard: '#/components/schemas/other2'
          initial: '#/components/schemas/other'
          1click: '#/components/schemas/other2'
      properties:
        means:
          type: object
          properties:
            card:
              type: object
              properties:
                pan:
                  type: string
                  description: Payment card number (PAN - personal account number)
                expYear:
                  type: integer
                  description: The year in which the card expires
                expMonth:
                  type: integer
                  description: The month in which the card expires
                clientName:
                  type: string
                  description: Name and surname of the card holder
                securityCode:
                  type: string
                  description: CVV/CVC code
              required:
              - pan
              - expYear
              - expMonth
              - clientName
            referenceNumber:
              type: object
              properties:
                id:
                  type: string
                  description: Reference number (token assigned by P24)
                securityCode:
                  type: string
                  description: Security code
              required:
              - id
            schemeToken:
              type: object
              properties:
                pan:
                  type: string
                  description: Token number
                expYear:
                  type: integer
                  description: The year in which the card expires
                expMonth:
                  type: integer
                  description: The month in which the card expires
                securityCode:
                  type: string
                  description: Cryptogram
                eci:
                  type: string
                  description: The Electronic Commerce Indicator
                type:
                  type: string
                  description: Typ tokenu
                  enum:
                  - visaToken
                  - mcToken
                  - visaMobile
                  - applepay
                  - googlepay
              required:
              - pan
              - expYear
              - expMonth
              - type
            xPayPayload:
              type: object
              properties:
                payload:
                  type: string
                  description: Base64 encrypted payment payload
                type:
                  type: string
                  description: Payment type
                  enum:
                  - applepay
                  - googlepay
              required:
              - payload
              - type
        transactionType:
          type: string
          description: 'Transaction type:<br> - <b>standard</b> - standard transaction<br> - <b>initial</b> - 1click or recurring initialization transaction. Launched in SCA mode<br> - <b>1click</b> - transaction with a saved card in the presence of the customer<br> - <b>recurring</b> - recurring transaction<br>

            '
      required:
      - means
      - transactionType
    SIMPGetTransactionBySessionId200:
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SIMPTransactionBySessionIdResponse200'
        responseCode:
          type: number
          default: 0
      type: object
    SIMPResponse400:
      properties:
        error:
          type: string
          example: Invalid simpClientId
        code:
          type: number
          example: 400
    TransactionRegistrationSIMPBody:
      type: object
      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
          maxLength: 2
          default: pl
        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
          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
        waitForResult:
          type: boolean
          description: Parameter determines wheter a user should wait for result of the transaction in the transaction service and be redirected back to the shop upon receiving confirmation or be redirected back to the shop immediately after payment. <a href="#section/Use-cases"><b>Read more</b></a>
        regulationAccept:
          type: boolean
          description: 'Acceptance of Przelewy24 regulations: <br/>false – display consent on p24 website (default),<br/>true – consent granted, do not display.<br/>In case the „true” parameter is sent, the consent – worded as follows – must be displayed on the Partner’s website: „I hereby state that I have read the [regulations](https://www.przelewy24.pl/regulamin) and [information obligation](https://www.przelewy24.pl/obowiazekinformacyjny) of ”Przelewy24”. <br/>Under words <i>regulations</i> and <i>information obligation</i> there must be hyperlinks redirecting to websites with these documents. The checkbox must not be ticked by default.'
          default: false
        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
        mobileLib:
          name: mobileLib
          description: The parameter is necessary while using SDK libraries. The value passed in <b>mobileLib</b> parameter is always 1 and value passed in <b>sdkVersion</b> determines which version of library should be used.
          type: integer
          enum:
          - 1
        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>"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"
        encoding:
          name: encoding
          in: formData
          description: 'Coding system for characters sent: ISO-8859-2, UTF-8, Windows-1250'
          type: string
          maxLength: 15
        methodRefId:
          name: methodRefId
          in: formData
          description: Special parameter for some payment flows e.g. BLIK and Card one-click.
          type: string
          maxLength: 250
        cardData:
          type: object
          allOf:
          - $ref: '#/components/schemas/cardData'
        cart:
          description: cart
          items:
            $ref: '#/components/schemas/CartParameters'
        additional:
          type: object
          description: Set of additional information about the transaction or the payer
          allOf:
          - $ref: '#/components/schemas/AdditionalProperties'
        simpCountryCode:
          type: string
          maxLength: 2
          description: Country code according to ISO 3166 to create an IBAN number. Currently, the only one supported is PL.
        simpClientId:
          type: string
          maxLength: 8
          description: Gives the possibility to assign an individual ID to the customer. After completing this parameter, the IBAN number in its last 8 digits, contains the specified ID (e.g. 59 1050 XXXX XXXX 1234 5678 for simpClientId = 12345678).
      required:
      - merchantId
      - posId
      - sessionId
      - amount
      - currency
      - description
      - email
      - country
      - language
      - urlReturn
      - ttl
      - sign
      - simpCountryCode
    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>
    SIMPConflict:
      properties:
        error:
          type: string
          example: Conflict
        code:
          type: number
          example: 409
    AdditionalProperties:
      properties:
        shipping:
          type: object
          description: Additional shipping information
          properties:
            type:
              type: integer
              description: Type of shipment:<br> 0 - courier<br>1 - delivery point<br>2 - parcel locker<br> 3 - package in a shop
              enum:
              - 0
              - 1
              - 2
              - 3
            address:
              type: string
              description: 'Shipment address: street and number'
            zip:
              type: string
              description: Shipment zip code
            city:
              type: string
              description: Shipment city
            country:
              type: string
              description: Shipment country
          required:
          - type
          - address
          - zip
          - city
          - country
        PSU:
          type: object
          description: 'Payment Service User<br> <b><font color = "#DB2053">IMPORTANT!:</font></b><br> Object required when using methods <b><a href="#tag/BLIK-API/paths/~1api~1v1~1paymentMethod~1blik~1chargeByCode/post">blikChargeByCode</a></b> or <b><a href="#tag/BLIK-API/paths/~1api~1v1~1paymentMethod~1blik~1chargeByAlias/post">blikChargeByAlias</a></b>.

            '
          properties:
            IP:
              type: string
              description: IPv4 or IPv6
            userAgent:
              type: string
              maxLength: 255
              description: UserAgent is a string identifying the browser and operating system.
    SIMPTransactionRegistrationResponse:
      properties:
        data:
          properties:
            token:
              type: string
              description: Token
            iban:
              type: string
              description: IBAN
              example: PL59105000996912000444444341
            companyName:
              type: string
              description: Company name
          type: object
        responseCode:
          type: string
          default: '0'
    SIMPTransactionBySessionIdResponse200:
      properties:
        statement:
          type: array
          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
    ErrorCodeResponse:
      properties:
        error:
          type: string
          example: Undefined error
          default: Undefined error
        code:
          type: integer
          example: 500
          default: 500
      type: object
    UnauthorizedResponse:
      properties:
        error:
          type: string
          default: Incorrect authentication
          example: Incorrect authentication
        code:
          type: number
          default: 401
          example: 401
  securitySchemes:
    basicAuth:
      description: This is the default authentication method. User and secretId are available in P24 panel:<br/>- "User" it's the same value as posId,<br/>- secretId it's the samevalue as key for reports (API key).
      type: http
      scheme: basic
x-tagGroups:
- name: Transaction service
  tags:
  - Transaction service API
  - Notification
  - Calculating Sign
- name: Additional services
  tags:
  - Additional API functionality
  - RefundNotification
  - Additional services Additional Notifications
  - Payment Methods Use Cases
  - Additional services Mass Payments Transactions
- name: Card payment
  tags:
  - Card API
  - Card Notification
  - Pre-authorization
- name: BLIK
  tags:
  - BLIK Use Cases
  - BLIK API
  - BLIK Additional
  - Alias Update Notification
- name: Reports
  tags:
  - Report API
- name: Card payment 2.0
  tags:
  - Introduction
  - Google Pay
  - Apple Pay
  - Form initialization
  - Form initialization v2
  - Tokenization
  - Card payment flow
  - Recursion (doPayment)
  - Card API v2
  - Card notification
  - Mobile payment (Android)
  - Mobile payment (iOS)
- name: How to integrate installments?
  tags:
  - Buttons and banners
  - Widget
  - Simulator