Przelewy24 Marketplace Management 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: Marketplace Przelewy24 REST API Documentation Marketplace…
  description: '# Marketplace Przelewy24


    Przelewy24 provides an authorisation and clearing system and provides payment services as a Domestic Payment Institution.'
  version: 1.0.1
servers:
- url: https://secure.przelewy24.pl/
  description: Production server (uses live data)
- url: https://sandbox.przelewy24.pl/
  description: Sandbox server
tags:
- name: Marketplace Management API
paths:
  /api/v1/multiStore/dispatchTransaction:
    post:
      tags:
      - Marketplace Management API
      summary: Dispatch Transaction
      description: The method allows to transfer the funds to specific submerchant's account.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchTransactionBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchTransactionResponse200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchTransactionResponse400'
        '401':
          description: Unathorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationRequired'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403ForbiddenGeneralError'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500UndefinedGeneralError'
      security:
      - basicAuth: []
      operationId: postApiV1MultiStoreDispatchTransaction
      x-operation-id-source: derived
  /api/v1/multiStore/dispatchInfo/{orderId}:
    get:
      tags:
      - Marketplace Management API
      summary: Dispatch Information
      description: The method reutrn information about a dispatched transaction for the given orderId.
      parameters:
      - name: orderId
        in: path
        description: Identifier of transaction
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchInfoResponse200'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchInfoResponse404'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationRequired'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500UndefinedGeneralError'
      security:
      - basicAuth: []
      operationId: getApiV1MultiStoreDispatchInfoByOrderId
      x-operation-id-source: derived
  /api/v1/multiStore/funds?merchantId={merchantId}:
    get:
      tags:
      - Marketplace Management API
      summary: Merchant's Balance
      description: The method returns information about the current stafe of given merchant's balance.
      parameters:
      - name: merchantId
        in: path
        description: Merchant's ID.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundsResponse200'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundsResponse400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundsResponse403'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationRequired'
      security:
      - basicAuth: []
      operationId: getApiV1MultiStoreFunds?merchantId={merchantId}
      x-operation-id-source: derived
  /api/v1/multiStore/affiliates?affiliateId={merchantId}:
    get:
      tags:
      - Marketplace Management API
      summary: Registered Submerchants
      description: The method allows to download information about registered submerchants in a given marketplace. If you send an optional parameter afiiliatedId, the method returns information about this specific merchant. If you don't send an afiliatedId, the method returns a full list of registered submerchants and their basic data.
      parameters:
      - name: affiliateId
        in: path
        description: Merchant's ID.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatesResponse200'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatesResponse400'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatesResponse404'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationRequired'
      security:
      - basicAuth: []
      operationId: getApiV1MultiStoreAffiliates?affiliateId={merchantId}
      x-operation-id-source: derived
  /api/v1/multiStore/refund:
    post:
      tags:
      - Marketplace Management API
      summary: Refund Dispatch Transaction
      description: To refund a dispatched transaction use an extended refund method. The additional parameters are merchantId and merchantAmount.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRefundBody'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse201'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationRequired'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundRsponse409'
      security:
      - basicAuth: []
      operationId: postApiV1MultiStoreRefund
      x-operation-id-source: derived
components:
  schemas:
    DataAffArrayObject:
      properties:
        id:
          type: integer
          description: Merchant's id
        name:
          type: string
          description: Merchant's name
          example: Sample Merchant Oddział Poznań
        nip:
          type: string
          description: Merchant's NIP number
        regon:
          type: string
          description: Merchant's REGON number
        customerStatus:
          type: string
          description: Merchant's status
          example: Verified
          enum:
          - Verified
          - Not verified
        extendedStatus:
          type: string
          description: Extended merchant's status
          enum:
          - Inactive
          - Active
          - Blocked
    AffiliatesResponse404:
      properties:
        error:
          type: string
          description: Error message
          example: Affiliates not found
        code:
          type: integer
          description: Erroc code
          example: 404
    500UndefinedGeneralError:
      properties:
        error:
          type: string
          description: Error message
          example: Undefined error
        code:
          type: integer
          description: Erroc code
          example: 500
    DispatchArrayObject:
      properties:
        date:
          type: string
          description: Date and time of dispatch
          example: '2020-03-27 15:18:38'
        orderId:
          type: integer
          format: int64
          description: Identifier of dispatched transaction
        partner_id:
          type: integer
          description: Submerchant's id. The funds are transferred to this sumberchant
        items:
          type: array
          description: Array of product data objects
        amount:
          type: integer
          description: Amount of transferred funds, in polish groshes
    DispatchInfoResponse404:
      properties:
        error:
          type: string
          description: Error message
          example: Transaction Not Found
        code:
          type: integer
          description: Erroc code
          example: 3
    RefundResponseArrayObject:
      properties:
        orderId:
          type: integer
          format: int64
          description: Identifier of refunded transaction
          example: 0
        sessionId:
          type: string
          description: Session's id of refunded transaction
        amount:
          type: integer
          description: The refunded amount, in polish groshes
          example: 1000
        data:
          description: Tablica danych sub-partnerów
          items:
            $ref: '#/components/schemas/RefundResponseArrDataObj'
        description:
          type: string
          description: Refund description
        status:
          type: boolean
          description: Refund's status
          example: true
        message:
          type: string
          description: Message
          example: success
    DispatchTransactionBody:
      properties:
        batchId:
          type: integer
          description: Unique id
        details:
          description: Array of dispatch transaction objects
          items:
            $ref: '#/components/schemas/ArrayDetailsDispatchTransaction'
      required:
      - batchId
      - details
    FundsResponse200:
      properties:
        result:
          type: integer
          description: Amount of funds in polish groshes
        code:
          type: integer
          description: Response code, 200 for correct
          example: 200
    DispatchTransactionResponse200:
      properties:
        result:
          description: Array of dispatched transaction results
          items:
            $ref: '#/components/schemas/DispatchResultObjectArrayBody'
        error:
          description: Dispatch error object
          $ref: '#/components/schemas/DispatchErrorObjectBody'
    DispatchResult600ObjectArrayBody:
      properties:
        orderId:
          type: integer
          format: int64
          description: Identifier of dispatched transaction
        orderIdNew:
          type: integer
          format: int64
          description: Identifier of new transaction created in P24 systemu. 0 in case of an error
        sessionId:
          type: string
          description: Session's id of dispatched transaction
        sellerId:
          type: integer
          description: Submerchant's id. The funds were supposed to be transferred to this submerchant
        status:
          type: boolean
          description: Status of transaction
          example: false
        error:
          type: string
          description: Error message
          example: Incorrect orderId or sessionId
    FundsResponse403:
      properties:
        error:
          type: string
          description: Error message
          example: You do not have rights to this account
        code:
          type: integer
          description: Erroc code
          example: 403
    DataArrayObjectRefundBody:
      properties:
        spId:
          type: integer
          description: Merchant's ID. The given merchant will be charged with the refund
          example: 0
        spAmount:
          type: integer
          description: The amount of funds, in polish groshes,to charge the merchant
      required:
      - spId
      - spAmount
    AffiliatesResponse400:
      properties:
        error:
          type: string
          description: Error message
          example: Invalid merchant or affiliate id
        code:
          type: integer
          description: Erroc code
          example: 400
    ErrorDispatch400Object:
      properties:
        errorCode:
          type: integer
          description: Erroc code
        errorMessage:
          type: string
          description: Error message
          example: Empty refund list!
    RefundRsponse409:
      properties:
        error:
          description: Error Array of refund object
          items:
            $ref: '#/components/schemas/ErrorRefundArrayObject'
        code:
          type: integer
          description: Erroc code
          example: 409
    DispatchResultObjectArrayBody:
      properties:
        orderId:
          type: integer
          format: int64
          description: Id number of dispatched transaction
        orderIdNew:
          type: integer
          format: int64
          description: Id number of new transaction created in P24 system
        sessionId:
          type: string
          description: Session's id of dispatched transaction podzielonej transakcji
        sellerId:
          type: integer
          description: Submerchant's id. The funds are transferred to this submerchant
        amount:
          type: integer
          description: Amount of transferred funds in polish groshes
        status:
          type: boolean
          description: Status of transaction
          example: true
        error:
          type: string
          description: Error message. Empty for correct transaction
          example: ''
    FundsResponse400:
      properties:
        error:
          type: string
          description: Error message
          example: Invalid merchant id
        code:
          type: integer
          description: Erroc code
          example: 400
    RefundResponseArrDataObj:
      properties:
        spId:
          type: integer
        spAmount:
          type: integer
    RefundResponse201:
      properties:
        data:
          description: Array of refund objects
          items:
            $ref: '#/components/schemas/RefundResponseArrayObject'
        responseCode:
          type: string
          description: Response code. 0 for correct
          example: 0
    RefundArrayObjectBody:
      properties:
        orderId:
          type: integer
          format: int64
          description: Identifier of refunded transaction in P24 system
        sessionId:
          type: string
          description: Session's id of refunded transactio in Partner's system
        amount:
          type: integer
          description: Amount of refund in polish groshes
        description:
          type: string
          description: Refund description
        data:
          description: Array of sub-merchants' data
          items:
            $ref: '#/components/schemas/DataArrayObjectRefundBody'
      required:
      - orderId
      - sessionId
      - amount
      - data
    AuthorizationRequired:
      properties:
        error:
          type: string
          description: Error message
          example: Incorrect authentication
        code:
          type: string
          description: Erroc code
          example: 401
    DataDispatchInfoObject:
      properties:
        amountLeft:
          type: integer
          description: The amount of left funds, in polish groshes
        dispatch:
          description: Array of dispatch information objects
          items:
            $ref: '#/components/schemas/DispatchArrayObject'
    AffiliatesResponse200:
      properties:
        data:
          descriptiom: Array of pbjects - a list of merchants
          items:
            $ref: '#/components/schemas/DataAffArrayObject'
        code:
          type: integer
          description: Response code, 200 for correct
          example: 200
    DispatchTransactionResponse400:
      properties:
        result:
          description: Array of transaction result objects
          items:
            $ref: '#/components/schemas/DispatchResult600ObjectArrayBody'
        error:
          description: Error object
          $ref: '#/components/schemas/ErrorDispatch400Object'
    ErrorRefundArrayObject:
      properties:
        orderId:
          type: integer
          format: int64
          description: Identifier of refunded transaction
        sessionId:
          type: string
          description: Session's id of refunded transaction
        amount:
          type: integer
          description: The refunded amount, in polish groshes
        description:
          type: string
          description: Refund description
        status:
          type: boolean
          description: Refund's status
          example: false
        message:
          type: string
          description: Error message
          example: The amount of refund exceeds available amount for the transaction
    ArrayDetailsDispatchTransaction:
      properties:
        orderId:
          type: integer
          format: int64
          description: Identifier of dispatch transaction
        sessionId:
          type: string
          description: Session's identifier of dispatch transaction
        sellerId:
          type: integer
          description: Submerchant's id. The funds are going to be transferred to this submerchant
        amount:
          type: integer
          description: Amount of transferred funds in polish groshes, e.g. 1 zł = 100 gr
    403ForbiddenGeneralError:
      properties:
        error:
          type: string
          description: Error message
          example: ''
        code:
          type: integer
          description: Erroc code
          example: 403
    DispatchErrorObjectBody:
      properties:
        errorCode:
          type: integer
          description: Erroc code. 0 for correct transaction
          example: 0
        errorMessage:
          type: string
          description: Error message. For correct transaction "Success, no error."
          example: Success, no error.
    DispatchInfoResponse200:
      properties:
        data:
          description: Information of dispatched transactio n
          $ref: '#/components/schemas/DataDispatchInfoObject'
        responseCode:
          type: integer
          description: Response code. 0 for correct
          example: 0
    TransactionRefundBody:
      properties:
        requestId:
          type: string
          description: Unique request id
        refundsUuid:
          type: string
          description: Unique id of correct refund request in Merchant's system
        urlStatus:
          type: string
          description: URL address for sendig refund's status
        refunds:
          description: Array of refund objects
          items:
            $ref: '#/components/schemas/RefundArrayObjectBody'
      required:
      - requestId
      - refundsUuid
      - refunds
    RefundResponse400:
      properties:
        error:
          type: string
          description: Error message
          example: Invalid input parameters
        code:
          type: integer
          description: Erroc code
          example: null
  securitySchemes:
    basicAuth:
      description: This is the default authentication method. Merchant's ID is user login and API key is the password.
      type: http
      scheme: basic
x-tagGroups:
- name: User creating and management
  tags:
  - Marketplace Merchant API
- name: Marketplace management
  tags:
  - Marketplace Management API
- name: Partner Marketplace
  tags:
  - Marketplace Partner API