## Transfer processing in P24 and P24mobile
P24 and P24mobile processes payments based on the funds paid in by the Client through [przelewy24.pl](https://www.przelewy24.pl). Using this mode, the partner registers the transfer in API and, subsequently, sends a payment link to the client (alternatively, the payment link may also be sent automatically via email). Once the transaction is paid by the client in [przelewy24.pl](https://www.przelewy24.pl), the transfer registered by the partner is sent for processing.NOTE: P24mobile is analogous to P24 in that it is designed to operate with a mobile library.
# Codes of responses and erros
## HTTP response codes
Ekspres Przelewy24 REST API uses response codes in HTTP headers to communicate the result of a query, potential problems and errors. An inventory of possible response codes and their meanings are explained in the appropriate subchapters describing the specific methods.
Always take note of the response code in order to react adequately to potential problems idempotent replies, etc.
Possible response codes for all methods: | Kod | Opis | Znaczenie | |--------------|:--------------|:------------| | 401 | Authorization Required | No access, check the key and the password, check if the key and the password are active and valid for this method. The code is also used to signal temporary failures. | | 403 | Forbidden | No access to a given method. The API key and the password are correct. Contact our staff in order to get access. | | 404 | Not Found | Method not found, check the URL address called. | | 405 | Method Not Allowed | The method used exists, but under a different http call. Check the calls for this method (GET/POST/etc.).| | 415 | Unsupported Media Type | The „Content-Type” value used is not allowed or a required header is missing. Inventory of allowed values available at General query format. | | 500 | Internal Server Error | Server error, if the error recurs, contact our staff and provide the whole query processed, as well as your API key. | | 503 | Service Unavailable | Service temporarily unavailable due to a failure or planned upgrade. | ## Error codes Error codes appear in the output object of a query that ended with an error and, if it’s possible, indicate its cause. This allows to precisely establish the cause of the error and triggers an automatic reaction / error notification.
Error codes are divided into the following groups:
- 1xxx – input parameter validation error (the query contains an error),
- 2xxx, 3xxx – transfer registration error (the query is correct, but the transfer cannot be processed, e.g. due to insufficient funds),
- 9xxx – external services error (API failure caused by unavailability of a related service necessary to process the transfer, e.g. currency exchange),
- 10000 – internal error (failure of Ekspres Przelewy24 REST API).
The table below presents error codes input parameter validation: | Error code | Description | |--------------|:--------------| | 1001 | The value of parameter parameter_name contains illicict characters | | 1002 | Parameter parameter_name value must not be empty | | 1003 | Passwords are not identical | | 1004 | The password must consist of at least 8 characters and contain small and capital letters and digits | | 1005 | Incorrect email address | | 1006 | Incorrect postal code | | 1007 | Incorrect country code | | 1008 | Incorrect amount | | 1009 | The parameter value submitted is not a correct integer | | 1010 | Incorrect currency | | 1011 | Incorrect account number | | 1012 | Incorrect URL address | | 1013 | Transaction type not serviced | | 1014 | Incorrect field value | | 1015 | Current transfer status prevents this operation, or incorrect transfer object | | 1016 | Incorrect date format / incorrect date | | 1017 | Incorrect query signature | | 1018 | Parameter value too long | | 1019 | IBAN number submitted has been blocked |
The table below presents transfer registration error codes: | Error code | Description | |--------------|:--------------| | 2001 | Bank unavailable | | 2002 | Insufficient funds in wallet | | 2003 | Limit for a single transfer has been exceeded | | 2004 | Daily limit on the amount of transfers paid has been exceeded | | 2005 | Transfer ID not recognised | | 2006 | Refund amount provided exceeds the transfer value available | | 2007 | Access denied | | 2008 | Incorrect transfer ID | | 2009 | Transfer limit exceeded | | 2010 | Transfer already returned in P24 mode | | 3000 | Incorrect ID query | | 3001 | Unknown sessionId in P24 mode |
The table below presents error codes for external services: | Error code | Description | |--------------|:--------------| | 9001 | Transfer processing error. Contact the customer service department and provide the query ID | | 9002 | Currency exchange error. Please, try again |
The table below presents the remaining error codes: | Error code | Description | |--------------|:--------------| | 10000 | Internal error. Please, contact the customer service department and provide the query ID | # General structures of queries and responses ## General query format API queries may be processed using any library that allows HTTPS protocol-based communication. Allowed Content-Type values:
- application/json – queries sent in JSON format,
- application/x-www-form-urlencoded – queries sent as POST (urlencoded).
Sample PHP code with the use of cURL ```php
NOTE!
All the responses returned by API are UTF-8-coded JSON objects without “slash” sign filters and unicode characters!
All the responses are returned using the following method:
json_encode($response, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
For more information see [PHP documentation](https://www.php.net/manual/en/json.constants.php).
In the case of some errors, e.g. internal error 500 or authorisation error 401, the same http code will be returned without additional information in the body. These are the cases when the system does not have any more information on the error or does not want to make it available (for instance, due to lack of authorisation).
When most errors are generated, GeneralErrorObject is returned (in addition to the relevant http code) with additional details:
GeneralErrorObject: | Field name | Type | Description | |--------------|:--------------:|:------------| | code | int | General error code | | description | string | Error details |
Przykład odpowiedzi z obiektem GeneralErrorObject:
```html HTTP/1.1 400 Bad Request Content-Type: application/json { „error”: { „code”: 1011, „description”: „Given IBAN value ”iban” is not valid” } } ``` # Environments ## Production environment Every request is differentiated by its own unique request URL. This way Ekspres P24 knows which API-function you want to access. Combined with the base URL for either the production- or test-environment, you will get the complete API-URL. Base URL production system:https://secure.przelewy24.pl/express/v1 ## Test environment During implementation of the mechanisms in merchant’s system, it is recommended to use test environment. Test environment allows to reproduce system functionalities without making actual payments.
Test environment endpoint:
https://sandbox.przelewy24.pl/express/v1
**The test version does not effect transfers and requires separate login keys.** # IP server addresses We recommend script protection against suspicious calls using address filtering for incoming connections. IP server ranges for the P24 servers:
5.252.202.255 , 5.252.202.254
20.215.81.124
193.178.213.0/24
91.220.177.0/24
20.215.183.48/28
134.112.88.8/29
# API Access Authentication is effected with the Basic Auth mechanism, which uses a REST API key (as a login) and the password assigned to it. Generating the API key is possible upon logging on to one’s account in the WWW System (left-hand menu, tab “API Users” -> “REST User List”). A single user may possess a few API access keys. # Authentication 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 paths: /express/v1/access/check: get: tags: - Ekspres P24 API summary: Access Check description: '
The method is used to test access to API. It allows you to verify if the key and the password are active and working correctly.
Object returned: NONE, empty response' responses: "200": description: OK - Access granted, API working properly "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method "403": description: Forbidden - Access active, but you are not authorised to use this method security: - basicAuth: [] /express/v1/user/balance: get: tags: - Ekspres P24 API summary: Current user's balance description:
The method allows to download the current balance of the user’s wallets.
responses: "200": description: OK - JSON object returned with account balance content: application/json: schema: $ref: "#/components/schemas/UserBalanceResponse200Body" "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method security: - basicAuth: [] /express/v1/bank/availability: get: tags: - Ekspres P24 API summary: Banks' availability description: The method returns declared by banks availability on specific weekdays and public holidays. The information allows you to find out at what time a given transfer may be processed. responses: "200": description: OK - JSON object returned with a list of availability of banks content: application/json: schema: $ref: '#/components/schemas/BankAvailabilityObjectResponseBody' "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method security: - basicAuth: [] /express/v1/payment/methods: get: description: The method returns payment methods available in przelewy24.pl. The information returned proves useful for ordering transfers in p24 and p24mobile. We can make the client use a specific payment method after they are redirected to przelewy24.pl in order to pay for the transaction.
It may also return an empty result if no method is available at the moment. tags: - Ekspres P24 API summary: Payment methods responses: "200": description: OK - JSON object returned with a list of payment methods available at przelewy24.pl content: application/json: schema: $ref: "#/components/schemas/PaymentMethodObjectResponseBody" "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method security: - basicAuth: [] /express/v1/payment/refund: put: description: This method refunds payment of transfers in p24 i p24mobile type that were rejected by bank or finished with errors and returned to wallet. Funds for this operation are taken from Ekspres user wallet and refund request is sent to Przelewy24 service for refunding money directly to client.
The progress of refunding a transfer can be watched through transfer notifications. tags: - Ekspres P24 API summary: Refund requestBody: content: application/json: schema: $ref: "#/components/schemas/PutPaymentRefundBody" responses: "200": description: OK - Refund for transfer has been accepted for processing in Przelewy24 service content: application/json: schema: $ref: "#/components/schemas/PutPaymentRefundResponse" "400": description: Bad Request - Incorrect parameter format, the error object returned should include a description of the field in which the problem occurred "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method "404": description: Not Found - No transfer was found, this will be also returned for transfers that aren’t p24/p24mobile type "409": description: Conflict - Transfer is in status that prevents its refunding security: - basicAuth: [] /express/v1/transfer/request: post: tags: - Ekspres P24 API summary: Transfer request description: This method is responsible for sending transfers. The query and the response look similar for each type of transfer, yet the results of the call will be different for each type.
- wallet – concludes with an immediate transfer of money upon a correct call, provided there are sufficient funds in the account,
- p24 and p24mobile – concludes with transaction registration in przelewy24.pl, a link to which will be generated. Once the transaction is paid and verified positively, the transfer will be sent to the entity whose details are indicated in the query,
- apiKey – user API key,
- apiPass – password to user API key,
- object – JSON object of internal method query no unicode or slash sign filtering,
- id – „id” parameter for a given query,
- crc – CRC value for a given API key.
- type – type of notification,
- id – transfer identifier provided,
- status – new transfer status provided,
- crc – CRC value for a given API key.
Note!
/v1/transfer/request method is idempotent.
It means that if the method is called for the first time and a positive result is obtained, a new transfer will be created. In this case, the http code returned is 201 Created.
If the same query is called again, the transfer will not be repeated and the same result as in the case of the original transfer will be generated. In this case, the http code returned is 200 OK. It is important to note that only code 201 Created means that the transfer has been sent / registered. Code 200 OK means that such a transfer already exists and the system only returns the result of the original call.
The mechanism serves to prevent accidental duplication of transfers. If the same transfer is called twice, the money will be sent only once. In case the API connection is interrupted (e.g. Timeout) while the method is being called, it can be repeated without worrying about the possibility of generating a duplicate transfer. At the same time, it is possible to check if the original query was successful and to obtain a link.
The mechanism is based on the ‘id’ parameter. In case the parameter is changed, the query is treated as an entirely new transfer. That is why one must still exercise caution so as to avoid creating a duplicate.
The method operates in an analogous manner to /v1/transfer/request, all the information regarding response codes and values returned may be found there. The description comprises only the elements that differ with respect to the call.
Note!
/v1/transfer/basket method is also idempotent!
The operation details are analogous to /v1/transfer/request. requestBody: content: application/json: schema: $ref: "#/components/schemas/TransferBasketPostBody" responses: "200": description: OK - The result returned is idempotent, the transfer has already been registered, no new transfer has been registered. content: application/json: schema: $ref: "#/components/schemas/TransferBasketResultBody" "201": description: Created - New transfer has been accepted and registered. content: application/json: schema: $ref: "#/components/schemas/TransferBasketResultBody" "202": description: Accepted - he transfer is being processed (occurs when the same request is called for again before an idempotent response is generated) content: application/json: schema: $ref: "#/components/schemas/TransferBasketResultBody" "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/GeneralErrorObjectResponseBody' "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method security: - basicAuth: [] /express/v1/transfer/history: get: tags: - Ekspres P24 API summary: Transfers' history description: The method allows to download the history of transfers from the account within a specified period of time. Warning! Do not use this method to verify whether a transfer was successful. In order to monitor the transfer status use Notifications.
. parameters: - name: limit in: path description: Limit of transfers downloaded in a single query. Default setting - 10. required: false schema: type: integer default: 10 - name: dateFrom in: path description: 'The date FROM which the transfer history will be downloaded.
Format: „YYYY-mm-dd”' required: false schema: type: string maxLength: 10 - name: dateTo in: path description: 'The date TO which the transfer history will be downloaded.
Format: „YYYY-mm-dd”' required: False schema: type: string maxLength: 10 responses: "200": description: OK -Table of JSON objects returned with history results content: application/json: schema: $ref: "#/components/schemas/TransferHistory200ResponseBody" "400": description: Bad Request - Incorrect parameter format, the error object returned should include a description of the field in which the problem occurred content: application/json: schema: $ref: "#/components/schemas/GeneralErrorObjectResponseBody" "401": description: Authorization Required - No access, check the key and the password, check if the key and the password are active and have authorisation to use this method security: - basicAuth: [] /express/v1/transfer/p24/refund: post: tags: - Ekspres P24 API summary: Refund (possible overrefund) description: This method generates new transfer for an existing transaction in Przelewy24 system. New transfer is created exactly the same as in method /v1/transfer/request, and its data is pulled from transaction in Przelewy24 system. Refunds are always created as Wallet type – the amount is pulled from user in Ekspres system.
As for default method does not allow creating a refund transfer for transactions that were previously refunded in Przelewy24 system. Optionally you can force such refund with overrefund parameter.
Warning! Refunds in foreign currencies are evaluated and refunded in PLN!
NOTE!
Method /v1/transfer/p24/refund is idempotent!
The operation details are analogous to /v1/transfer/request
NOTE!
Even if the method of returning that the bank is an existing system, re-recover the information for a given user, which will direct the transfer to another bank.
tags:
- Ekspres P24 API
summary: Verification of the bank's activity
parameters:
- name: iban
in: path
description: IBAN number
required: true
schema:
type: string
maxLength: 40
default: PL0000000000000000000000000000
responses:
"200":
description: The returned JSON object with the default bank activity parameter for the given IBAN
content:
application/json:
schema:
$ref: "#/components/schemas/GetBankCheck"
"400":
description: The provided IBAN is incorrect or parameters were provided incorrected
security:
- basicAuth: []
components:
securitySchemes:
basicAuth:
description: This is the default authentication method. User login is API REST key the password assigned to it.
type: http
scheme: basic
schemas:
PostTransferRefundBody:
properties:
refund:
type: object
description: Refund object
allOf:
- $ref: "#/components/schemas/TransferP24RefundObject"
id:
type: string
maxLength: 255
description: Unique transfer ID, UUID recommended
sign:
type: string
maxLength: 255
description: Signature calculated separately for each transfer. For more information see sign parameter calculation
required:
- refund
- id
- sign
TransferP24RefundObject:
properties:
sessionId:
type: string
maxLength: 255
description: Session ID in Przelewy24 system
title:
type: string
maxLength: 255
description: Title of refund transaction
currency:
type: string
maxLength: 3
description: 'Currency in which refund will be executed as ISO 4217 code (currently available: EUR, PLN)'
amount:
type: integer
description: 'Amount of created refund in smallest denomination
Example: "100" (1 PLN)'
overrefund:
type: boolean
default: false
description: If TRUE, refund will be executed no matter if there was any other refunds executed for this transaction earlier. It ignores error 2010.
Default value is FALSE
required:
- sessionId
- title
- currency
- amount
PutPaymentRefundBody:
properties:
transferId:
type: integer
description: ID of Ekspres transfer that we want to refund
amount:
type: integer
description: Amount to refund, if empty by default whole transfer will be refunded. Refund is always in currency of original transfer
required:
- transferId
PutPaymentRefundResponse:
properties:
transferId:
type: integer
description: ID of refunded transfer
refundId:
type: integer
description: ID of refund (important for notifications)
amount:
type: integer
description: Amount of created refund in smallest denomination
1000 = 10.00
currency:
type: string
maxLength: 3
description: Currency of created refund as ISO 4217 code
TransferRequestPostBody:
properties:
transfer:
description: Object of transfer
allOf:
- $ref: "#/components/schemas/TransferObjectBody"
type:
type: string
description: 'Payment types available: wallet, p24, p24mobile'
example: wallet
express:
type: boolean
description: 'Default setting - True:
True – upon payment, the transfer will be sent in the express mode,
False – upon payment, the transfer will be sent in the elixir mode.'
default: true
example: true
currency:
type: string
maxLength: 3
description: 'Transfer currency in which the funds will be collected for specific payment types:
wallet – funds will be collected from the wallet in a given currency;
p24, p24mobile – the currency in which the client will pay in their funds,
'
example: PLN
send:
type: integer
description: 'Values:
0 - none,
1 – send an email with the url to the recipient of the transfer ,
2 – send an email with the url to the sender of the transfer,
4 – send an email with a confirmation of completion to the recipient,
8 – send an email with a confirmation of completion to the sender.
In order to choose, e.g. two options, provide the sum of the respective values: email with url to the sender + to the recipient + email with confirmation to the sender:
2 + 1 + 8 = 11 -> value to be provided'
example: 11
regulations:
type: boolean
default: false
description: 'Acceptance of Przelewy24 regulations:
false – display consent on p24 website (default),
true – consent granted, do not display.
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”.
Under words regulations and information obligation there must be hyperlinks redirecting to websites with these documents. The checkbox must not be ticked by default.'
id:
type: string
maxLength: 255
description: Unique transfer ID, UUID recommended
sign:
type: string
maxLength: 255
description: Signature calculated separately for each transfer. For more information see Calculation of sign parameter
label:
type: string
maxLength: 20
description: Additional fields used solely for payments of the following types p24, p24mobile.
Additional description in the transfer title.
Can be send in the object of transfer, in the label parameter. Value from the object overwirtes value from this parameter
ttl:
type: integer
description: Additional fields used solely for payments of the following types p24, p24mobile.
Timestamp – date and time after which it will not be possible to pay the transaction
NOTE! For the parameter to work in P24 system, please send a request to partner@przelewy24.pl
Example:
1577833200 = 2020-01-01 00:00:00
0 = no limit (as default)
paymentMethod:
type: integer
description: Additional fields used solely for payments of the following types p24, p24mobile.
The payment method selected in P24, see v1/payment/methods
returnUrl:
type: string
maxLength: 255
description: Additional fields used solely for payments of the following types p24, p24mobile.
The address to which the client will be redirected after processing the payment in Przelewy24.pl. By default, the client will return to the URL address generated upon transfer registration.
sdkVersion:
type: string
maxLength: 10
default: '3.0'
description: Additional fields used solely for payments of the following type p24mobile.
Mobile library version number must be provided. This parameter may be obtained directly from the library (iOS - class P24, Android - class P24SdkVersion). The default value sent is „3.0”.
required:
- transfer
- type
- currency
- send
- id
- sign
TransferObjectBody:
properties:
iban:
type: string
maxLength: 40
description: Recipient’s IBAN no. with country prefix
recipient:
description: Object representing recipient’s details
allOf:
- $ref: "#/components/schemas/PersonObjectBody"
sender:
description: Object representing sender’s details
allOf:
- $ref: "#/components/schemas/PersonObjectBody"
label:
type: string
description: Additional description in the transfer title – only for p24, p24mobile modes
maxLength: 20
title:
type: string
maxLength: 150
description: Transaction title
amountOut:
type: integer
description: Amount of transaction in the smallest denomination
1000 = 10.00
currencyOut:
type: string
maxLength: 3
description: Transfer currency [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)
externalParam:
type: string
maxLength: 100
description: We recommend that additional, individual transfer ids are used with this parameter, as it significantly simplifies transaction identification in notifications.
The parameter is defined at the user’s discretion and is generated when notifications are sent.
This parameter may be the same as the “id” parameter.
confirmation:
type: boolean
default: false
description: Defines if this transfer should get generated confirmation from outgoing bank in PDF format.
Warning! This feature of generating PDF confirmations from outgoing bank is required to be consulted and enabled with integrations support before use! By default using this parameter will do nothing instead!
confirmationFilename:
type: string
maxLength: 100
example: "string"
description: The name of the generated confirmation from the bank (PDF file).
If the `confirmationFilename` parameter isn't sent in request and `confirmation` parametr is set to 'true' then the default file name takes the value from the formula "EX_timestamp_idtransfer_iduser".
required:
- iban
- recipient
- sender
- title
- amountOut
- currencyOut
- externalParam
PersonObjectBody:
properties:
name:
type: string
maxLength: 100
description: Name (company / name and surname)
email:
type: string
maxLength: 100
description: Email (used later for sending notifications)
address:
type: string
maxLength: 100
description: Address – street name, street no., apartment no.
zip:
type: string
maxLength: 10
description: Postal code – validated depending on the country parameter
city:
type: string
maxLength: 50
description: City
country:
type: string
maxLength: 2
description: '2-character country code ([ISO-3166-1](https://pl.wikipedia.org/wiki/ISO_3166-1_alfa-2))
exception: UK = GB, Great Britain'
required:
- name
- email
- address
- zip
- city
- country
TransferBasketPostBody:
properties:
transfers:
description: Comprises a table of transfers to be processed once they are paid through przelewy24.pl or with a payment card.
items:
$ref: "#/components/schemas/TransferObjectBody"
type:
type: string
description: 'Payment methods available: p24, p24mobile.
Wallet mode is not accepted in this method.'
express:
type: boolean
description: 'Default setting - True:
True – upon payment, the transfer will be sent in the express mode,
False – upon payment, the transfer will be sent in the elixir mode.'
default: true
example: true
currency:
type: string
maxLength: 3
description: 'Transfer currency in which the funds will be collected for specific payment types:
wallet – funds will be collected from the wallet in a given currency;
p24, p24mobile – the currency in which the client will pay in their funds,
'
example: PLN
send:
type: integer
description: 'Wartości:
0 - none,
1 – send an email with the url to the recipient of the transfer ,
2 – send an email with the url to the sender of the transfer,
4 – send an email with a confirmation of completion to the recipient,
8 – send an email with a confirmation of completion to the sender.
In order to choose, e.g. two options, provide the sum of the respective values: email with url to the sender + to the recipient + email with confirmation to the sender:
2 + 1 + 8 = 11 -> value to be provided'
example: 11
regulations:
type: boolean
default: false
description: 'Acceptance of Przelewy24 regulations:
false – display consent on p24 website (default),
true – consent granted, do not display.
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”.
Under words regulations and information obligation there must be hyperlinks redirecting to websites with these documents. The checkbox must not be ticked by default.'
id:
type: string
maxLength: 255
description: Unique transfer ID, UUID recommended
sign:
type: string
maxLength: 255
description: Signature calculated separately for each transfer. For more information see Calculation of sign parameter
label:
type: string
maxLength: 20
description: Additional fields used solely for payments of the following types p24, p24mobile.
Additional description in the transfer title.
Can be send in the object of transfer, in the label parameter. Value from the object overwirtes value from this parameter
ttl:
type: integer
description: Additional fields used solely for payments of the following types p24, p24mobile.
Timestamp – date and time after which it will not be possible to pay the transaction
NOTE! For the parameter to work in P24 system, please send a request to partner@przelewy24.pl
Example:
1577833200 = 2020-01-01 00:00:00
0 = no limit (as default)
paymentMethod:
type: integer
description: Additional fields used solely for payments of the following types p24, p24mobile.
The payment method selected in P24 v1/payment/methods
returnUrl:
type: string
maxLength: 255
description: Additional fields used solely for payments of the following types p24, p24mobile.
The address to which the client will be redirected after processing the payment in Przelewy24.pl. By default, the client will return to the URL address generated upon transfer registration.
sdkVersion:
type: string
maxLength: 10
default: '3.0'
description: Additional fields used solely for payments of the following type p24mobile.
Mobile library version number must be provided. This parameter may be obtained directly from the library (iOS - class P24, Android - class P24SdkVersion). The default value sent is „3.0”.
example: 3.0
required:
- transfers
- type
- currency
- send
- id
- sign
NotificationTransferStatusBody:
properties:
type:
type: string
description: 'Sent: always.
Specifies which stage the notification refers to.
Possible values:
- pay - transfer payment(transferRequestId),
- payout - payout of funds (transferIds),
- refund.'
id:
type: string
description: 'Sent: always.
Identifier of transfer, payout or refund which the notification refers to.'
status:
type: integer
description: Sent: always.
Operation statuses are described in Table of tansaction statuses
externalParam:
type: string
description: 'Sent: always.
Parameter defined at transfer registration.
Note!
For method /v1/transfer/basket n case of notifications of the type „pay”, the field comprises all the externalParam values of the sent transfers separated with commas.'
method:
type: string
description: 'Sent: only if it is a notification on the payment of the transfer.
Transfer payment method: p24/p24code/wallet/card.'
example: wallet
sign:
type: string
description: Sent: always.
Control sum is a value calculated with the use of sha384 algorithm. For details, see Calculation of sign parameter dla powiadomień.
UserBalanceResponse200Body:
properties:
balance:
description: Object representing the account balance for a given wallet
items:
$ref: "#/components/schemas/BalanceObjectBody"
timestamp:
type: integer
description: Unix time stamp of the exact moment for which the results are presented
BalanceObjectBody:
properties:
amount:
type: integer
description: The amount of the balance in the smallest denomination (grosz)
currency:
type: string
maxLength: 3
description: Currency in the form of [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code
example: PLN
GetBankCheck:
properties:
available:
type: boolean
description: Indication whether the bank is active
example: true
BankAvailabilityObjectResponseBody:
properties:
name:
type: string
maxLength: 50
description: Bank name
workweek:
type: string
maxLength: 50
description: Working hours from Monday to Friday
saturday:
type: string
maxLength: 50
description: Working hours on Saturdays
sunday:
type: string
maxLength: 50
description: Working hours on Sundays
holidays:
type: boolean
description: 'Availability on public holidays:
false – unavailable
true – available'
PaymentMethodObjectResponseBody:
properties:
id:
type: integer
description: Unique payment method ID
name:
type: string
description: Name of a payment method
status:
type: boolean
description: True – ON, False – OFF
TransferRequestResultObjectBody:
properties:
result:
description: Includes the object of the query result
$ref: "#/components/schemas/TransferOutObjectBody"
TransferOutObjectBody:
properties:
transferRequestId:
type: string
description: Query ID of a registered transfer, marked in notifications as type „pay”
transferIds:
type: array
description: Table of registered transfers, marked in notifications as type „payout”
items:
type: integer
url:
type: string
description: The URL address that allows you to check the current status of the transfer. In case of payments in P24 mode, the redirection to przelewy24.pl will take place in order for the transaction to be paid.
TransferBasketResultBody:
properties:
result:
description: Includes the object of the query result
$ref: "#/components/schemas/TransferBasketOutObjectBody"
TransferBasketOutObjectBody:
properties:
transferRequestId:
type: string
description: Query ID of a registered transfer, marked in notifications.
as type „pay”
transferIds:
type: array
description: Table of registered transfers, marked in notifications.
as type „payout”
items:
type: integer
url:
type: string
description: The URL address that allows you to check the current status of the transfer. In case of payments in P24 mode, the redirection to przelewy24.pl will take place in order for the transaction to be paid.
TransferHistory200ResponseBody:
properties:
result:
description: Comprises a table of objects of the transfer history or an empty table if no transfers have been found
items:
$ref: "#/components/schemas/HistoryOutObjectBody"
HistoryOutObjectBody:
properties:
transfer:
description: Object of transfer TransferObject
$ref: "#/components/schemas/TransferObjectBody"
express:
type: boolean
description: Was the transfer ordered in the express mode?
date:
type: string
description: Transfer registration date
status:
type: integer
description: Transfer current status
statusDescription:
type: string
description: Current status (description)
type:
type: string
description: 'Type of payment: wallet, p24, p24code'
id:
type: string
description: “id” parameter provided during transfer registration
transferId:
type: integer
description: Transfer identifier in the express system
transferRequestId:
type: integer
description: Request identifier in the express mode
GeneralErrorObjectResponseBody:
properties:
error:
description:
$ref: "#/components/schemas/GeneralErrorObject"
GeneralErrorObject:
properties:
code:
type: string
description:
type: string
##############################
tags:
- name: Calculation of sign parameter
x-displayName: Calculation of sign parameter
description: >
# Calculation of sign parameter for API methods
The sign parameter is used to sign queries which trigger registration of transfers or process other important operations. It is always accompanied by the “id” parameter, which guarantees the idempotent character of the method.
Note!
The sign parameter for notifications is calculated in a different manner than for calling methods.
For details concerning the calculation of the signature for notifications, see: Calculation of sign parameter for notifications.
NOTE! The order of the parameters transferred MATTERS, both for the general object and the internal value “object”.
Sample signature:
```php 'api-key', 'apiPass' => 'api-key-password', 'object' => json_encode( $data['transfer'], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES ), 'id' => $data['id'], 'crc' => 'api-crc-key' ]; // Calculating sign parameter $data['sign'] = hash( 'sha384', json_encode($signArray, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) ); ``` # Calculation of sign parameter for notifications In the case of notifications on the change of transfer status which are sent to the Partner’s destination point configured for a given key, the “sign” parameter included in them should be calculated and verified to ensure that they come from a correct source.
Note!
The sign parameter for the API methods is calculated in a different manner than for notifications.
For details concerning the calculation of the signature for transfers, see: Calculation of sign parameter for API methods.
The parameters above should be transferred as JSON object, without unicode or slash sign filtering, to the hash method. The result of this calculation constitutes a correct signature.
NOTE! When calculating the sign, please take care not to change the order of the parameters you received. Sample calculation of the signature for the notification received:
```php $data['type'], 'id' => $data['id'], 'status' => $data['status'], 'crc' => 'api-crc-key' ]; // Calculating sign parameter $data['sign'] = hash( 'sha384', json_encode($signArray, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) ); ``` - name: Notifications on transfer status x-displayName: Notifications on transfer status description: > Whenever the status of a transfer/refund changes in Ekspres, a notification may be sent. The address for notifications may be configured in the WWW system, in the API key settings. The notification will have the structure presented in the table below and will be sent as JSON object using the POST method. Sending a notification requires a response from the partner’s server with code 200.
If the response code is different, the notification will be repeated after 5, 10, 15, 20, 25, 55 and 95 minutes.
Note! Special attention should be given to parameters type and id!
Parameter type specifies the value that parameter id possess.
In case the value is pay, parameter id will have transferRequestId identifier.
In case the value is payout, parameter id will have transferId identifier.
In case the value is refunded, parameter id will have refund identifier.
All the identifiers are unique, nd they should be considered separately. If they are confused, the respective transfers may be ascribed wrong statuses.
Use externalParam to ascribe notifications in a simpler way according to an independently assigned identifier.
| Code | Name | English equivalent | |------|:--------------|:------------| | 1 | Zarejestrowana | Registered | | 2 | Przekazany do realizacji | Sent to processing | | 3 | Błąd przekazania do realizacji | Error while sending to processing | | 4 | Opłacona | Paid | | 5 | Wypłacona | Finished | | 6 | Przeterminowana | Expired | | 7 | Błąd podczas wypłaty | Error while processing | | 8 | Błąd opłacenia transakcji | Error while payment | | 9 | Wypłacona przez zewnętrznego operatora | Finished by external operator | | 10 | Zlecony zwrot | Refund commissioned | | 11 | Zwrot zrealizowany | Refund finished | | 12 | Zwrot odrzucony | Refund rejected | | 13 | Błąd podczas realizacji zwrotu | Error while refunding | | 14 | Zwrot zarejestrowany | Refund registered | | 15 | Wypłacona zwrócona | Finished and refunded | | 16 | Anulowana | Canceled | | 17 | Oczekuje na dane | Pending for data | - name: Transfer scenarios x-displayName: Transfer scenarios description: > # Introduction Below are transfer scenarios that occur most frequently. Subsequent transfer statuses are indicated.
Note!
For status 1 “Registered” no notification is sent!
This is because it is an input status, i.e. obtaining the correct response from API during transfer registration serves to inform that it was assigned this status.
**1** Registered → **4** Paid → **3** Error while sending to processing # Transfer stopped at payout at the bank The funds are returned to the wallet.
**1** Registered → **4** Paid → **2** Sent to processing → **5** Paid out → **7** Processing error # Transfer finished and refunded The funds are returned to the wallet.
**1** Registered → **4** Paid → **2** Sent to processing → **5** Paid out → **15** Paid out and refunded # Insufficient funds to make a transfer that has already been initiated Funds have not been collected.
**1** Registered → **4** Paid → **8** Payment error