General principles of interaction

Rules for forming a request:

1. The encoding used — UTF-8.
2. The names of all parameters that relate to the interaction between Platron and the merchant have a prefix pg_. All other parameters do not have it.
3. In all monetary amounts:
   • a dot is used to separate the fractional part.
   • if the number is an integer, then indicating the fractional part is optional.
   • the number of characters after the dot is no more than two.
   • thousands are not separated by any signs.
4. Any messages (requests and responses) between Platron and the merchant are signed.

Signature formation

Example of a call http://domain.com/path/to/script.php

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>9imM909TH820jwk387</pg_salt>
    <pg_t_param>value3</pg_t_param>
    <pg_a_param>value1</pg_a_param>
    <pg_z_param>
        <pg_q_subparam>subvalue2</pg_q_subparam>
        <pg_m_subparam>subvalue1</pg_m_subparam>
    </pg_z_param>
    <pg_b_param>value2</pg_b_param>
    <pg_sig>a8a4d5a9188f24038a14a4d65c387bf7</pg_sig>
</request>

In this example pg_sig is calculated using the formula:

pg_sig = md5('script.php' + ';' + pg_a_param + ';' + pg_b_param + ';' + pg_salt + ';' + pg_t_param + ';' + pg_m_subparam + ';' + pg_q_subparam + ';' + secret_key);

If it was specified in the settings that secret_key is equal mypasskey, then after substituting the values you get:

pg_sig = md5('script.php;value1;value2;9imM909TH820jwk387;value3;subvalue1;subvalue2;mypasskey')
pg_sig = 'a8a4d5a9188f24038a14a4d65c387bf7'

To ensure security, all messages between Platron and third-party merchants are specially signed. To generate a signature, you must complete the following steps:

1. Get the name of the script being called. Is this the part of the URL from the last slash “/" to the end or the question mark “?".
2. Get all message parameters. If the message is in XML format, the parameters are taken from all nested tags in alphabetical order. Parameters with the same name are taken in the order in which they are present in the message.
3. Get a random string pg_salt. This is a string consisting of an arbitrary number of numbers and letters of the Latin alphabet.
4. Concatenate the resulting values with the separator “;". The concatenation order is as follows: script name, all message fields, pg_salt and payment password secret_key, which is set in the merchant settings.
5. Calculate MD5-hash from the resulted string.
6. Write the resulting MD5-hash as a hexadecimal string in lowercase 32 characters long (pg_sig).
7. Add pg_sig parameter to request or response.

Any party may add additional parameters to a request or response that are not specified in the documentation. These parameters are also involved in the signature calculation.

If Platron cannot identify the merchant (merchant), so it does not know its secret key (secret_key), then the message is not signed and therefore pg_salt и pg_sig parameters are missing. In this case field pg_error_code, which contains the numeric error code, takes the value 101. To check the correctness of the signature formation, it is recommended to use a special tool in the personal account of the merchant: Verifying the signature to a request.

Direct interaction

When transferring complex structured data via GET, such as multidimensional arrays, the following recording format is used:

https://www.platron.ru/script.php?param_1=val1&m_2[subparam_1]=val2&m_2[subparam_2]=val3&m_3=val4

Example of xml request:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_param1>value1</pg_param1>
    <pg_param2>value2</pg_param2>
    <pg_param3>value3</pg_param3>
</request>

Example of a successful response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_param1>value1</pg_param1>
    <pg_param2>value2</pg_param2>
    <pg_param3>value3</pg_param3>
</response>

Example of an error response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>19imfwM909TH820jwk387</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_error_description>amount not specified</pg_error_description>
    <pg_sig>ccde41a4f425d124a23c3a53a3140bdc158ac</pg_sig>
</response>

There are three ways to transfer information directly between the merchant and Platron:

1. GET method – data is transferred in parameters using the GET method.
2. POST method – data is transferred in parameters using the POST method.
3. Via XML – requests are transmitted using the POST method in a single parameter pg_xml:

Regardless of the method of forming the request (GET, POST or XML), the response is always given in XML format.

The response always contains the pg_status parameter, which indicates the result of the query execution. It takes the value ok if the request was successfully completed and error if an error occurred. In the latter case, the response will contain the following fields:

• pg_error_code – numeric error code (possible values are listed in the section Error code reference book)
• pg_error_description – error description (optional field).

Through the user's browser

Platron and the merchant can transfer information to each other at the same time as the control is transferred to the buyer. The transfer can take place by the buyer's action or automatically.

Transfer of information on the buyer's action

The transfer of buyer and information between Platron and the merchant is possible in the following ways::

1. A link that leads to another site
2. A form whose action redirects to another resource. The user presses the button himself.

Automatic transmission of information

Example of auto-submit form

<html>
<body onload="document.forms[0].submit()">
<form method="POST" action="https://www.platron.ru/payment.php">
    <input type="hidden" name="pg_param1" value="value1"/>
    <input type="hidden" name="pg_param2" value="value2"/>
    <input type="hidden" name="pg_param3" value="value3"/>
    <input type="hidden" name="pg_param4" value="value4"/>
</form>
</body>
</html>

Automatic transfer of buyer and information between Platron and the merchant is possible in the following ways:

1. Using HTTP redirect 302 (Location header) - only for GET method.
2. Automatic form submission. GET and POST methods are supported. The website provides the user with a page containing a form whose action redirects to another resource. The form contains only hidden fields and is automatically submitted on onload event, so the user does not see this page.

Merchant settings

Before you start working, you need to fill in the following merchant settings in Platron.

All specified parameters, except for merchant information and secret_key, can be redefined for each specific payment at the time of payment initialization.

List of PS

https://www.platron.ru/ps_list.php?pg_salt=123&pg_merchant_id=456&pg_amount=800.45&pg_currency=RUB&pg_sig=aec5f9d237952f83bd05c602d287098d

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>123</pg_salt>
    <pg_merchant_id>456</pg_merchant_id>
    <pg_amount>800.45</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_sig>aec5f9d237952f83bd05c602d287098d</pg_sig>
</request>

This method allows you to get information about available payment systems and final amounts taking into account commissions.

Request URL

https://www.platron.ru/ps_list.php

Request parameters

Required parameters are highlighted in bold

Response parameters

Example answer:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9938745</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_system>
        <pg_name>MIXPLATMTS</pg_name>
        <pg_description>Payment from a mobile phone account МТС</pg_description>
        <pg_payment_scenario>offline</pg_payment_scenario>
        <pg_amount_to_pay>808.67</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>mobile</pg_category>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>CASH</pg_name>
        <pg_description>Cash: Euroset, OSMP, Elecsnet</pg_description>
        <pg_payment_scenario>offline</pg_payment_scenario>
        <pg_amount_to_pay>830.00</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>cash</pg_category>
        <pg_sub_payment_systems>
            <pg_sub_payment_system>
                <pg_sub_name>ELECSNET</pg_sub_name>
                <pg_sub_description>Elecsnet</pg_sub_description>
            </pg_sub_payment_system>
            <pg_sub_payment_system>
                <pg_sub_name>EUROSET</pg_sub_name>
                <pg_sub_description>Евросеть</pg_sub_description>
            </pg_sub_payment_system>
            <pg_sub_payment_system>
                <pg_sub_name>QIWI</pg_sub_name>
                <pg_sub_description>QIWI</pg_sub_description>
            </pg_sub_payment_system>
        </pg_sub_payment_systems>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>WEBMONEYRBANK</pg_name>
        <pg_description>Система WebMoney</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_amount_to_pay>810.35</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>wallet</pg_category>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>YANDEXMONEY</pg_name>
        <pg_description>Yandex-money system</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_amount_to_pay>812.15</pg_amount_to_pay>
        <pg_amount_to_pay_currency>RUB</pg_amount_to_pay_currency>
        <pg_category>wallet</pg_category>
    </pg_payment_system>
    <pg_sig>73daf9d237952f56bd05c602d2878dc2</pg_sig>
</response>

The response tag contains a list of payment systems and a signature. The description of each payment system is located inside the pg_payment_system tag with a unique identifier in the pg_name attribute – the name of the payment system. Parameters can be returned for each system:

The response to the request is XML (in utf-8 encoding) containing a list of payment systems available for this merchant and their attributes. The attributes are the amount and currency of the payment, the name and description of the PS, as well as a list of additional pg_required parameters required for this PS. The response also contains a list of parameters that can be sent additionally for pg_additional payment systems.

Merchant must control the filling of these parameters. If a payment system is selected for which there is a mandatory parameter to fill in, but this parameter is not transmitted, then it will be requested from the buyer on the website www.platron.ru.

The list of payment systems in the response is sorted by the pg_name parameter, and within the group by pg_sub_name. If the payment system is a group of payment systems, then the list of payment systems included in the group is presented in the tag pg_sub_payment_systems.

An example of constructing a list for selecting a payment system can be seen on the website www.platron.ru, if you do not transmit the PS identifier when initializing the payment.

Initializing payment

Common

To create a payment transaction (initialize a payment), the merchant must perform two actions:

1. transfer payment data to Platron
2. transfer the buyer to the management of Platron

This can be done in two ways:

1. transfer payment information through the user's browser, while at the same time the user goes to the Platron website.
2. transfer the payment information directly to Platron, in response, receive the payment transaction ID and URL for subsequent redirection of the buyer, and then redirect the buyer to this URL.

In both cases, the composition of the transmitted data is completely identical, only the transmission method and response format differ.

Required parameters:

Optional parameters:

Host-To-Host

When transferring data directly from a merchant to Platron, the merchant must send data to a URL

Request URL

https://www.platron.ru/init_payment.php

Response parameters

Example of response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>ijoi894j4ik39lo9</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>15826</pg_payment_id>
    <pg_redirect_url>
        https://www.platron.ru/payment_params.php?customer=ccaa41a4f425d124a23c3a53a3140bdc15826
    </pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_sig>af8e41a4f425d124a23c3a53a3140bdc17ea0</pg_sig>
</response>

Response in case of error:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>101</pg_error_code>
    <pg_error_description>Empty merchant</pg_error_description>
</response>

If the merchant receives a response with pg_redirect_url_type="need data", the merchant may not redirect the buyer to the received URL, but specify the missing parameters on its website. In this case, after clarifying the parameters and re -requesting the creation of a payment transaction, a new transaction will be created.

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_salt>b54a5e50</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_system>
        <pg_name>CONNECTUMUSD</pg_name>
        <pg_description>Оплата картой</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_amount_to_pay>1.09</pg_amount_to_pay>
        <pg_amount_to_pay_currency>usd</pg_amount_to_pay_currency>
        <pg_category>bankcard</pg_category>
        <pg_additional source="merchant">pg_user_email</pg_additional>
        <pg_additional source="merchant">pg_user_login</pg_additional>
    </pg_payment_system>
    <pg_sig>c7c1448d92cb00235a1206d1e46e6bad</pg_sig>
</response>

If the buyer needs to know any additional data in order to make a payment using a certain payment system , the response contains this data in the fields pg_required и pg_additional. The fields transmitted when making a payment through specific payment systems can be viewed in the section Handbook of additional PS parameters.

Through the user's browser

https://www.platron.ru/payment.php?pg_merchant_id=111&pg_amount=1000&pg_order_id=123&pg_check_url=http://www.shop.ru/check.php&pg_result_url=http://www.shop.ru/result.php&pg_success_url=http://www.shop.ru/thankyou.php&pg_failure_url=http://www.shop.ru/failed.php&pg_description=Ticket+SU1234+Moscow-Berlin+1+Jun+2008&custom_param1=gagaga&custom_param2=gugugu&pg_sig=af8e41a4f425d124a23c3a53a3140bdc17ea0

When transmitting information through the user's browser, the user must be transmitted using the POST or GET method.

Request URL

https://www.platron.ru/payment.php

In case of an error, an error message is displayed on the user's screen.

If merchant does not transmit all the parameters necessary to create a payment transaction (payment system, user's phone number and parameters necessary for the selected payment system), they are requested from the user on the website www.platron.ru

Recurring payments

Recurring payments are available:

1. In the authorization-write-off scheme. The recurrent profile will be available only after clearing on the primary transactions
2. In the authorization scheme, the recurrent profile will be available immediately after authorization.

To use the recurring payment profile, the store should initialize the payment in the usual way by passing the additional parameter pg_recurring_start, indicating the requirement to create a recurring profile and specifying a payment system that supports recurring payments in the parameter pg_payment_system (see Payment systems Handbook). The profile number for repeating the payment will be transmitted when notifying about the payment result in the parameter pg_recurring_profile. The seller can also define the validity period of the recurring profile (this parameter is optional and if not specified, the card expiration date will be used).If the pg_recurring_lifetime parameter specified by the seller exceeds the validity period of the card, then the validity period of the recurrent profile expires on the expiration date of the card. Before using recurring payments, you need to contact your manager to clarify the details.

Payment recurrence

https://www.platron.ru/make_recurring_payment.php?pg_merchant_id=82&pg_recurring_profile=109642&pg_description=example&pg_salt=my_salt&pg_sig=3fe59db16e24d78bfecfd8d72324b83c

Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_salt>my_salt</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>22241128</pg_payment_id>
    <pg_amount>1</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_recurring_profile_id>109642</pg_recurring_profile_id>
    <pg_recurring_profile_expiry_date>2029-01-29 00:00:00</pg_recurring_profile_expiry_date>
    <pg_sig>5b2ff43cfa1b7588e5844484f0843b11</pg_sig>
</response>

Merchant may repeat payments for a recurring profile at any time at its discretion.

Request URL

https://www.platron.ru/make_recurring_payment.php

Request parameters

Platron will notify the seller about the result of the payment at Result URL

On schedule

For a recurring profile, you can specify a payment schedule. In this case, payments will be made automatically according to the specified schedule. You can specify the schedule either as a template or as a simple list of dates.

Creating a schedule

An example indicating a template.

For better readability, service characters are not escaped in the example.
https://www.platron.ru/index.php/api/recurring/set-schedule?pg_merchant_id=82&pg_recurring_profile=337146&pg_amount=21.23&pg_template[pg_start_date]=2018-08-15 15:30:00&pg_template[pg_interval]=week&pg_template[pg_period]=2&pg_template[pg_max_periods]=5&pg_salt=salt&pg_sig=5036eda9b1a31d5d8ed825c5d658ad43

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_recurring_profile>337146</pg_recurring_profile>
    <pg_amount>12.41</pg_amount>
    <pg_template>
        <pg_start_date>2018-08-15 15:30:00</pg_start_date>
        <pg_interval>week</pg_interval>
        <pg_period>2</pg_period>
        <pg_max_periods>5</pg_max_periods>
    </pg_template>
    <pg_salt>salt</pg_salt>
    <pg_sig>458a8161df06e21bcc6967c44e9965qw</pg_sig>
</request>

Example with a list of dates.

For better readability, service characters are not escaped in the example.
https://www.platron.ru/index.php/api/recurring/set-schedule?pg_merchant_id=82&pg_recurring_profile=337146&pg_amount=21.23&pg_dates[]=2018-08-15 14:00:00&pg_dates[]=2018-08-15 14:30:00&pg_dates[]=2018-08-15 15:00:00&pg_salt=salt&pg_sig=0d32e1bfb8795a7c2a7ff86973vct5er

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_recurring_profile>337146</pg_recurring_profile>
    <pg_amount>12.41</pg_amount>
    <pg_dates>2018-08-15 14:00:00</pg_dates>
    <pg_dates>2018-08-15 14:30:00</pg_dates>
    <pg_dates>2018-08-15 15:00:00</pg_dates>
    <pg_salt>salt</pg_salt>
    <pg_sig>b71988a7cc47ae411d9292a0933944ac</pg_sig>
</request>

Request URL

https://www.platron.ru/index.php/api/recurring/set-schedule

Request parameters

*To create a schedule, you must specify either template data or a list of dates. If both template data and a list of dates are specified, the list of dates will be used to create the schedule.

Template Parameters (pg_template):

*The period is used in combination with the interval. For example, 1 month means once a month, 2 week means once every two weeks.

Response when the schedule is successfully created.

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_recurring_profile>337146</pg_recurring_profile>
    <pg_salt>salt</pg_salt>
    <pg_sig>a764fb36af2e607ee2e841989adr65ty</pg_sig>
</response>

Closing a recurring profile

It is necessary to delete the schedule in Platron, if it was created, and mark such a profile as closed in your accounting system.

Payment status

https://www.platron.ru/get_status.php?pg_salt=9865&pg_merchant_id=82&pg_payment_id=765432&pg_sig=a1b7ccc945c0a60949f6bd6383f5f768

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>9865</pg_salt>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_sig>a1b7ccc945c0a60949f6bd6383f5f768</pg_sig>
</request>

The merchant may query Platron about the status of any payment initiated by the merchant. This can be useful, for example, if the Result URL call was not received by the merchant due to a temporary communication failure, and the customer was already transferred to the Success URL, but the transaction status is not yet known to the mechant.

Request URL

https://www.platron.ru/get_status.php

Request Parameters

All parameters are required

*Either pg_payment_id or pg_order_id is required. In the case of pg_order_id, if it is not unique, information will be provided for the last payment with this order_id.

Response parameters

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>1234567</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_create_date>2009-01-12 10:22:30</pg_create_date>
    <pg_result_date>2009-01-12 10:25:07</pg_result_date>
    <pg_payment_system>RUSSIANSTANDARD</pg_payment_system>
    <pg_card_brand>CA</pg_card_brand>
    <pg_card_pan>527594******4984</pg_card_pan>
    <pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash>
    <pg_auth_code>014318</pg_auth_code>
    <pg_captured>0</pg_captured>
    <pg_sig>8380d43c7719e6ce48da0c79aa7eb2ba</pg_sig>
    <pg_qr_code>https://www.platron.ru/index.php/api/qr-code/getcustomer=c79a5520e313a8f836bb6fc17d0ffa7c3504513922
    </pg_qr_code>
</response>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_payment_id>1234567</pg_payment_id>
    <pg_transaction_status>pending</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_create_date>2009-01-12 10:22:30</pg_create_date>
    <pg_accepted_payment_systems>EUROSET,EUROPLAT,QIWI</pg_accepted_payment_systems>
    <pg_sig>8380d43c7719e6ce48da0c79aa7eb2ba</pg_sig>
    <pg_qr_code>https://www.platron.ru/index.php/api/qr-code/getcustomer=c79a5520e313a8f836bb6fc17d0ffa7c3504513922
    </pg_qr_code>
</response>

All dates are written in the format YYYY-MM-DD hh:mm:ss.

Clearing

https://www.platron.ru/do_capture.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_sig=7f3af9d237952f56bd05c602d2879a3c

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>123</pg_salt>
    <pg_merchant_id>456</pg_merchant_id>
    <pg_payment_id>1234567</pg_payment_id>
    <pg_sig>7f3af9d237952f56bd05c602d2879a3c</pg_sig>
</request>

Merchant can independently request clearing from the bank via Platron if the bank is configured to process payments in two steps - authorization and clearing.

If the system is configured accordingly, after the transaction is carried out, the transaction will be authorized, but not calculated. The maximum authorization time is regulated on the Platron side and can be up to 5 calendar days. The possibility of setting up deferred clearing should be clarified with your supervising manager.

Request URL

https://www.platron.ru/do_capture.php

Request parameters

Response parameters

E[ample of response

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>1111</pg_salt>
    <pg_status>ok</pg_status>
    <pg_clearing_refund_id>449312</pg_clearing_refund_id>
    <pg_sig>c38ebf6a6b7f5e30316bc984dc69ce37</pg_sig>
</response>

Cancel payment

Before payment

https://www.platron.ru/cancel.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_sig=628e300c3204c8ee398d878a5109b520

<?xml version="1.0" encoding="utf-8"?>
<request>
  <pg_salt>123</pg_salt>
  <pg_merchant_id>456</pg_merchant_id>
  <pg_payment_id>1234567</pg_payment_id>
  <pg_sig>628e300c3204c8ee398d878a5109b520</pg_sig>
</request>

Merchant can cancel payment that has been issued but not yet paid. After this operation, Platron will refuse to process the payment at the stage of checking the possibility of making the payment. Cancellation of the payment on the payment system side is possible if such functionality is supported by it. (See Payment systems handbook))

Request URL

https://www.platron.ru/cancel.php

Request parameters

Response parameters

Example of response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig>
</response>

In case of error:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_error_description>
        transaction not found
    </pg_error_description>
    <pg_sig>ac08f9d237952f5bc4e5c602d2873481</pg_sig>
</response>

The "ok" response means that the request to cancel the has been accepted. The invoice may still be paid if the PS to which the invoice was issued does not support invoice cancellation operations and does not make preliminary requests to confirm the possibility of making a payment.

If the PS does not support invoice cancellation, but supports refunds (e.g. TRANSCRED), Platron will attempt to cancel the received payment. In this case, an additional fee may be charged for the payment cancellation operation.

After payment

https://www.platron.ru/revoke.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_refund_amount=800&pg_description=возврат%20товара&pg_sig=6dd2a9d237952f56bd05c602d2872af8

<?xml version="1.0" encoding="utf-8"?>
<request>
  <pg_salt>123</pg_salt>
  <pg_merchant_id>456</pg_merchant_id>
  <pg_payment_id>1234567</pg_payment_id>
  <pg_refund_amount>800</pg_refund_amount>
  <pg_sig>6dd2a9d237952f56bd05c602d2872af8</pg_sig>
</request>

Merchant can cancel a successfully completed payment if the payment system allows it (for example, Bank cards). In this case, the money is returned to the buyer. You can return either the full amount of the payment or part of the amount. You can make several partial refunds until the total amount of refunds reaches the amount of the original payment.

Request URL

https://www.platron.ru/revoke.php

Request Parameters

Response parameters

Example of response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig>
</response>

In case of error:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>490</pg_error_code>
    <pg_error_description>this transaction can’t be revoked</pg_error_description>
    <pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>
</response>

Receipts (ФЗ-54)

Before setting up, you need to contact the manager.

Creating a receipt

https://www.platron.ru/receipt.php?pg_merchant_id=123&pg_salt=your_salt&pg_sig=generated_sig&pg_operation_type=payment&pg_payment_id=payment_id&pg_additional_payment_amount=12.23&pg_additional_payment_type=credit&pg_customer_name=customer_name&pg_customer_inn=12345678901&pg_items[0][pg_label]=item1&pg_items[0][pg_price]=1.1&pg_items[0][pg_quantity]=2&pg_items[0][pg_vat]=20&pg_items[0][pg_type]=product&pg_items[0][pg_payment_type]=full_payment&pg_items[0][pg_agent_type]=agent&pg_items[0][pg_agent_name]=name&pg_items[0][pg_agent_inn]=12345678902&pg_items[0][pg_agent_phone]=79999999999

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_merchant_id>123</pg_merchant_id>
    <pg_salt>your_salt</pg_salt>
    <pg_sig>generated_sig</pg_sig>
    <pg_operation_type>payment</pg_operation_type>
    <pg_payment_id>payment_id</pg_payment_id>
    <pg_additional_payment_amount>12.23</pg_additional_payment_amount>
    <pg_additional_payment_type>credit</pg_additional_payment_type>
    <pg_customer_name>customer_name</pg_customer_name>
    <pg_customer_inn>12345678901</pg_customer_inn>
    <pg_items>
        <pg_label>item1</pg_label>
        <pg_price>1.1</pg_price>
        <pg_quantity>2</pg_quantity>
        <pg_vat>20</pg_vat>
        <pg_type>product</pg_type>
        <pg_payment_type>full_payment</pg_payment_type>
        <pg_agent_type>agent</pg_agent_type>
        <pg_agent_name>name</pg_agent_name>
        <pg_agent_inn>12345678902</pg_agent_inn>
        <pg_agent_phone>79999999999</pg_agent_phone>
    </pg_items>
</request>

It is necessary to generate data for the receipt immediately after creating the operation. The receipt will be sent to the OFD and the buyer only after the successful completion of the operation.

To be able to test the functionality, you need to contact the supervising manager.

If the payment is made in a foreign currency or a payment system is used that charges an additional fee in excess of the payment amount, the receipt must be issued after receiving a notification on the Result Url about the successful payment. This request does not work for refund requests and refunds without payment (moneyback) not linked to a transaction.

Request URL

https://www.platron.ru/receipt.php

Request Parameters

*Either pg_payment_id or pg_order_id is required. If pg_order_id is not unique, the receipt will be created for the last order.

Position parameters in the receipt:

If at least one of the pg_agent parameters is passed, all remaining fields must be filled.

If the store does not need to pass additional parameters, no changes need to be made.

* New VAT rates are available from 01.01.2025. Before using them, you need to make sure that your online cash register supports them.

Response Parameters

The response to the request is XML of the following format if the request is successful:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_receipt_id>135</pg_receipt_id>
    <pg_salt>salt</pg_salt>
    <pg_sig>60beff140b3c9c6dt87603522cc1c07f</pg_sig>
</response>

In case of error:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>100</pg_error_code>
    <pg_error_description>Incorrect signature</pg_error_description>
    <pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>
</response>

The status of the receipt in the OFD

https://www.platron.ru/get_receipt_status.php?pg_merchant_id=82&pg_receipt_id=10000&pg_salt=aaaaaaaaaa&pg_sig=b2c010162d43d2ba98a7f68caee24761

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_merchant_id>82</pg_merchant_id>
    <pg_receipt_id>10000</pg_receipt_id>
    <pg_salt>aaaaaaaaaa</pg_salt>
    <pg_sig>b2c010162d43d2ba98a7f68caee24761</pg_sig>
</request>

Request URL

https://www.platron.ru/get_receipt_status.php

Request parameters

Response Parameters

The response to the request is XML of the following format if the request is successful:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_receipt_status>ok</pg_receipt_status>
    <pg_fiscal_receipt_number>6</pg_fiscal_receipt_number>
    <pg_shift_number>23</pg_shift_number>
    <pg_receipt_date>2017-04-12 20:16:00</pg_receipt_date>
    <pg_fn_number>1110000100238211</pg_fn_number>
    <pg_ecr_registration_number>0000111118041361</pg_ecr_registration_number>
    <pg_fiscal_document_number>133</pg_fiscal_document_number>
    <pg_fiscal_document_attribute>3449555941</pg_fiscal_document_attribute>
    <pg_salt>aaaaaa</pg_salt>
    <pg_sig>531b7999c74d984fa8c9e1ff029a40d7</pg_sig>
</response>

In case there is no information on the receipt yet:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>ok</pg_status>
    <pg_receipt_status>pending</pg_receipt_status>
    <pg_sig>75ed486aa0dfd5363e2e5a87e8e30634</pg_sig>
</response>

In case of error:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>9865</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>100</pg_error_code>
    <pg_error_description>Incorrect signature</pg_error_description>
    <pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>
</response>

Moneyback

List of PS for moneyback

https://www.platron.ru/moneyback_system_list.php?pg_merchant_id=82&pg_salt=aaaaa&pg_sig=0c86434c28fcc71166b28778c961a5d0

Getting a list of contacts with payment systems available for them

Request URL

https://www.platron.ru/moneyback_system_list.php

Request Parameters

Response parameters

Example of response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_contract_list>
        <pg_contract>
            <pg_contract_id>24258</pg_contract_id>
            <pg_account_amout>-30061.6100</pg_account_amout>
            <pg_moneyback_system_list>
                <pg_moneyback_system>
                    <pg_system_name>YANDEXMONEY_O</pg_system_name>
                    <pg_description>Description</pg_description>
                    <pg_amout>Amount</pg_amout>
                    <destination_account>wallet number</destination_account>
                </pg_moneyback_system>
                <pg_moneyback_system>
                    <pg_system_name>CONTACT_O</pg_system_name>
                    <pg_description>Description</pg_description>
                    <pg_amout>Amount</pg_amout>
                    <bName>Recipient's last name</bName>
                    <bLastName>Recipient's name</bLastName>
                    <bSurName>Recipient's patronymic</bSurName>
                </pg_moneyback_system>
            </pg_moneyback_system_list>
        </pg_contract>
    </pg_contract_list>
    <pg_salt>3399407</pg_salt>
    <pg_sig>700466634e329c11f6bbf094ea264eb8</pg_sig>
</response>

In response, Platron will return a list of valid contracts for which payment systems are available for moneyback and mandatory additional fields.

Request for moneyback

https://www.platron.ru/create_moneyback.php?pg_merchant_id=82&pg_contract_id=24258&pg_payment_id=22568489&pg_moneyback_system=CONTACT_O&pg_amount=120.00&pg_description=Тестовая_выплата&pg_salt=732343&bName=Фамилия_получателя&bLastName=Имя&bSurName=Отчество получателя&pg_sig=4f22f5a4903738a69e3ac74b96b23d4e

Merchant can make a moneyback to its customer without reference to a previous payment via Platron. This can be useful, for example, if the payment was not accepted through Platron, or if it is necessary to return funds for several payments of one client in one operation. Current functionality can only be connected through the supervising manager.

The standard moneyback is carried out with reference to the transaction.

Request URL

https://www.platron.ru/create_moneyback.php

Request Parameters

Each PS may have its own set of mandatory additional parameters that must be passed when requesting a payment, these parameters will be returned when requesting a list of available PS.

Response parameters

Example of response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_moneyback_id>727188</pg_moneyback_id>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

Example of a response in case of an error in the request:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>100</pg_error_code>
    <pg_description>Error description</pg_description>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

The response will contain the result of an attempt to create a moneyback. In case of an error, the pg_error_code parameter will appear with the error number and the pg_description parameter with the error description.

If the pg_payment_id parameter is passed, the moneyback is linked to the transaction and the moneyback amount cannot exceed the direct transaction amount, otherwise an error will be returned.

You can make a moneyback transaction for less than the full amount, or several moneyback, as long as the total moneysback amount does not exceed the direct transaction amount.

Moneyback status

https://www.platron.ru/get_moneyback_status.php?pg_merchant_id=1234&pg_moneyback_id=72612&pg_salt=f387f3h3&pg_sig=bfc5f9d2379d287052f56bd05c60296e

Request URL

https://www.platron.ru/get_moneyback_status.php

Request parameters

Response parameters

Example of response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>pending</pg_status>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

In case of an error, the response will look like this:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_description>The required parameter is missing</pg_description>
    <pg_salt>kdjdope983</pg_salt>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

Cancellation of moneyback

Moneyback cancellation is available in your personal account on the Platron website at the link https://www.platron.ru/admin/moneyback_transactions.php

Register of Operations

Sending by email

In the merchant's parameters, it is possible to set an e-mail address to which the register of payments for the previous day will be sent every day. The register is formed at 0:10 Moscow time.

The headers of the letter contain the following information:

1. X-Merchant-ID: Merchant ID, issued to merchant (example: 14)
2. X-Registry-Date: The date on which the register was compiled, in the format YYYY-MM-DD (example: 2009-12-02)
3. The "From" field of the letter contains info@platron.ru
4. Subject of the letter: Platron report for merchant #id [YYYY-MM-DD]

For security purposes, merchant is advised to check the letter headers to ensure the authenticity of the received registry.

The registry is sent in the body of the letter or in an attachment, depending on the settings in the personal account, it is a set of data with tab separators. The first line contains the names of the fields. If the field is not defined, two tabs follow in a row.

The register is sent even if there were no transactions in the past day. In this case, the body of the letter contains only the header line.

Description of registry fields

Example of registry

Registry Request

https://www.platron.ru/get_registry.php?pg_merchant_id=1234&pg_date=2016-11-15&pg_salt=f387f3h3&pg_sig=bfc5f9d2379d287052f56bd05c60296e

Request URL

https://www.platron.ru/get_registry.php

Request parameters

You cannot make another request until the first request has been processed. In this case, you will get an error.

Response parameters

If successful, the following response will be returned:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <operation>
        <type>pay</type>
        <payment_type>direct</payment_type>
        <pg_payment_id>28236796</pg_payment_id>
        <order_id>9789932</order_id>
        <description>hotel reservetion description</description>
        <merchant_id>82</merchant_id>
        <payment_system>GDSHOTELWITHRUSSIANSTANDARD</payment_system>
        <bill_amount>5138.0000</bill_amount>
        <amount>0.0000</amount>
        <currency>RUB</currency>
        <bill_cur_symbol>RUB</bill_cur_symbol>
        <op_date>15.11.2016</op_date>
        <op_time>10:26:45</op_time>
        <to_pay>0.0000</to_pay>
        <pg_commission>0.0000</pg_commission>
        <ps_commission>0.0000</ps_commission>
    </operation>
    <pg_salt>f387f3h3</pg_salt>
    <pg_sig>cac84530938b7e51b2d272e1d0212457</pg_sig>
</response>

In case of an error, the response will look like this:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>200</pg_error_code>
    <pg_description>Required parameter is missing</pg_description>
</response>

See the description of the fields of the file sent to email

Notifications

Checking the possibility of payment

Example of GET call of merchant by gate:

http://store.ru/check.php?pg_salt=8765&pg_order_id=654&pg_payment_id=765432&pg_payment_system=WEBMONEYR&pg_amount=100.00&pg_currency=RUB&pg_net_amount=95.00&pg_ps_amount=100.00&pg_ps_currency=RUB&pg_ps_full_amount=100.80&pg_sig=bfc5f9d237952f56bd05c602d287096e&uservar1=45363456

Example of xml call (POST with XML in pg_xml parameter) of merchant store:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>8765</pg_salt>
    <pg_order_id>654</pg_order_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_payment_system>WEBMONEYR</pg_payment_system>
    <pg_amount>100.00</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_ps_currency>RUB</pg_ps_currency>
    <pg_ps_amount>100.00</pg_ps_amount>
    <pg_ps_full_amount>100.00</pg_ps_full_amount>
    <uservar1>45363456</uservar1>
    <pg_sig>bfc5f9d237952f56bd05c602d287096e</pg_sig>
</request>

Before accepting money from a customer on an invoice, the payment gate can call merchant's Check URL script using the Request Method.

If merchant selected an encoding other than utf-8 when initializing the payment, the request will be made in the encoding set by merchant. The gate transmits information about the order number and properties and waits for a response within 30 seconds. The absence of a response within the specified time is perceived as a temporary refusal of payment, in which case the Check URL call can be repeated later if it is initiated again by the payment system.

The Check URL script is called only if this option is supported by the payment system through which the payment is made. If the Check URL is not specified or is defined as empty at the time of payment initialization, and is set to empty in the merchant settings, then the step of checking the possibility of making a payment is skipped and it is considered that the merchant agrees to accept the payment.

Request parameters

Response parameters (merchant)

Examples of responses

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>654j8rlvbyuj</pg_salt>
    <pg_status>ok</pg_status>
    <pg_timeout>300</pg_timeout>
    <pg_sig>6e952f52d23770986bd05c6fc5f902db</pg_sig>
</response>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>654j8rlvbyuj</pg_salt>
    <pg_status>rejected</pg_status>
    <pg_description>The payment deadline for the order has expired</pg_description>
    <pg_sig>d2377096e952f5286bd05c602dbfc5f9</pg_sig>
</response>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>654j8rlvbyuj</pg_salt>
    <pg_status>error</pg_status>
    <pg_error_code>1000</pg_error_code>
    <pg_error_description>database connection failed</pg_error_description>
    <pg_sig>8a417096e952f5286bd05c602dbfc562</pg_sig>
</response>

If the store confirms that the order is ready and the amount is correct, it should respond in XML with the ok status.

The rejected status is perceived as a final refusal, in which case the pg_description parameter is displayed to the user as the reason for the refusal ( if this option is supported by the payment system), and the invoice is canceled. Merchant should be prepared for the fact that even after the rejected response, nevertheless, the Check URL can be called again (for example, if Platron did not wait for merchant's response).

The error status is perceived as a temporary failure on the store's side. The invoice remains active, and a request for the possibility of making a payment can be made again if it is re-initiated by the user. If the merchant's server is unavailable at the time of calling the Check URL or if a response is received that cannot be interpreted, the payment will also be temporarily canceled.

Payment result

Example of a GET call to merchant by a gate, when paying via a regular payment system:

http://store.ru/result.php?pg_salt=0bd68e&pg_order_id=654&pg_payment_id=765432&pg_amount=100.0000&pg_currency=RUB&pg_net_amount=100.00&pg_ps_amount=105.00&pg_ps_full_amount=105.00&pg_ps_currency=RUB&pg_payment_system=INPLATMTS&pg_result=1&pg_payment_date=2008-12-30+23:59:30&pg_can_reject=0&pg_user_phone=79818244116&pg_need_phone_notification=1&pg_user_contact_email=test@test.ru&pg_need_email_notification=1&uservar1=45363456&pg_sig=da61f9d237952f56bd05c602d28780b3

Example of an xml call (POST with XML in the pg_xml parameter) of a gate merchant, when paying via a regular payment system:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>0bd68e</pg_salt>
    <pg_order_id>654</pg_order_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_amount>100.0000</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_net_amount>100.00</pg_net_amount>
    <pg_ps_amount>105.00</pg_ps_amount>
    <pg_ps_full_amount>105.00</pg_ps_full_amount>
    <pg_ps_currency>RUB</pg_ps_currency>
    <pg_payment_system>INPLATMTS</pg_payment_system>
    <pg_result>1</pg_result>
    <pg_payment_date>2008-12-30 23:59:30</pg_payment_date>
    <pg_can_reject>0</pg_can_reject>
    <pg_user_phone>79818244116</pg_user_phone>
    <pg_need_phone_notification>1</pg_need_phone_notification>
    <pg_user_contact_email>test@test.ru</pg_user_contact_email>
    <pg_need_email_notification>1</pg_need_email_notification>
    <uservar1>45363456</uservar1>
    <pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig>
</request>

Example of a GET call to merchant by a gate, when paying by card payment system:

http://store.ru/result.php?pg_salt=0bd68e&pg_order_id=654&pg_payment_id=765432&pg_amount=100.0000&pg_currency=RUB&pg_net_amount=100.00&pg_ps_amount=105.00&pg_ps_full_amount=105.00&pg_ps_currency=RUB&pg_payment_system=RUSSIANSTANDARD&pg_result=1&pg_payment_date=2008-12-30+23:59:30&pg_can_reject=1&pg_card_brand=CA&pg_card_pan=527594******4984&pg_card_hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_captured=0&pg_user_phone=79818244116&pg_need_phone_notification=1&pg_user_contact_email=test@test.ru&pg_need_email_notification=1&uservar1=45363456&pg_sig=da61f9d237952f56bd05c602d28780b3

Example of an xml call (POST with XML in the pg_xml parameter) of a gate merchant, when paying by card payment system:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>0bd68e</pg_salt>
    <pg_order_id>654</pg_order_id>
    <pg_payment_id>765432</pg_payment_id>
    <pg_amount>100.0000</pg_amount>
    <pg_currency>RUB</pg_currency>
    <pg_net_amount>100.00</pg_net_amount>
    <pg_ps_amount>105.00</pg_ps_amount>
    <pg_ps_full_amount>105.00</pg_ps_full_amount>
    <pg_ps_currency>RUB</pg_ps_currency>
    <pg_payment_system>RUSSIANSTANDARD</pg_payment_system>
    <pg_result>1</pg_result>
    <pg_payment_date>2008-12-30 23:59:30</pg_payment_date>
    <pg_can_reject>1</pg_can_reject>
    <pg_card_brand>CA</pg_card_brand>
    <pg_card_pan>527594******4984</pg_card_pan>
    <pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash>
    <pg_auth_code>014318</pg_auth_code>
    <pg_captured>0</pg_captured>
    <pg_user_phone>79818244116</pg_user_phone>
    <pg_need_phone_notification>1</pg_need_phone_notification>
    <pg_user_contact_email>test@test.ru</pg_user_contact_email>
    <pg_need_email_notification>1</pg_need_email_notification>
    <uservar1>45363456</uservar1>
    <pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig>
</request>

If merchant accepts the payment, it should respond in XML with the ok status.:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>kdjdope983</pg_salt>
    <pg_status>ok</pg_status>
    <pg_description>The product has been transferred to the buyer</pg_description>
    <pg_sig>9bfc5f602d287096ed237952f56bd05c</pg_sig>
</response>

After receiving money from the client or if it is impossible to make a payment, Platron calls the merchant's Result URL and sends information about the payment result to it using the Request Method. If merchant selected an encoding other than utf-8 when initializing the payment, the request will be made in the encoding set by merchant. Upon receipt of this request, the store must perform the necessary actions to transfer products or services to the buyer, if the payment was successful. If pg_com_reject=1 and merchant cannot accept the payment (for example, the ticket reservation has expired), it must respond with the rejected status, and Platron will cancel the payment (according to INPLAT, there is no possibility of refusing the payment). In this case, the pg_description parameter from the merchant's response is shown to the user as the reason for the refusal.

If the merchant's server is unavailable at the time of calling the Result URL (no response for more than 30 seconds) or its response could not be interpreted, Platron will make repeated attempts to call it for 2 hours, even if the pg_lifetime of the invoice expires. If the first attempt to call the Result URL is unsuccessful, the payment is not cancelled, and if the payment system allows you to cancel the payment only immediately after the payment, then Platron accepts the payment from the payment system and in subsequent calls to the Result URL does not allow the merchant to cancel the payment. The merchant must be prepared for the Result URL to be called again for the same payment. The responses to the repeated calls must match the original response, even if the transaction lifetime (pg_lifetime) has expired.

Request parameters

Response parameters (merchant)

If the merchant refuses the payment and the pg_can_reject=1 parameter was passed in the request, the merchant must respond in the form XML with status rejected:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>kdjdope983</pg_salt>
    <pg_status>rejected</pg_status>
    <pg_description>Бронь истекла</pg_description>
    <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>
</response>

The rejected status can be returned by the merchant only if the incoming request from the gate specified the parameter pg_can_reject=1, otherwise, regardless of the store's response, the payment will be considered completed. If the merchant refused the payment (responded with rejected), the buyer is redirected to the Failure URL, otherwise - to the Success URL.

Clearing result

Example of a GET call to merchant by a gate:

http://store.ru/onCapture.php?pg_salt=gw41b38vc&pg_order_id=2614&pg_payment_id=825941&pg_sig=afaef9d237932f57bd05c602d287df34&uservar1=45363456

Example of xml call (POST with XML in pg_xml parameter) of the gate merchant:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <pg_salt>gw41b38vc</pg_salt>
    <pg_order_id>2614</pg_order_id>
    <pg_payment_id>825941</pg_payment_id>
    <uservar1>45363456</uservar1>
    <pg_sig>afaef9d237932f57bd05c602d287df34</pg_sig>
</request>

If merchant is configured to conduct transactions on bank cards in two stages - authorization and clearing - Platron notifies merchant about the execution of clearing immediately after sending the corresponding command to the bank.

Clearing is usually performed at the initiative of merchant, when merchant Platron a clearing command (see the Clearing section), however, if the store has not given this command within the period specified in merchant settings (no more than 5 days) after authorization, Platron independently sends a clearing command to the bank.

To notify merchant about clearing, Platron calls merchant's Capture URL script using the Request Method. Platron transmits information about the order number and waits for a response within 30 seconds. If the merchant's server is unavailable at the time of calling the Capture URL (no response for more than 30 seconds) or its response could not be interpreted, Platron will make repeated attempts to call it within 2 hours.

Request parameters

Response parameters (merchant)

Example of merchant response:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_salt>eyhfh42za22h</pg_salt>
    <pg_status>ok</pg_status>
    <pg_sig>ea362f52d23770986bd05c6fc5f9427d</pg_sig>
</response>

Payment refund

In case of a full or partial refund of the payment on the Platron or payment system side, the payment gate calls the Refund URL store script using the Request Method method. The request will be made in the encoding set by the merchant when initializing the payment, by default utf-8. The gate transmits information about the order number and properties and waits for a response within 30 seconds. If the merchant's server is unavailable at the time of calling the Refund URL (no response for more than 30 seconds) or its response could not be interpreted, Platron will make repeated attempts to call it within 2 hours.

Request parameters

Response parameters (merchant)

Return of the buyer to the merchant's website

Example of a GET or AUTOGET transition if successful:

https://store.ru/success.php?pg_salt=54c6a8786f19e&pg_order_id=654&pg_payment_id=765432&uservar1=45363456&pg_card_brand=CA&pg_card_pan=527594******4984&pg_card_hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_auth_code=014318&pg_sig=20bcedd8320ac8868b97706abedec0b4

After completing the payment in the online payment system, the buyer is redirected to the merchant's Success URL page or Failure URL, depending on the result of the payment. Redirection occurs using the Success URL Method or Failure URL Method specified when initiating the payment.

In case of payment via an offline payment system, the buyer is not returned to the merchant's website.

Request parameters

If the Success URL or Failure URL already contains parameters in the query string, then the additional parameters pg_order_id, pg_payment_id and the merchant's custom variables are appended to the end of the query string. The merchant must ensure that the names of the additional parameters do not match the names of the existing parameters.

It is important to clearly understand the difference between Result URL and Success URL. Result URL is called directly from Platron server, while Success URL is called by user's browser when user is redirected back to the merchant's website.

It is incorrect to use the Success URL as the only way to know about the payment completion, because the user may, for various reasons (for example, a connection interruption), not reach the Success URL after payment. The most reliable way to know about the payment completion is to implement a Result URL, which is obliged to call again within 2 hours after payment, if the first attempt failed for any reason.

Testing

All new merchants are initially in test mode. After testing is completed and sent by the merchant to Platron signed the Act of connection, it can be downloaded from the link https://www.platron.ru/admin/documents.php, the Platron administration switches the store to working mode.

To debug the integration with Platron in test mode, you need to select pg_payment_system=TEST or pg_payment_system=TESTCARD, in this case a fictitious test PS will be used, conducting settlements in a fictitious currency "testiks", and real funds will not be transferred. In test mode, you can use only test payment systems, and in working mode, on the contrary, payment by test payment systems is impossible. To test the integration of the TESTCARD payment system, you must use the currency — RUB.

After the merchant switches to the working mode, you can create individual transactions in test mode by passing the pg_testing_mode parameter in requests for creating a payment, repeating a recurring payment, and getting a list of payment systems. The pg_testing_mode=1 value enables test mode for one specific transaction. If the merchant itself is in test mode, the value of the passed pg_testing_mode flag does not matter. Enabling and disabling test mode in the merchant settings is carried out only by the Platron administration.

When filling in the payment details, you can specify the following special phone numbers:

• 79009999999 — for automatic successful payment
• 79008888888 — for automatic unsuccessful payment

If you specify any other phone number, then after the transaction is created, no automatic actions will occur with it. In order to test the further progress of the transaction, you need to go to the administrative panel on the transaction page and manage its actions using the test buttons.

To emulate the user's transition to the 3DS passage page when using the TESTCARD payment system, you need to ask your manager to enable client authorization via 3DS.

The test payment system allows testing of clearing, PCI DSS, long record and recurring payments.

When paying through a test card payment system, you must enter the card number. You can use a real card (no write-off occurs), select a card number (according to the luna rule), or use test cards. Test cards are not validated by the fraud monitoring module. List of test cards:

• 5285 0000 0000 0005 valid until 01/2025
• 4276 0000 0000 0009 valid until 01/2025
• 5241 0000 0000 0016 valid until 01/2025
• 5326 0000 0000 0006 valid until 01/2025
• 4257 0000 0000 0002 valid until 01/2025

Anti-fraud

A task. Integrate into the Platron system only for anti-fraud solutions.

Solution. Integration is performed in a standard way. To transfer card details, the merchant must have a PCI DSS certificate. Additional documentation on integration with the presence of PCI DSS can be requested from the manager.

1. To create a transaction, you must use the payment initialization method — Host-to-host
2. When creating a transaction, the payment system must be specified ANTIFRAUD (pg_payment_system=ANTIFRAUD).
3. In response (see Payment result or Payment status) an additional parameter will be given fraud_filter_action

Possible response options:

Required parameters, in addition to the parameters from the Payment Initialization section, necessary for the correct operation of the anti-fraud:

For e-travel segment stores, the following data can be transmitted in additional fields:

Marketplace

The Marketplace implies the payment of funds to the accounts of legal entities. The initiation of the payment of funds to a legal entity occurs according to the scheme described in the section Request for moneyback.

To make payments in favor of a legal entity, the BANKTRANSFER_WALLET_ONE_LEGAL payment system is used.

In case of moneyback via the BANKTRANSFER_WALLET_ONE_LEGAL payment system, the pg_description parameter is added to the payment order as a payment description. The maximum number of characters is 90.

Funds are credited to the account for payments according to the standard Payment Initialization protocol.

Handbooks

Payment systems

Working payment systems

Test payment systems

Bank cards

Test payment systems

Additional PS parameters

Currencies

Currently, all currencies that have an official exchange rate of the Central Bank of the Russian Federation are supported.

Payment statuses

Each payment transaction can be in one of the following states:

Error codes

*To analyze the reasons for the signature error that occurred, you can use the "Request signature check" page in your Personal Account.

Reasons for refusal

Moneybacksystems and parameters

BANKTRANSFER_WALLET_ONE_LEGAL

First, all recipients must be registered in the system through the manager.

TEST

Moneyback statuses