1. RECEIVING PAYMENTS¶
There are two methods of accepting payments from customers. The first method (presented in subchapter Basic version) is intended for Sellers who do not have e-shops or services integrated with the Dotpay system.
The second method (presented in subchapter Advanced version) is designed for e-shops and services, at which the payment process begins (e.g. customer is ordering some item).
Dotpay payment gateway is located at:
- production environment: https://ssl.dotpay.pl/t2/
- test environment : https://ssl.dotpay.pl/test_payment/
Caution
Because of security policy, Dotpay payment gateway cannot be embedded in iframe (X-Frame-Options:SAMEORIGIN).
1.1. Basic version¶
To redirect the customer to payment, all data can be saved in the URL - link. In the example below, link_pre-id01| id sklepu, amount , currency and description is passed to the payment form:
https://ssl.dotpay.pl/t2/?id=123456&amount=123.00¤cy=PLN&description=Test
The above address redirects by the method: GET.
Other parameters that can be passed in this way to Dotpay payment form are listed in Table 1 and Table 2 of this document.
After logging to My Dotpay panel you can use menu . This menu allows to determine such data as: id , amount , currency , description and lang .. Generating a payment request means creating a special key which allows defining the given parameters thus prevent modification of payment data.
Links generated this way can be listed and modified (e.g. amount ), in the above mentioned menu.
Key example: rfhu4jb5ym657g3xluf4bbqfmbyj6t17
Using such a generated key you can elicit payment site from the link:
https://ssl.dotpay.pl/t2/?pid=rfhu4jb5ym657g3xluf4bbqfmbyj6t17
In case payment language was NOT specified or defined language was removed, parameter lang allows you to determine language on payment page.
Example of payment page with added parameter lang = en to present payment form in English:
https://ssl.dotpay.pl/t2/?pid=rfhu4jb5ym657g3xluf4bbqfmbyj6t17&lang=en
Additionally, you can attach the ignore_last_payment_channel = 1 parameter to the payment link in order to ignore the payment method recently chosen by the customer (stored in the browser’s memory), so that he will always see the full list of available payment methods.
https://ssl.dotpay.pl/t2/?pid=rfhu4jb5ym657g3xluf4bbqfmbyj6t17&ignore_last_payment_channel=1&lang=pl
Such a prepared link with a key can be sent for example by e-mail to a buyer.
Generated payment link with a key can be used repeatedly until erased by the Merchant in My Dotpay panel ().
Caution
By default for shop is also required sending the chk parameter. In the case of generating payment links from seller administration panel the chk parameter is automatically added to the link.
However for links generated manually or using seller administration panel API chk value has to be calculated and added separately.
Exemplary link is going to look like:
https://ssl.dotpay.pl/t2/?chk=c7dc9bb5d0c726a44cf478d3b78390011641f0f52c3db3c0ba6b9a658c6fb400&pid=poup7bulug5996r7fjc2jl056vfqbgp2
How to calculate chk has been described in Redirection parameters integrity protection (CHK) section. .
Note
If shop doesn’t use automatic notifications URLC and confirmation of each transaction is carried out after manual verification of correctness of booked amount and currency for a specific order, the maturity of the chk parameter may be disabled. For this purpose please contact us by email at the address administracja@dotpay.pl
1.1.1. Example forms of payments / donations¶
Caution
For proper functioning below forms require prior modification of parameters specified in section CONFIGURATION, for example inserting appropriate account id in which payment is to be made (id number can be found after logging in to the seller administration panel tab ,this is a 6-digit number placed after the sign # in column ). Otherwise, you will be redirected to the page with error message.
Customer after clicking button is redirected to the Dotpay payment form (https://ssl.dotpay.pl/t2/) to choose a payment method. Simultaneously with the POST method are sent the following parameters:
- seller’s ID (e.g.
id= 123456)- transaction’s amount (e.g.
amount= 12.42)currency- transaction’s description (e.g.
description= Payment for invoice #12345/2014)- redirection’s type (e.g.
type= 0)- return address after payment (e.g.
url= https://www.example.com)- return button text (e.g.
buttontext= Return)
Caution
The following forms don’t include a function to calculate the mandatory chk parameter. This functionality should be completed on its own or contact Dotpay administration department (administracja@dotpay.pl) in order to disable the verification of chk . Please read the Security of payment integration chapter before.
The form may also send other, optional parameters of which description can be found in the tables in the further parts of documentation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | <html>
<head>
<meta charset="UTF-8">
</head>
<!-----------------------------
Górna część strony
------------------------------------->
<!--- copy start--->
<script type="text/javascript" src="http://code.jquery.com/jquery-3.5.1.min.js"></script>
<style>
div.dotpay_form_donation {
font-family: sans-serif;
text-align: center;
}
div.dp_temat {
font-size: 1.5em;
font-style: inherit;
font-weight: bold;
color: #334242;
}
input#dp_def_amount {
border: 1px solid #bbb;
border-radius: 3px;
height: 50px;
font-size: 1.3em;
background: #dae6ff;
text-align: center;
font-weight: 500;
cursor: pointer;
}
input#dp_kwota {
border: 1px solid #bbb;
border-radius: 3px;
font-size: 1.2em;
background: #f8f6fb;
text-align: center;
}
input#dp_other_amount {
font-size: 1em;
background: #daedff;
border: 1px solid #bbb;
border-radius: 3px;
padding: 5px;
text-align: center;
cursor: pointer;
}
button#dp_buttomDarowizna {
font-size: 1.3em;
background: #ae3131;
border: 1px solid #bbb;
border-radius: 3px;
padding: 5px;
text-align: center;
cursor: pointer;
color: #f3f0ed;
letter-spacing: 0.1em;
}
table.tbl_center{
margin-left: auto;
margin-right: auto;
}
</style>
<script>
$(document).ready(function () {
$("#dp_buttomDarowizna").click(function () {
if ($('#dp_kwota').val().trim() === '') {
$("#dp_kwota_alert").text("Proszę wybrać lub wprowadzić kwotę darowizny.").show();
$('#dp_kwota_alert').css("display", "inline").fadeOut(5000);
return false;
}
});
});
</script>
<div class="dotpay_form_donation">
<form action="https://ssl.dotpay.pl/t2/" method="post" target="_parent">
<div class="dp_temat">Wybierz kwotę darowizny</div>
<p>
<input type="button" id="dp_def_amount"
onClick="$('#dp_kwota').val('10'); $('#dp_kwota').prop('readonly', true);$('#dp_kwota').attr('style','color:blue');$('#dp_other_amount_txt').html('Wybrana Kwota')"
value="10.00 zł" />
<input type="button" id="dp_def_amount"
onClick="$('#dp_kwota').val('20'); $('#dp_kwota').prop('readonly', true);$('#dp_kwota').attr('style','color:blue');$('#dp_other_amount_txt').html('Wybrana Kwota')"
value="20.00 zł" />
<input type="button" id="dp_def_amount"
onClick="$('#dp_kwota').val('50'); $('#dp_kwota').prop('readonly', true);$('#dp_kwota').attr('style','color:blue');$('#dp_other_amount_txt').html('Wybrana Kwota')"
value="50.00 zł" />
<input type="hidden" name="type" value="0" />
<input type="hidden" name="currency" value="PLN" />
<table class="tbl_center">
<tr>
<td>
<br><input type="button" id="dp_other_amount"
onClick="$('#dp_kwota').prop('readonly', false);$('#dp_kwota').attr('style','color:brown');$('#dp_other_amount_txt').html('<span style=\'color:brown\'>Wprowadź kwotę</span>')"
value="Inna kwota" />
</td>
<td>
<br><span id="dp_other_amount_txt">Wybrana Kwota</span>:
<input type="text" name="amount" id="dp_kwota" size="5" readonly
pattern="^([1-9])((\.\d{1,2})?)$|^((?!0)(\d){1,5})((\.\d{1,2})?)$|^(1(\d{5})(.\d{1,2})?)$|^(200000(.[0]{1,2})?)$"
placeholder="np. 100" maxlength="9" size="9"
title="Kwota powinna zawierać się w przedziale 1 - 200000 PLN. Dozwolony format to np: 100 lub 152.43"
oninput="this.value = this.value.replace(/[^0-9\.]/g, ''); this.value = this.value.replace(/(\..*)\./g, '$1');" />
PLN<br />
</td>
</tr>
</table>
<!--------------------------------- KONFIGURACJA --------------------------------------->
<!---- zamiast 000000 nalezy podstawic numer ID w Dotpay -->
<input type="hidden" name="id" value="000000" />
<!--- Tytuł transakcji --->
<input type="hidden" name="description" value="Testowa płatność" />
<!--- Ardes URL powrotu --->
<input type="hidden" name="url" value="http://www.example.com" />
<!-- Tekst przycisku powrotu do sklepu --->
<input type="hidden" name="buttontext" id="buttontext" value="Powrót do sprzedawcy" />
</p>
<!--------------------------------- KONIEC KONFIGURACJI --------------------------------------->
<p><br><button class="dp_buttomDarowizna" id="dp_buttomDarowizna">Wpłać darowiznę</button></p>
</form>
<div id="dp_kwota_alert" style="color:red;"></div>
</div>
<!--- copy end--->
<!-----------------------------
Dolna część strony
------------------------------------->
</html>
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | <html>
<!-----------------------------
Górna część strony
------------------------------------->
<div style="text-align: center;">
<form action="https://ssl.dotpay.pl/t2/" method="post" target="_parent">
<p style="font-size: 18px">Wybierz kwotę darowizny</p>
<input type="radio" name="amount" value="10.00" />10.00 zł
<input type="radio" name="amount" value="20.00" />20.00 zł
<input type="radio" name="amount" value="50.00" checked />50.00 zł<br />
<input type="hidden" name="type" value="0" />
<input type="hidden" name="currency" value="PLN" />
<!--------------------------------- KONFIGURACJA --------------------------------------->
<!---- zamiast 000000 nalezy podstawic numer ID w Dotpay -->
<input type="hidden" name="id" value="000000" />
<!--- Tytuł transakcji --->
<input type="hidden" name="description" value="Testowa płatność" />
<!--- Ardes URL powrotu do sklepu--->
<input type="hidden" name="url" value="http://www.example.com" />
<!-- Tekst przycisku powrotu do sklepu --->
<input type="hidden" name="buttontext" value="Powrót do sprzedawcy" />
<!--------------------------------- KONIEC KONFIGURACJI --------------------------------------->
<p><br><button class="buttomDarowizna">Wpłać darowiznę</button></p>
</form>
</div>
<!-----------------------------
Dolna część strony
------------------------------------->
</html>
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | <html>
<meta charset="utf-8">
<!-----------------------------
Górna część strony
------------------------------------->
<div style="text-align: center;">
<form action="https://ssl.dotpay.pl/t2/" method="post" target="_parent">
<p style="font-size: 18px">Wybierz kwotę darowizny</p>
<input name="description" value="Darowizna na cele statutowe" type="hidden">
<input name="amount" id="kwota" size="6" value="" type="text" required
pattern="^([1-9])((\.\d{1,2})?)$|^((?!0)(\d){1,5})((\.\d{1,2})?)$|^(1(\d{5})(.\d{1,2})?)$|^(200000(.[0]{1,2})?)$"
placeholder="np. 10" maxlength="9" size="9"
title="Kwota powinna mieścić się w przedziale 1 - 200 000 PLN. Dozwolony format to np: 10 lub 10.00">PLN
<!--------------------------------- KONFIGURACJA --------------------------------------->
<!---- zamiast 000000 nalezy podstawic numer ID w Dotpay -->
<input name="id" value="000000" type="hidden">
<!--------------------------------- KONIEC KONFIGURACJI ---------------------------------->
<p><br><button class="buttomDarowizna">Wpłać darowiznę</button></p>
</form>
<br>
</div>
<!-----------------------------
Dolna część strony
------------------------------------->
</html>
|
1.2. Advanced version¶
Direct version is based on direct integration with Dotpay payment system. In this version a customer after making an order will be redirected from the seller’s web site to Dotpay payment form. Client located on the Seller’s web page, after clicking on the button to confirm payment (e.g. pay by Dotpay) should be redirected to https://ssl.dotpay.pl/t2/.
In the next step the customer makes the payment with use of selected payment channel. If there is a defined return address and right parameter value of type , on the payment confirmation page will be displayed a button to return to the seller web page.
A seller may also specify URLC address on which information about the status of the transaction will be sent via POST method. The address can be defined by logging into Dotpay () or sent when you initiate the payment as a parameter named urlc .
In the second case you should unlock for your store getting the urlc parameters from external sources, ie deselect the option: Block external urlc () . With such a configuration a seller can define other URLC addresses for each payment.
The principle of URLC operation notifications is described in chapter URLC CONFIRMATION
1.2.1. Diagram 1. Example of the payment process in the following diagram and description:¶
- Buyer places an order in shop
- after completing shopping cart customer selects payment method with Dotpay and is redirected to the payment format
- where presented is channel list.
- Customer makes a choice
- and is redirected to the bank.
- The login page for banking is shown
- where he enters credentials and confirms the transfer.
- After logging out is following return to the Dotpay website.
- During waiting for confirmation
- the browser periodically inquires about the status of payment.
- Bank informs Dotpay about the final status of payment
- and this information is presented to payer.
Note
Steps 13 - 18 are optional (depending on the model of integration) and don’t have effect on payment process.
- Buyer clicks on return button
- and is redirected to the store
- During waiting for confirmation
- the browser periodically inquires about the status of payment.
- After receiving URLC notification
- shop confirms that customer has paid for order.
1.2.2. Table 1. (Basic parameters)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
api_version |
API version - according to which the system sends URLC confirmation (see chapter RECEIVING PAYMENT CONFIRMATION (URLC CONFIRMATION)). Sending parameter overrides default shop ( Available values:
Important If shop configuration () has API version set to something else than Example:
|
id |
Account ID for which payment is made. ID can be found in the administration panel in tab, it is a 6-digit number after # . column.
Example:
|
amount |
The amount of the transaction given with centesimal part (always two places after the separator). Centesimal separator is a dot (.) type: string min length: 1 max length: 10 examplary regular expression (for amount in the range 0.01 - 200000.00) : ^0\.(0)([1-9])$|^0\.(([1-9])(\d)?)$|^([1-9])((\.\d{1,2})?)$|^((?!0)(\d){1,5})((\.\d{1,2})?)$|^(1(\d{5})(.\d{1,2})?)$|^(200000(.[0]{1,2})?)$
Example:
|
currency |
This parameter determines the currency in which the
Example:
|
description |
Payment description.
|
chk |
Checksum used to verify sent data integrity. Description of functionality can be found in Redirection parameters integrity protection (CHK) section. Important Required by default. |
1.2.3. Table 2. (Additional parameters)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
channel |
This parameter defines which payment channel will be selected after redirecting client to Dotpay payment form. Numerical values only available (see ATTACHMENT 1 - PAYMENT CHANNELS) Example: Seller wishes 1 to select a mTransfer channel by default. List of available payment channels for given shop (
Example: https://ssl.dotpay.pl/t2/payment_api/channels/?id=123456&amount=301.00¤cy=PLN&lang=pl&format=json |
ch_lock |
Forcing the channel specified in the The parameter Available values: 0 - channel will not be forced (default) 1 – force the selected Example: Sending parameters |
ignore_last_payment_channel |
Sending parameter will cause Dotpay website to ignore last payment channel used by costomer (saved in their browser data), i.e. all available payment channels will be shown as if it was first payment. By default for consecutive payments last used channel is shown with an option to choose another one. Available values: 1– ignore last chosen channel Example:
|
channel_groups |
This parameter defines which channel groups will be displayed after redirecting client to Dotpay payment form (by default all are presented). When using this parameter it is recommended to use Available values:
Parameter can have more than one group as a value, in this case letters have to be separated with commas. Example:
|
url |
This parameter defines the Internet address (HTTP or HTTPS) to which buyer is expected to return after payment. Behavior of
Example:
Important Parameter status informs only about the payment process. Information about the current status of the transaction (new, completed, rejected, etc.) contains a variable Example:
|
type |
This parameter defines a method of redirection to the seller’s web page. Parameter value influences
Important If direct redirection mechanism ( Example:
|
buttontext |
The content that appears on a button to return to the seller website. Default text is Back to shop.
Example:
|
bylaw |
Parameter informing client has accepted Dotpay Sp. z o.o. Regulations of Payments and cookies policy. If this parameter is used, seller should display a checkbox to the client with information as follows.
Example:
|
personal_data |
Parameter informing about displaying to the Payer information on the processing of personal data by Dotpay Sp. z o.o..
Example:
|
urlc |
Web address (HTTP or HTTPS) to receive parameters confirming or denying completion of the transaction. A detailed description of URLC confirmation is described further in chapter RECEIVING PAYMENT CONFIRMATION (URLC CONFIRMATION). It is recommended for the address to lead directly to the receiving file. If any 301 or 302 redirections occur in the way (which allow HTTP method to change), notification from Dotpay might be empty. Another way is to use 307 / 308 redirections on the server, since they do not allow such behavior. Sending parameter overrides default shop ( Important If option Block external urlc (menu ) is checked, Important If option HTTPS verify (menu ) is checked, address has to use HTTPS protocol. type: string max length: 1000 Example:
|
expiration_date |
Payment request expiration date, according to the Europa / Warsaw time zone. When using this parameter it is recommended to sign the request sent to Dotpay. Description of signature creation can be found in Redirection parameters integrity protection (CHK) section.
Example:
|
control |
Control parameter allows you to store sequence of data. Unchanged parameter is sent to the Merchant’s service in URLC confirmation.
Example:
|
firstname |
This parameter identifies the first name of the person making the payment.
Example:
|
lastname |
This parameter identifies the surname of the person making the payment.
Example:
|
email |
E-mail address of a person making the payment. Payment confirmation will be sent at this address.
Example: |
street |
Street name. A part of the address of the buyer.
Example:
|
street_n1 |
Building number. A part of the address of the buyer.
Example:
|
street_n2 |
Flat number. A part of the address of the buyer.
Example:
|
state |
Additional address data. A part of the address of the buyer.
Example:
|
addr3 |
Additional address data. A part of the address of the buyer.
|
city |
City name. A part of the address of the buyer.
Example:
|
postcode |
Postal code. A part of the address of the buyer.
Example:
|
phone |
Buyer’s phone number.
|
country |
Country name. A part of the address of the buyer. The name should be given in accordance with the ISO 3166-1 (alfa-2 or alfa-3) or a text English short name (using title case).
Example:
|
lang |
Defines the language of web page and payment forms.
Example:
|
customer |
Recipient and shipping data. Parameter required for some channels (eg. 95 /PayPo/ ). This data should be in JSON a format and then encoded using Base64. List of data for this parameter and it’s encoding has been described in Shipping and payer data section.
type: string Example:
|
deladdr |
Delivery address. Parameter is used by Dotpay system only for informational purposes.
Example:
|
p_info |
With use of this parameter a seller can define the name of a payment receiver which will be displayed on the payment Dotpay website. In case the name is not provided the default name will be displayed. Sending parameter overrides default shop ( type: string max length: 300 Example:
|
p_email |
This parameter describes an e-mail address, which will be seen by a customer. It overwrites an email address provided during registration process. Sending parameter overrides default shop (
Example:
|
pid |
Payment link for a given store (
Example:
The
or with additional parameters:
|
blik_code |
BLIK code confirming payment with given channel. In standard procedure the code is entered by customer on payment provider website after choosing BLIK channel. Sending the parameter in redirection allows shortening payment process because code is entered on shop’s website with other order data.
Example:
|
gp_token |
Encoded using the Base64 function token received from Google Pay after the merchant’s implementation of the Google Pay API. It contains encrypted data of the tokenized pay card used to process the payment. Sending the parameter in redirection allows shortening payment process because the authentication of the payer’s card data is already on the seller’s store page.
Example:
|
ap_token |
Encoded using the Base64 function token received from Apple Pay after the merchant’s implementation of the Apple Pay. It contains encrypted data of the tokenized pay card used to process the payment. Sending the parameter in redirection allows shortening payment process because the authentication of the payer’s card data is already on the seller’s store page/payer device.
Example:
|
2. RECEIVING PAYMENT CONFIRMATION (URLC CONFIRMATION)¶
In order to inform the Seller about the executed operation (transaction) an URLC confirmation mechanism has been created (HTTP request asynchronous connection, callback) which is sent by POST method and fully independent from a buyer’s action.
Confirmations are directed to the seller’s address which can be set in settings of a given shop in Dotpay panel (menu ) or to the address read from urlc sent by the Seller’s system in redirection of a Buyer to the payment site (unless urlc parameter has been unblocked from external sources, i.e. uncheck Block external URLC option). If URLC notification address DON’T use HTTP secure protocol (i.e. HTTPS) remember to deactivate HTTPS verify and SSL certificate verify options in menu mentioned above.
Verifying whether transaction is unique in merchant’s system should NOT be based only on value of control == control parameter. If for some reason customer redirects multiple times between shop and Dotpay or Dotpay and bank, there is a possibility of receiving for example 2 notifications with contradicting status for the same control. Transaction should be identified by taking as well operation_number into account, transaction id given by Dotpay.
Caution
No verification of a amount == operation_original_amount , currency == operation_original_currency and signature parameters on a merchant’s site is unsecure and may cause financial loss.
Content and result of URLC notifications is available in Dotpay panel by showing given operation details (by clicking on its number) in list menu. In the same place there is also an option to resend those notifications.
Caution
For correctly received URLC confirmation by the Seller’s system Dotpay expects an answer
OK
(only two capital letters, nothing more – encoding UTF8 without BOM, HTTP response status code 200). OK is a correctly received and processed confirmation, for example:
echo "OK";
When a different answer than OK is reversed by the Seller’s system Dotpay system will repeat confirmations (every few, several minutes). The X-Dotpay-URLC-Number parameter may be passed in the notification header, which will be one value higher than the previous one, counting from ‘0’ as the first message.
Parameters and optional values sent in URLC confirmations to the Seller’s system have been presented in the table below.
Note
Optional parameters are not returned by default. To activate them contact Dotpay tech support ( tech@dotpay.pl ).
Note
By default system sends notifications URLC only for payment operations for completed and rejected status (listed in table below). To enable notifications for other operations and statuses contact Technical Support at tech@dotpay.pl .
2.1. Table 3. (Parameters sent by Dotpay back to merchant’s system)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
id |
Account ID.
Example:
|
operation_number |
Transaction number.
Example:
|
operation_type |
Transaction type. Available values:
Example:
|
operation_status |
Transaction status. Available values:
Detailed description of operation statuses are presented in chapter ATTACHMENT II - OPERATION STATUSES DESCRIPTION Note completed and rejected status is final and will not change in the future. Example:
|
operation_amount |
Transaction amount. The centesimal separator is a dot (.)
Example:
|
operation_currency |
The currency in which the amount parameter is given. Format according to ISO 4217 standard. Example:
|
operation_withdrawal_amount |
Optional parameter indicating the operation withdrawal amount. Example:
|
operation_commission_amount |
Optional parameter indicating the operation commission amount. The parameter is presented as a negative amount, and therefore contains a - sign. Example:
|
is_completed |
Optional parameter indicating the transaction marked as completed in the seller’s panel. Example:
|
operation_original_amount |
The amount taken from typ: string min length: 1 max length: 10 Example:
Important No verification of a |
operation_original_currency |
The currency taken from Example:
Important No verification of a |
operation_datetime |
Date and time of transaction’s status change. Format: YYYY-MM-DD hh:mm:ss Example:
|
operation_related_number |
Number of related transaction, if any exists (e.g. in case of a refund). Format according to regular expression:
Example:
If a confirmation regards refund number M9876-5432 executed for an original operation M1234-5678 the parameter will accept original transaction number value which is M1234-5678. |
control |
This value corresponds with typ: string max length: 1000 Example:
|
description |
This value corresponds with typ: string min length: 1 max length: 255 Example:
|
email |
E-mail address of a person making the payment. typ: string max length: 100 Example: |
p_info |
Name of a payment receiver which was displayed on the Dotpay payment website during Customer payment making. typ: string max length: 300 Example:
|
p_email |
E-mail address which was displayed for customer as contact to Seller. typ: string max length: 100 Example:
|
credit_card_issuer _identification_number |
Optional parameter. Masked payment card number with which payment has been made. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_masked_number |
Optional parameter. Masked payment card number with which payment has been made. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_expiration_year |
Optional parameter. Year expiration date of a payment card, which payment has been made. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_expiration_month |
Optional parameter. Month expiration date of a payment card, which payment has been made. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_brand_codename |
Optional parameter. Payment card brand with which payment has been made. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_brand_code |
Optional parameter. Payment card brand code with which payment has been made. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_unique_identifier |
Optional parameter. The unique identifier of the card registered in Dotpay. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Example:
|
credit_card_id |
Optional parameter. Payment card ID given by Dotpay system. Important In order for parameter to be sent, options HTTPS verify and SSL certificate verify (menu ) have to be enabled. Additionally given account ( Example:
|
channel |
Payment channel (method) used by the buyer. For available values see ATTACHMENT 1 - PAYMENT CHANNELS . Example:
|
channel_country |
Optional parameter. Indicates the country of the payment instrument from which payment was made. Format: ISO 3166-1 (alpha-3). Example:
|
geoip_country |
Optional parameter. Indicates the location of the country resulting from IP address from which the payment was made. Format: ISO 3166-1 (alpha-3). Example:
|
payer_bank_account_name |
Optional parameter. Account owner name registered in the bank. Example:
|
payer_bank_account |
Optional parameter. The bank account number from which the payment was made. Format compliant with the IBAN. Example:
|
payer_transfer_title |
Optional parameter. The original title of the operation registered in the payer’s bank. Example:
|
blik_voucher_pin |
Optional parameter. PIN for the issued BLIK vouchers. Example:
|
blik_voucher_amount |
Optional parameter. The nominal value of issued voucher BLIK. Example:
|
blik_voucher_amount_used |
Optional parameter. Actual amount paid from the issued BLIK voucher. This amount may be equal to or less than the face value of the Example:
|
channel_reference_id |
Optional parameter. Additional details of the operation, e.g. bank reference number. Example:
|
operation_seller_code |
Optional parameter (only available by prior arrangement). A reply code for a rejected transaction that describes the possible reason for a transaction being refused. Sample codes are presented in table (equivalent to ‘seller_code’ in api seller). Example:
|
signature |
The checksum created by an acronym function SHA-256 being a concatenation of the above mentioned parameters according to the following formula: PIN + Important Sign + in the above formula has been used only for its readability. It is NOT used to calculate the checksum. If in sent notification some parameter is NOT present, should be considered as null value or omitted in the calculation. Note PIN used to calculate a signature parameter is a string of characters which should be generated by a Merchant ( It is only used to create the checksum and should NOT be sent along other payment data! Important No verification of a |
2.2. An example of calculating the signature parameter¶
An example of calculating parameter signature value is presented below in PHP.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | <?php
$PIN = "Np3n4QmXxp6MOTrLCVs905fdrGf3QIGm";
$sign =
$PIN.
$_POST['id'].
$_POST['operation_number'].
$_POST['operation_type'].
$_POST['operation_status'].
$_POST['operation_amount'].
$_POST['operation_currency'].
$_POST['operation_withdrawal_amount'].
$_POST['operation_commission_amount'].
$_POST['is_completed'].
$_POST['operation_original_amount'].
$_POST['operation_original_currency'].
$_POST['operation_datetime'].
$_POST['operation_related_number'].
$_POST['control'].
$_POST['description'].
$_POST['email'].
$_POST['p_info'].
$_POST['p_email'].
$_POST['credit_card_issuer_identification_number'].
$_POST['credit_card_masked_number'].
$_POST['credit_card_expiration_year'].
$_POST['credit_card_expiration_month'].
$_POST['credit_card_brand_codename'].
$_POST['credit_card_brand_code'].
$_POST['credit_card_unique_identifier'].
$_POST['credit_card_id'].
$_POST['channel'].
$_POST['channel_country'].
$_POST['geoip_country'].
$_POST['payer_bank_account_name'].
$_POST['payer_bank_account'].
$_POST['payer_transfer_title'].
$_POST['blik_voucher_pin'].
$_POST['blik_voucher_amount'].
$_POST['blik_voucher_amount_used'].
$_POST['channel_reference_id'].
$_POST['operation_seller_code'];
$signature=hash('sha256', $sign);
?>
|
3. ADDITIONAL FEATURES¶
3.1. Redirection parameters integrity protection (CHK)¶
In order to protect redirection parameters integrity Dotpay system allows to sign their values.
Signature should be sent as additional parameter called chk (alongside rest of the payment parameters). chk value is checksum calculated with SHA‑256 algorithm using parameter concatenation described below keeping the order.
PIN + api_version + lang + id + pid + amount + currency + description + control + channel + credit_card_brand + ch_lock + channel_groups + onlinetransfer + url + type + buttontext + urlc + firstname + lastname + email + street + street_n1 + street_n2 + state + addr3 + city + postcode + phone + country + code + p_info + p_email + n_email + expiration_date + deladdr + recipient_account_number + recipient_company + recipient_first_name + recipient_last_name + recipient_address_street + recipient_address_building + recipient_address_apartment + recipient_address_postcode + recipient_address_city + application + application_version + warranty + bylaw + personal_data + credit_card_number + credit_card_expiration_date_year + credit_card_expiration_date_month + credit_card_security_code + credit_card_store + credit_card_store_security_code + credit_card_customer_id + credit_card_id + blik_code + credit_card_registration + surcharge_amount + surcharge + ignore_last_payment_channel + vco_call_id + vco_update_order_info + vco_subtotal + vco_shipping_handling + vco_tax + vco_discount + vco_gift_wrap + vco_misc + vco_promo_code + credit_card_security_code_required + credit_card_operation_type + credit_card_avs + credit_card_threeds + customer + gp_token + blik_refusenopayid + auto_reject_date + ap_token + id1 + amount1 + currency1 + description1 + control1 + … + id(n) + amount(n) + currency(n) + description(n) + control(n)
Caution
Character + was used only for visual clarity. It is NOT used to calculate the signature.
In case of links generated using seller administration panel ( pid ), calculation of chk value is done on basis of PIN + pid (according to the above formula), don’t take into account the parameters from which pid was created.
If given parameter is not used in redirection it has to be skipped.
Note
PIN used to calculate a chk parameter is a string of characters which should be generated by a Merchant ( id ) in My Dotpay panel (menu ).
Caution
Default shop ( id ) configuration verifies chk parameter sent in payment request.
If it’s absent or its value is incorrect, error will be returned.
chk verification isn’t the only payment security mechanism, in some cases it might prove to be unnecessary. chk verification allows to check parameters in the first step of payment: redirecting customer to Dotpay. The most important part is compare amount and currency from payment created in Dotpay with data saved in seller’s service - RECEIVING PAYMENT CONFIRMATION (URLC CONFIRMATION).
If your shop doesn’t have chk verification enabled (it’s optional or completely disabled), ask Dotpay to change your account’s settings.
If you are not sure your integration supports chk, please contact your service provider / programmer responsible for the implementation, or Doptay Tech support (email: tech@dotpay.pl ).
In case you don’t want to use this security measure and are aware of possible implications, you can disable chk for your account ( id ). To do so, send an email to administracja@dotpay.pl .
Below are exemplary functions (PHP) generating POST / GET request with chk .
3.1.1. Basic Example¶
Download this example (change extension to .php): Download example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | <?php
################### https://www.dotpay.pl/developer/doc/api_payment/ ######################################################################
#
# Exemplary function (PHP) generating the correct payment redirection (POST / GET) to Dotpay payment api with parametr 'chk' (checksum).
# You enter the payment data in the parameter: $ParametersArray.
#
#
# Dotpay Sp. z o.o.
# Tech Customer Service: tech@dotpay.pl
# Date: 2020-02-11
#
##############################################################################################################################################
/** --------- BASE CONFIG --------- **/
// Your Dotpay ID shop (6 digits)
$DotpayId = "123456";
// PIN for Your Dotpay ID (copy this from your dotpay panel carefully, without space)
$DotpayPin = "MyDotpayPIN000000j4suuSgMPXlg100";
// Dotpay Environment, available: "test" or "production"
$Environment = "test";
//Redirection method: POST or GET ; recommended method is "POST"
$RedirectionMethod = "POST";
/** --------- end config --------- **/
// ** ----------------------- SAMPLE DATA ------------------------- **/
/* ## SAMPLE PAYMENT DATA IN ## */
// Note! You can use more parameters if You need
// You must give at least: 'amount', 'currency', 'description' (and of course ID and PIN in the configuration of this script)
// see more: https://www.dotpay.pl/developer/doc/api_payment/en/index.html#tabela-1-podstawowe-parametry-przesylane-do-serwisu-dotpay
// and: https://www.dotpay.pl/developer/doc/api_payment/en/index.html#tabela-2-dodatkowe-parametry-przesylane-do-serwisu-dotpay
// ------
$ParametersArray = array(
"api_version" => "dev",
"amount" => "100.00",
"currency" => "PLN",
"description" => "Order no. 567915976",
"url" => "https://www.example.com/thanks_page.php",
"type" => "0",
"buttontext" => "Back to the www.example.com",
"urlc" => "https://www.example.com/urlc_receiver.php",
"control" => "M1231MzaUdLQWR3",
"firstname" => "Jan",
"lastname" => "Nowak",
"email" => "jan.nowak@example.com",
"street" => "Warszawska",
"street_n1" => "1",
"city" => "Krakow",
"postcode" => "12-345",
"phone" => "123456789",
"country" => "POL",
"ignore_last_payment_channel" => 1
);
// ** ----------------------- SAMPLE DATA end ------------------------- **/
## CALCULATE CHECKSUM - CHK
function GenerateChk($DotpayId, $DotpayPin, $ParametersArray)
{
$ParametersArray['id'] = $DotpayId;
$CHkInputString = $DotpayPin.
(isset($ParametersArray['api_version']) ? $ParametersArray['api_version'] : null).
(isset($ParametersArray['lang']) ? $ParametersArray['lang'] : null).
(isset($ParametersArray['id']) ? $ParametersArray['id'] : null).
(isset($ParametersArray['amount']) ? $ParametersArray['amount'] : null).
(isset($ParametersArray['currency']) ? $ParametersArray['currency'] : null).
(isset($ParametersArray['description']) ? $ParametersArray['description'] : null).
(isset($ParametersArray['control']) ? $ParametersArray['control'] : null).
(isset($ParametersArray['channel']) ? $ParametersArray['channel'] : null).
(isset($ParametersArray['url']) ? $ParametersArray['url'] : null).
(isset($ParametersArray['type']) ? $ParametersArray['type'] : null).
(isset($ParametersArray['buttontext']) ? $ParametersArray['buttontext'] : null).
(isset($ParametersArray['urlc']) ? $ParametersArray['urlc'] : null).
(isset($ParametersArray['firstname']) ? $ParametersArray['firstname'] : null).
(isset($ParametersArray['lastname']) ? $ParametersArray['lastname'] : null).
(isset($ParametersArray['email']) ? $ParametersArray['email'] : null).
(isset($ParametersArray['street']) ? $ParametersArray['street'] : null).
(isset($ParametersArray['street_n1']) ? $ParametersArray['street_n1'] : null).
(isset($ParametersArray['city']) ? $ParametersArray['city'] : null).
(isset($ParametersArray['postcode']) ? $ParametersArray['postcode'] : null).
(isset($ParametersArray['phone']) ? $ParametersArray['phone'] : null).
(isset($ParametersArray['country']) ? $ParametersArray['country'] : null).
(isset($ParametersArray['ignore_last_payment_channel']) ? $ParametersArray['ignore_last_payment_channel'] : null);
return hash('sha256',$CHkInputString);
}
## GENERATE FORM TO DOTPAY
function GenerateChkDotpayRedirection($DotpayId, $DotpayPin, $Environment, $RedirectionMethod, $ParametersArray)
{
$ChkValue = GenerateChk($DotpayId, $DotpayPin, $ParametersArray);
if ($Environment == 'production') {
$EnvironmentAddress = 'https://ssl.dotpay.pl/t2/';
} elseif ($Environment == 'test') {
$EnvironmentAddress = 'https://ssl.dotpay.pl/test_payment/';
}
if ($RedirectionMethod == 'POST') {
$RedirectionCode = '<form action="'.$EnvironmentAddress.'" method="POST" id="dotpay_redirection_form" accept-charset="UTF-8">'.PHP_EOL;
$RedirectionCode .= "\t".'<input name="id" value="'.$DotpayId.'" type="hidden"/>'.PHP_EOL;
foreach ($ParametersArray as $key => $value)
{
$RedirectionCode .= "\t".'<input name="'.$key.'" value="'.$value.'" type="hidden"/>'.PHP_EOL;
}
$RedirectionCode .= "\t".'<input name="chk" value="'.$ChkValue.'" type="hidden"/>'.PHP_EOL;
$RedirectionCode .= '</form>'.PHP_EOL.'<button id="dotpay_redirection_button" type="submit" form="dotpay_redirection_form" value="Submit">Confirm and Pay</button>'.PHP_EOL;
return $RedirectionCode;
} elseif ($RedirectionMethod == 'GET') {
$RedirectionCode = $EnvironmentAddress.'?';
foreach ($ParametersArray as $key => $value)
{
$RedirectionCode .= $key.'='.rawurlencode($value).'&';
}
$RedirectionCode .= 'id='.$DotpayId;
$RedirectionCode .= '&chk='.$ChkValue;
return '<a href="'.$RedirectionCode.'">Link to Pay</a>';
}
}
## get form (POST method) or payment link (GET method)
## ("Dotpay ID","PIN","[test|production]","[POST|GET]","payment data")
echo GenerateChkDotpayRedirection($DotpayId, $DotpayPin, $Environment, $RedirectionMethod , $ParametersArray);
?>
|
3.1.2. Full Example¶
Download this example (change extension to .php): Download example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 | <?php
################### https://www.dotpay.pl/developer/doc/api_payment/ ######################################################################
#
# Exemplary function (PHP) generating the correct payment redirection (POST / GET) to Dotpay payment api with parametr 'chk' (checksum).
# You enter the payment data in the parameter: $ParametersArray.
#
# In addition, the examplary includes the use of data for the Multimerchant service ($MultiMerchantList)
# and some payment channels that require additional data, e.g. a delivery address ($customer).
# You do not need to use them if you do not use these features.
#
# Dotpay Sp. z o.o.
# Tech Customer Service: tech@dotpay.pl
# Date: 2019-04-15
#
##############################################################################################################################################
/** --------- BASE CONFIG --------- **/
// Your Dotpay ID shop (6 digits)
$DotpayId = "123456";
// PIN for Your Dotpay ID (copy this from your dotpay panel carefully, without space)
$DotpayPin = "Oi9xSl8lE4cJhygjKn2L1MW2MBqkv234";
// Dotpay Environment, available: "test" or "production"
$Environment = "test";
//Redirection method: POST or GET ; recommended method is "POST"
$RedirectionMethod = "POST";
/** --------- end config --------- **/
// Do not remove this!
$MultiMerchantList = array(); //optional data
$customer = null; //optional data
## CALCULATE CHECKSUM - CHK
function GenerateChk($DotpayId, $DotpayPin, $Environment, $RedirectionMethod, $ParametersArray, $MultiMerchantList, $customer_base64)
{
$ParametersArray['id'] = $DotpayId;
$ParametersArray['customer'] = $customer_base64;
$chk = $DotpayPin.
(isset($ParametersArray['api_version']) ? $ParametersArray['api_version'] : null).
(isset($ParametersArray['lang']) ? $ParametersArray['lang'] : null).
(isset($ParametersArray['id']) ? $ParametersArray['id'] : null).
(isset($ParametersArray['pid']) ? $ParametersArray['pid'] : null).
(isset($ParametersArray['amount']) ? $ParametersArray['amount'] : null).
(isset($ParametersArray['currency']) ? $ParametersArray['currency'] : null).
(isset($ParametersArray['description']) ? $ParametersArray['description'] : null).
(isset($ParametersArray['control']) ? $ParametersArray['control'] : null).
(isset($ParametersArray['channel']) ? $ParametersArray['channel'] : null).
(isset($ParametersArray['credit_card_brand']) ? $ParametersArray['credit_card_brand'] : null).
(isset($ParametersArray['ch_lock']) ? $ParametersArray['ch_lock'] : null).
(isset($ParametersArray['channel_groups']) ? $ParametersArray['channel_groups'] : null).
(isset($ParametersArray['onlinetransfer']) ? $ParametersArray['onlinetransfer'] : null).
(isset($ParametersArray['url']) ? $ParametersArray['url'] : null).
(isset($ParametersArray['type']) ? $ParametersArray['type'] : null).
(isset($ParametersArray['buttontext']) ? $ParametersArray['buttontext'] : null).
(isset($ParametersArray['urlc']) ? $ParametersArray['urlc'] : null).
(isset($ParametersArray['firstname']) ? $ParametersArray['firstname'] : null).
(isset($ParametersArray['lastname']) ? $ParametersArray['lastname'] : null).
(isset($ParametersArray['email']) ? $ParametersArray['email'] : null).
(isset($ParametersArray['street']) ? $ParametersArray['street'] : null).
(isset($ParametersArray['street_n1']) ? $ParametersArray['street_n1'] : null).
(isset($ParametersArray['street_n2']) ? $ParametersArray['street_n2'] : null).
(isset($ParametersArray['state']) ? $ParametersArray['state'] : null).
(isset($ParametersArray['addr3']) ? $ParametersArray['addr3'] : null).
(isset($ParametersArray['city']) ? $ParametersArray['city'] : null).
(isset($ParametersArray['postcode']) ? $ParametersArray['postcode'] : null).
(isset($ParametersArray['phone']) ? $ParametersArray['phone'] : null).
(isset($ParametersArray['country']) ? $ParametersArray['country'] : null).
(isset($ParametersArray['code']) ? $ParametersArray['code'] : null).
(isset($ParametersArray['p_info']) ? $ParametersArray['p_info'] : null).
(isset($ParametersArray['p_email']) ? $ParametersArray['p_email'] : null).
(isset($ParametersArray['n_email']) ? $ParametersArray['n_email'] : null).
(isset($ParametersArray['expiration_date']) ? $ParametersArray['expiration_date'] : null).
(isset($ParametersArray['deladdr']) ? $ParametersArray['deladdr'] : null).
(isset($ParametersArray['recipient_account_number']) ? $ParametersArray['recipient_account_number'] : null).
(isset($ParametersArray['recipient_company']) ? $ParametersArray['recipient_company'] : null).
(isset($ParametersArray['recipient_first_name']) ? $ParametersArray['recipient_first_name'] : null).
(isset($ParametersArray['recipient_last_name']) ? $ParametersArray['recipient_last_name'] : null).
(isset($ParametersArray['recipient_address_street']) ? $ParametersArray['recipient_address_street'] : null).
(isset($ParametersArray['recipient_address_building']) ? $ParametersArray['recipient_address_building'] : null).
(isset($ParametersArray['recipient_address_apartment']) ? $ParametersArray['recipient_address_apartment'] : null).
(isset($ParametersArray['recipient_address_postcode']) ? $ParametersArray['recipient_address_postcode'] : null).
(isset($ParametersArray['recipient_address_city']) ? $ParametersArray['recipient_address_city'] : null).
(isset($ParametersArray['application']) ? $ParametersArray['application'] : null).
(isset($ParametersArray['application_version']) ? $ParametersArray['application_version'] : null).
(isset($ParametersArray['warranty']) ? $ParametersArray['warranty'] : null).
(isset($ParametersArray['bylaw']) ? $ParametersArray['bylaw'] : null).
(isset($ParametersArray['personal_data']) ? $ParametersArray['personal_data'] : null).
(isset($ParametersArray['credit_card_number']) ? $ParametersArray['credit_card_number'] : null).
(isset($ParametersArray['credit_card_expiration_date_year']) ? $ParametersArray['credit_card_expiration_date_year'] : null).
(isset($ParametersArray['credit_card_expiration_date_month']) ? $ParametersArray['credit_card_expiration_date_month'] : null).
(isset($ParametersArray['credit_card_security_code']) ? $ParametersArray['credit_card_security_code'] : null).
(isset($ParametersArray['credit_card_store']) ? $ParametersArray['credit_card_store'] : null).
(isset($ParametersArray['credit_card_store_security_code']) ? $ParametersArray['credit_card_store_security_code'] : null).
(isset($ParametersArray['credit_card_customer_id']) ? $ParametersArray['credit_card_customer_id'] : null).
(isset($ParametersArray['credit_card_id']) ? $ParametersArray['credit_card_id'] : null).
(isset($ParametersArray['blik_code']) ? $ParametersArray['blik_code'] : null).
(isset($ParametersArray['credit_card_registration']) ? $ParametersArray['credit_card_registration'] : null).
(isset($ParametersArray['surcharge_amount']) ? $ParametersArray['surcharge_amount'] : null).
(isset($ParametersArray['surcharge']) ? $ParametersArray['surcharge'] : null).
(isset($ParametersArray['surcharge']) ? $ParametersArray['surcharge'] : null).
(isset($ParametersArray['ignore_last_payment_channel']) ? $ParametersArray['ignore_last_payment_channel'] : null).
(isset($ParametersArray['vco_call_id']) ? $ParametersArray['vco_call_id'] : null).
(isset($ParametersArray['vco_update_order_info']) ? $ParametersArray['vco_update_order_info'] : null).
(isset($ParametersArray['vco_subtotal']) ? $ParametersArray['vco_subtotal'] : null).
(isset($ParametersArray['vco_shipping_handling']) ? $ParametersArray['vco_shipping_handling'] : null).
(isset($ParametersArray['vco_tax']) ? $ParametersArray['vco_tax'] : null).
(isset($ParametersArray['vco_discount']) ? $ParametersArray['vco_discount'] : null).
(isset($ParametersArray['vco_gift_wrap']) ? $ParametersArray['vco_gift_wrap'] : null).
(isset($ParametersArray['vco_misc']) ? $ParametersArray['vco_misc'] : null).
(isset($ParametersArray['vco_promo_code']) ? $ParametersArray['vco_promo_code'] : null).
(isset($ParametersArray['credit_card_security_code_required']) ? $ParametersArray['credit_card_security_code_required'] : null).
(isset($ParametersArray['credit_card_operation_type']) ? $ParametersArray['credit_card_operation_type'] : null).
(isset($ParametersArray['credit_card_avs']) ? $ParametersArray['credit_card_avs'] : null).
(isset($ParametersArray['credit_card_threeds']) ? $ParametersArray['credit_card_threeds'] : null).
(isset($ParametersArray['customer']) ? $ParametersArray['customer'] : null).
(isset($ParametersArray['gp_token']) ? $ParametersArray['gp_token'] : null).
(isset($ParametersArray['blik_refusenopayid']) ? $ParametersArray['blik_refusenopayid'] : null).
(isset($ParametersArray['auto_reject_date']) ? $ParametersArray['auto_reject_date'] : null).
(isset($ParametersArray['ap_token']) ? $ParametersArray['ap_token'] : null);
foreach ($MultiMerchantList as $item) {
foreach ($item as $key => $value) {
$chk = $chk.
(isset($value) ? $value : null);
}
}
return $chk;
}
## GENERATE FORM TO DOTPAY
function GenerateChkDotpayRedirection($DotpayId, $DotpayPin, $Environment, $RedirectionMethod, $ParametersArray, $MultiMerchantList, $customer_base64)
{
$ParametersArray['id'] = $DotpayId;
$ChkParametersChain = GenerateChk($DotpayId, $DotpayPin, $Environment, $RedirectionMethod, $ParametersArray, $MultiMerchantList, $customer_base64);
$ChkValue = hash('sha256', $ChkParametersChain);
if ($Environment == 'production') {
$EnvironmentAddress = 'https://ssl.dotpay.pl/t2/';
} elseif ($Environment == 'test') {
$EnvironmentAddress = 'https://ssl.dotpay.pl/test_payment/';
}
if ($RedirectionMethod == 'POST') {
$RedirectionCode = '<form action="'.$EnvironmentAddress.'" method="POST" id="dotpay_redirection_form" accept-charset="UTF-8">'.PHP_EOL;
foreach ($ParametersArray as $key => $value) {
$RedirectionCode .= "\t".'<input name="'.$key.'" value="'.$value.'" type="hidden"/>'.PHP_EOL;
}
if(isset($customer_base64)) {
$RedirectionCode .= "\t".'<input name="customer" value="'.$customer_base64.'" type="hidden"/>'.PHP_EOL;
}
foreach ($MultiMerchantList as $item) {
foreach ($item as $key => $value) {
$RedirectionCode .= "\t".'<input name="'.$key.'" value="'.$value.'" type="hidden"/>'.PHP_EOL;
}
}
$RedirectionCode .= "\t".'<input name="chk" value="'.$ChkValue.'" type="hidden"/>'.PHP_EOL;
$RedirectionCode .= '</form>'.PHP_EOL.'<button id="dotpay_redirection_button" type="submit" form="dotpay_redirection_form" value="Submit">Confirm and Pay</button>'.PHP_EOL;
return $RedirectionCode;
} elseif ($RedirectionMethod == 'GET') {
$RedirectionCode = $EnvironmentAddress.'?';
foreach ($ParametersArray as $key => $value) {
$RedirectionCode .= $key.'='.rawurlencode($value).'&';
}
if(isset($customer_base64)) {
$RedirectionCode .= 'customer='.$customer_base64.'&';
}
foreach ($MultiMerchantList as $item) {
foreach ($item as $key => $value) {
$RedirectionCode .= $key.'='.rawurlencode($value).'&';
}
}
$RedirectionCode .= 'chk='.$ChkValue;
return '<a href="'.$RedirectionCode.'">Go to Pay</a><br>link:<br>'.$RedirectionCode;
}
}
// ** ----------------------- SAMPLE DATA ------------------------- **/
/* ## SAMPLE PAYMENT DATA IN ## */
// Note! You can use more parameters if You need
// You must give at least: 'amount', 'currency', 'description' (and of course ID and PIN in the configuration of this script)
// see more: https://www.dotpay.pl/developer/doc/api_payment/en/index.html#tabela-1-podstawowe-parametry-przesylane-do-serwisu-dotpay
// and: https://www.dotpay.pl/developer/doc/api_payment/en/index.html#tabela-2-dodatkowe-parametry-przesylane-do-serwisu-dotpay
// ------
$ParametersArray = array(
"api_version" => "dev",
"amount" => "100.00",
"currency" => "PLN",
"description" => "Order no. 567915976",
"url" => "https://www.example.com/thanks_page.php",
"type" => "4",
"channel" => "2",
"buttontext" => "Back to the www.example.com",
"urlc" => "https://www.example.com/urlc_receiver.php",
"control" => "M1231MzaUdLQWR3",
"firstname" => "Jan",
"lastname" => "Nowak",
"email" => "jan.nowak@example.com",
"street" => "Warszawska",
"street_n1" => "1",
"city" => "Krakow",
"postcode" => "12-345",
"phone" => "123456789",
"country" => "POL",
"ignore_last_payment_channel" => "true"
);
// ------
/* ### SAMPLE CUSTOMER DATA IN with delivery address (optional) ###
You can remove it if You don't need it
*/
// ------
$customer = array(
"payer" => array(
"first_name" => "Jan",
"last_name" => "Kowal",
"email" => "mymail@example.com",
) ,
"order" => array(
"delivery_address" => array(
"city" => "Kraków",
"street" => "Wielicka",
"building_number" => "28B",
"postcode" => "30-552",
)
)
);
// ------
/* ### SAMPLE Multimerchant DATA IN (3 accounts 'child' type ) - optional ###
You can remove it if You don't need it
see more: https://www.dotpay.pl/developer/doc/api_payment/en/index.html#platnosc-dzielona-multimerchant-pasaz
*/
// ------ uncomment if you need:
/*
$MultiMerchantList = array(
$MultiMerchant1 = array(
"id1" => "123456",
"amount1" => "10.00",
"currency1" => "PLN",
"description1" => "description1",
"control1" => "control1",
) ,
$MultiMerchant2 = array(
"id2" => "234561",
"amount2" => "60.00",
"currency2" => "PLN",
"description2" => "description2",
"control2" => "control2",
) ,
$MultiMerchant3 = array(
"id3" => "234562",
"amount3" => "30.00",
"currency3" => "PLN",
"description3" => "description3",
"control3" => "control3",
)
);
*/
// ------
// ** ----------------------- SAMPLE DATA end ------------------------- **/
if (empty($customer) || !isset($customer['payer']) || !isset($customer['order']['delivery_address'])) {
$customer_base64 = null;
} else {
$customer_base64 = base64_encode(json_encode($customer));
}
## get form (POST method) or payment link (GET method)
## ("Dotpay ID","PIN","[test|production]","[POST|GET]","payment data","Multimerchant data", "additional customer data")
echo GenerateChkDotpayRedirection($DotpayId, $DotpayPin, $Environment, $RedirectionMethod , $ParametersArray, $MultiMerchantList, $customer_base64);
?>
|
3.2. One-click and recurring payments¶
Note
Functionality is only available for shops ( id ) which were adequately configured by Dotpay, what is dependent on signed agreement.
Functionality is only available for payment card channel (number 248), allowing client to realize payments without entering complete card data in future transactions made via Dotpay.
In order to use the functionality seller’s system has to send additional parameters (described below) in payment request and client should allow his card information to be stored by Dotpay (all data is stored according to highest security standards – PCI DSS Level 1).
When using described functionality it is recommended for request sent to Dotpay to be signed as well as signature verification to be required on given shop ( id ). Description of signature creation can be found in Redirection parameters integrity protection (CHK) section.
In order to register client’s card data in Dotpay system additional parameters have to be sent:
3.2.1. Table 4. (Parameters for card registration)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
credit_card_store |
Parameter defining whether client card data should be stored by Dotpay. Available values: 1 – Storing credit card data is accepted Example:
|
credit_card_customer_id |
Unique buyer ID generated and stored by seller’s system. Required for future payments Important Dotpay does NOT return this information anywhere (i.e. URLC or API). type: string min length: 4 max length 1024 Example:
|
credit_card_registration |
Optional parameter. Creates operation credit_card_registration instead of payment, what allows to register credit card without paying. Instead of charge temporary funds blockade will be issued, which is lifted when registration process is completed. Tip For operation credit_card_registration it’s required to use an amount of value 1.00 ( Available values: true – registration without payment Example:
|
In order to make payment with registered card additional parameters described below need to be sent:
3.2.2. Table 5. (Parameters for consecutive payments with previously registered card)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
credit_card_customer_id |
Unique buyer ID generated by seller’s system described in table above. |
credit_card_id |
Buyer’s registered card ID This information might be sent in URLC notification (special account configuration required, described in RECEIVING PAYMENT CONFIRMATION (URLC CONFIRMATION) section). It also might be received via API from operation details. |
Common parameters for both first and consecutive payments have been described in table below, all of them are optional. Standard account configuration doesn’t allow them to be used (default settings are applied, configurable by Dotpay), special agreement might be required in order to send them.
3.2.3. Table 6. (Common parameters for both first and consecutive payments)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
credit_card_operation_type |
Optional parameter. Operation type. Available values: e_commerce – first and consecutive payment in one-click model (default value), recurring_init – first transaction allowing later use of recurring payments, recurring – recurring payment (customer doesn’t have to be present in order to charge the registered card), Account ( Parameter is required when one account ( Tip Card registered using e_commerce cannot be used for recurring operation. Cards registered using recurring_init can be used for both recurring and e_commerce . |
credit_card_security_code_required |
Optional parameter. Allows to control whether CVV/CVV2 security code is required during payment. Applies only to consecutive e_commerce (one click). Available values: yes – required (default value), no – not required, option – field for security code will show up on payment form, but it won’t be mandatory. |
credit_card_threeds |
Optional parameter. Allows to control whether 3-D Secure authentication code is required during payment. Applies only to e_commerce model for enrolled cards. Available values: yes – required (default value, recommended for transaction security), no – not required, Tip Operation type recurring_init requires and recurring doesn’t require 3-D Secure authentication code, ignoring account settings or sent parameters. |
credit_card_avs |
Optional parameter. Allows to control whether customer will be required to enter additional personal data on payment form (address and phone number). Available values: yes – required, no – not required (default value). |
3.2.4. Exemplary integration models and their corresponding requirements)¶
3.2.4.1. Integration model: 1 click¶
| Card registration | Consecutive payment |
|---|---|
Required parameters: - Payment process: - CVV - required - 3DS – required* |
Required parameters: Payment process: - CVV - optional - 3DS - required* |
* - recommended for transaction security
3.2.4.2. Integration model: recurring¶
| Card registration | Consecutive payment |
|---|---|
Required parameters: - Payment process: - CVV - required - 3DS - required |
Required parameters: Payment process: - CVV - not applicable - 3DS - not applicable |
* - recommended for transaction security
3.2.4.3. Mixed integration model: 1 click + recurring¶
| Integration model | Card registration | Consecutive payment |
|---|---|---|
| 1 click | Required parameters: - Payment process: - CVV - required - 3DS - required* |
Required parameters: Payment process: - CVV - optional - 3DS - required* |
| recurring | Required parameters: - - Payment process: - CVV - required - 3DS - required |
Required parameters: - Payment process: - CVV - not applicable - 3DS - not applicable |
* - recommended for transaction security
| Integration model | Card registration | Consecutive payment |
|---|---|---|
| 1 click | Required parameters: - - Payment process: - CVV - required - 3DS - required* |
Required parameters: - Payment process: - CVV - optional - 3DS - required* |
| recurring | Required parameters: - Payment process: - CVV - required - 3DS - required |
Required parameters: Payment process: - CVV - not applicable - 3DS - not applicable |
* - recommended for transaction security
Below are exemplary redirection forms for one-click payment realization.
Exemplary payment request with card registration:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <div>
<form action="https://ssl.dotpay.pl/t2/" method="post" id="dotpay_redirection_form">
<input name="api_version" value="dev" type="hidden" />
<input name="id" value="123456" type="hidden" />
<input name="amount" value="320.00" type="hidden" />
<input name="currency" value="PLN" type="hidden" />
<input name="description" value="Płatność za 12345/2014" type="hidden" />
<input name="control" value="202cb962ac590" type="hidden" />
<input name="channel" value="248" type="hidden" />
<input name="ch_lock" value="1" type="hidden" />
<input name="firstname" value="John" type="hidden" />
<input name="lastname" value="Smith" type="hidden" />
<input name="email" value="john.smith@example.com" type="hidden" />
<input name="type" value="0" type="hidden" />
<input name="url" value="https://www.example.com/thanks_page.php" type="hidden" />
<input name="urlc" value="https://www.example.com/urlc_receiver.php" type="hidden" />
<input name="credit_card_store" value="1" type="hidden" />
<input name="credit_card_customer_id" value="f9c6a4-25473" type="hidden" />
<input name="chk" value="11ac1938ac47ddd53815b4aeb6230ab9fe4554d82ee11e39c41b9055f38f5c08" type="hidden" />
</form>
<p>
<button type="submit" form="dotpay_redirection_form" value="Submit">
Potwierdź zamówienie i zapłać</button>
</p>
</div>
|
Exemplary payment request using registered card data (one-click):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <div>
<form action="https://ssl.dotpay.pl/t2/" method="post" id="dotpay_redirection_form">
<input name="api_version" value="dev" type="hidden" />
<input name="id" value="123456" type="hidden" />
<input name="amount" value="410.00" type="hidden" />
<input name="currency" value="PLN" type="hidden" />
<input name="description" value="Płatność za 12346/2014" type="hidden" />
<input name="control" value="31ee79b30dc39a9cbaa" type="hidden" />
<input name="channel" value="248" type="hidden" />
<input name="ch_lock" value="1" type="hidden" />
<input name="firstname" value="John" type="hidden" />
<input name="lastname" value="Smith" type="hidden" />
<input name="email" value="john.smith@example.com" type="hidden" />
<input name="type" value="4" type="hidden" />
<input name="url" value="https://www.example.com/thanks_page.php" type="hidden" />
<input name="urlc" value="https://www.example.com/urlc_receiver.php" type="hidden" />
<input name="credit_card_customer_id" value="f9c6a4-25473" type="hidden" />
<input name="credit_card_id" value="59f92e2bf8bedc36bec2219862448dd54d...1829a239eb7432d0easuxp2w158eb13d6333ce71369184eb7ab02ae" type="hidden" />
<input name="chk" value="ed0ef4e488ec2de3135b0a1ca226c31867f78bbcd8fe06506ae666210a78d68c" type="hidden" />
</form>
<p>
<button type="submit" form="dotpay_redirection_form" value="Submit">Potwierdź zamówienie i zapłać (płatność one-click)</button>
</p>
</div>
|
Note
For recurring payments it is recommended to use direct communication with Dotpay using REST API ( register order ).
Table below describes parameters which allow payment card data to be sent to Dotpay system if it is entered by client on seller’s website (for example on order summary page) instead of Dotpay.
Note
Processing payment card data by seller’s system requires – according to Payment Card Industry Data Security Standard (PCI DSS) – additional conditions to be met.
In order to receive more information about necessary formalities please contact Sales Department (handlowy@dotpay.pl).
Caution
Sending payment card data with parameters described below is only possible via POST method.
3.2.5. Table 11. (Parameters for credit card data)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
credit_card_number |
Client’s payment card number. type: credit_card_number max length: 26 regular expression: ^[\d\s]{12,26}$
Example:
|
credit_card_expiration_date_year |
Year of client’s payment card expiration date. length: 4 regular expression: ^(20)((19)|([2-9][0-9]))$
Example:
|
credit_card_expiration_date_month |
Month of client’s payment card expiration date. length: 2 regular expression: ^(0[1-9])|(1[0-2])$
Example:
|
credit_card_security_code |
Client’s payment card security code (CVV2/CVC2). type: number max length: 4 regular expression: ^\d{3,4}$
Example:
|
Deleting registered card might be realized with methods below:
- Client might use link given in payment confirmation emails.
- Deregistration request might be sent to Dotpay from seller’s system via API.
Request should be sent using DELETE method to the https://ssl.dotpay.pl/t2/payment_api/v1/cards/{credit_card_id}/ address where {credit_card_id} is card ID which should be removed.
Below is exemplary request (in PHP) and response of card deregistration. Authorization data (user, password) is adequate to seller GUI login credentials.
Request:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | <?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://ssl.dotpay.pl/t2/payment_api/v1/cards/59f92e2bf8bedc36bec221...718c58eb13d6333ce71369184eb7ab02ae/");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_CAINFO, "ca-bundle.crt"); //http://curl.haxx.se/docs/caextract.html
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 100);
curl_setopt($ch, CURLOPT_USERPWD, 'user:password');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$response = curl_exec($ch); // API response
$curl_info = curl_getinfo($ch); //curl info
curl_close($ch);
echo '<pre>';
echo 'HTTP status code: '.$curl_info[http_code];
echo PHP_EOL.'-------------------------'.PHP_EOL.PHP_EOL;
print_r(json_decode($response));
echo '</pre>';
|
Sample request to unregister the card:
-
DELETE/cards/(string: credit_card_id)/¶
Response:
HTTP/1.1 204 No Content
HTTP status code meaning:
| CODE | MEANING / DESCRIPTION |
|---|---|
| 204 No Content | Deleted |
| 404 Not Found | Credit Card not found |
| 400 Bad Request | Request processing error |
3.3. Split payment (Multimerchant)¶
Note
Functionality is only available for shops ( id ) which were adequately configured by Dotpay, what is dependent on signed agreement.
Functionality allows to split one payment into multiple amounts to be accounted on given shops ( id ). Request has to contain additional parameters (required id(n) , amount(n) , and optional currency(n) , description(n) , control(n) , where (n) is a greater than 0 integer defining consecutive ID, amounts etc.) alongside standard parameters described in ADVANCED VERSION section.
Caution
It is not possible to make a Multimerchant payment with different currencies at once, value of each currency(n) parameter has to be the same as currency .
When using this functionality parameter id defines shop (called multimerchant parent) where operation payment_multimerchant_parent will be created, only as an information about full payment amount (sent in amount parameter). Meanwhile on shops id(n) (called multimerchant child) amounts amount1 - amount(n) will be accounted as payment_multimerchant_child operation.
Information sent is URLC notifications is adequate to given payment_multimerchant_parent or payment_multimerchant_child created on each shop ( id ).
Caution
In order for URLC notifications to be sent on multimerchant child accounts, an address has to be entered in each id(n) configuration () as there is no option to define parameter like urlc(n) .
Caution
It is only possible to refund payment_multimerchant_child operation accounted on given id(n) . It is NOT possible to refund whole payment using payment_multimerchant_parent .
Below is an exemplary split payment form.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | <div>
<form action="https://ssl.dotpay.pl/t2/" id="dotpay_redirection_form" method="POST" enctype="application/x-www-form-urlencoded">
<input type="hidden" name="id" value="123456">
<input type="hidden" name="amount" value="320.00">
<input type="hidden" name="currency" value="PLN">
<input type="hidden" name="description" value="Płatność za zamówienie 01/2017 parent">
<input type="hidden" name="control" value="control_parent">
<input type="hidden" name="id1" value="456123">
<input type="hidden" name="amount1" value="120.00">
<input type="hidden" name="currency1" value="PLN">
<input type="hidden" name="description1" value="Płatność za zamówienie 01/2017 child1">
<input type="hidden" name="control1" value="control_child1">
<input type="hidden" name="id2" value="561423">
<input type="hidden" name="amount2" value="90.00">
<input type="hidden" name="currency2" value="PLN">
<input type="hidden" name="description2" value="Płatność za zamówienie 01/2017 child2">
<input type="hidden" name="control2" value="control_child2">
<input type="hidden" name="id3" value="642513">
<input type="hidden" name="amount3" value="110.00">
<input type="hidden" name="currency3" value="PLN">
<input type="hidden" name="description3" value="Płatność za zamówienie 01/2017 child3">
<input type="hidden" name="control3" value="control_child3">
</form>
<p>
<button type="submit" form="dotpay_redirection_form" value="Submit">
Potwierdź zamówienie i zapłać
</button>
</p>
</div>
|
Important
Sum of amounts sent in parameters amount1, amount2, …, amount(n) has to be equal to the total amount of payment, defined in parameter amount .
3.4. Masscollect¶
Note
Functionality is only available for shops ( id ) which were adequately configured by Dotpay, what is dependent on signed agreement.
Functionality allows to send recipient bank account number in transaction request, which Is going to be used in payout, that is default account number defined is account ( id ) configuration will be overwritten.
Depending on account configuration, payouts created by automatic payouts mechanism will either be aggregated by bank account numbers or in 1:1 for where every payment creates separate payout. Payouts of any amount are always aggregated.
Caution
Using described functionality requires request sent to Dotpay to be signed as well as signature verification to be required on given shop ( id ). Description of signature creation can be found in Redirection parameters integrity protection (CHK) section.
In order to make Masscollect payments, additional parameters described in the table below should be sent in the order. Only the recipient_account_number parameter is required, however, it is also recommended to provide the recipient’s name using the parameter recipient_company or recipient_first_name and recipient_last_name .
3.4.1. Table 12. (Additional parameters used in the Masscollect service)¶
| PARAMETER | MEANING / DESCRIPTION |
|---|---|
recipient_account_number |
Recipient account number in BBAN format.
Example:
|
recipient_company |
Recipient company name
Example:
|
recipient_first_name |
Recipient first name
Example:
|
recipient_last_name |
Recipient last name
Example:
|
recipient_address_street |
Street – recipient address
Example:
|
recipient_address_building |
Building number – recipient address
Example:
|
recipient_address_apartment |
Flat number – recipient address
Example:
|
recipient_address_postcode |
Postcode – recipient address
Example:
|
recipient_address_city |
City – recipient address
Example:
|
Below is an exemplary Masscollect payment form.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <div>
<form action="https://ssl.dotpay.pl/t2/" id="dotpay_redirection_form" method="POST" enctype="application/x-www-form-urlencoded">
<input type="hidden" name="id" value="123456">
<input type="hidden" name="amount" value="123.45">
<input type="hidden" name="description" value="Płatność za zamówienie 07/2017">
<input type="hidden" name="recipient_account_number" value="32249000896640389235035459">
<input type="hidden" name="recipient_company" value="Moja Firma S.A.">
<input type="hidden" name="recipient_first_name" value="Jan">
<input type="hidden" name="recipient_last_name" value="Kowalski">
<input type="hidden" name="recipient_address_street" value="Wielicka">
<input type="hidden" name="recipient_address_building" value="72">
<input type="hidden" name="recipient_address_apartment" value="1">
<input type="hidden" name="recipient_address_postcode" value="30-552">
<input type="hidden" name="recipient_address_city" value="Kraków">
<input type="hidden" name="chk" value="3135b6debcd8fe4e488ec2easux506c31867f78bed0ef0a1ca2266210a78d68c" />
</form>
<p>
<button type="submit" form="dotpay_redirection_form" value="Submit">
Potwierdź zamówienie i zapłać
</button>
</p>
</div>
|
3.5. Shipping and payer data¶
In order for channel provider to evaluate customer’s credit score, new additional parameters have been added.
Below is the list of those parameters with their description and requirements.
Sending more data than just required minimum might have big impact on credit score. If it is possible, it’s recommended to send complete data.
In order to process a given payment method, a new customer parameter has been added for integration with Dotpay. This parameter should contain specific information according to the following Table 13. Some payment channels may require less data, such as PayPo or Raty Alior.
3.5.1. Table 13. (Data handled by customer parameter)¶
| FIELD NAME | TYPE | DESCRIPTION |
|---|---|---|
payer.first_name |
string | Payer name |
payer.last_name |
string | Payer lastname |
payer.email |
string | Payer email address |
payer.phone |
string | Payer phone number |
payer.address |
- | Payer address |
payer.address.city |
string | Payer address: city |
payer.address.street |
string | Payer address: street |
payer.address.building_number |
string | Payer address: building number |
payer.address.flat_number |
string | Payer address: flat number |
payer.address.postcode |
string | Payer address: post code |
payer.address.country |
string | Payer address: (ISO 3166-1 alpha2) or (ISO 3166-1 alpha3) country code |
is_logged_in |
boolean | Whether payer has register an account before placing an order |
registered_since |
string | Payer’s registration date on the seller’s website, format YYYY-MM-DD or YYYY-MM-DD hh:mm:ss Optional, if it’s sent, |
registered_since_indicator |
string (indicator) | Payer’s registration date on the seller’s website, indicator for the Optional, if it’s sent, |
account_update |
string | Date of last change of paying account on the seller’s website, format YYYY-MM-DD |
account_update_indicator |
string (indicator) | Date of last change of paying account on the seller’s website, indicator for the field account_update |
password_change |
string | Date of last password change for the paying account on the seller’s website, format YYYY-MM-DD |
password_change_indicator |
string (indicator) | Date of last change of password for the paying account on the seller’s website, indicator for the field password_change |
shipping_address_since |
string | Date from when the payer’s delivery address is used, format YYYY-MM-DD |
shipping_address_since_indicator |
string (indicator) | Date from which the payer’s delivery address is used, the indicator for the field shipping_address_since |
order_count |
int | How many orders the payer has made made since registration Optional, if it’s sent, |
order_count_day |
int | The number of orders placed by the paying seller on the same day |
order_count_year |
int | Number of orders placed by the paying seller in the same year |
fraud_activity |
boolean | Has the store ever seen suspicious activity on this buyer’s account |
order_history |
- | Current payer order history |
order_history.date |
string | n-order place date in YYYY-MM-DD format |
order_history.amount |
decimal (10,2) | Gross price of n-product |
order |
- | Order |
order.total_amount |
string | The value of the entire order |
order.id |
string | Order ID in the seller’s system. Corresponds to the ID number of the entire order in the store database |
order.items |
- | The contents of the shopping cart. We recommend that you do not exceed the number 100 articles in the list |
order.items.id |
string | ID of given shop product |
order.items.name |
string | The name of a single product in the seller’s system. Corresponds to the name of the product in the store database.
[\w\s\-_. ,'?@\\\/ąćęłńóśźżĄĆĘŁÓŃŚŹŻ]+$
|
order.items.quantity |
int | Number of items in the customer’s order (n * Goods = total number of items)
|
order.items.unit_type |
string | Item measurement unit, eg. quantity, kg, liters, meters and so on. |
order.items.gross_price |
decimal(10,2) | Gross price of n-product. Corresponds to the price of the product in the store database. |
order.items.type |
string | Order type (eg. product, payment, delivery, discount) |
order.items.is_virtual |
boolean | Product is virtual (doesn’t require a delivery) |
order.items.category |
string | The category of a single product in the seller’s system. the category should match one of the elements listed in the dictionary. List of available categories: Dictionary of available sales categories |
order.delivery_type |
string | Delivery method Available values:
|
order.delivery_address |
- | Delivery address If the package is delivered to a point / parcel locker / etc, such address and name should be given, not the details of the actual recipient. |
order.delivery_address.city |
string | Delivery address: city |
order.delivery_address.street |
string | Delivery address: street |
order.delivery_address.building_number |
string | Delivery address: building number |
order.delivery_address.flat_number |
string | Delivery address: flat number |
order.delivery_address.postcode |
string | Delivery address: post code |
order.delivery_address.country |
string | Delivery address: (ISO 3166-1 alpha2) or (ISO 3166-1 alpha3) country code |
order.delivery_address.name |
string | Name of recipient / collection point.
|
order.delivery_address.phone |
string | Recipient’s phone number |
order.delivery_address.is_verified |
bool | Delivery address: Whether the delivery address is verified |
Note
If the store does not want to provide the correct date, it is possible to use an indicator field of replacement type for selected parameters.
3.5.2. Values used for indicator field replacement for selected fields:¶
| VALUE | DESCRIPTION |
|---|---|
| 01 | The payer’s account does not exist on the seller’s website |
| 02 | Date of the transaction just ordered |
| 03 | Date not older than 30 days ago |
| 04 | Date in the range 30 - 60 days ago |
| 05 | Date older than 60 days ago |
Exemplary use of parameters described above:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | {
"payer": {
"first_name": "Jan",
"last_name": "Kowal",
"email": "jankowal@example.com",
"phone": "123456789",
"address": {
"city": "Warszawa",
"street": "Krucza",
"building_number": "1a",
"flat_number": "4",
"postcode": "00-950",
"country": "POL"
}
},
"is_logged_in": true,
"registered_since": "2017-02-11",
"order_count": 2,
"order_history": [
{
"date": "2017-02-11",
"amount": "456.21",
"delivery_type": "COURIER"
},
{
"date": "2018-05-21",
"amount": "879.67",
"delivery_type": "POCZTA_POLSKA"
}
],
"order": {
"id": "MHH67HF8DS",
"items": [
{
"id": "3245623",
"name": "Super Phone 1",
"quantity": 1,
"unit_type": "szt.",
"gross_price": "856.52",
"type": "towar",
"is_virtual": false
},
{
"id": "3245625",
"name": "Dostawa",
"quantity": 1,
"unit_type": "szt.",
"gross_price": "15.00",
"type": "dostawa",
"is_virtual": false
}
],
"delivery_type": "POCZTA_POLSKA",
"delivery_address": {
"city": "Kraków",
"street": "Wielicka",
"building_number": "28b",
"flat_number": "5",
"postcode": "30-552",
"country": "POL"
}
}
}
|
3.5.3. Dictionary of article categories for the parameter order.items.category¶
| VALUE | DESCRIPTION |
|---|---|
| ART_ANTIQUES | Works of art, antiques |
| BOOKS_EDUCATIONAL | Books, educational materials |
| BUILDING_MATERIALS | Building Materials |
| CARS_MOTORBIKES_SCOOTERS | Cars, motorbikes, mopeds, scooters |
| CLOTHING_SHOES | Clothing, shoes |
| COMP_COMPONENTS | Computer components and accessories including monitors, printers and scanners |
| COMPUTERS | Computers |
| CONSOLES_GAMES | Consoles and games |
| DEVOTIONAL | Devotional articles |
| DOORS_WINDOWS | Windows and doors |
| ECO_SYSTEMS | Ecological systems |
| FOR_CHILDREN | Baby carriages, car seats and others |
| FUEL_COAL | Fuel and coal |
| FURNITURE | Furniture |
| GARDENING | Seeds, fertilizers, plants |
| GIFT_VOUCHERS | Gift vouchers, packages (other than medical) |
| HEATING | Central heating boilers, JUNKERS |
| HOME_FURNISHINGS | Home furnishings |
| HOME_TEXTILES | Home textiles, bedding and blankets |
| HOUSEHOLD_GOODS_BIG | Household appliances large |
| HOUSEHOLD_GOODS_SMALL | Household appliances small |
| INSURANCE | Insurance services |
| JEWELRY_WATCHES | Jewelry, watches |
| LAPTOPS_TABLETS | Laptops and tablets |
| MUSICAL_INSTRUMENTS | Musical instruments |
| OTHER_MOTORIZATION | Other motorization |
| PHONES_GPS | Telephones and GPS |
| PHOTO_CAMERA | Photo and Camera |
| RTV | RTV |
| SERVICES | Services |
| SOFTWARE | Software and other computer components |
| SPORTS_REHABILITATION | Sporting / rehabilitation / tourist articles |
| TOOLS_DEVICES | Tools and devices |
| VEHICLE_ACCESSORIES_EQUIPMENT | Vehicle accessories and equipment |
3.5.4. Data required in customer parameter for PayPo channel¶
To make a payment with PayPo channel, specific data is required, which has been described in Table 13 :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | {
"payer": {
"first_name": "Jan",
"last_name": "Kowal",
"email": "jankowal@example.com"
},
"order": {
"delivery_address": {
"city": "Kraków",
"street": "Wielicka",
"building_number": "28B",
"postcode": "30-552"
}
}
}
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | {
"payer": {
"first_name": "Jan",
"last_name": "Kowal",
"email": "jankowal@example.com",
"phone": "+48126882600"
},
"registered_since": "2017-02-11",
"order_count": 2,
"order": {
"id": "MHH67HF8DS",
"delivery_type": "POCZTA_POLSKA",
"delivery_address": {
"city": "Kraków",
"street": "Wielicka",
"building_number": "28b",
"flat_number": "5",
"postcode": "30-552",
"country": "POL"
}
}
}
|
Optional parameters for PayPo have been colored, their absence might negatively impact payer’s credit score.
In order for this information to be passed to Dotpay in customer parameter, it has to be formatted correctly. First it needs to be encoded in JSON format and then encoded using Base64.
customer parameter value (minimum) for PayPo channel in PHP:¶1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | <?php
$customer = array (
"registered_since" => "2017-12-31",
"order_count" => 12,
"payer" => array(
"first_name" => "Jan",
"last_name" => "Kowal",
"email" => "jan@example.com"
),
"order" => array(
"delivery_type" => "COURIER",
"delivery_address" => array(
"city" => "Krakow",
"street" => "Wielicka",
"building_number" => "11",
"flat_number" => "7",
"postcode" => "30-553",
"country" => "POL"
)
)
);
$customer_base64 = base64_encode(json_encode($customer));
?>
|
3.5.5. Data required in customer parameter for Raty Alior channel¶
To make a payment with Raty Alior channel, specific data is required, which has been described in Table 13 :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | {
"payer":{
"first_name":"Jan",
"last_name":"Kowal",
"email":"jankowal@example.com"
},
"order":{
"items":[
{
"name":"Super Phone 1",
"quantity":1,
"gross_price":"1200.00",
"category":"PHONES_GPS"
},
{
"name":"Pendrive 64GB",
"quantity":4,
"gross_price":"50.00",
"category":"COMP_COMPONENTS"
}
]
}
}
|
The value of the order.items.category parameter should be filled in according to the category dictionary.
The number of products in the order.items parameter is limited and should not be more than 500 items.
In order for this information to be passed to Dotpay in customer parameter, it has to be formatted correctly. First it needs to be encoded in JSON format and then encoded using Base64.
customer parameter value (minimum) for Raty Alior channel in PHP:¶1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | <?php
$customer = array(
"payer" => array(
"first_name" => "Jan",
"last_name" => "Kowal",
"email" => "jankowal@example.com",
),
"order" => array(
"items" => [
array(
"name" => "Super Phone 1",
"quantity" => 1,
"gross_price" => "1200.00",
"category" => "PHONES_GPS"
),
array(
"name" => "Pendrive 64GB",
"quantity" => 4,
"gross_price" => "50.00",
"category" => "COMP_COMPONENTS"
)
],
)
);
$customer_base64 = base64_encode(json_encode($customer));
?>
|
3.5.6. Data required in customer parameter for PayPal channel (only with PayPal SPP)¶
The technical requirements necessary to obtain the “Extended Seller Protection Policy (SPP)” from PayPal to buy online - shop or reception point.
If you use the seller protection program on your PayPal account and you have an appropriate agreement in this regard with PayPal, in integration with Dotpay it is necessary to send additional information.
To make a payment with PayPal in SPP channel, specific data is required, which has been described in Table 13 :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | {
"payer":{
"first_name":"Jan",
"last_name":"Kowal",
"email":"jankowal@example.com"
},
"order":{
"delivery_address":{
"name":"PPP:6252652",
"city":"Kraków",
"street":"Wielicka",
"building_number":"28B",
"postcode":"30-552",
"phone":"+48126880000",
"country":"PL"
}
}
}
|
In order for this information to be passed to Dotpay in customer parameter, it has to be formatted correctly. First it needs to be encoded in JSON format and then encoded using Base64.
customer parameter value (minimum) for PayPal (SPP) channel in PHP:¶1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <?php
$customer = array(
"payer" => array(
"first_name" => "Jan",
"last_name" => "Kowal",
"email" => "jan@example.com"
) ,
"order" => array(
"delivery_address" => array(
"name" => "PPP:6252652",
"city" => "Krakow",
"street" => "Wielicka",
"building_number" => "28B",
"postcode" => "30-552",
"phone" => "+48126880000",
"country" => "PL"
)
)
);
$customer_base64 = base64_encode(json_encode($customer));
?>
|
Note
In order for the sent data to be correctly interpreted and sent from Dotpay to PayPal, such fact must be reported to Dotpay (tech@dotpay.pl) in advance for the correct configuration of the account.
3.6. Faulty redirections from the merchant’s system¶
On Dotpay’s side a shop ( id ) may be configured in such a way that in case of a faulty redirection to Dotpay (caused by e.g. a faulty parameters passed by the merchant’s system) an automated redirection will be made to the address from the url parameter (sent by merchant’s system) along with a faulty code.
When an error occurs a redirection to the address from url parameter will be made error_code parameter with a proper value will be added.
Note
In order to activate functionality enable Handling error codes in URL option available in seller administration panel in .
For example, while redirecting from a merchant’s system to unknown payment channel number in Dotpay, for passed in the redirection parameter url : url = https://example.com/
redirection will be to: https://example.com/?error_code=UNKNOWN_CHANNEL
error_code values are listed below:
PAYMENT_EXPIRED - payment link expired or datetime defined in expiration_date parameter has been exceeded
UNKNOWN_CHANNEL – invalid value of parameter channel
DISABLED_CHANNEL – payment channel is unavailable
UNKNOWN_CURRENCY – currency code is invalid
BLOCKED_ACCOUNT – account ( id ) is blocked
INACTIVE_SELLER – account ( id ) is inactive
AMOUNT_TOO_LOW - amount is lower than minimum defined for shop
AMOUNT_TOO_HIGH - amount is higher than maximum defined for shop
BAD_DATA_FORMAT - invalid request data, e.g. invalid expiration_date format
URLC_INVALID - account ( id ) settings require the URLC to contain SSL (the address starts with: ‘https: // ‘)
REQUIRED_PARAMETERS_NOT_PRESENT – one of the required parameters is missing
MULTIMERCHANT_INVALID_ACCOUNT_CONFIGURATION – one of the accounts is not properly configured for Multimerchant payments
MULTIMERCHANT_INSUFFICIENT_AMOUNT – sum of amount(n) parameters is not equal to amount value
MULTIMERCHANT_WRONG_CURRENCY – values of parameters currency and currency(n) are not equal
CREDIT_CARD_NOT_ACCEPTED – credit card data has been sent, but account ( id ) configuration doesn’t allow processing it
CREDIT_CARD_OPERATION_TYPE_NOT_ACCEPTED_CODE – parameter sent credit_card_operation_type , but account serrings ( id ) does not allow its processing
CREDIT_CARD_SECURITY_CODE_REQUIRED_NOT_ACCEPTED_CODE – parameter sent credit_card_security_code_required , but account serrings ( id ) does not allow its processing
CREDIT_CARD_3DS_NOT_ACCEPTED_CODE – parameter sent credit_card_threeds , but account serrings ( id ) does not allow its processing
CREDIT_CARD_AVS_NOT_ACCEPTED_CODE – parameter sent credit_card_avs , but account serrings ( id ) does not allow its processing
UNKNOWN_ERROR - returned value in other case than the above mentioned
4. TEST ENVIRONMENT¶
It is possible to create a test environment (independently on production environment) which allows to make a simulation payment (transaction) in order to test the shop integration with Dotpay payment system.
Note
In order to receive Dotpay test environment access fill in registration form available at : https://ssl.dotpay.pl/test_seller/test/registration/
The address of a test environment has been placed below. Any action which should be taken in order to integrate with Dotpay payment system is analogical to the above described.
https://ssl.dotpay.pl/test_payment/ - address of the payment form
https://ssl.dotpay.pl/test_seller/ - address of the administration panel
https://ssl.dotpay.pl/test_payment/payment_api/channels/ - payment API address (channel list)
Simulating card payment (channel 248) requires valid card data.
Table below contains few exemplary cards which might be used for that purpose. Expiration date is anything from current date to December 2030.
4.1. Table 14. (List of sample card numbers that can be used in the process of testing card payments)¶
| TYPE | NUMBER | CVV2 / CVC2 | 3DS |
|---|---|---|---|
| Visa* | 4916 9715 6289 1025 | 025 | No |
| Visa* | 4929 5320 2788 7670 | 670 | Yes |
| MasterCard* | 5498 5400 7907 4343 | 343 | No |
| MasterCard* | 5344 6642 8071 1026 | 026 | Yes |
| Visa | 4111 1111 1111 1111 | 111 | No |
| Visa | 4444 4444 4444 4448 | 448 | Yes |
| MasterCard | 5500 0055 5555 5559 | 559 | No |
* for One-click or recurring payment testing
5. ADDITIONAL INFORMATION¶
5.1. Verification of the IP address¶
Dotpay IP address:
195.150.9.37
Using the above-mentioned IP service Dotpay sends all confirmation to the merchant’s system. For proper communication, the merchant should accept connections from this address.
Caution
Merchant’s system should always verify IP address from which a confirmation has been sent for security reasons.
Because of PCI DSS requirement the only SSL version used by Dotpay server is TLSv1.2 and TLSv1.3, with other protocol versions encrypted connection with host ssl.dotpay.pl will not be possible.
5.2. Security of payment integration¶
In order to provide the highest security standards for your transactions we recommend using all available security mechanisms.
Note
Transaction security should be handled in two places:
5.2.1. Redirecting customer from shop to Dotpay¶
Redirecting customer to Dotpay involves sending parameters defining payment details. To prevent unauthorized data manipulation in this step we recommend using data integrity protection. Parameters can be signed, this signature is passed as an additional chk parameter along other standard parameters.
A description of this functionality can be found in the chapter Redirection parameters integrity protection (CHK).
If your service is ready to send chk parameter for all of the transactions please contact Dotpay to enforce its verification.
Caution
Keep in mind minimal amount of payment parameters sent to Dotpay is: id , amount , currency , description .
Please verify whether your integration send those parameters correctly, according to format defined in this payment implementation manual.
5.2.2. Receiving confirmation of the posted payment in Dotpay¶
In order to send operation (transaction) confirmation to shop URLC (HTTP request, callback), mechanism is used, which using POST method passes all parameters.
If you are using this automatic notifications URLC, please make sure for every order received data is verified, especially when it comes to operation type ( operation_type ), it’s status ( operation_status ) and: - operation_original_amount - The amount taken from amount parameter which has been sent by merchant’s system.- operation_original_currency - The currency taken from currency parameter which has been sent by merchant’s system. - signature - checksum created by SHA‑256 function from concatenated notification parameters.
We also recommend to verify URLC notification origin, so in this case if IP belongs to Dotpay and is made using POST method. The IP address from which Dotpay sends notifications is listed in the chapter Verification of the IP address.
Caution
After receiving the confirmation of payment in the Dotpay service, the store should absolutely compare the value of the amount and currency paid with the expected amount registered when placing the order by the buyer in the store’s database.
The order should be processed by the store only when it checks whether the value due for the order stored in the store’s database is equal to the value posted in Dotpay assigned to the order!
6. ATTACHMENT I - PAYMENT CHANNELS¶
In the following table all channels which are available in Dotpay system are presented. Availability of payment method in a given account ( id ) depends on signed contract.
In the table the following are presented channel names, their providers and numbers, logotypes and remarks. Channel numbers are values which are accepted by channel parameter described in the above chapters.
6.1. Table 15. (Payment channels available in Dotpay system)¶
6.1.1. PAYMENT CARDS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 71 | MasterPass | - | 
|
24/7 | Available only for business accounts. |
| 246 | Payment cards | - | 
|
24/7 | Available only for business accounts. |
| 248 | Payment cards | - | 
|
24/7 | Available only for business accounts. Available for currency: PLN, EUR, USD, GBP |
| 249 | Visa SRC | - | 
|
24/7 | Available only for business accounts. |
| 260 | Google Pay | Google LLC | 
|
24/7 | Available only for business accounts. Required separate agreement. |
| 262 | Apple Pay | Apple Inc. | 
|
24/7 | Available only for business accounts. |
6.1.2. FAST TRANSFERS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 1 | mTransfer | mBank S.A. | 
|
24/7 | |
| 2 | Płacę z Inteligo | Bank PKO BP | 
|
24/7 | |
| 4 | Płacę z iPKO | Bank PKO BP | 
|
24/7 | |
| 6 | Przelew24 | Santander Bank Polska SA (previously Bank Zachodni WBK SA) | 
|
24/7 | |
| 36 | Pekao24Przelew | Bank Pekao S.A. | 
|
24/7 | |
| 38 | Płać z ING | ING Bank Śląski S.A. | 
|
24/7 | |
| 44 | Millennium - Płatności Internetowe | Millennium Bank S.A. | 
|
24/7 | |
| 45 | Pay with Alior Bank | Alior Bank S.A. | 
|
24/7 | |
| 46 | Płacę z Citi Handlowy | Citi Bank Handlowy S.A. | 
|
24/7 | |
| 50 | Pay Way Toyota Bank | Toyota Bank Polska | 
|
24/7 | |
| 51 | Płać z BOŚ | BOŚ Bank S.A. | 
|
24/7 | |
| 66 | Bank Nowy BFG S.A. | Bankowy Fundusz Gwarancyjny (dawniej Podkarpacki Bank Spółdzielczy) | 
|
24/7 | |
| 70 | Pocztowy24 | Bank Pocztowy S.A. | 
|
24/7 | |
| 73 | BLIK | Polski Standard Płatności Sp. z o.o. | 
|
24/7 | |
| 74 | Banki Spółdzielcze | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | |
| 75 | Płacę z Plus Bank | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | |
| 76 | Getin Bank PBL | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | |
| 80 | Noble Pay | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | |
| 81 | Idea Cloud | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | |
| 83 | EnveloBank | Bank Pocztowy S.A. | 
|
24/7 | |
| 86 | TrustPay | Trust Pay | 
|
24/7 | Available only for business accounts. Available for currency: CZK, EUR |
| 87 | Credit Agricole PBL | Credit Agricole Bank Polska S.A. | 
|
24/7 | Available only for business accounts. |
| 90 | BNP Paribas – płacę z Pl@net | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | Available only for business accounts. |
| 91 | Nest Bank | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | Available only for business accounts. |
| 92 | Bank Spółdzielczy w Brodnicy | Krajowa Izba Rozliczeniowa S.A. | 
|
24/7 | Available only for business accounts. |
| 93 | Kasa Stefczyka | Spółdzielcza Kasa Oszczędnościowo-Kredytowa im. F. Stefczyka | 
|
24/7 |
6.1.3. TRANSFERS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 7 | ING Corporate customers | ING Bank Śląski S.A. | 
|
Mon - Sat 8:00am - 8:00pm |
|
| 10 | Millennium Corporate customers | Millennium Bank S.A. | 
|
Mon - Fri 8:00am - 8:00pm |
|
| 15 | iPKO | Bank PKO BP | 
|
0:00am – 11:00pm / 7 | |
| 16 | Credit Agricole | Credit Agricole Bank Polska S.A. | 
|
4:00am – 11:00pm / 7 | |
| 32 | BNP Paribas | BNP Paribas Bank Polska SA | 
|
Mon - Fri 8:00am – 9:00pm |
|
| 89 | Santander | Santander Bank Polska SA (previously Bank Zachodni WBK SA) | 
|
Mon - Fri 8:00am – 9:00pm |
6.1.4. CASH¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 11 | Bank transfer / postal | - | 
|
Mon - Fri 3 Elixir sessions |
|
| 82 | SEPA transfer | - | 
|
Mon - Fri 3 Elixir sessions |
Available only for business accounts. Available for currency: EUR |
6.1.5. PURSES AND VOUCHERS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 52 | SkyCash | SkyCash Poland S.A. | 
|
24/7 | |
| 59 | CinkciarzPAY | Conotoxia Sp. z o.o. | 
|
24/7 | |
| 218 | paysafecard | Paysafecard | 
|
24/7 | Available for currency: PLN WARNING: refunds are not available on this channel |
6.1.6. INSTALLMENTS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 55 | Raty z Alior Bankiem | Alior Bank S.A. | 
|
24/7 | Available only for business accounts, for orders between 300.00 PLN and amount defined in the agreement. |
| 68 | mRaty | mBank S.A. | 
|
24/7 | Available only for business accounts, for orders between 300.00 PLN and amount defined in the agreement. |
6.1.7. OTHERS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 212 | PayPal | PayPal | 
|
24/7 | Available for currency: PLN Gateway model, Dotpay doesn’t send funds to the seller. |
6.1.8. POSTPONED PAYMENTS¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 94 | Kupuj teraz, zapłać później [Buy now, pay later] | Aiqlabs Sp. z o.o. | 
|
24/7 | Available only for business accounts, for orders between 100.00 PLN and 2000.00 PLN or amount defined in the agreement. |
| 92 | PayPo | PayPo Sp. z o.o. | 
|
24/7 | Available only for business accounts. for orders between 40.00PLN and 1000.00PLN. Required separate agreement. Requires |
6.1.9. MOBILE TRANSFERS - Direct Carrier Billing type¶
| NUMBER | NAME | PROVIDER | LOGO | POSTING PAYMENTS | REMARKS |
|---|---|---|---|---|---|
| 231 | Orange | Orange Polska S.A. | 
|
24/7 | Available only for business accounts. Required separate agreement with Dotpay partner. |
| 232 | T-Mobile | T-Mobile Polska S.A. | 
|
24/7 | Available only for business accounts. Required separate agreement with Dotpay partner. |
| 233 | PLAY | P4 Sp. z o.o. | 
|
24/7 | Available only for business accounts. Required separate agreement with Dotpay partner. |
| 234 | Plus | Polkomtel Sp. z o.o. | 
|
24/7 | Available only for business accounts. Required separate agreement with Dotpay partner. |
6.2. Payment Channel List - available for download¶
Note
Listed channels and their logos are available for download at:
- Channel logos: ( zip format )
- Available payment methods : ( format xlsx )
- Available payment methods: ( format json )
7. ATTACHMENT II - OPERATION STATUSES DESCRIPTION¶
In the following table are presented description of operation statuses which are created in system.
7.1. Table 16. (Operation statuses created in the Dotpay system)¶
| STATUS | MEANING / DESCRIPTION |
|---|---|
new (new) |
A new operation. It means establishment of the operation. |
processing (waiting for deposit) |
The operation is being processed, e.g. for payment type it means that a payer came back to Dotpay from a payment channel provider or a provider has informed Dotpay about this fact. payment and payment_multimerchant_child operations don’t have the accounting in the processing state. Complaint operation in this state means that a complaint procedure has been started. |
completed (completed) |
For payment, payment_multimerchant_child types it means that Dotpay has already had (or is sure to have) funds from the payment made by a customer. For release_rollback type it means that locked funds from rollback were released to the shop’s account ( For payout, refund and complaint types it means that funds have been transferred to a merchant, to a payer or a payment channel provider. This is the final status which means the operation will not change its status. For this operation additional accounting may be written but only those that are as a result of e.g. correction or correction incorrectly calculated. |
rejected (rejected) |
For payment, payment_multimerchant_child types it means that Dotpay has NOT received funds from a payer and is sure that won’t receive those funds. This means that e.g. a payer has cancelled a payment or doesn’t have enough funds at a payment channel provider (e.g. bank) to execute the payment. For payout, refund and complaint types it means that the operation was cancelled - funds were refunded to a shop’s account ( For this operation additional accounting may be written but only those that are as a result of e.g. correction or correction incorrectly calculated. |
processing_realization_waiting (waiting for realization) |
Operation in this state expects execution, e.g. for payout operation it means a withdrawal request (manually by a merchant or by auto withdrawal mechanism). Operation in this state expects execution in “n” business days where “n” is specified in the agreement signed by a merchant. |
processing_realization (realisation) |
This status means start of withdrawal execution procedure, for payout type operation it means payout transfer to the merchant’s account, for refund type operation funds transfer to a payer’s account. If possible (e.g. card payment channels), instead of funds transfer, a refund is executed on a given channel. |
8. CHANGELOG¶
| VERSION | DATE | CHANGES DESCRIPTION |
|---|---|---|
| 1.78.22.1 | 2021-04-26 | adding an additional optional parameter to Receiving confirmation of the posted payment in Dotpay updating the list of available payment channels |
| 1.77.10.1 | 2021-02-22 | changed channels logo: 71 ‘MasterPass’, 246, ‘Payment cards’, 248 (Payment cards) removed channel 35 ‘Kantor Polski’ |
| 1.75.7.1 | 2020-11-30 | logo change for the channel: 1 (mTransfer) adding new values for removed channel 60 (Płacę z T-Mobile Usługi Bankowe’) |
| 1.74.2.1 | 2020-11-16 | adding an additional optional parameter to URLC notification: add new channel group in |
| 1.73.13.1 | 2020-10-16 | logo change for the channel: 50 (Pay Way Toyota Bank) |
| 1.72.3.1 | 2020-09-15 | removed channel 21 ‘VIA - Moje Rachunki’ adding a new parameters adding data requirements sent in the parameter |
| 1.71.10.1 | 2020-08-18 | removed channel 84 ‘Volkswagen Bank direct’ adding an additional optional parameter to URLC notification: |
| 1.70.0.1 | 2020-07-27 | logo change for the channel 55 (Raty z Alior Bankiem) and channel 249 (Visa SRC) |
| 1.69.18.2 | 2020-06-26 | changed channels logo and and provider name for 249 ‘Visa SRC’ (before: ‘Visa Checkout’) |
| 1.69.18.1 | 2020-06-19 | logo change for the channel: 94 (Kupuj teraz, zapłać później) |
| 1.67.18.2 | 2020-04-22 | removed channel 65 (Płacę z Idea Bank) |
| 1.67.18.1 | 2020-04-22 | adding a new parameter adding data requirements sent in the parameter adding additional optional parameters to URLC CONFIRMATION: |
| 1.65.2.1 | 2020-02-11 | changed channels logo and and provider name for 66 ‘Bank Nowy BFG S.A.’ (before: ‘Płacę z PBS’) |
| 1.62.2.1 | 2019-11-08 | remove channels 48 (BNP Paribas – Płacę z Żółty), 88 (BNP Paribas dawni Klienci Raiffeisen), 56 (eurobank - płatność online) added channel 262 (Apple Pay) logo change for the channel 90 (BNP Paribas – płacę z Pl@net) extension of the added parameter |
| 1.60.16.1 | 2019-09-19 | removed channel 33 (Volkswagen Bank) |
| 1.59.10.2 | 2019-08-12 | adding a new parameter order.id in Chapter Shipping and payer data , adding parameter description pid typographic corrections |
| 1.59.10.1 | 2019-07-12 | logo change for the channel 51 (Płać z BOŚ) and channel 95 (PayPo) |
| 1.58.2.1 | 2019-06-10 | changed channels logo and and provider name for 55 ‘Raty z Alior Bankiem’ (before: ‘erata - raty z dotpay’) |
| 1.58.0.2 | 2019-06-03 | changed channels logo and and provider name for 93 ‘Kasa Stefczyka’ (before: ‘eSKOK’) adding a new Chapter: Security of payment integration; typographical corrections |
| 1.58.0.1 | 2019-05-23 | typographical corrections |
| 1.56.14.1 | 2019-04-24 | added new value for parameter currency : BGN, CHF, HRK, HUF, RUB |
| 1.56.11.3 | 2019-04-10 | removed channel 72 (Płacę z Orange) added parameter |
| 1.56.11.2 | 2019-04-01 | changed names and logos for channels: 32 (previously: BGŻ BNP Paribas), 48 (previously: R - Przelew), 88 (previously: Raiffeisen), 90 (previously: BGŻ BNP Paribas) added parameter |
| 1.56.11.1 | 2019-03-28 | added channel 95 (PayPo) added channel 260 (Google Pay) added current channel list in xlsx file for download changed names and logos for channels: 32 (previously: BGŻ BNP Paribas), 48 (previously: R - Przelew), 88 (previously: Raiffeisen), 90 (previously: BGŻ BNP Paribas) |
| 1.55.8.1 | 2019-03-22 | removed channel 31 (Zapłać w Żabce i we Freshmarket) removed channel 24 (mPay) |
| 1.55.7.1 | 2019-02-15 | added new value for parameter added new value for parameter added new value for parameter removed alternative payment parameters names: |
| 1.53.5.1 | 2018-12-10 | typographical corrections added parameter |
| 1.52.6.1 | 2018-11-13 | removed channel 58 („Szybkie Płatności Internetowe z Deutsche Bank PBC”) added a regular expression for the parameter amount |
| 1.51.0.1 | 2018-10-03 | added parameters in URLC notifications: credit_card_expiration_year and credit_card_expiration_month |
| 1.50.11.1 | 2018-09-27 | added channel 59 („CinkciarzPAY”) change of channel provider name from Volkswagen Bank Polska S.A. to Volkswagen Bank GmbH |
| 1.50.8.2 | 2018-09-07 | logo change for the channel 6 (Przelew24) and channel 89 (BZWBK) |
| 1.50.8.1 | 2018-09-05 | Newly created accounts now require changes in descriptions regarding verification of order amount and currency |
| 1.49.11.1 | 2018-06-26 | added values
|
| 1.45.2.1 | 2018-03-30 | changed name of section One-click payments to One-click and recurring payments added new parameters to the section mentioned above and included them in Redirection parameters integrity protection ( added new values for |
| 1.44.12.2 | 2018-03-08 | added channel 93 (eSKOK) |
| 1.44.12.1 | 2018-02-20 | logo change for the channel 48 (R-Przelew) and 246, 248 (Payment cards) |
| 1.44.10 | 2018-02-13 | added new values for parameter added new values for parameter added exemplary cards to TEST ENVIRONMENT chapter |
| 1.39.2.1 | 2017-09-03 | added channel 83 (EnveloBank) added channel 249 (Visa Checkout) changed channels logo 246 (Payment cards via Payeezy) and 248 (Payment cards) |
| 1.38.1.1 | 2017-08-21 | added channel 15 (iPKO) |
| 1.37.3.3 | 2017-07-10 | added parameter in URLC notifications: is_completed |
| 1.37.3.2 | 2017-06-28 | added Masscollect subchapter |
| 1.37.3.1 | 2017-06-27 | added Split payment (Multimerchant) subchapter added Multimerchant and Surcharge parameters to Redirection parameters integrity protection ( updated Faulty redirections from the merchant’s system subchapter added parameter |
| 1.36.10.1 | 2017-06-12 | logo change for the channel 36 („Pekao24Przelew”) |
| 1.36.7.1 | 2017-06-01 | added channel 90 (BGŻ BNP Paribas) added channel 91 (Nest Bank) added channel 92 (Bank Spółdzielczy w Brodnicy) added information about dowloading payment |
| 1.35.4.2 | 2017-04-05 | added value UAH for parameter added channel 88 (Raiffeisen) added channel 89 (BZWBK) |
| 1.35.4.1 | 2017-03-28 | removed kanału 18 (Przelew z BPH) |
| 1.34.9.3 | 2017-01-26 | added parameter in URLC notifications: credit_card_registration |
| 1.34.9.2 | 2017-01-11 | added regular expressions changed channels logo: 71 („MasterPass”), 246 („Payment cards via Payeezy”), 248 (Payment cards) |
| 1.34.9.1 | 2017-01-02 | removed channel 77 (FerBuy) removed value O – postponed payments from parameter |
| 1.33.4.2 | 2016-12-06 | added channel 218 (paysafecard) |
| 1.33.4.1 | 2016-11-14 | removed channel 27 (BGŻ) |
| 1.32.6.2 | 2016-11-07 | added removed channel 63 (Płacę z IKO) |
| 1.32.6.1 | 2016-09-23 | added channel 84 (Volkswagen Bank direct) added channel 86 (TrustPay) added channel 87 (Credit Agricole PBL) |
| 1.30.6.3 | 2016-06-22 | added deladdr parameter |
| 1.30.6.2 | 2016-06-17 | typographical corrections added added new way of receiving test environment access (added registration link) |
| 1.30.6.1 | 2016-06-01 | typographical corrections added One-click payments section added added value HASH_NOT_EQUAL_CHK for parameter |
| 1.29.11.1 | 2016-03-21 | added chapter ADDITIONAL FEATURES added subchapter Redirection parameters integrity protection ( moved subchapter Faulty redirections from the merchant’s system to chapter ADDITIONAL FEATURES |
| 1.29.8.1 | 2016-02-26 | added parameter added information about HTTPS verify and SSL certificate verify in II. RECEIVING PAYMENT CONFIRMATION (URLC CONFIRMATION) chapter added channel 82 (Przelew SEPA) added channel 248 (Payment cards) removed channel 64 (PeoPay) |
| 1.28.5.2 | 2016-01-07 | added parameter added chapter ATTACHMENT II - OPERATION STATUSES DESCRIPTION |
| 1.28.5.1 | 2015-12-31 | removed channel 79 (Open Pay) |
| 1.27.0.1 | 2015-11-10 | removed channel 25 (Plus Bank) |
| 1.25.7.1 | 2015-10-30 | removed channel 49 (MeritumBank) |
| 1.25.3.1 | 2015-10-22 | removed channel 22 (Ukash) removed channel 43 (Bank Spółdzielczy we Wschowie) removed channel 62 (DNB Nord) |
| 1.25.1.1 | 2015-10-19 | change of the main payment site (from https://ssl.dotpay.pl to https://ssl.dotpay.pl/t2/) removed channel 3 (MultiTransfer) |
| 1.24.9.1 | 2015-10-12 | added channel 81 (Idea Cloud) |
| 1.23.13.3 | 2015-09-24 | typographical corrections |
| 1.23.13.2 | 2015-08-20 | removed channel 69 (V.me) |
| 1.23.13.1 | 2015-08-12 | added channel 79 (Open Pay) added channel 80 (Noble Pay) removed channel 15 (iPKO) |
| 1.23.9.2 | 2015-07-30 | removal of UNKNOWN_ACCOUNT value of error_code parameter described in FAULTY REDIRECTIONS FROM THE MERCHANT’S SYSTEM chapter |
| 1.23.9.1 | 2015-07-20 | added channel 77 (FerBuy) |
| 1.22.9.1 | 2015-06-01 | added channel 74 (Banki Spółdzielcze) added channel 75 (Płacę z Plus Bank) added channel 76 (Getin Bank PBL) removed channel 17 (Płacę z iPKONET) removed channel 57 (Getin Bank) added parameters |
| 1.20.9.2 | 2015-02-09 | added channel 73 (BLIK) |
| 1.20.9.1 | 2015-01-14 | removed channel 245 (MasterCard Mobile) added chapter CHANGE LOG. |
| 1.19.15.2 | 2014-12-12 | added channel 72 (Płacę z Orange) |
| 1.19.15.1 | 2014-12-08 | added channel 71 (MasterPass) |
| 1.18.5.4 | 2014-11-04 | added channel 69 (V.me) |
| 1.18.5.3 | 2014-11-19 | removed channels 14 (KB24) and 61 (Bank Pocztowy) |
| 1.18.5.2 | 2014-10-28 | added channels 66 (Płacę z PBS ) and 70 (Pocztowy24) renamed channel 17 (from Płać z Nordea to Płacę z IPKOnet) added https://ssl.dotpay.pl/test_seller/ address to TEST ENVIRONMENT chapter |