Page Comparison

Funkcjonalność wykonywania zwrotów nie jest dostępna w godzinach 00:00 - 06:00 , ze względu na wykonywanie w tym czasie procesu rozliczeń/wypłat na konto Merchanta.

Do wygenerowania sygnatury należy użyć secret'u. Aby go otrzymać można go wygenerować samodzielnie w serwisie merchant.inpost.pl lub skontaktować się ze wsparciem dostępnym pod adresem integracjapay@inpost.pl

Nie jest to ten sam client_secret, wykorzystywany w celu otrzymania access_token'u. Pełen opis jak poprawnie wygenerować sygnaturę wiadomości znajduje się poniżej.

openapi: 3.0.1
info:
  title: InPost IZI Merchant Transaction API
  description: Merchant Transaction REST API
  license:
    name: Integration API
  version: 1.0.0
servers:
  - url: https://sandbox-api.inpost.pl
    description: Sandbox
  - url: https://api.inpost.pl
    description: Produkcja
security:
  - JWT:
      - read
      - write
paths:
  /v1/izi/transaction:
    get:
      tags:
        - Merchant Transaction
      description: Get a list of transactions
      operationId: getTransactions
      parameters:
        - name: page
          in: query
          required: false
          schema:
            minimum: 0
            type: integer
            format: int32
            default: 0
          description: Zero-based page index.
        - name: per_page
          in: query
          required: false
          schema:
            minimum: 1
            type: integer
            format: int32
            default: 20
          description: Number of items to be returned per page.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - created_date
              - amount
              - status
              - payment_method
              - order_id
          description: Name of a field which defines sorting criteria.
        - name: sort_direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - ASC
              - DESC
            default: ASC
          description: Specifies either ascending or descending sort.
        - name: order_id
          in: query
          required: false
          schema:
            type: string
          description:  Order ID consists of "order ID by merchant"&"|"&"order ID by InPost Pay".Same value can be shared between multiple transactions. Relates to physical order.
          example: "12345678|d30ef4c8-3e3e-3456-bb76-67y543ed66" 
        - name: transaction_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Unique transaction ID assigned by the payment service provider.
        - name: merchant_pos_id
          in: query
          required: false
          schema:
            type: string
          description: Point of Sale ID assigned by the payment service provider.
        - name: amount_from
          in: query
          required: false
          schema:
            minimum: 0
            type: number
          description: Transaction amount criteria which will return transactions with amount greater than or equal to the specified amount.
        - name: amount_to
          in: query
          required: false
          schema:
            minimum: 0
            type: number
          description: Transaction amount criteria which will return transactions with amount less than or equal to the specified amount.
        - name: currency
          in: query
          required: false
          schema:
            type: string
          description: Currency Code in [**ISO 4217**](https://www.iso.org/iso-4217-currency-codes.html) format.
        - name: date_from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Transaction creation date criteria which will return transactions created on or after specified date.
        - name: date_to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Transaction creation date criteria which will return transactions created on or before specified date.
        - name: paymentMethod
          in: query
          required: false
          schema:
            uniqueItems: true
            type: array
            items:
              type: string
              enum:
                - CARD
                - CARD_TOKEN
                - GOOGLE_PAY
                - APPLE_PAY
                - BLIK_CODE
                - BLIK_TOKEN
                - PAY_BY_LINK
                - SHOPPING_LIMIT
                - DEFERRED_PAYMENT
                - PIS
          description: Payment method used to complete transaction
        - name: status
          in: query
          required: false
          schema:
            uniqueItems: true
            type: array
            items:
              type: string
              enum:
                - PENDING
                - AUTHORIZED
                - CARD_VERIFIED
                - CAPTURED
                - REFUNDED
                - PARTIALLY_REFUNDED
                - CANCELLED
                - DECLINED
          description: Current transaction status
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                json-response:
                  value: {"items":[{"transaction_id":"72ae5e36-80ce-4307-9d9f-fea6a289e151","merchant_pos_id":"V0123456789","external_transaction_id":"09c6ed97-00dd-4c37-8115-be6beb46f136","description":"Transaction Description","status":"CAPTURED","created_date":"2023-01-30T14:27:03.37883Z","amount":57.29,"currency":"PLN","payment_method":"BLIK_CODE","order_id":"343","operations":[{"external_operation_id":"5fbdabf0-0728-44bb-9f2a-3145eedcef97","type":"CAPTURE","status":"SUCCESS","amount":57.29,"currency":"PLN","operation_date":"2023-01-30T14:27:12.190391Z"},{"external_operation_id":null,"type":"AUTHORIZATION","status":"SUCCESS","amount":57.29,"currency":"PLN","operation_date":"2023-01-30T14:27:03.460984Z"}]}],"page":0,"per_page":1,"count":88}
              schema:
                $ref: '#/components/schemas/GetTransactionsResponse'
        '400':
          description: |
            Bad Request. Possible errors:
            * **validation_failed** - Data sent to the server was invalid. Check details for more information
            * **required** - Value is required
            * **invalid** - Provided value is invalid. Please refer to documentation
            * **too_short** - Provided value is too short
            * **too_long** - Provided value is too long
            * **too_small** - Provided value is too small
            * **too_large** - Provided value is too large
            * **invalid_format** - Provided value has invalid format
            * **bad_request** - Bad Request
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":400,"error":"validation_failed","message":"Data sent to the server was invalid. Check details for more information","details":{"amount_to":["invalid_format"]}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not Found. Possible errors:
            * **merchant_not_found** - Merchant was not found
            * **not_found** - Not Found
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":404,"error":"merchant_not_found","message":"Merchant was not found","details":{"merchant_id":["00001"]}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internval Server Error. Possible errors:
            * **server_error** - Unexpected error occurred during request processing
            * **internal_server_error** - Interval Server Error
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":500,"error":"server_error","message":"Unexpected error occurred during request processing","details":{}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/izi/transaction/{transaction_id}/refund:
    post:
      tags:
        - Merchant Transaction
      description: Order a refund for a given transaction
      operationId: orderRefund
      parameters:
        - name: X-Command-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: Unique id needed to perform idempotency check.
        - name: transaction_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique transaction ID assigned by the payment service provider.
      requestBody:
        content:
          application/json:
            examples:
              json-request:
                value: '{"signature":"2ae979eab57f72a979e3be3d79952876c981f6a918b4fe905479b6bfa5baf1ae604a73ae117a9abf1c91d1bb648115c5e608aeef32003c98618671e66cf22fe1","refund_amount":1.23,"external_refund_id":"0b374857-2096-46e0-a9d6-26f313073d32","additional_business_data":{"additional_data":"value"}}'
            schema:
              $ref: '#/components/schemas/OrderRefundRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                json-response:
                  value: {"external_refund_id":"0b374857-2096-46e0-a9d6-26f313073d32","refund_amount":1.23,"status":"PENDING","description":"refund description"}
              schema:
                $ref: '#/components/schemas/OrderRefundResponse'
        '400':
          description: |
            Bad Request. Possible errors:
            * **validation_failed** - Data sent to the server was invalid. Check details for more information
            * **required** - Value is required
            * **invalid** - Provided value is invalid. Please refer to documentation
            * **too_short** - Provided value is too short
            * **too_long** - Provided value is too long
            * **too_small** - Provided value is too small
            * **too_large** - Provided value is too large
            * **invalid_format** - Provided value has invalid format
            * **invalid_signature** - Provided signature does not match expected signature
            * **unsupported_signature_algorithm** - Requested Signature Algorithm is not supported. Please refer to documentation to get a full list of supported algorithms.
            * **bad_request** - Bad Request
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":400,"error":"validation_failed","message":"Data sent to the server was invalid. Check details for more information","details":{"refund_amount":["invalid_format"]}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible errors:
            * **forbidden** - You are not allowed to access requested resource
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":403,"error":"forbidden","message":"You are not allowed to access requested resource","details":{}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not Found. Possible errors:
            * **resource_not_found** - Resource you are looking for was not found
            * **merchant_not_found** - Merchant was not found
            * **merchant_secret_not_found** - Merchant Secret was not found
            * **not_found** - Not Found
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":404,"error":"merchant_not_found","message":"Merchant was not found","details":{"merchant_id":["00001"]}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict. Possible errors:
            * **command_already_performed** - Command has already been performed
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":409,"error":"command_already_performed","message":"Command has already been performed","details":{"commandId":["5d247a70-ef37-4dab-9d41-135f91395ec8"]}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
           
        '422':
          description: |
            Conflict. Possible errors:
            * **refund_amount_exceeded** - Requested refund amount exceeds remaining transaction amount
            * **insufficient_balance** - Merchant account has insufficient balance
            * **unavailable_balance** - Merchant account balance is currently unavailable
            * **cannot_refund_transaction** - Requested transaction cannot be refunded
            * **full_refund_unavailable** - Transaction cannot be fully refunded because it has already been partially refunded. Please provide refund amount
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":422,"error":"refund_amount_exceeded","message":"Requested refund amount exceeds remaining transaction amount","details":{}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internval Server Error. Possible errors:
            * **server_error** - Unexpected error occurred during request processing
            * **internal_server_error** - Interval Server Error
          content:
            application/json:
              examples:
                json-response:
                  value: {"status":500,"error":"server_error","message":"Unexpected error occurred during request processing","details":{}}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GetTransactionsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          description: List of returned transactions satisfying requested criteria
        page:
          type: integer
          format: int32
          description: Returned page number
        per_page:
          type: integer
          format: int32
          description: Number of items returned
        count:
          type: integer
          format: int64
          description: Count of all items satisfying requested criteria
      required:
        - items
        - page
        - per_page
        - count
    Transaction:
      type: object
      properties:
        transaction_id:
          type: string
          description: Unique transaction ID assigned by the payment service provider.
        merchant_pos_id:
          type: string
          description: Point of Sale ID assigned by the payment service provider.
        external_transaction_id:
          type: string
          nullable: true
          description: Unique transaction ID assigned by merchant.
        description:
          type: string
          nullable: true
          description: Message describing transaction
        status:
          type: string
          enum:
            - PENDING
            - AUTHORIZED
            - CARD_VERIFIED
            - CAPTURED
            - REFUNDED
            - PARTIALLY_REFUNDED
            - CANCELLED
            - DECLINED
          description: Current transaction status
        created_date:
          type: string
          format: date-time
          description: Transaction creation date
        amount:
          type: number
          description: Original transaction amount
        currency:
          type: string
          description: Currency Code in [**ISO 4217**](https://www.iso.org/iso-4217-currency-codes.html) format.
        payment_method:
          type: string
          enum:
            - CARD
            - CARD_TOKEN
            - GOOGLE_PAY
            - APPLE_PAY
            - BLIK_CODE
            - BLIK_TOKEN
            - PAY_BY_LINK
            - SHOPPING_LIMIT
            - DEFERRED_PAYMENT
            - PIS
          description: Payment method used to complete transaction
        order_id:
          type: string
          nullable: true
          description: Order ID consists of "order ID by merchant"&"|"&"order ID by InPost Pay".Same value can be shared between multiple transactions. Relates to physical order.
          example: "12345678|d30ef4c8-3e3e-3456-bb76-67y543ed66" 
        operations:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
          description: List of operations related to the given transaction
      required:
        - transaction_id
        - merchant_pos_id
        - external_transaction_id
        - description
        - status
        - created_date
        - amount
        - currency
        - payment_method
        - order_id
        - operations
    Operation:
      type: object
      properties:
        external_operation_id:
          type: string
          nullable: true
          description: Operation ID provided by merchant.
        type:
          type: string
          enum:
            - CAPTURE
            - REFUND
            - REVERSAL
            - AUTHORIZATION
            - AUTHENTICATION
            - CARD_VERIFICATION
          description: Operation type
        status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
          description: Current operation status
        amount:
          type: number
          description: Operation amount
        currency:
          type: string
          description: Operation currency code in [**ISO 4217**](https://www.iso.org/iso-4217-currency-codes.html) format.
        operation_date:
          type: string
          format: date-time
          description: Timestamp defining when given operation happened
      required:
        - external_operation_id
        - type
        - status
        - amount
        - currency
        - operation_date
    OrderRefundRequest:
      type: object
      properties:
        external_refund_id:
          maxLength: 250
          minLength: 0
          type: string
          nullable: true
          description: Refund Order ID assigned by merchant.
        refund_amount:
          minimum: 0.01
          exclusiveMinimum: false
          type: number
          nullable: true
          description: Amount to be refunded. If none is specified, full refund will be requested.
        additional_business_data:
          type: object
          additionalProperties:
            type: string
          description: Additional data related to the refund order.
        signature:
          maxLength: 140
          minLength: 32
          type: string
          description: |
            Message signature required to verify genuinity of the request. Calculated by concatenating **X-Command-ID** header value, path variable **transaction_id**, all request body field values (ignoring signature field) in alphanumerical order and a merchant secret (If any of the values is null, then it should be treated as an empty string). Final signature is a lowercase hexadecimal digest of a hash function applied to the concatenated message.
               
            Supported hash functions are: SHA-512
               
            Default hash function: SHA-512
               
            If a non-default hash function is used, then the signature must be prefixed by its ID and '_' character
               
            Example 1:
               
              Merchant Secret: 0051db3a-b9ea-4351-bfeb-bcbe1adcc045
                 
              X-Command-ID: f3daf649-30bd-4578-a3bc-89ee822e2887
                 
              transaction_id: c50c3756-7ca1-431d-8b4e-4fc322b18548
                 
              request_body: {
                "signature": "TBD",
                "refund_amount": 1.23,
                "external_refund_id": "0b374857-2096-46e0-a9d6-26f313073d32",
                "additional_business_data":
                {
                    "key1": "value1",
                    "key2": "value2"
                }
              }
                 
              Intermediate signature: f3daf649-30bd-4578-a3bc-89ee822e2887c50c3756-7ca1-431d-8b4e-4fc322b18548key1value1key2value20b374857-2096-46e0-a9d6-26f313073d321.230051db3a-b9ea-4351-bfeb-bcbe1adcc045
                 
              Valid Signatures:
                a5cf845e2a8361a4422f54485e423df60b0209c0b039ea8cad8a0cceb67ca5bdd51a3fa8634e3a2e9ecdb61279b1875d2b83fcf64ab1f93d4336116a13558b8a
                   
                SHA-512_a5cf845e2a8361a4422f54485e423df60b0209c0b039ea8cad8a0cceb67ca5bdd51a3fa8634e3a2e9ecdb61279b1875d2b83fcf64ab1f93d4336116a13558b8a
                   
            Example 2:
               
              Merchant Secret: 0051db3a-b9ea-4351-bfeb-bcbe1adcc045
                 
              X-Command-ID: f3daf649-30bd-4578-a3bc-89ee822e2887
                 
              transaction_id: c50c3756-7ca1-431d-8b4e-4fc322b18548
                 
              request_body: {
                "signature": "TBD",
                "refund_amount": null,
                "external_refund_id": null
              }
                 
              Intermediate signature: f3daf649-30bd-4578-a3bc-89ee822e2887c50c3756-7ca1-431d-8b4e-4fc322b185480051db3a-b9ea-4351-bfeb-bcbe1adcc045
                 
              Valid Signatures:
                3d0eab2e4b972655c24c3df583967484820920daf5771f4638def264c86a9c66646d38b455c0d753414cda22ec94ff88dc5d2163ea5a98aca3b34eea04897b9d
                   
                SHA-512_3d0eab2e4b972655c24c3df583967484820920daf5771f4638def264c86a9c66646d38b455c0d753414cda22ec94ff88dc5d2163ea5a98aca3b34eea04897b9d
               
      required:
        - signature
    OrderRefundResponse:
      type: object
      properties:
        external_refund_id:
          type: string
          description: Refund ID assigned by the merchant.
          nullable: true
        refund_amount:
          type: number
          description: Amount that has been ordered to be refunded
        status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
          description: Current refund status
        description:
          type: string
          nullable: true
          description: Refund order description
      required:
        - external_refund_id
        - refund_amount
        - status
        - description
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code
        error:
          type: string
          description: Error code identifying the type of error
        message:
          type: string
          description: Message describing occurred error
        details:
          type: object
          description: Details object possibly containing information related to the occurred error. Please see specific API docs for examples
      required:
        - status
        - error
        - message
        - details
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT