Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Przelewy24 Transaction service API
contact:
name: Przelewy24 Support
url: https://www.przelewy24.pl/support
x-refined-note:
- x-logo differs across the merged source definitions and was not carried
version: '1.0'
description: 'Operations tagged Transaction service API across 2 of this provider''s published API definitions: openapi-extended.yml, openapi.yml. Each path carries the servers of the definition it was published in.'
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: Transaction service API
x-displayName: Transaction service API
paths:
/api/v1/transaction/register:
post:
tags:
- Transaction service API
summary: Transaction registration
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequestBody1'
description: 'Before sending the transaction request, transaction data must be saved in the merchant’s local database. In particular, the session ID and the transaction amount should be stored. <br><br><hr> <h3>Redirection to transaction panel</h3> URL address:https://secure.przelewy24.pl/trnRequest/{TOKEN}<br><br> where {TOKEN} was obtained upon transaction registration.<br> <hr><br>
On transaction success the URL address transferred in <a href="#tag/Transaction-service-API/paths/~1api~1v1~1transaction~1register/post"><b>"urlStatus"</b></a> parameter is used to send notification irrespective of whether the customer has been redirected to <a href="#tag/Transaction-service-API/paths/~1api~1v1~1transaction~1register/post"><b>"urlReturn"</b></a> or not. The notification is sent only for correct payments. The system does not send information on invalid or failed payments. The notification is sent in the JSON format.<br><br> <a href="#tag/Notification"><font color = "red"><b>Show Transaction result JSON</b></font></a>'
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRegistrationResponse'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidInputData'
'401':
description: not authorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
security:
- basicAuth: []
operationId: postApiV1TransactionRegister
x-operation-id-source: derived
servers:
- url: https://sandbox.przelewy24.pl
description: Sandbox server (uses test data)
- url: https://secure.przelewy24.pl
description: Production server (uses live data)
/api/v1/transaction/verify:
put:
tags:
- Transaction service API
summary: Transaction verification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionVerificationBody'
description: After receiving notification, the merchant’s system should perform an additional action to confirm the payment and authenticate the notification. It is necessary to use transaction/verify method.<br><br> **Important!** Transaction will be confirmed only after verification process. In case the customer performs transaction and merchant does not verify performed transaction, amount will not be transferred to the merchant and settled. It will stay at the customer’s disposal as an advance payment.
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionVerificationResponse'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidInputData'
'401':
description: not authorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
security:
- basicAuth: []
operationId: putApiV1TransactionVerify
x-operation-id-source: derived
servers:
- url: https://sandbox.przelewy24.pl
description: Sandbox server (uses test data)
- url: https://secure.przelewy24.pl
description: Production server (uses live data)
components:
schemas:
TransactionVerificationBody:
properties:
merchantId:
description: Merchant ID
type: integer
posId:
description: Shop identification number (defaults to merchant ID)
type: integer
sessionId:
description: Unique identifier from merchant's system
type: string
maxLength: 100
amount:
description: Transaction amount which format is presented as amount in lowest currency unit, e.g. 1.23 PLN = 123
type: integer
currency:
description: Currency
type: string
maxLength: 3
default: PLN
orderId:
description: Id of an order assigned by P24
type: integer
format: int64
sign:
description: Checksum of parameters:<br> {<font color = "brown">"sessionId":</font>"str",<font color = "brown">"orderId":</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"
type: string
required:
- posId
- sessionId
- amount
- currency
- orderId
- sign
- merchantId
TransactionRequestBody1:
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
urlNotify:
name: urlNotify
in: formData
description: URL address to which transaction notifications will be sent
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'
required:
- merchantId
- posId
- sessionId
- amount
- currency
- description
- email
- country
- language
- urlReturn
- ttl
- sign
InvalidInputData:
properties:
error:
type: string
default: Invalid input data
example: Invalid input data
code:
type: number
default: 400
example: 400
TransactionRegistrationResponse:
properties:
data:
properties:
token:
type: string
type: object
responseCode:
type: number
default: 0
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
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>
TransactionVerificationResponse:
properties:
data:
properties:
status:
type: string
default: success
type: object
responseCode:
type: number
default: 0
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.
UnauthorizedResponse:
properties:
error:
type: string
default: Incorrect authentication
example: Incorrect authentication
code:
type: number
default: 401
example: 401
TransactionRequestBody1_2:
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
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_2'
required:
- merchantId
- posId
- sessionId
- amount
- currency
- description
- email
- country
- language
- urlReturn
- ttl
- sign
AdditionalProperties_2:
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.
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-refined-from:
- openapi-extended.yml
- openapi.yml
x-tagGroups:
- name: Methods available in API
tags:
- Ekspres P24 API
- name: Sign parameter
tags:
- Calculation of sign parameter
- name: Transfer
tags:
- Notifications on transfer status
- Table of transfer statuses
- Transfer scenarios