Introduction

Przelewy24 is the largest online payment operator in Poland offering innovative solutions for e-commerce. Using Przelewy24 allows you to carry out transactions on all devices and use many payment methods – fast transfers, BLIK, card payments, mobile payments (Apple Pay, Google Pay), electronic wallets and instalments.

Przelewy24, owned by PayPro S.A., is a team of over 250 experts and specialists. We have been present on the payment market for 19 years, supporting e-commerce companies in their development. In 2020, we joined forces with Dotpay and eCard. Our goal is to make online payments more accessible, secure and user-friendly.

Security

Payment Card Industry Data Security Standard
SSL Certificate ensures protection for websites as well as confidentiality of data transferred electronically, enables coding any service provided through the Internet. This security measure makes it impossible to intercept the data passed by means of Internet websites. Website users are absolutely sure that they safely contact a proper service. Przelewy24 system is based on SSL - Thawte Technologies Inc security certificate. Thawte Certificates are recognized as trustworthy by all Internet search engines. PCI Level1

ISO/IEC 27001:2013 Information Security Management System standard
The ISO 27001 standard specifies the requirements for establishing, implementing, maintaining, monitoring and improving an organization's information security management system. Obtaining the ISO 27001 certification means that PayPro SA has properly implemented a system for managing and protecting information and assets. It is also another confirmation of compliance with legal requirements.

Test DAta
These test data will not work with Frontend. Frontend is a payment form that is provided by PAYONE Platform (URL https://frontend.pay1.de/frontend/v2/ or https://secure.pay1.de/frontend/). These test data will work with Server-API / Client-API / shop modules (e.g. Magento, Oxid, Shopware, …).
Login Password

sandbox

sandbox

Integrations

POST Request - Pre-/ Authorization

Specials are:

- genericPayment(calculation) is used for the calculation of installment plans
- genericPayment(profile) is used for retrieval of account settings from Ratepay

Account Parameters
request
required
Fixed Value: preauthorisation/authorization
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
clearingtype
required
Fixed Value sb
onlinebanktransfertype
required
Fixed Value P24

reference
required
Format CHAR(1..20)
Permitted Symbols [0-9][a-z][A-Z], .,-,_,/

Merchant reference number for the payment process (case insensitive)

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required

Format List

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples

EUR

USD

GBP

narrative_text
optional
Format CHAR(1..81)

Dynamic text element on account statements.

(3 lines with 27 characters each) and credit card statements.

Personal Data Parameters
firstname
required
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use

"company" or "lastname" or "firstname" plus "lastname"

lastname
required
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use

"company" or "lastname" or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

Company name, required for B2B transactions (if add_paydata[b2b] = “yes”)

street
required
Format CHAR(1..50)

Street number and name (required: at least one character)

zip
required
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]
Postcode
city
required
Format CHAR(2..50)

City of customer

country
required
Format List
Permitted values ISO 3166 2-letter-codes
Samples
DE / GB / US

Specifies country of address for the customer.

Some countries require additional information in parameter "state"
email
required
Format CHAR(5..254)
Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters

Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters.
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

email-address of customer

birthday
optional
Format DATE(8), YYYYMMDD
Samples
20190101
19991231

Date of birth of customer

telephonenumber
optional

Telephone number

Bank transfer parameter
bankcountry
required
Format LIST
Account type/ country for use with BBAN (i.e. bankcode, bankaccount): PL

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

iban
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

Bank Identifier Code to be used for payment or to be checked

bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

Article Parameters
it[n]
optional
Format LIST
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount
id[n]
optional
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/

International Article Number (EAN bzw. GTIN)

Product number, SKU, etc. of this item

pr[n]
optional
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]

Unit gross price of the item in smallest unit! e.g. cent

no[n]
optional
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
optional
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

Response Parameters
Permitted Values
REDIRECT
ERROR
Response Parameter (Redirect)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

redirecturl
Format CHAR(2..2000)

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

Response Parameter (Error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded    
Payload
request=preauthorization mid=54399 aid=54400 portalid=2039743 key=17031f73e2c6f9755788bddfff04169b reference=1232500904 clearingtype=sb onlinebanktransfertype=P24 bankcountry=PL clearingtype=sb amount=19481 currency=PLN email=pepe_przelewy@payone.com mode=test successurl=https://yourdomain.patsy.dev/success backurl=https://yourdomain.patsy.dev/back errorurl=https://yourdomain.patsy.dev/error salutation=Herr firstname=Pepe lastname=Przelewy street=Marszałkowska 5 zip=00-102 city=Warszawa country=PL language=de ip=172.19.0.1
RESPONSE

status=REDIRECT
redirecturl=https://r3.girogate.de/ti/dumbdummy?tx=140153668120
txid=958011863
POST Request Capture

The capture request is used to finalize a preauthorized transaction.

If you use preauth/Capture with installment transactions, the capture request has to be sent right after the preauthorization

Account Parameters
request
required
Fixed Value: preauthorisation/authorization
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
txid
required
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

capturemode
required
Format LIST
Value Comment
completed Set with last capture; i.e.: Delivery completed.
No further capture is allowed.
notcompleted Set with partial deliveries (last delivery with "completed")
Another capture is expected to complete the transaction.

Specifies whether this capture is the last one or whether there will be another one in future.

sequencenumber
optional
Format NUMERIC(1..3)
Permitted values 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Fixed Value EUR
narrative_text
optional
Format CHAR(1..81)

Dynamic text element on account statements
(3 lines with 27 characters each) and credit card statements.

settleaccount
required
Format LIST 
Value Comment
yes

Settlement of outstanding balances is carried out.

no

Do not carry out settlement of outstanding balances, book request only.

Provides information about whether a settlement of balances has been carried out required with capturemode.

Article Parameters
it[n]
required
Format List
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

Parameter it[n] specifies the item type of a shopping cart item.

id[n]
required
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/

International Article Number (EAN bzw. GTIN)

Product number, SKU, etc. of this item

pr[n]
required
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]

Unit gross price of the item in smallest unit! e.g. cent

no[n]
required
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
required
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

va[n]
required
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400]

VAT rate (% or bp)

value < 100 = percent

value > 99 = basis points (e.g. 1900 = 19%)

Response Parameters
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

settleaccount
Format LIST 
Value Comment
yes

Settlement of outstanding balances is carried out.

no

Do not carry out settlement of outstanding balances, book request only.

Provides information about whether a settlement of balances has been carried out required with capturemode.

Response parameters (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payoad

request=capture
mid=54399
aid=54400
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
mode=tes
amount=19481
currency=PLN
capturemode=completed
sequencenumber=1
settleaccount=yes
txid=958011863
Response

tatus=APPROVED
txid=958011863
settleaccount=no    
POST Request Debit

Refund with Ratepay can currently only be ordered via this API, not via the PMI.

Account Parameters
request
required
Fixed Value: preauthorisation/authorization
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
txid
required
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

sequencenumber
required
Format NUMERIC(1..3)
Permitted values 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking. If you use the request debit, the amount must be negative.

currency
required
Fixed Value EUR
settleaccount
optional
Format LIST
Value Comment
yes Settlement of outstanding balances is carried out.
no Do not carry out settlement of outstanding balances, book request only.
auto The system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Article Parameters
it[n]
required
Format List
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

Parameter it[n] specifies the item type of a shopping cart item.

id[n]
required
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/

International Article Number (EAN bzw. GTIN)

Product number, SKU, etc. of this item

pr[n]
required
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]

Unit gross price of the item in smallest unit! e.g. cent

no[n]
required
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
required
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

va[n]
required
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400]Permitted

VAT rate (% or bp)

value < 100 = percent

value > 99 = basis points (e.g. 1900 = 19%)

Response Parameters
status
required
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

settleaccount
Format LIST
value Comment
yes Settlement of outstanding balances has been carried out.
no Settlement of outstanding balances has not been carried out.

Provides information about whether a settlement of balances has been carried out.

Response Parameter (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload
request=debit
mid=54399
aid=54400
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
amount=-19481
currency=PLN
mode=test
bankcountry=PL
sequencenumber=2
txid=958011863    
RESPONSE    

status=APPROVED
txid=958011863
settleaccount=yes