Contents

Przelewy24

PAYMENT PRZELEWY24
Przelewy24 is a Polish real-time bank transfer method. When selecting Przelewy24, customers will be prompted to select their bank and then to sign in to their online banking account. After reviewing the pre-filled payment details, they authorise the payment, before being redirected back to your website. Once completed, you will receive confirmation via a URL notification.

 

Features

Supported customer countries PL
Supported currencies
EUR, PLN
Protect Plus Supported.
Refunds Full and partial refunds supported (permitted for up to 90 days).
After 90 days, the customer must seek refund directly with P24.
Chargebacks
Payments are not subject to chargebacks.

 


 

Configuration

To enable Przelewy24 on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.

 


 

Process overview

1
Initiate the customer

  • Customer agrees to a payment using Przelewy24 on the merchant’s website.
  • Merchant submits AUTH request to initiate the session, including the successfulurlredirect and errorurlredirect.
  • Merchant receives AUTH response, including redirecturl.

2
Redirect to Przelewy24

  • Merchant redirects the customer’s browser to the redirecturl.
  • Customer follows instructions on Przelewy24’s hosted pages to authorise the payment.
  • If successful, the browser is redirected to the successfulurlredirect, a page hosted by the merchant that displays confirmation of payment.
  • If there has been a problem with the payment, the browser is redirected to the errorurlredirect, a page hosted by the merchant that displays an error to the customer.

3
Payment completion

  • At a later time, Przelewy24 will contact Secure Trading with confirmation that funds have been settled.
  • Secure Trading will submit a URL notification to the merchant’s system to confirm funds have settled.
  • Merchant receives the notification and responds to inform Secure Trading the notification was received successfully.

 


 

1. Initiate the customer

When the customer chooses to pay with Przelewy24, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.

 

AUTH request

The example request below is for a Przelewy24 AUTH request:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
    "currencyiso3a": "EUR",
    "requesttypedescriptions": ["AUTH"],
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "paymenttypedescription": "PRZELEWY24",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "PL",
    "billingemail": "[email protected]"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
    'username' => '[email protected]',
    'password' => 'Password1^'
);

$requestData = array(
    'currencyiso3a' => 'EUR',
    'requesttypedescriptions' => array('AUTH'),
    'accounttypedescription' => 'ECOM',
    'sitereference' => 'test_site12345',
    'baseamount' => '1050',
    'paymenttypedescription' => 'PRZELEWY24',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'PL',
    'billingemail' => '[email protected]'
);

$api = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
    "currencyiso3a": "EUR",
    "requesttypedescriptions": ["AUTH"],
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "paymenttypedescription": "PRZELEWY24",
    "successfulurlredirect": "https://www.example.com/success",
    "errorurlredirect": "https://www.example.com/error",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "PL",
    "billingemail" : "[email protected]"
}]}'

 

AUTH response


{
  u'requestreference': u'An3ug1kap',
  u'version': u'1.00',
  u'responses': [{
    u'transactionreference': u'23-86-113',
    u'merchantname': u'Test Merchant',
    u'paymenttypedescription': u'PRZELEWY24',
    u'settleduedate': u'2017-03-16',
    u'baseamount': u'1050',
    u'transactionstartedtimestamp': u'2017-03-16 16:25:08',
    u'errormessage': u'Ok',
    u'settlestatus': u'10',
    u'accounttypedescription': u'ECOM',
    u'errorcode': u'0',
    u'redirecturl': u'https://example.com',
    u'acquirertransactionreference': u'12',
    u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww',
    u'requesttypedescription': u'AUTH',
    u'acquirerresponsemessage': u'PENDING',
    u'operatorname': u'[email protected]',
    u'livestatus': u'0',
    u'currencyiso3a': u'EUR'
  }]
}
array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(18) {
      ["transactionreference"] => string(9) "23-86-113"
      ["merchantname"] => string(4) "Test Merchant"
      ["paymenttypedescription"] => string(10) "PRZELEWY24"
      ["settleduedate"] => string(10) "2017-03-16"
      ["baseamount"] => string(4) "1050"
      ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08"
      ["errormessage"] => string(2) "Ok"
      ["settlestatus"] => string(2) "10"
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["redirecturl"] => string(107) "https://example.com"
      ["acquirertransactionreference"] => string(2) "12"
      ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww"
      ["requesttypedescription"] => string(4) "AUTH"
      ["acquirerresponsemessage"] => string(7) "PENDING"
      ["operatorname"] => string(11) "[email protected]"
      ["livestatus"] => string(1) "0"
      ["currencyiso3a"] => string(3) "EUR"
    }
  }
}
{
  "requestreference": "W23-fjgvn3d9",
  "version": "1.00",
  "responses": [{
    "transactionreference": "23-86-113",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "PRZELEWY24",
    "settleduedate": "2017-03-16",
    "baseamount": "1050",
    "transactionstartedtimestamp": "2017-03-16 16:25:08",
    "errormessage": "Ok",
    "settlestatus": "10",
    "accounttypedescription": "ECOM",
    "errorcode": "0",
    "redirecturl": "https://example.com",
    "acquirertransactionreference": "12",
    "acquirersecret": "q9gy5ppgdyd5fh60kfe2j0f26peu2xww",
    "requesttypedescription": "AUTH",
    "acquirerresponsemessage": "PENDING",
    "operatorname": "[email protected]",
    "livestatus": "0",
    "currencyiso3a": "EUR"
  }]
}

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 Only “ECOM” (e-commerce) is supported.
acquirersecret Alphanumeric 64 This is used by Secure Trading to verify the response from the acquirer. (Your system does not need to verify this)
acquirertransactionreference Alphanumeric including symbols 127 Unique transaction reference assigned by Przelewy24.
baseamount Numeric 13 The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
billingemail Email 255 The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingprefixname Alphanumeric including
symbols
 25 The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
billingfirstname  127 The customer’s billing first name.
billingmiddlename 127 The customer’s billing middle name(s).
billinglastname 127 The customer’s billing last name.
billingsuffixname 25 The suffix of the customer’s billing name (e.g. Bsc).
billingcountryiso2a Alpha 2 The country for the customer’s billing address. This will need to be in ISO2A format.

For a list of country codes supported by Przelewy24, refer to the list found at the top of this page.

currencyiso3a Alpha 3 The currency that the transaction will be processed in (in ISO3A format).

For a list of currency codes supported by Przelewy24, refer to the list found at the top of this page.

errorcode Numeric 5   The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

errordata Alphanumeric 255 Additional information to help troubleshoot the error.
errormessage Alphanumeric 255   This is the corresponding message to the above code.Click here for a full list of errorcode and message values.
errorurlredirect URL 2048 The URL that the customer will be returned to following an error on Przelewy24’s hosted pages.
paymenttypedescription Alpha 20 This value must be submitted as “PRZELEWY24”. This will be returned in the response.
redirecturl URL 255 Redirect the customer’s browser to this URL, to allow them to complete the payment on Przelewy24’s hosted pages.
requesttypedescription Alpha 255 The value in the request must be “AUTH”. This will be returned in the response.
settlestatus Numeric 3 This allows you to determine the state of the Przelewy24 payment. Refer to the Handling the response section below for information on how to best interpret this field.
sitereference Alphanumeric including
underscore
50 The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.
successfulurlredirect URL 2048 The URL that the customer will be returned to following a successful authorisation by Przelewy24.
transactionreference Alphanumeric including
hyphens
25 A unique reference for the transaction assigned by Secure Trading.

 

Handling the response

The settlestatus returned in the AUTH response is used to determine the status of the Przelewy24 payment:

Settle status 10
If the settlestatus is “10”, the payment is pending settlement.

  • The funds have not yet been settled into your bank account.
  • The next step is to redirect the customer’s browser to the redirecturl to complete the payment.

Funds will not be settled into your account until the customer is redirected to Przelewy24’s pages, in order to complete the payment. Read on for further information.

 

  • When there is an update to the settle status of the AUTH, you will receive a URL notification to inform you that the settlestatus has been updated to either “3” or “100”.
  • Further information on the notifications can be found below.

Settle status 3
If the settlestatus is “3”, the payment has been cancelled.

  • The payment has been declined, or has encountered an error.
  • To learn more about why the payment was unsuccessful, you will need to look at the errorcode. e.g. “70000” indicates that the payment was declined. Click here for a full list of error codes.

In addition to the above, we also recommend following our Best practices.

 


 

2. Redirect to Przelewy24

Your system will need to redirect the customer’s browser to the redirecturl, which is a page hosted by Przelewy24, in order to process the payment. At a later time, the customer will be redirected back to either the successfulurlredirect or the errorurlredirect provided in the AUTH request.

Status good
If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on Przelewy24’s pages.
Recommended actions: Display confirmation that the payment was successful.
Status attention
If the customer is redirected to the errorurlredirect:
The customer encountered a problem that has prevented them from completing the payment.
Recommended actions: Inform the customer that there was a problem with the payment, displaying sufficient transaction details for the customer to query the payment attempt.
Info
When testing, you will be displayed the sandbox as provided by Przelewy24. To complete a test transaction, you will need to follow the instructions displayed on screen. Please contact your account manager for test credentials to enter while on the sandbox.

 


 

3. Payment completion

Once the customer returns from Przelewy24’s hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively. After some time has passed, you will receive a URL notification informing you that settlement has occurred (or alternatively that an issue has arisen that has prevented settlement from being completed).

 

Settlement

PAYMENT
The settlement process for Przelewy24 differs from the standard process followed with card-based payment methods.

Once a payment has been processed with Przelewy24, funds will not be transferred into your account immediately until the settlement process has been completed. When we receive confirmation that the funds have been settled, we will submit a URL notification to your system.

URL
The notification may not be sent immediately after processing the AUTH. For this reason, you should display a success or error message to the customer immediately after they return from Przelewy24’s hosted pages, and not wait for this notification.

 

In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.

 

Notification

When creating your Przelewy24 account, our Support team will assist you in configuring a URL notification to inform you of updates to pending payments.

You will need to check the contents of each notification received and respond accordingly by following the processes outlined here. In the notification received, you will need to look at the updated settlestatus value:

 


 

 

Testing

You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.

Info
Requirements

You will need to contact our Support team, providing your Przelewy24 test account details. We will then configure your test site reference to connect directly to the Przelewy24 testing environment.

When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the Przelewy24 testing environment to simulate a payment. Other than this, the process will be exactly the same as processing live payments.

 


 

Refunds

After processing a payment with Przelewy24, it is possible to pay the customer back by submitting a REFUND request.

Info
Refunds for Przelewy24 are settled immediately (settlestatus “100”).

 

Requirements

The REFUND request and response for Przelewy24 payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.