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 assigned by merchant. Same value can be shared between multiple transactions. Relates to physical order.
- 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 assigned by merchant. Same value can be shared between multiple transactions. Relates to physical order.
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 |
