Versions Compared
| Version | Old Version 5 | New Version Current |
|---|---|---|
| Changes made by | ||
| Saved on |
Key
- This line was added.
- This line was removed.
- Formatting was changed.
In this chapter, you will learn how to handle transaction returns, and how to use the Merchant's Portal.
Transaction returns may be ordered by the Merchant through the API, to do this prepare the handling of the methods described in Returns and Transactions - API. The second method to perform a return is ordering through the Merchant's Portal manually.
| Info |
|---|
The functionality of making returns is not available in the hours between 0011:00 ap.m. - 06:00 30 a.m. due to the settlement /payment process being performed on the Merchant's account at the time. |
On this page:
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Returns and Transactions - API
The Merchant API app which is part of the InPost Pay system provides the following services:
Status colour Blue title GET /v1/izi/transactionMakes it possible to download the list of transactions for an authorized Merchant. A full description of the fields related to
the transactions and filters by means of which the result being returned may be limited, is below.Status colour Green title POST /v1/izi/transaction/{transaction_id}/refundMakes it possible to order a full or partial return for a given transaction,
performed in one of an authorized Merchant's stores. In the case of this service, an additional verification of the order is being performed
by verifying the signature of the message.
| Info |
|---|
To generate the signature, use the secret. In order to obtain it, it could be generated independently on the website merchant.inpost.pl, or contact the support service available through integracjapay@inpost.pl |
| Info |
|---|
This is not the same client_secret used to receive access_token. A full description of how to generate a message signature correctly is below. |
List of methods:
Status colour Blue title GET /v1/izi/transaction- List of transactionsStatus colour Green title POST /v1/izi/transaction/{transaction_id}/refund- Returning an order
Authorization
Authentication is required, and it is performed as in the case of the integration with InPost Pay (Basket App). Download access_token using
the client_id and the client_secret held, and then transfer it as a Bearer Token in the Authorization header.
Environments available:
Sandbox: https://sandbox-api.inpost.pl
Production: https://api.inpost.pl
REST API Specification
| Confluence open api |
|---|
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 |
The Merchant's Panel
The Merchant's Portal is a portal which makes it possible to:
View the details of particular transactions
Make returns
Browse settlements
View documents signed.
At the very bottom of the page there are manuals for using the Merchant's Portal.
The link to the Merchant's Panel (returns and transactions): https://merchant.aion.eu/
The link to the administration panel (assigning rights): https://merchant.aion.eu/administration
The Merchant's Panel Operating Manual
User Manual
| View file | ||
|---|---|---|
|
Example settlement report
| View file | ||
|---|---|---|
|