Platron API. Technical description. version 3.5

Transcription

1 Platron API Technical description version 3.5

2 2

3 Contents Contents... 3 Version History... 5 The Goal of the Service Payment Scenario General Principles of Interaction Between Merchant and Platron Methods of Direct Interaction Between Merchant and Platron Methods of Interaction Between Platron and Merchant through Customer s Browser Merchant Settings Payment Initialization Description Can be 0 or 1. Value 1 turns testing mode on for a single transaction when merchant is already in live mode. See details in section test Entry Point for Payment Initialization via User s Browser Entry Point for Direct Transfer of Information from the Merchant to Platron Checking the Possibility to Proceed with Payment Payment Result Buyer s Return to the Merchant s Site Notification about Refund of Payment Notification about Capture for Credit Card Transactions Testing Recurrent payments Initialize the recurrent Profile Description Auxiliary Requests Receiving the List of Payment Systems and Prices Querying Payment Status Capture Request for Credit Card Transactions Payment Revocation (full or partial) Creation of Demand for Refund Bill Cancelation before Payment Payout without a Prior Payment Querying of Status of Payout without Prior Payment Cancel Payout without a Prior Payment List of Payment Statuses List of Payment Systems and Groups Technical details List of Additional Parameters of Payment Systems List of Currencies List of Error Codes List of Reasons for Payment Failure Typical Integration Scenarios Donations Simplest Merchant Usual Merchant Special Merchant Payment Registry Format

4 4

5 Version History version date author A.Churyumov A.Churyumov A.Churyumov A.Churyumov A.Churyumov A.Redozubov A.Redozubov A.Redozubov A.Churyumov A.Churyumov S.Predein object of changes documentation Initial revision 5 changes documentation Added the following information into the list of payment systems: support for checking for possibility of payment, support for payment revocation, the place of PS commission documentation Clarified Platron s behavior when calling Check URL Result URL documentation documentation Added references to lists of payment systems and currencies. Clarified Platron s handling of temporary failures of Check URL. Clarified the procedure of customer redirect after payment was rejected by merchant. Clarified Platron s handling of order lifetime. Added information about PS ability to track order lifetime. Added note about method of return URL in the current version. Corrected example of signature calculation. In payment system list response, PS name moved from attributes to tags and the list is sorted by PS name. Added the list of member payment systems in the response to payment system list request Added paying wait time in answer on check documentation Deleted comment about not full protocol realization in Platron in request methods in Failure URL and Success URL documentation Removed the notes about non-complete signature implementation. Corrected the order of fields in the signature example. Added the comment about pg_redirect_url_type= need data. Added the note about check and result fields charset. documentation Clarifications about Platron s behavior for pg_redirect_url_type= need data. Changed reply format for check URL invocation: added rejected status, renamed pg_error_description to pg_description, changed the reaction for error status. Changed Check URL invocation format: removed pg_net_amount

6 A.Churyumov A.Churyumov A.Churyumov A.Redozubov I.Bakulin A.Tolmachev I.Bakulin I.Bakulin A.Tolmachev A.Tolmachev I.Bakulin I.Bakulin A.Tolmachev A.Churyumov A.Tolmachev A.Tolmachev A.Tolmachev documentation Refined the requirements for amounts format, refined payment system list. documentation documentation Removed notes about missing. Changed version number. Added Refund URL. Cleared descriptions of requests and responses (pg_salt and pg_sig). Corrected name of Beeline payment system. Added daily sends of payment registries. Corrected the name of Credit Cards payment system. Added TRANSCRED, COMEPAY, and WEBMONEYRBANK payment systems. If Platron is unable to identify the merchant, and therefore does not know his secret_key and cannot sign the response message, it returns error 101. Added information about partial refunds. If some data is required to pay using chosen payment system, this data is passed in gate s reply. Added field pg_payment_scenario in PS list. documentation Added the list of error codes. Added new mandatory field pg_user_ip. Added API call for bill cancelation. Added restriction for the value of pg_lifetime parameter. documentation Updated list of payment systems and details about bill cancellation by different PSs. Added info about pg_description field max length. Changed Result URL invocation format: added pg_user_phone. Added restriction for the minimum value of pg_lifetime parameter. Added merchant setting site_url. Added pg_accepted_payment_systems field. 6

7 I.Bakulin A.Churyumov A.Churyumov D.Karmichkin D.Karmichkin A.Churyumov D.Karmichkin D.Karmichkin D.Karmichkin D.Karmichkin D.Karmichkin D.Karmichkin A.Lashnev A.Churyumov D.Karmichkin documentation documentation documentation documentation documentation Added ability to refund partial amounts. Added link to signature debugging page. Added refund details to refund notification. Added more payment systems. Added API call in order to create demands for refunds when payment system cannot refund online. Added testing payment system TESTCARD that emulates credit card payments. Added pg_user_contact_ field in payment initialization request. Added postponed payment. Added ability to set language of payment pages. Types of operations added to the registry. Added payment systems. Added testing mode Added pg_card_brand in Result URL call. Registry format extended by adding fields that better describe the bill. Added two-phase (auth/capture) credit card processing for TRANSCRED, RUSSIANSTANDARD, MASTERBANKCARD. Added long record capability for TRANSCRED, MASTERBANKCARD. See additional long record documentation. Added ability to take overpayment. Added recommendations on using Result URL and Success URL. Now sending failure reason with information about unsuccessful payment. Added per-transaction setting of Site URL. Added pg_auth_code parameter for bank card payments. Added ability to query payment status by pg_order_id. Reordered payment system list. Added pg_card_pan parameter for bank card payments. Added ability to create payouts without a previous payment. Added ability to query status of payout without a previous payment. Added ability to process recurrent payment. Expanded when working GDS Amadeus. Expanded the list of payment systems. Added a request to cancel payout without a previous payment. 7

8 D.Karmichkin A. Lashnev A. Lashnev A. Lashnev T. Muradyan T. Muradyan, new payment systems, new payment systems Expanded catalog of reasons for refusal. Qiwi on protocol QIWIREST Protocol TINKOFFBACKCARD Long recording on RUSSIANSTANDARD Display the long record transaction in the administrative panel Platrona Internal optimization for working with bens Opportunity to cancel the transaction from the administrative panel Platrona Added new tags in ps_list.php script response, pg_require and pg_additional. Added new parameters, pg_state_url and pg_state_url_method. Added ability to hold client on merchant side, while the payment status is pending. Parameters are editable in merchant settings and also can be in transaction creation request. Added new scheme of work with GDS and Sabre. Modified scheme of work with Galileo. Added ability to write off penalty from client during working with GDS (recurring payments) and limit the type of accepted cards. Added buttons send refund/reverse result to merchant in admin. Maestro validation cards with 19 number cards. New payment system QBANK You can use TESTCARD payment system to test inserting card pan, send long record, capture and make recurring transactions. Also you can send long record when transaction start. Added get bin info service (see addition documentation). New payment systems: MOBICOMMTS, MOBICOMMEGAFON, MOBICOMTELE2, PAYLATE Mobile operator determine threw state registry and include users, who changed operator. Opportunity to use test payment system as real bank payment system. Opportunity to send the long record not only on capture. Opportunity to customize admin panel and wizard pages for payment gates. The mobile operator is now determined on the basis of data Rossvaz registry and counts users, who changed operator. New PS MOBICOMMTS, MOBICOMMEGAFON, MOBICOMTELE2, PAYLATE. New PS UNISTREAM, SBRF The ability to customize each store and Gate own sms and templates 2. Hashing card number now given to store the query result The ability to create fraud filters by customer data 2. The ability to pay by JSB card 8

9 Payment systems Payment systems Payment systems 3. The ability don t create sms and notification to customer (pg_need_phone_notification and pg_need_ _notification) 4. Add parameters pg_user_contact_ , pg_need_phone_notification and pg_need_ _notification in result request 5. Accelerate searching transaction 6. Deleted pg_description in result request 1.Renamed PS SBRF as SBRFOFFLINE 2.Added new PS SBRF Added new PS 1. MININTERNETBANK 2. OCEANINTERNETBANK Added new PS QIWIACTIVATION 9

10 The Goal of the Service Service is designed to allow sellers to accept electronic payments on their sites. The service includes the possibility of receiving payments, using several payment methods (credit cards, webmoney, Yandex.Money, payment terminals, etc.) on the choice of the buyer. Merchant frees itself from the need to integrate with each payment system (PS) separately, it is necessary to integrate only with platron.ru. Payment Scenario 1. Buyer places an order on the merchant s site 2. Buyer chooses payment method 3. The payment is processed by the selected payment system 4. platron.ru informs merchant of the result of the payment by calling a predetermined URL on the seller s site 5. If the payment was successful the buyer receives the ordered product / service General Principles of Interaction Between Merchant and Platron Exchange of information between merchant and Platron can occur in two ways: 1. Directly, by calling certain URL 2. Through user s browser These two ways are described in more detail in subsections below. There is a naming convention for all data interchange between Platron and merchant: names of all parameters that concern interaction between Platron and merchant are prefixed with pg _, all other parameters don t have this prefix. In all monetary values, decimal point is used in order to separate integer and fractional parts. If the value is integer, it is not necessary to explicitly specify the fractional part. No more than two decimal places after decimal point are allowed. Thousands are not separated with either commas nor any other means. All messages (requests and replies) between Platron and merchant are signed. The source string for the signature is obtained by concatenating the following fields delimited by '; ': 1. name of the script being called (from the last ' / ' up to the end or '? ') 2. all fields of the message in alphabetical order, including random string pg_salt, consisting of any number of digits and Latin letters; notes: a. this rule is applied recursively to enclosed tags (only XML) b. fields with identical names are taken in the order they appear in the message 3. payment password secret_key which is set in merchant options and is known only to merchant and Platron. To receive the signature one should apply md5 hash to the string calculated by concatenation of the above fields. The signature is added to the request or the answer as additional parameter pg_sig. MD5 hash is represented as a lower case hexadecimal line (32 symbols). For example: Calling <request> <pg_salt>9imm909th820jwk387</pg_salt> <pg_t_param>value3</pg_t_param> <pg_a_param>value1</pg_a_param> <pg_z_param> 10

11 <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 by the formula: that is pg_sig = md5( script.php + ; + pg_a_param + ; + pg_b_param + ; + pg_salt + ; + pg_t_param + ; + pg_m_subparam + ; + pg_q_subparam + ; + secret_key); pg_sig = md5( 'script.php;value1;value2;9imm909th820jwk387;value3;subvalue1;subvalue2;my passkey'); if secret_key is set to mypasskey in merchant options. Any side can add additional parameters not described in this API to any request or response. These parameters also participate in signature calculation. The message is not signed, and accordingly the fields pg_salt and pg_sig are absent only in one case when Platron could not identify merchant and consequently does not know its secret_key. In this case, the field pg_error_code (numeric error code) is set to 101. See the list of common error codes in List of Error Codes chapter. In order to debug signature calculation it is recommended to use the page in merchant control panel. Methods of Direct Interaction Between Merchant and Platron Three methods of a direct information transfer between merchant and Platron are used: 1. GET method the data are transferred in HTTP GET parameters. When necessary to send structured data with GET method, arrays are used as in this example: param_2[subparam_2]=val3&param_3=val4 2. POST method the data are transferred in HTTP POST parameters. Structured data sent in the same manner as with GET method. 3. Through XML requests are transferred in a single HTTP POST parameter pg_xml which is a XML string like this: <request> <pg_param1>value1</pg_param1> <pg_param2>value2</pg_param2> <pg_param3>value3</pg_param3> </request> 11

12 Irrespective of request method (GET, POST or XML) the response is always in XML format: <response> <pg_status>ok</pg_status> <pg_param1>value1</pg_param1> <pg_param2>value2</pg_param2> <pg_param3>value3</pg_param3> </response> Only utf-8 encoding is supported in XML requests and responses. The response should always contain pg_status field that shows result of the operation. pg_status may be equal to ok if the request was processed successfully or error if there was an error. In the latter case the following fields might also be included: pg_error_code numeric code of the error (required field; see the list of common error codes in List of Error Codes chapter) pg_error_description description of the error (optional field). Example: <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> Apart from ok and error, other values of pg_status can also be used in responses to some requests as indicated below in this document. Methods of Interaction Between Platron and Merchant through Customer s Browser Platron and merchant can pass information to each other at the same time that customer is handed over from one party to the other. This event can be triggered by the customer or happen automatically. Interaction Triggered by Customer Transfer of control over the customer and simultaneous transfer of information between Platron and merchant can be accomplished by the following ways: 1. A link leading to another party s site 2. A form with action that leads to another party s site. The user presses the button manually. Automatic Transfer of Information Automatic passing of customer and information between Platron and merchant is possible by the following means: redirect (HTTP header Location). Only GET method. 2. Auto-submit form. GET and POST methods. Site sends to the customer a page that consists only of a form with action that leads to another party s site. The form consists only of hidden fields. The form automatically submits upon onload event. Thus, the user does not even see this page. Example: 12

13 <html> <body onload= document.forms[0].submit() > <form method= POST action= > <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> Merchant Settings In order to start accepting payments it is necessary to edit the following settings of the merchant account at platron.ru: Name of the merchant Logo of the merchant Data transfer method between merchant and Platron (Request method) Check URL Result URL Refund URL Capture URL Success URL Success URL Method Name of the merchant, will be displayed at platron.ru pages while guiding the customer through the payment process Logo of the merchant, will be displayed at platron.ru pages while guiding the customer through the payment process This parameter sets the data transfer method only for direct requests of Platron to the merchant used to execute the operations: Checking the possibility of accepting the payment (Check URL request) Informing the merchant of the payment result (Result URL request) Possible values: GET, POST, XML. See chapter Methods of direct interaction between merchant and Platron URL of script on the merchant site that is requested to check the possibility of initializing the payment. Used to prohibit the possibility to receive the payment upon the past-time order (for example, when reservation of a ticket has expired). If the Check URL is not defined, the check is not done. URL of script on the merchant site where result of payment is directed. If Result URL is not defined, it is not requested. URL of script on the merchant site for sending notifications about refunds. If Refund URL is not defined, it is not requested. URL of script on the merchant site for sending notifications about capture (clearing) performed on credit card transactions. If Capture URL is not defined, it is not requested. URL of script on the merchant site, where buyer is directed in case of successful payment. GET button, submitted with GET method. POST button, submitted with POST method. AUTOGET 302 redirect. See Automatic transfer of information, Chapter1. AUTOPOST a form that is submitted automatically. See Automatic transfer of information, Chapter 2. If either GET or POST method is chosen, the payment confirmation page is displayed to the user at platron.ru and suggests pressing a button in order to return to the merchant site. If either AUTOGET or AUTOPOST method is chosen, the payment confirmation page is not shown to the user, and user is automatically redirected to the merchant. 13

14 Failure URL Failure URL Method State URL State URL Method Site URL Take overpayment Send sms to customer Send to customer Payment password (secret_key) URL of script on the merchant site, where buyer is directed in case of unsuccessful payment. May be equal to Success URL. GET button, submitted by GET method. POST button, submitted by POST method. AUTOGET 302 redirect. See Automatic transfer of information, Chapter1. AUTOPOST form that is submitted automatically. See Automatic transfer of information, Chapter 2. If either GET or POST method is chosen, the page informing of unsuccessful payment is shown to the user at platron.ru site and suggests pressing a button in order to return to the merchant site. If either AUTOGET or AUTOPOST method is chosen, no page informing about unsuccessful payment is shown to the user, and the user is immediately redirected to the merchant. URL of script on the merchant site, where buyer is directed to wait for a response from the payment system. GET button, submitted by GET method. POST button, submitted by POST method. AUTOGET 302 redirect. See Automatic transfer of information, Chapter1. AUTOPOST form that is submitted automatically. See Automatic transfer of information, Chapter 2. If either GET or POST method is chosen, the page informing of unsuccessful payment is shown to the user at platron.ru site and suggests pressing a button in order to return to the merchant site. If either AUTOGET or AUTOPOST method is chosen, no page informing about unsuccessful payment is shown to the user, and the user is immediately redirected to the merchant. URL of the merchant s site. Used to create a link for the buyer to return to the merchant s site after payment initialization. It is used for offline PS (cash). Always when possible Platron tries to receive from customer only exactly the amount that is expected from customer. However, some payment systems, e.g. bank transfer, don t allow preventing overpayment. This setting says whether the merchant is willing and prepared to take overpayment and deal with it. This parameter shows if don t need to send sms to customer about transaction process (if service is allowed). Default send. This parameter shows if don t need to send to customer about transaction process. Default send. Used to protect the data given by Platron to the merchant and by the merchant to Platron. All the above parameters (except payment password) can be redefined for each particular payment at the moment of payment initialization. Payment Initialization In order to create a payment transaction (initiate the payment) the merchant is to do two things: 1. transfer the data about payment to Platron 2. hand over the buyer to Patron This may be done in two ways: 1. transfer the information about payment via user s browser, then the user simultaneously goes to Platron site. 14

15 2. transfer all payment details directly to Platron, get back the response payment transaction identificator and URL for further redirection of the user and then redirect the user to this URL. In both cases the contents of the transferred data are absolutely identical; the only things that differ are interaction method and the format of response. Field (required fields are marked bold) pg_merchant_id pg_order_id Default value Description Merchant identificator in Platron. Given at signup. Payment identificator in the merchant s internal system. It is recommended to keep this field unique. pg_amount Payment amount, in pg_currency pg_currency RUR Currency in which the amount is specified. RUR, USD, EUR. In case the selected payment system s base currency is different, the amount is converted into payment currency according Central Bank of Russia exchange rate on the day of payment. See the full list of supported currencies in List of Currencies chapter. pg_check_url pg_result_url pg_refund_url pg_capture_url pg_request_method pg_success_url From the merchant settings Check URL From the merchant settings Result URL From the merchant settings Refund URL From the merchant settings Capture URL From the merchant settings Request Method From the merchant (string[256]) URL for checking if payment is required. The check is performed just before accepting the payment if the payment system offers such possibility. If the parameter is not specified, then it is taken from global merchant settings. If the parameter is specified as a blank string, then the check is not done and the payment system is allowed to proceed to payment. (string[256]) URL for notifying the merchant about payment result. The URL is called just after the payment completes with success or failure. If the parameter is not specified, then it is taken from global merchant settings. If the parameter is set to a blank string, then Platron does not notify the merchant about payment result. (string[256]) URL for notifying the merchant about refunds initiated on Platron or PS side. The URL is called just after the payment is revoked. If the parameter is not specified, then it is taken from global merchant settings. If the parameter is set to a blank string, then Platron does not notify the merchant about refunds. (string[256]) URL for notifying the merchant about captures performed on previously authorized transactions. The URL is called just after capture command is sent to the acquiring bank. If the parameter is not specified, then it is taken from global merchant settings. If the parameter is set to a blank string, then Platron does not notify the merchant about captures. (string[4]) GET, POST or XML method of calling Check URL, Result URL, Refund URL, and Capture URL scripts. (string[256]) URL to direct user to in case of successful payment (only for online systems) 15

16 pg_failure_url pg_success_url_method settings Success URL From the merchant settings Failure URL From the merchant settings Success URL Method (string[256]) URL to direct user to in case of unsuccessful payment (only for online systems) Method of redirecting user to Success URL. GET a button that is submitted with GET method. POST a button that is submitted with POST method. AUTOGET 302 redirect. See Automatic transfer of information, Chapter1. AUTOPOST form that is submitted automatically. See Automatic transfer of information, Chapter 2. If either GET or POST method is chosen, the payment confirmation page is displayed to the user at platron.ru and suggests pressing a button in order to return to the merchant site. If either AUTOGET or AUTOPOST method is chosen, the payment confirmation page is not shown to the user, and user is automatically redirected to the merchant. pg_failure_url_method Method GET button, submitted by GET method. POST button, submitted by POST method. AUTOGET 302 redirect. See Automatic transfer of information, Chapter1. AUTOPOST form that is submitted automatically. See Automatic transfer of information, Chapter 2. If either GET or POST method is chosen, the page informing of unsuccessful payment is shown to the user at platron.ru site and suggests pressing a button in order to return to the merchant site. If either AUTOGET or AUTOPOST method is chosen, no page informing about unsuccessful payment is shown to the user, and the user is immediately redirected to the merchant. pg_state_url From the URL of script on the merchant site, where buyer is merchant directed to wait for a response from the payment system. settings State URL Method pg_state_url_method Method GET button, submitted by GET method. POST button, submitted by POST method. AUTOGET 302 redirect. See Automatic transfer of information, Chapter1. AUTOPOST form that is submitted automatically. See Automatic transfer of information, Chapter 2. If either GET or POST method is chosen, the page informing of unsuccessful payment is shown to the user at platron.ru site and suggests pressing a button in order to return to the merchant site. If either AUTOGET or AUTOPOST method is chosen, 16

17 pg_site_url pg_payment_system From the merchant settings Site URL no page informing about unsuccessful payment is shown to the user, and the user is immediately redirected to the merchant. URL of the merchant s site. Used to create a link for the buyer to return to the merchant s site after payment initialization. It is used for offline PS (cash). The selected payment system or payment system group identifier. Examples: WEBMONEY, YANDEXMONEY, EUROSET, CYBERPLATCASH, CASH. See the full list of payment systems and groups in List of Payment Systems and Groups chapter below. This parameter is specified only if the choice of payment system is offered at the merchant site. If the parameter is not specified, the choice of payment system is offered at platron.ru site 1. pg_lifetime 1 day Time (in seconds), that the payment is valid and is to be completed. When this term is expired, the order will be canceled. This parameter is controlled by Platron and, if payment system supports that, by the payment system. See List of Payment Systems and Groups. Minimum allowed value: 300 seconds (5 minutes). Maximum allowed value: seconds (7 days). In the event of non-acceptable boundary values will be set to the minimum or maximum value, respectively. pg_encoding UTF-8 Encoding of other fields of the request (only when GET or POST method is used). pg_description (string[1024]) Product or service description. Displayed to the user in the process of payment. Encoded in pg_encoding. pg_user_phone 2 (int[14]) user s phone number (starting from 79 in Russia), necessary to identify the user. If it is not specified, the choice will be offered to user on platron.ru site. pg_need_phone_notification 1 Parameter shows if don t need send notification to customer by sms. 0 not send. pg_user_contact_ 2 (string[100]) User s contact . If passed, Platron will send transaction status updates to this . pg_need_phone_notification 1 Parameter shows if don t need send notification to pg_user_ip 2 pg_postpone_payment customer by . 0 not send. Client s IP address. It is necessary if payment is suspected to be fraudulent, to help investigating the details. If payment is initialized via User s Browser, pg_user_ip may not be passed in this case the IP address of the user that has made request to Platron would be recorded. Setting this parameter to 1 instructs Platron to create 1 The customer can insert credit card information on merchants side when merchant have PSI DSS and manager approve. 2 This parameter use in Fraud Monitoring. You must to send real user parameters to write fraud monitoring working. 17

18 postponed payment (instead of ordinary payment that is to be paid immediately). Information about postponed payment is available at If postponed payment is activated, the customer will be redirected to a page informing him that we sent him an containing a link to be clicked in order to continue with the payment. If pg_postpone_payment=1 then pg_user_contact_ should be also passed, otherwise Platron will ask the customer to provide his address in order to postpone this payment. pg_language ru Language of payment pages at and (if possible) sites of payment systems. The value ru sets Russian language, en sets English. pg_testing_mode From merchant s settings Can be 0 or 1. Value 1 turns testing mode on for a single transaction when merchant is already in live mode. See details in section test. pg_recurring_start 0 The flag takes a value of 0 or 1. Detailed description see in recurrent payments. pg_recurring_lifetime Time on the continuation of which the seller intends to use the profile of recurrent payments. The allowed minimum value: 1 (one month). The allowed maximum value: 156 (13 years old). In case of boundary values for non-acceptance is given minimum or maximum value. For detailed description read recurrent payments. Merchant s additional parameters Merchant can pass any additional parameters, provided that their names do not start with pg_. All these parameters will be passed back to pg_check_url, pg_result_url, pg_success_url, pg_failure_url. Names of additional merchant s parameters must be unique. pg_salt Random string pg_sig Signature Entry Point for Payment Initialization via User s Browser In order to initialize payment and pass payment parameters via user s browser merchant should direct the user to or URL with POST or GET method. Example of a GET request: er_id=123&pg_check_url= :// ou.php&pg_failure_url= ket+su1234+moscow- Berlin+1+Jun+2008&custom_param1=gagaga&custom_param2=gugugu&pg_sig=af8e41a 4f425d124a23c3a53a3140bdc17ea0 If an error occurs, it is displayed to the user. 18

19 If the set of parameters passed by the merchant is not complete in order to create payment transaction (e.g. payment system, user s phone or parameters needed for the selected payment system are missing), the missing parameters are requested from the user at platron.ru. Entry Point for Direct Transfer of Information from the Merchant to Platron In order to initialize payment transaction via direct transfer of data to Platron the merchant should send data to the URL Platron responds with XML like: <response> <pg_salt>ijoi894j4ik39lo9</pg_salt> <pg_status>ok</pg_status> <pg_payment_id>15826</pg_payment_id> <pg_redirect_url> 41a4f425d124a23c3a53a3140bdc15826</pg_redirect_url> <pg_redirect_url_type>need data</pg_redirect_url_type> <pg_sig>af8e41a4f425d124a23c3a53a3140bdc17ea0</pg_sig> </response> Here: pg_payment_id pg_redirect_url pg_redirect_url_type Unique identificator of the payment transaction within Platron. Used as a key for all subsequent work with the transaction. URL for redirecting the user. May direct either to platron.ru or the payment system site. Type of the page, where redirection is made. Possible values: need data dialogue with the buyer in order to get all necessary parameters: payment system, phone number, required parameters for the payment system; payment system a page of the payment system or a page with instructions for payment via this specific payment system. Instructions page may be either at platron.ru or at the merchant s site. pg_accepted_payment_systems If pg_redirect_url_type = payment_system, contains a list of payment systems that in fact may be used to pay newly created bill. The contents of this field should be taken into account when displaying the list of payment systems to the customer. pg_salt Random string pg_sig Signature If merchant gets response with pg_redirect_url_type= need data, he may not redirect the customer to this URL, but ask the necessary data from customer himself. In this case, after merchant submits repeated payment request, a new payment transaction will be created. If some data is required to pay using chosen payment system, the response contains this data in pg_ps_additional_data field, as shown in the example: <?xml version="1.0" encoding="utf-8"?> <response> <pg_salt>c1058bea</pg_salt> <pg_status>ok</pg_status> <pg_payment_id>17837</pg_payment_id> 19

20 <pg_redirect_url> 9f392abc4e847ca340b237c79cd8a817837</pg_redirect_url> <pg_redirect_url_type>payment system</pg_redirect_url_type> <pg_ps_additional_data> <pg_payment_system> <pg_name>rapida</pg_name> <pg_ps_data> <index>22</index> </pg_ps_data> </pg_payment_system> </pg_ps_additional_data> <pg_sig>13daa b5f9ae176e57cc1d70</pg_sig> </response> For description of all fields that are passed when paying through different payment systems see chapter List of additional parameters of payment systems. In case of an error: <response> <pg_status>error</pg_status> <pg_error_code>101</pg_error_code> <pg_error_description>empty merchant</pg_error_description> </response> Here: pg_error_code pg_error_description Error code Error description When the request is valid, but the merchant gives only some of the parameters necessary for payment initialization (payment system, user s phone number and parameters needed for the chosen payment system), pg_redirect_url is a page at platron.ru where the missing parameters are to be specified by the user. Checking the Possibility to Proceed with Payment Before taking the money from the user upon the bill, the payment gate may request the Check URL script of the merchant. The request will be sent in pg_encoding encoding specified with payment initialization (utf-8 by default). The gate sends the information about the ID and properties of the order and waits for the response for 30 seconds. If no response is received within this time, this means temporary refusal of the payment. In this case, Check URL can be called again if Platron is triggered by the payment system again. Check URL call happens only when this possibility is supported by the payment system that processes the payment. If Check URL is defined blank at the moment of payment initialization or it is not defined at this moment but it is set blank in the merchant settings, then no check of payment possibility is done and Platron thinks that the merchant agrees to accept the payment. Parameters of Check URL request: pg_order_id Payment identificator in the merchant system pg_payment_id Internal identificator of payment in Platron 20

21 pg_amount pg_currency pg_ps_amount pg_ps_full_amount pg_ps_currency pg_payment_system Merchant parameters pg_salt pg_sig Amount of the bill (in pg_currency currency), is equal to pg_amount at the moment of payment initialization Currency of the bill, is equal to pg_currency at the moment of payment initialization Amount of the bill (in pg_ps_currency) sent to the payment system Complete amount (in pg_ps_currency currency) that will be paid by the user, including all commissions Currency, in which the payment will be processed in the payment system Identificator of the payment system All of the fields earlier received from the merchant that do not have the pg_ prefix Random string Signature Example of the gate s GET request to the merchant: ayment_system=webmoneyr&pg_amount=100.00&pg_currency=rur&pg_net_amount=95.00&pg_ ps_amount=100.00&pg_ps_currency=rur&pg_ps_full_amount=100.80&pg_sig=bfc5f9d f56bd05c602d287096e&uservar1= Example of the xml (POST with XML in pg_xml parameter) request by the gate to the merchant: <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>rur</pg_currency> <pg_ps_currency>rur</pg_ps_currency> <pg_ps_amount>100.00</pg_ps_amount> <pg_ps_full_amount>100.00</pg_ps_full_amount> <uservar1> </uservar1> <pg_sig>bfc5f9d237952f56bd05c602d287096e</pg_sig> </request> If the merchant confirms the validity of the order and correctness of the amount, merchant is to respond by XML with OK status: <response> <pg_salt>654j8rlvbyuj</pg_salt> <pg_status>ok</pg_status> <pg_timeout>300</pg_timeout> <pg_sig>6e952f52d bd05c6fc5f902db</pg_sig> </response> 21

22 Rejected status is interpreted as final refusal to continue with the payment, in this case pg_description field can be displayed to the user as the reason of the refusal (if this possibility is supported by the payment system) and the bill is canceled. Merchant should be prepared that its Check URL will be called again even after rejected response (e.g. if Platron timeouts waiting for merchant s response). <response> <pg_salt>654j8rlvbyuj</pg_salt> <pg_status>rejected</pg_status> <pg_description>payment expired</pg_description> <pg_sig>d e952f5286bd05c602dbfc5f9</pg_sig> </response> Error status is interpreted as temporary failure on merchant s side. The payment transaction remains in pending state and Check URL request can be received again, if it is triggered by user again. <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> Description of the fields in the merchant s response to Check URL request: Parameter Description pg_status ok payment is allowed to continue rejected payment is rejected error error in interpreting request pg_description (string[1024]) If the payment is accepted this field is not required. If the payment is rejected, description of rejection reason for the buyer. If there is an error description of the error, can be the same as pg_error_description. pg_timeout (int[10]) time in seconds that merchant will wait for pay request on this transaction, default is 600 seconds pg_error_description Error description if pg_status=error pg_salt Random string pg_sig Signature In case the merchant s server is not available at the moment of Check URL request or if the response cannot be interpreted, the payment will be temporarily refused. Payment Result After the money is received from the buyer or when Platron learns from the payment system that payment failed, Platron requests Result URL of the merchant and sends information about payment 22

23 result. The request will be sent in pg_encoding encoding specified with payment initialization (utf-8 by default). When receiving this request the merchant is to deliver the goods or services to the buyer, in case the payment is successful. If pg_can_reject=1 and the merchant cannot receive the payment (for example the booking has expired), it is to answer with rejected status, and Platron will cancel the payment (There is no possibility to cancel the payment through INPLAT). In this case pg_description field from the merchant answer will be shown to the buyer as the reason of failure. If the merchant server is not available at the moment of Result URL request (no response within 30 seconds) or its response couldn t be interpreted, Platron will keep trying to send the payment result information over to the merchant for the next 2 hours, even if pg_lifetime expires. If the first attempt to call Result URL failed, the payment is not canceled within the payment system. Moreover, if the payment system allows to cancel the payment only immediately after success notification, Platron accepts the payment and doesn t allow the merchant to refuse the payment in subsequent calls to Result URL. The merchant should be prepared for the situation when Result URL is requested more than once for the same payment. Responses to the repeated requests are to be exactly the same as the original response, even after pg_lifetime expires. Parameters passed with Result URL request: pg_order_id Payment identificator in merchant s system pg_payment_id Internal payment identificator in Platron pg_amount Amount of the bill (in pg_currency), is equal to pg_amount in payment initialization request pg_currency Currency of the bill, is equal to pg_currency in payment initialization request pg_net_amount Amount (in pg_currency) that the merchant will receive if he accepts the payment pg_ps_amount Amount of the bill (in pg_ps_currency), sent to the payment system. Might be omitted for failed payments. pg_ps_full_amount Full amount (in pg_ps_currency) paid by the buyer, including all commissions. Might be omitted for failed payments. pg_ps_currency Currency, in which the payment was processed by the payment system. Might be omitted for failed payments. pg_overpayment Overpayment amount in payment system currency. This parameter is passed only when overpayment is allowed and customer paid more than expected. If the paid amount is exactly as expected, or payment was not successful, this parameter is not passed. pg_payment_system Payment system identificator pg_result 1 success, 0 failure pg_payment_date Date and time of the payment in the format YYYY-MM-DD HH:MM:SS pg_can_reject 1 the payment can be canceled (credit cards for example), 0 the payment may not be canceled. By default pg_can_reject=0. pg_card_brand Type of card used by payer. CA MasterCard and subsidiaries, VI Visa, AX AmericanExpress. This parameter is passed only when transaction was paid by card. pg_card_pan Masked card number (part of numbers are hidden). This parameter is passed only when transaction was paid by card. pg_card_hash Hashed card number (card number is encrypted irreversible encryption algorithm). This parameter is passed only when 23

24 transaction was paid by card. pg_auth_code Authorization code. This parameter is passed only when transaction was paid by card. pg_captured 0 or 1. This parameter is passed only when transaction was paid by card and shows if clearing was performed automatically immediately after authorization. If pg_captured=0 then merchant needs to issue capture command later (see section Capture Request for Credit Card Transactions) or wait that Platron will do it itself. pg_user_phone Buyer s phone number (specified at the initialization of payment) pg_need_phone_notification Need customer notification by sms pg_user_contact_ Customer . Send if exist pg_need_ _notification Need customer notification by . Send if exist pg_user_contact_ pg_failure_code Failure reason code (see the list and description of codes in section List of Reasons for Payment Failure ). The field is present only if payment failed. pg_failure_description Description of failure reason. The description is given in transaction language and in terms that customer can understand. This description can be communicated to customer by any available means. The field is present only if payment failed. pg_recurring_profile_id The recurring payment profile identificator. pg_recurring_profile_expiry_date Date by which the recurrent profile available for use. Merchant parameters All the fields previously received from the merchant that do not have pg_ prefix pg_salt Random string pg_sig Signature Example of GET request of the merchant by Platron, when paying by usual payment system: g_amount= &pg_currency=rur&pg_net_amount=100.00&pg_ps_amount=105.00&pg_ps _full_amount=105.00&pg_ps_currency=rur&pg_payment_system=inplatmts&pg_result=1&p g_payment_date= :59:30&pg_can_reject=0&pg_user_phone= &pg_need_phone_notification =1&pg_user_contact_ [email protected]&pg_need_ _notification=1&uservar1= &pg_sig=da61f9d237952f56bd05c602d28780b3 Example of xml request (POST with XML in pg_xml parameter) of the merchant by Platron, when paying by usual payment system: <request> <pg_salt>0bd68e</pg_salt> <pg_order_id>654</pg_order_id> <pg_payment_id>765432</pg_payment_id> <pg_amount> </pg_amount> <pg_currency>rur</pg_currency> <pg_net_amount>100.00</pg_net_amount> 24

25 <pg_ps_amount>105.00</pg_ps_amount> <pg_ps_full_amount>105.00</pg_ps_full_amount> <pg_ps_currency>rur</pg_ps_currency> <pg_payment_system>inplatmts</pg_payment_system> <pg_result>1</pg_result> <pg_payment_date> :59:30</pg_payment_date> <pg_can_reject>0</pg_can_reject> <pg_user_phone> </pg_user_phone> <pg_need_phone_notification>1</pg_need_phone_notification> <pg_need_ _notification>1</pg_need_ _notification> <uservar1> </uservar1> <pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig> </request> Example of GET request of the merchant by Platron, when paying by card payment system: g_amount= &pg_currency=rur&pg_net_amount=100.00&pg_ps_amount=105.00&pg_ps _full_amount=105.00&pg_ps_currency=rur&pg_payment_system=russianstandard&pg_resu lt=1&pg_payment_date= :59:30&pg_can_reject=1&pg_card_brand=CA&pg_card_pan=527594******4984&pg_car d_hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_captured= 0&pg_user_phone= &pg_need_phone_notification=1&pg_user_contact_ =t 56bd05c602d28780b3 Example of xml request (POST with XML in pg_xml parameter) of the merchant by Platron, when paying by card payment system: <request> <pg_salt>0bd68e</pg_salt> <pg_order_id>654</pg_order_id> <pg_payment_id>765432</pg_payment_id> <pg_amount> </pg_amount> <pg_currency>rur</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>rur</pg_ps_currency> <pg_payment_system>russianstandard</pg_payment_system> <pg_result>1</pg_result> <pg_payment_date> :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> </pg_user_phone> 25

26 <pg_need_phone_notification>1</pg_need_phone_notification> <pg_need_ _notification>1</pg_need_ _notification> <uservar1> </uservar1> <pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig> </request> In case the merchant accepts the payment, he is to answer in XML with ok status. <response> <pg_salt>kdjdope983</pg_salt> <pg_status>ok</pg_status> <pg_description>the service has been delivered to the buyer</pg_description> <pg_sig>9bfc5f602d287096ed237952f56bd05c</pg_sig> </response> If the merchant would like to reject the payment and there was pg_can_reject=1 parameter in the request, the merchant is to answer with XML with status rejected: <response> <pg_salt>kdjdope983</pg_salt> <pg_status>rejected</pg_status> <pg_description>booking has expired</pg_description> <pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig> </response> Response parameters list: Parameter Description pg_status ok payment has been accepted rejected payment has been rejected (if pg_can_reject=1) error error in interpreting request pg_description (string[1024]) If the payment is accepted this field is not used. If the payment is rejected, description of rejection reason for the buyer. If there is an error description of the error, can be the same as pg_error_description. pg_error_description Error description, if pg_status is error pg_salt Random string pg_sig Signature Rejected status may be returned by the merchant only if there was pg_can_reject=1 parameter in the inbound request from Platron. Otherwise, disregarding the merchant s response, the payment is accepted. 26

27 If merchant rejected the payment, the buyer is redirected to Failure URL, otherwise the buyer is redirected to Success URL. Buyer s Return to the Merchant s Site After the payment process is completed in an online payment system the buyer is redirected back to the merchant s page Success URL or Failure URL depending on the payment result. The redirect is performed by Success URL Method or Failure URL Method indicated in the payment initialization parameters or global merchant settings. The following parameters are passed to Success URL or Failure URL page: pg_order_id Payment identificator within merchant s system pg_payment_id Internal payment identificator in Platron pg_card_brand Type of card used by payer. CA MasterCard and subsidiaries, VI Visa, AX AmericanExpress. This parameter is passed only when transaction was paid by card. pg_card_pan Masked card number (part of numbers are hidden). This parameter is passed only when transaction was paid by card. pg_card_hash Hashed card number (card number is encrypted irreversible encryption algorithm). This parameter is passed only when transaction was paid by card. pg_auth_code Authorization code. This parameter is passed only when transaction was paid by card. pg_captured 0 or 1. This parameter is passed only when transaction was paid by card and shows if clearing was performed automatically immediately after authorization. If pg_captured=0 then merchant needs to issue capture command later (see section Capture Request for Credit Card Transactions) or wait that Platron will do it itself. pg_overpayment Overpayment amount in payment system currency. This parameter is passed only when overpayment is allowed and customer paid more than expected. If the paid amount is exactly as expected, this parameter is not passed. pg_failure_code Same as in Result URL call (see above). Passed only to Failure URL. pg_failure_description Same as in Result URL call (see above). Passed only to Failure URL. pg_recurring_profile_id The recurrent payment profile identificator. pg_recurring_profile_expiry_date Date by which the recurrent profile available for use. Merchant parameters All fields received from the merchant in the moment of payment initialization that do not have pg_ prefix pg_salt Random string pg_sig Signature If the payment is done via an offline payment system, the buyer is never returned to the merchant s site. Example of GET or AUTOGET redirect in case of successful payment: =765432&uservar1= &pg_card_brand=CA&pg_card_pan=527594******4984&pg_card_ 27

28 hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_auth_code= &pg_sig=20bcedd8320ac8868b97706abedec0b4 If Success URL or Failure URL already have query parameters (after the? ), additional parameters pg_order_id, pg_payment_id and user parameters of the merchant are added to the end of the query string. The merchant has to take care that the names of additional parameters do not collide with the names of existing parameters. It is important to understand the difference between Result URL and Success URL. Result URL is called by Platron directly, while Success URL is called by customer s browser when customer is redirected by Platron back to merchant s site. It would be a mistake to use Success URL as sole method of knowing that a payment is finished since for various reasons (e.g. network interruption) customer might not reach merchant s site after payment. The most reliable way of knowing that a payment is finished is implementing a Result URL. Platron guarantees to retry calling merchant s Result URL within 2 hours after payment if the first attempt to call Result URL was unsuccessful for any reason. Notification about Refund of Payment If the payment is refunded (fully or partially) on Platron or PS side, Platron calls the merchant s Refund URL script with Request Method. The request is sent in encoding defined by the merchant at the moment of payment initialization, utf-8 by default. The gate sends information about the ID and properties of the payment transaction and waits for response for 30 seconds. If the merchant s server is unreachable (no response within 30 seconds) or its response couldn t be interpreted, Platron will retry the notifications within 2 hours. Refund URL parameters: pg_order_id Payment ID in the merchant s system pg_payment_id Payment ID in Platron s internal register pg_amount Invoice amount (in pg_currency currency), same as pg_amount at the moment of payment initialization pg_currency Invoice currency, same as pg_currency at the moment of payment initialization pg_net_amount Amount (in pg_ps_currency), that will be debited from merchant pg_ps_full_amount Full amount (in pg_ps_currency), that will be refunded to the buyer pg_ps_currency Currency, in which the refund will be done in the payment system pg_payment_system Payment system name pg_refund_date Date and time of refund in YYYY-MM-DD HH:MM:SS format pg_refund_type Refund type: reversal transaction fully revoked before being sent to clearing (bank cards only), refund full or partial refund, moneyback full or partial refund through a provider different from original payment system. The difference between reversal and refund makes sense only for bank card payments. Reversal can only happen before clearing, while refund can only happen after clearing. pg_refund_system Payout system that executed the refund. Makes sense only when pg_refund_type=moneyback. Possible values: CONTACT_O payout through CONTACT money transfer system, MOBILEPHONE_O mobile phone recharge. pg_refund_id Unique refund id for filtering out repeated notifications about the same refund. 28

29 Each refund type has its own set of unique ids. Merchant parameters All the fields previously received from the merchant that do not have pg_ prefix pg_salt Random string pg_sig Signature If only a part of amount was refunded (for example, a partial refund when paying by credit cards), pg_net_amount and pg_ps_full_amount contain amount taken from the shop and amount returned to the payer s card, respectively; pg_amount always contains the original invoice amount. Merchant should be ready that it may receive multiple partial refund requests for the same payment. Example of GET request of merchant by Platron: 41&pg_payment_system=CREDITCARD&pg_amount=100.00&pg_currency=RUR&pg_net_amount= &pg_ps_currency=RUR&pg_ps_full_amount=100.80&pg_refund_date= :32:30&pg_sig=afaef9d237932f56bd05c602d287df3a&uservar1= Example of XML request (POST with XML in pg_xml): <request> <pg_salt>gw41b38vc</pg_salt> <pg_order_id>2614</pg_order_id> <pg_payment_id>825941</pg_payment_id> <pg_payment_system>creditcard</pg_payment_system> <pg_amount>100.00</pg_amount> <pg_net_amount>100.00</pg_net_amount> <pg_currency>rur</pg_currency> <pg_ps_currency>rur</pg_ps_currency> <pg_ps_full_amount>100.00</pg_ps_full_amount> <pg_refund_date> :32:30</pg_refund_date> <uservar1> </uservar1> <pg_sig>afaef9d237932f56bd05c602d287df3a</pg_sig> </request> After receiving refund notification merchant should reply with ok status: <response> <pg_salt>eyhfh42za22h</pg_salt> <pg_status>ok</pg_status> <pg_sig>ea362f52d bd05c6fc5f9427d</pg_sig> </response> List of parameters of merchant response: Parameter pg_status ok information received error error in interpreting data 29 Description

30 pg_error_description Error description if pg_status=error pg_salt Random string pg_sig signature Notification about Capture for Credit Card Transactions If merchant works in auth/capture mode, Platron notifies merchant immediately after sending capture command to acquiring bank. Usually capture is initiated by merchant who sends capture command to Platron (see chapter Capture Request for Credit Card Transactions below). If merchant doesn t issue this command within the timeframe specified in merchant settings (max 5 days), Platron sends capture command to the acquiring bank on its own. In order to notify merchant about the performed capture, Platron calls the merchant s Capture URL script with Request Method. The gate sends information about payment ID and waits for response for 30 seconds. If the merchant s server is unreachable (no response within 30 seconds) or its response couldn t be interpreted, Platron will retry the notifications within 2 hours. Capture URL parameters: pg_order_id Payment ID in the merchant s system pg_payment_id Payment ID in Platron s internal register Merchant parameters All the fields previously received from the merchant that do not have pg_ prefix pg_salt Random string pg_sig Signature Example of GET request of merchant by Platron: &pg_sig=afaef9d237932f57bd05c602d287df34&uservar1= Example of XML request (POST with XML in pg_xml): <request> <pg_salt>gw41b38vc</pg_salt> <pg_order_id>2614</pg_order_id> <pg_payment_id>825941</pg_payment_id> <uservar1> </uservar1> <pg_sig>afaef9d237932f57bd05c602d287df34</pg_sig> </request> After receiving capture notification merchant should reply with ok status: <response> <pg_salt>eyhfh42za22h</pg_salt> <pg_status>ok</pg_status> <pg_sig>ea362f52d bd05c6fc5f9427d</pg_sig> </response> List of parameters of merchant response: 30

31 Parameter pg_status ok information received error error in interpreting data pg_error_description Error description if pg_status=error pg_salt Random string pg_sig signature Description Testing All new merchants start in testing mode, then after finishing integration and submitting of Letter of Integration (it can be printed from to Platron the merchant is switched over to live mode by Platron administration. In order to test integration in testing mode, merchant needs to use one of testing payment systems (pg_payment_system=test or pg_payment_system=testcard) that work in artificial currency called TESTIK. No real money will be transferred as a result of successful payments in testing payment systems. In testing mode, only testing payment systems can be used. In live mode, on the contrary, testing payment systems cannot be used and will be filtered out of the list of available payment systems. After the merchants goes into live mode you can still create transactions in test mode by specifying additional parameter pg_testing_mode in requests that create new payments and get list of available payment systems. The value pg_testing_mode=1 turns testing mode on for a single transaction, pg_testing_mode=0 (or empty) leaves live mode on. If the merchant itself is in testing mode, the parameter pg_testing_mode doesn t affect transaction mode. The switching of merchant s testing mode on and off is done only by Platron administration. The payment transaction will not change status automatic. You must go to transactions section in platron, choose those transaction and use test buttons. Test card payment system support clearing, PSI DSS, long record and recurring. When you use test card payment system you need to set payment card. It could be real card (there will no payment), not real payment card (use lune rule), and it can be test card. Fraud monitoring will not check transaction by testing cards. List of test cards: Recurrent payments Initialize the recurrent Profile For initialize a profile of recurring payments merchant must paying the usual way transaction of an additional parameter pg_recurring_start, indicating the demand for the creation of recurrent profile and pg_payment_system that indicates payment system with recurring payment support (Technical details). Profile number to repeat the payment will be given in the result notification of the payment 31

32 in field pg_recurring_profile. The recurring profile will be available only when start transaction will be captured. Recurrent payments available only in auth capture mode. The merchant can set the desired time period during which it will be possible to use a recurring profile (the parameter is optional, otherwise will be used card expiration date). If the company has set the pg_recurring_lifetime more than the lifetime of card, the expiration date will be used the expire date of the card. If the merchant needs recurring profile without first payment, it is possible to specify the amount pg_amount = 0, in this case, a profile is created for recurring payments without first payment. For working with recurring payments you need to ask manager. Use recurring profile The merchant can repeat payment by recurring profile at any time in its sole discretion, the client must request with one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Maximum wait time is 30 seconds. List of request parameters: Field (required fields are marked bold) pg_merchant_id pg_order_id pg_recurring_profile pg_amount pg_result_url pg_refund_url pg_request_method Default value Start recurring profile payment amount value From the merchant settings Result URL From the merchant settings Refund URL From the merchant settings Request Method Description Merchant identificator in Platron. Given at signup. Payment identificator in the merchant s internal system. It is recommended to keep this field unique. The recurring profile identificator. Has been received by the seller in creating a profile of recurrent payments. Payment amount, in pg_currency. (string[256]) URL for notifying the merchant about payment result. The URL is called just after the payment completes with success or failure. If the parameter is not specified, then it is taken from global merchant settings. If the parameter is set to a blank string, then Platron does not notify the merchant about payment result. (string[256]) URL for notifying the merchant about refunds initiated on Platron or PS side. The URL is called just after the payment is revoked. If the parameter is not specified, then it is taken from global merchant settings. If the parameter is set to a blank string, then Platron does not notify the merchant about refunds. (string[4]) GET, POST or XML method of calling Check URL, Result URL, Refund URL, and Capture URL scripts. pg_encoding UTF-8 Encoding of other fields of the request (only when GET or POST method is used). pg_description (string[1024]) Product or service description. Displayed to the user in the process of payment. Encoded in pg_encoding. 32

33 Merchant s additional parameters pg_salt pg_sig Merchant can pass any additional parameters, provided that their names do not start with pg_. All these parameters will be passed back to pg_check_url, pg_result_url, pg_success_url, pg_failure_url. Names of additional merchant s parameters must be unique. Random string Signature About a result of payment Platron notify the seller to the Result URL (see Payment Result) Auxiliary Requests Receiving the List of Payment Systems and Prices If the merchant wishes that the buyer makes payment system choice at the merchant s site, he can either manually display the list of available payment systems and manually calculate the final price for each of the payment systems, taking into account all commissions based on the data from his agreement with Platron, or receive the actual list of available payment systems and commissions automatically. In the latter case the merchant needs to use direct request to Platron that is described below. The merchant sends request to or with one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Maximum wait time is 30 seconds. List of request parameters: Parameter (required fields are marked bold) pg_merchant_id pg_amount Default value Description (string[16]) merchant identificator (decimal) bill amount in merchant system in pg_currency. pg_currency RUR (string[3]) bill currency pg_testing_mode From Can be 0 or 1. Value 1 turns testing mode on for a single merchant s transaction when merchant is already in live mode. See settings details in section testing. pg_salt pg_sig Random string Signature Example of GET request: 45&pg_currency=RUR&pg_sig=aec5f9d237952f83bd05c602d287098d Example of XML request (requested by POST in pg_xml parameter): <request> <pg_salt>123</pg_salt> <pg_merchant_id>456</pg_merchant_id> <pg_amount>800.45</pg_amount> <pg_currency>rur</pg_currency> 33

34 <pg_sig>aec5f9d237952f83bd05c602d287098d</pg_sig> </request> The response to this request is an XML (in utf-8 encoding), which contains the list of all payment systems and their attributes available to this merchant. The attributes are the amount and currency of payment, name and description of the payment system and the list of additional parameters pg_required that are required for this payment system. Currently, the required fields are pg_user_ field for MONEYMAIL and BANKCARDPRU that holds the -address for identification in payment system, pg_alfaclick_client_id for ALFACLICK. Also you have pg_additional parameter as not necessary field. The merchant is to take care that these fields are properly filled. If a payment system is selected that mandates that a specific field is required but this field is not specified, then Platron will request the field from the buyer at platron.ru. Example of response: <response> <pg_salt> </pg_salt> <pg_status>ok</pg_status> <pg_payment_system> <pg_name>beelinepurse</pg_name> <pg_description>beeline cellphone payment</pg_description> <pg_payment_scenario>offline</pg_payment_scenario> <pg_amount_to_pay>808.67</pg_amount_to_pay> <pg_amount_to_pay_currency>rur</pg_amount_to_pay_currency> </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>rur</pg_amount_to_pay_currency> <pg_sub_payment_systems> <pg_sub_payment_system> <pg_sub_name>elecsnet</pg_sub_name> <pg_sub_description>elecsnet electronic kiosks</pg_sub_description> </pg_sub_payment_system> <pg_sub_payment_system> <pg_sub_name>euroset</pg_sub_name> <pg_sub_description>euroset retail network</pg_sub_description> </pg_sub_payment_system> <pg_sub_payment_system> <pg_sub_name>osmp</pg_sub_name> <pg_sub_description>osmp/qiwi electronic kiosks</pg_sub_description> </pg_sub_payment_system> </pg_sub_payment_systems> </pg_payment_system> <pg_payment_system> <pg_name>moneymail</pg_name> <pg_description>moneymail system</pg_description> 34

35 <pg_payment_scenario>online</pg_payment_scenario> <pg_amount_to_pay>822.00</pg_amount_to_pay> <pg_amount_to_pay_currency>rur</pg_amount_to_pay_currency> <pg_required>pg_user_ </pg_required> </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>rur</pg_amount_to_pay_currency> </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>rur</pg_amount_to_pay_currency> </pg_payment_system> <pg_sig>73daf9d237952f56bd05c602d2878dc2</pg_sig> </response> There is a list of payment systems and signature in the response tag. Description of each payment system is placed within pg_payment_system tag with unique identificator in pg_name attribute the name of the payment system. For each of the payment systems the following parameters may be specified: Parameter Description pg_name (string[32]) payment system name pg_description (string[256]) description of the system, to be shown to the user pg_payment_scenario offline / online pg_amount_to_pay (decimal) amount that will be paid by user pg_amount_to_pay_currency currency that will be paid by user pg_required pg_additional pg_sub_name pg_sub_description (string[32]) name of required parameter, if any. If there are several required parameters, each of them is placed in a separate tag pg_required. (string[32]) optional parameter, similar pg_required (string[32]) name of payment system in a group (string[256]) description of payment system in a group, can be displayed to the user along with or instead of pg_description of the grouping payment system pg_sub_payment_systems container for payment systems in a group pg_salt Random string pg_sig Signature The list of payment systems is sorted in the response by pg_name and by pg_sub_name within a group. If a payment system is a group of payment systems, its member payment systems are listed in pg_sub_payment_systems tag. Example of payment system choice page can be found at platron.ru if payment system identificator is not specified while initializing the payment. 35

36 In case of an error, an XML for the error is returned (see Methods of direct interaction between merchant and Platron). Querying Payment Status The merchant can request Platron about status of any payment transaction initiated by the merchant. This may be useful, for example, in case Result URL request was not received by the merchant because of a network failure, and the buyer has already been redirected to Success URL, but the merchant does not know the transaction result yet. The merchant makes request to or by one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Maximum wait time is 30 seconds. List of request parameters (all fields are required): pg_merchant_id pg_payment_id or pg_order_id pg_salt pg_sig Example of GET request: Merchant identificator Payment identificator within Platron or within merchant s shop. In the latter case merchant must guarantee that order_ids are unique, otherwise Platron will return information about the most recent order with this order_id. Random string Signature id=765432&pg_sig=a1b7ccc945c0a60949f6bd6383f5f768 Example of XML request (by POST, in pg_xml parameter): <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 response to the request is an XML of the following format: <response> <pg_salt>9865</pg_salt> <pg_status>ok</pg_status> <pg_payment_id> </pg_payment_id> <pg_transaction_status>ok</pg_transaction_status> <pg_can_reject>1</pg_can_reject> <pg_create_date> :22:30</pg_create_date> <pg_result_date> :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> 36

37 <pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash> <pg_auth_code>014318</pg_auth_code> <pg_captured>0</pg_captured> <pg_sig>8380d43c7719e6ce48da0c79aa7eb2ba</pg_sig> </response> Here: pg_status pg_payment_id pg_transaction_status pg_can_reject pg_create_date pg_result_date pg_revoke_date pg_payment_system pg_card_brand pg_card_pan pg_card_hash pg_auth_code pg_captured pg_overpayment Request handling result (not to be confused with payment status). Ok if the payment is found and does really belong to this merchant, or error elsewhere. Platron s payment identifier. Payment status. See List of Payment Stati 0 or 1 payment can or cannot be canceled. 1 is possible only if payment status is ok and payment system allows canceling the payment. In this case the merchant may call revoke.php, as described in the next chapter. Date and time of creation of payment transaction. Date and time of successful (ok) or non-successful (failed) payment completion. This is the date of Result URL request. The field is filled only when transaction status is ok, failed or revoked. Date and time of canceling of payment. The field is filled only when transaction status is revoked. Identificator of payment system, which the payment has been processed (or is to be processed) through. Type of card used by payer. CA MasterCard and subsidiaries, VI Visa, AX AmericanExpress. This parameter is passed only when transaction was paid by card. Masked card number (part of numbers are hidden). This parameter is passed only when transaction was paid by card. Hashed card number (card number is encrypted irreversible encryption algorithm). This parameter is passed only when transaction was paid by card. Authorization code. This parameter is passed only when transaction was paid by card. 0 or 1. This parameter is passed only when transaction was paid by card and shows if clearing was performed automatically immediately after authorization. If pg_captured=0 then merchant needs to issue capture command later (see section Capture Request for Credit Card Transactions) or wait that Platron will do it itself. Overpayment amount in payment system currency. This parameter is passed only when overpayment is allowed and customer paid more than expected. If the paid amount is exactly as expected, this parameter is not passed. pg_failure_code Same as in Result URL call (see above). Passed only when pg_transaction_status is failed or revoked. pg_failure_description Same as in Result URL call (see above). Passed only when pg_salt pg_sig pg_transaction_status is failed or revoked. Random string Signature 37

38 All dates are in YYYY-MM-DD hh:mm:ss format. Capture Request for Credit Card Transactions Merchant can request capture (clearing) of credit card transactions if it is set up in auth/capture mode. In the case of a corresponding configuration, after the transaction, the transaction will be authorized, but not captured. Maximum delay time is 5 days and can be adjusted on the Platron side from 1 to 5 days. The merchant makes request to or by one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Maximum wait time is 30 seconds. List of request parameters: pg_merchant_id Merchant identificator pg_payment_id pg_long_record pg_salt pg_sig Example of GET request: Payment identificator within Platron Long record for air ticket sales, see additional section for details. You can get it in technical department. Random string Signature id= &pg_sig=7f3af9d237952f56bd05c602d2879a3c Example of XML request (by POST, in pg_xml parameter): <request> <pg_salt>123</pg_salt> <pg_merchant_id>456</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_sig>7f3af9d237952f56bd05c602d2879a3c</pg_sig> </request> The response to the request is an XML of the following format: <response> <pg_salt>9865</pg_salt> <pg_status>ok</pg_status> <pg_sig>5e1af9d237952f56bd05c602d28704ac</pg_sig> </response> Here: pg_status pg_salt pg_sig Result of handling the request ok if the request is accepted. Merchant will be notified about the result by calling its Capture URL. error otherwise. Random string Signature 38

39 Payment Revocation (full or partial) The merchant can cancel any successfully completed payment if the payment system allows that (for example, credit cards). In this case the money goes back to the buyer. Merchant can return full amount or part of original payment. Multiple refunds are allowed until their total amount reaches amount of original payment. It is possible to cancel the payment both from the merchant area at platron.ru and automatically by requesting the scripts or Parameters are passed by one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Maximum wait time is 30 seconds. List of request parameters (all of the parameters are required): pg_merchant_id Merchant identificator pg_payment_id Payment identificator within Platron pg_refund_amount Amount to return. If the parameter is omitted or set to 0, full amount is returned. pg_salt Random string pg_sig Signature GET request example: &pg_refund_amount=800&pg_sig=6dd2a9d237952f56bd05c602d2872af8 XML request example (POST with pg_xml parameter): <request> <pg_salt>123</pg_salt> <pg_merchant_id>456</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_refund_amount>800</pg_refund_amount> <pg_sig>6dd2a9d237952f56bd05c602d2872af8</pg_sig> </request> The response to the request is an XML of the following format in case of successful execution of the payment cancelation request: <response> <pg_salt>9865</pg_salt> <pg_status>ok</pg_status> <pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig> </response> In case of an error: <response> <pg_salt>9865</pg_salt> 39

40 <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> Here: pg_status pg_error_code pg_error_description pg_salt pg_sig Result of request processing. Error code Description of error result Random string Signature Creation of Demand for Refund In case the payment system cannot refund money by means of an online API call, merchant can create a demand for returning all or part of the money received. In this case the money is refunded to customer in one of the two ways: to the purse in the same payment system that received the payment (electronic money only, such as WebMoney or YandexMoney), through a mobile top-up system (to customer s mobile phone account) or Contact money transfer system. Merchant can refund full amount paid or part of it. It is possible to do several partial refunds as long as the total amount refunded doesn t exceed amount received. Refund demands can be created from merchant s admin panel or through an API request to Platron s script or create_refund_request.php. Parameters are passed by one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Timeout is 30 seconds. Depending on the combination of payment system and refund method, different parameters are sent in the demand request: 1. For returning the money paid from electronic purses (WEBMONEYRBANK, YANDEXMONEY, RBKMONEY, MOBW): pg_merchant_id Merchant identificator pg_payment_id Payment identificator within Platron pg_comment Reason for returning the money pg_refund_amount Amount to return. If the parameter is omitted or set to 0, full amount is returned. pg_salt Random string pg_sig Signature Example of GET request: 243&pg_payment_id= &pg_comment=Ticket+returned&pg_refund_amount=100&pg_sig =149b5b52ab0b5ebfa bc222 Example of XML request (POST with single pg_xml parameter): 40

41 <request> <pg_salt>sdasdasd</pg_salt> <pg_merchant_id>243</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_comment>ticket returned</pg_comment> <pg_refund_amount>100</pg_refund_amount> <pg_sig>149b5b52ab0b5ebfa bc222</pg_sig> </request> 2. For payment systems that are not able to return money themselves, there are two methods to return money: a. Mobile phone top-up: pg_merchant_id Merchant identificator pg_payment_id Payment identificator within Platron pg_comment Reason for returning the money pg_payout_system Provider used to return the money (MOBILEPHONE_O in this case) pg_account Customer s mobile phone number pg_refund_amount Amount to return. If the parameter is omitted or set to 0, full amount is returned. pg_salt Random string pg_sig Signature Example of GET request: 254&pg_payment_id= &pg_payout_system=MOBILEPHONE_O&pg_account= & pg_comment=ticket+returned&pg_refund_amount=100&pg_sig=17afcf9e7f84a651ba29f2903 f Example of XML request (POST with single pg_xml parameter): <request> <pg_salt>erewrwer</pg_salt> <pg_merchant_id>254</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_comment>ticket returned</pg_comment> <pg_payout_system>mobilephone_o</pg_payout_system> <pg_account> </pg_account> <pg_refund_amount>100</pg_refund_amount> <pg_sig>17afcf9e7f84a651ba29f2903f133314</pg_sig> </request> b. Payout through CONTACT money transfer system: pg_merchant_id Merchant identificator pg_payment_id Payment identificator within Platron pg_comment Reason for returning the money pg_payout_system Provider used to return the money 41

42 pg_destination_code pg_fio pg_refund_amount pg_salt pg_sig (CONTACT_O in this case) Contact destination point code Full name of the recipient Amount to return. If the parameter is omitted or set to 0, full amount is returned. Random string Signature Example of GET request: d=254&pg_payment_id= &pg_payout_system=contact_o&pg_destination_code=xxxx& pg_fio=радужная+василиса+сергеевна&pg_comment=ticket+returned&pg_refund_amount=1 00&pg_sig=ccfe7190cd89972a17e489fda7257c41 Example of XML request (POST with single pg_xml parameter): <request> <pg_salt>edwedwd</pg_salt> <pg_merchant_id>254</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_comment>ticket returned</pg_comment> <pg_payout_system>contact_o</pg_payout_system> <pg_destination_code>xxxx</ pg_destination_code > <pg_fio>радужная Василиса Сергеевна</pg_fio> <pg_refund_amount>100</pg_refund_amount> <pg_sig>ccfe7190cd89972a17e489fda7257c41</pg_sig> </request> c. Payout to Yandex.Money purse pg_merchant_id pg_payment_id pg_comment pg_payout_system pg_destination_account pg_refund_amount pg_salt pg_sig Merchant identificator Payment identificator within Platron Reason for returning the money Provider used to return the money (YANDEXMONEY_O in this case) Yandex.Money purse number to be recharged. 16 digits. Amount to return. If the parameter is omitted or set to 0, full amount is returned. Random string Signature Example of GET request: 254&pg_payment_id= &pg_payout_system=YANDEXMONEY_O&pg_destination_account= xxxx&pg_comment=payout+reason&pg_refund_amount=100&pg_sig=6ffe7190cd89972a17e489 fda7257c82 42

43 Example of XML request (POST in parametr pg_xml): <request> <pg_salt>edwedwd</pg_salt> <pg_merchant_id>254</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_comment>payout reason</pg_comment> <pg_payout_system>yandexmoney_o</pg_payout_system> <pg_destination_account>xxxx</pg_destination_account> <pg_refund_amount>100</pg_refund_amount> <pg_sig>6ffe7190cd89972a17e489fda7257c82</pg_sig> </request> Response format is identical to that of response to payment revocation request (see previous chapter). Bill Cancelation before Payment The merchant can cancel any bill that has not been paid yet. After this operation Platron will refuse to process the payment when the payment system makes the pre-payment request (if supported by the payment system). Moreover, the bill is canceled in all payment systems that support such request. So canceling the bill doesn t mean that it won t be processed by all payment systems. To cancel the bill, the merchant may request the script or Parameters are passed by one of the methods of direct request (see Methods of direct interaction between merchant and Platron). Maximum wait time is 30 seconds. List of request parameters (all of the parameters are required): pg_merchant_id Merchant identificator pg_payment_id Payment identificator within Platron pg_salt Random string pg_sig Signature GET request example: &pg_sig=628e300c3204c8ee398d878a5109b520 XML request example (POST with pg_xml parameter): <request> <pg_salt>123</pg_salt> <pg_merchant_id>456</pg_merchant_id> <pg_payment_id> </pg_payment_id> <pg_sig>628e300c3204c8ee398d878a5109b520</pg_sig> </request> The response to the request is an XML of the following format in case of successful execution of the bill cancelation request: 43

44 <response> <pg_salt>9865</pg_salt> <pg_status>ok</pg_status> <pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig> </response> In case of an error: <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>ac08f9d237952f5bc4e5c602d </pg_sig> </response> Here: pg_status Result of request processing. pg_error_code Error code pg_error_description Description of error result pg_salt Random string pg_sig Signature ok means that the bill cancelation request was received. The bill still may be paid if the payment system that was requested to process the payment doesn t support bill cancelation and doesn t make any pre-payment requests. If the payment system doesn t support payment revocation but supports refunding money (for example TRANSCRED), Platron makes refund request. Additional fees may be taken in this case. Payout without a Prior Payment Merchant can make a payout to its customer without linking it to a previous payment processed by Platron. It can be useful if the payment was accepted through non-platron payment methods or if merchant wants to refund several payments in a single operation. Before using this service merchant needs to create a node attached to his account. Merchant needs to sign in to with his login and password, navigate to Nodes page and follow online instructions in order to create a desktop app. Payout POST requests must be sent to with the following parameters: Parameter name Description node_id token Merchant's node id Calculated as: sha1("from="+node_id+";to="+to_node_id+";"+secret_key), where node_id merchant's node id obtained by following the above procedure, to_node_id id of node the request is sent to; for Platron it is to_node_id=2, secret_key secret key entered by merchant when creating the node. 44

45 verifier_node_id verifier_node_id=1 id of node that verifies signature_for_verifier during the first request to the service signature_for_verifier Request signature, passed only with verifier_node_id. Calculated as: md5(node_id+ ; +to_node_id+ ; +verifier_node_id+ ; +sha1(token_for_azid)) node_id merchant's node id to_node_id=2 (platron.ru) verifier_node_id=1 (azid.ru) token_for_azid token calculated according the above formula for request to azid.ru. amount Amount of payout description Description of payout payout_system Name of payout system. Currently supported CONTACT_O and YANDEXMONEY_O. contract_id ID of merchant's contract with Platron which is to be used for payout. It can be taken from control panel at If there is only one contract with active payouts, this parameter is optional. Payout system specific parameters See the decriptions above in Creation of Demand for Refund, field names are passed without pg_ prefix (destination_code and fio for CONTACT_O and destination_account for YANDEXMONEY_O). The fields verifier_node_id and signature_for_verifier are required only in first request. After first successful request they are optional. Platron's response is json with the following fields: Field name error_code payout_id Description Error code: 2 for failed authentication (wrong token or signature_for_verifier); 1 for invalid payout parameters or when payout is impossible; 0 for success. ID of payout (only with zero error code). It can be used to query payout status (see next section) error_description Error description (only when error code is non-zero) Example of successful response: { error_code: 0, payout_id: } Example of error response: { error_code: 2, error_description: Authentification failed } If merchant receives successful response, it means that the payout was queued for execution. At the time of request, merchant's balance is not checked. Just before sending the payout command to the payout system, Platron will check merchant's balance and if it is not sufficient, the payout will stay in the queue. Payout status can be tracked in control panel at or by automatic querying (see next section). Querying of Status of Payout without Prior Payment In order to query status of a payout without prior payment, (previous section) merchant sends GET request to with parameters: Field name Description node_id Merchant's node id 45

46 token payout_id Calculated as in the previous section Payout ID received from request in the previous section. Platron's response is json with the following fields: Field name Description error_code Error code. 2 for failed authentication (wrong token); 1 for invalid parameters in request; 0 for success. status Payout status (only for zero error code). Values: pending: payout is awaiting manual execution ok: payout request was successfully forwarded to payout system received: the payout was received by client canceled: the payout was canceled by merchant revoked: the payout was revoked from payment system can_cancel Possible to cancel the payment error_description Error description (only when error code is non-zero) Example of successful response: { error_code: 0, status: received can_cancel: 0 } Cancel Payout without a Prior Payment The merchant can cancel or return the payment, if it was not received by the client. To do this, run the query with the following parameters passed by POST: Field name Description node_id Merchant's node id token Calculated as in the previous section payout_id Payout ID received from request in the previous section. Example of successful answer: { error_code: 0, payout_id: status: revoked } Example of error: { error_code: 2, error_description: Authentification failed } List of Payment Statuses Each payment transaction can be in one of the following stati: partial Payment transaction has not fully created yet, for example the payment system is not defined yet. This status can change only to pending. pending Payment transaction has been created and is waiting for the payment. This status can change to ok or failed. 46

47 ok The payment has successfully completed. This status can change only to revoked. failed The payment has failed. This is final status. revoked The payment completed successfully but was later canceled. This is final status. List of Payment Systems and Groups Payment systems that are not yet activated, are shown in grey. When you create a payment through the group payment system, it is necessary to specify the name of the group. Payment systems of the group can not be used separately. Identificator (value of pg_payment_system field) Name Base Place of payment Electronic money currency system commission WEBMONEYR WebMoney, R-Wallets RUR on top WEBMONEYZ WebMoney, Z-Wallets USD on top WEBMONEYE WebMoney, E-Wallets EUR on top WEBMONEYRBANK WebMoney, R-Wallets, revenues transferred to a bank account RUR inside and on top YANDEXMONEY Yandex.Money RUR inside MOBW OSMP/QIWI Mobile wallet RUR inside QIWI VISA QIWI WALLET RUR inside QIWIACTIVATION VISA QIWI WALLET with active pay RUR inside W1RUR W1 payment system RUR UNISTREAM UniStream wallet RUR PAYPALUSD Pay Pal USD inside PAYPALEUR Pay Pal EUR inside PAYPALRUR Pay Pal RUR inside PAYLATE Credit threw PayLate RUR inside Bank cards TRANSCRED Credit cards through Transcreditbank processing RUR inside RUSSIANSTANDARD Credit cards through Russian Standard Bank processing RUR inside PSCB Credit cards through PSCB RUR inside BANKCARDPRU Credit cards through Ocean bank RUR inside TINKOFFBANKCARD Credit cards through Tinkoff bank RUR inside Cash EUROSET Euroset shops RUR inside SVYAZNOY Svyaznoy shops RUR inside ELECSNET Elecsnet terminals RUR inside OSMP OSMP/QIWI terminals RUR inside OSMP-II OSMP/QIWI terminals with activation payment RUR inside OSMPSTD OSMP/QIWI terminals RUR inside OSMPTRAVEL OSMP/QIWI terminals RUR inside ESGP Терминалы ESGP RUR внутри PETROCOMMERCE PetrocommerzBank ATMs RUR inside CONTACT CONTACT money transfer system RUR inside BANKTRANSFER Payment by bank transfer receipt RUR inside BANKTRANSFERUSD Payment by bank transfer receipt USD inside BANKTRANSFEREUR Payment by bank transfer receipt EUR inside CASH Cash (includes EUROSET, ELECSNET, OSMP, OSMP-II, OSMPSTD, RUR inside OSMPTRAVEL,QIWI, CONTACT, EUROPLAT, SVYAZNOY) Mobile phone accounts RURU Beeline cell-phone bill RUR inside INPLATMTS INPLATMEGAFON MTS, Megafon, Tele2 cellphone bill RUR inside MTSMK MEGAFONMK MTS and Megafon cell-phone bill RUR inside MOBICOMMTS MOBICOMMEGAFON MTS, Megafon and TELE2 cell-phone bill RUR inside MOBICOMTELE2 MOBILEPHONE Cellpone bill (includes all PS of this group) RUR inside Electronic banking FAKTURA Faktura internet bank RUR inside ALFACLICK AlfaBank internet bank RUR inside PSB PromSvyazBank internet bank RUR inside HANDYBANK HandyBank internet bank RUR inside 47

48 VTB24 VTB24 internet bank RUR inside RUSSIANSTANDARDIB Russian Standard internet bank RUR inside QBANK Internet bank Svyaznoy and cash RUR inside SBRFOFFLINE Sberbank internet bank RUR SBRF Sberbank Online RUR inside MININTERNETBANK Minbank internet bank RUR inside OCEANINTERNETBANK Oceanbank internet bank RUR inside TEST TESTCARD Testing payment systems Test payment system in fictional currency. Used for debugging of integration with Platron Test payment system in fictional currency. Used for debugging credit card payments through Platron testik testik inside inside Technical details Identificator (value of pg_payment_system field) Checking the possibility of accepting the payment (is Check URL requested) Support for order lifetime by the payment system (pg_lifetime) Possibility of canceling the payment (if pg_can_reject=1 is possible) Bill cancelation before payment Recurring payment suport Refund method Electronic money WEBMONEYR yes no no on Platron side, before check only no manually, to purse WEBMONEYZ yes no no on Platron side, before check only no manually, to purse WEBMONEYE yes no no on Platron side, before check only no manually, to purse WEBMONEYRBANK yes no yes on Platron side, before check only no demand, to purse on Platron side, YANDEXMONEY yes no yes no demand, to purse before check only MOBW no yes no yes no demand, to purse QIWI no yes yes yes no demand, to purse QIWIACTIVATION no yes yes yes no demand, to purse W1RUR no yes no no no demand, through payout system UNISTREAM no yes no no no demand, through payout system PAYPALUSD yes no yes yes no demand, to purse PAYPALEUR yes no yes yes no demand, to purse PAYPALRUR yes no yes yes no demand, to purse PAYLATE yes no no Bank cards TRANSCRED no no yes RUSSIANSTANDARD no no yes 48 on Platron side, before check only on Platron side, reversal after payment on Platron side, reversal after payment no no yes demand, through payout system online, to card online, to card online, to card. PSCB no yes yes no no Only one refund for each transaction BANKCARDPRU no no no no no demand, to card TINKOFFBANKCARD no no yes on Platron side, reversal after payment yes online, to card Cash EUROSET yes yes no on Platron side, demand, through no before check only payout system SVYAZNOY yes no no on Platron side, demand, through no before check only payout system ELECSNET yes no no on Platron side, no demand, through

49 before check only payout system OSMP no yes no yes no demand, to purse OSMP-II yes yes no yes no demand, to purse OSMPSTD no yes no yes no demand, to purse OSMPTRAVEL no yes no yes no demand, to purse ESGP да да нет PETROCOMMERCE yes yes no CONTACT yes yes no на стороне Platronа, только до check on Platron side, before check only on Platron side, before check only BANKTRANSFER no no no no no BANKTRANSFERUSD no no no no no BANKTRANSFEREUR no no no no no CASH depends on payment system depends on payment no system Mobile phone accounts depends on payment system RURU yes yes no no no INPLATMTS INPLATMEGAFON MTSMK MEGAFONMK yes no no no no no yes no yes no нет no no no по заявке, через системы возврата demand, through payout system demand, through payout system demand, through payout system demand, through payout system demand, through payout system demand, through payout system demand, through payout system demand, through payout system demand, through payout system MOBICOMMTS MOBICOMMEGAFON MOBICOMTELE2 no no no no no demand, through payout system MOBILEPHONE no yes no yes no Electronic banking FAKTURA no no no no no ALFACLICK yes no no yes no PSB yes no no on Platron side, before check only no demand, through payout system demand, through payout system demand, through payment system demand, through payout system HANDYBANK no yes yes no no Online, only refund VTB24 yes no no on Platron side, before check only no demand, through payout system RUSSIANSTANDARD IB yes no no on Platron side, before check only no demand, through payout system QBANK yes no no on Platron side, before check only no demand, through payout system SBRFOFFLINE no yes no no no demand, through payout system SBRF yes no yes on Platron side, before check only no demand, to purse MININTERNETBANK no no no no no demand, through payout system OCEANINTERNETBA NK no no no no no demand, through payout system Testing payment systems TEST yes yes no yes no demand, to purse on Platron side, TESTCARD no no yes reversal after yes online payment 49

50 List of Additional Parameters of Payment Systems List of additional compulsory parameters in response required to request to create a new bill: Identificator Field name Field description ALFACLICK pg_alfaclick_client_id Digital customer ID or login BANKCARDPRU pg_user_ User EPAYKZT pg_user_ User List of Currencies Identificator (value of pg_currency field) RUR USD EUR Name Russian Roubles US dollars Euro List of Error Codes Error code Error description 100 Incorrect signature * 101 Invalid merchant id 110 Missing or not valid contract with the merchant 120 The requested action is disabled by merchant settings 200 Not enough or incorrect query parameter 340 Transaction not found 350 The transaction is blocked 360 The transaction has expired 365 The recurrent profile has expired 400 Payment canceled by a customer or a payment system 420 Payment is canceled due to exceeding the limit 490 Payment cancelation is impossible 600 General error 700 Customer data contains an error 701 Incorrect phone number 711 The phone number is not acceptable for the selected PS 850 None of the payment system is not ready to accept the request 1000 Internal error of service (may not repeat at the repeated request) * To figure out the error cause, you may use this page: List of Reasons for Payment Failure Failure code Failure reason 0 No error (empty string as description) 1 Unknown failure reason 2 General error 3 PS internal error 4 Unable to send bill to any payment systems 5 Invalid request to the payment system 40 over limit 50 Payment error 50

51 100 Wrong customer data 101 Invalid phone number 300 Invalid transaction 301 Bad card number 302 Bad cardholder name 303 Invalid CVV2/CVC2 304 Wrong card expiry date 305 This type of card is not supported by the bank 306 Incorrect amount 310 Card has expired 320 Suspected fraud 321 3D Secure Authentication Failed 329 The card was stolen 330 Unknown Acquirer Bank 350 Exceeding limit of card use frequency 351 Exceeding the limit on the amount 352 Insufficient funds 353 The transaction is not permitted to the cardholder 354 The transaction is not permitted to the acquirer bank 389 General technical system error 390 Restricted card 391 Card is locked 400 The transaction is blocked by the decision of fraud-filters 410 The client did not confirm their phone number Typical Integration Scenarios Below we describe several typical integration scenarios of merchant with Platron. The list is not complete, it shows only the most common needs and ways of their realization. Donations Goal. A merchant wants to receive donations for arbitrary amounts. No services are offered in exchange. Realization. The merchant site displays a button for giving donations and a field to type the amount in. The button leads to Platron, where buyer chooses payment system and gives the money out. The collected money is periodically sent to the merchant. pg_order_id Not used Check URL Not implemented Result URL Not implemented Simplest Merchant Goal. A merchant sells a short list of items, all orders are processed manually, the quantity of goods/services is not limited. The merchant does not need to know about successful payment online. Realization. A button is attached to each item, each button leads to Platron. HTML code of the button has only the price, description of service/good and merchant identification. After being sent to Platron the buyer selects payment system and completes the payment. Merchant employees learn about the payment via the merchant account at Platron, contact the buyer and organize delivery of good/ service. pg_order_id Not used 51

52 Check URL Result URL Not implemented Not implemented Usual Merchant Goal. Merchant sells a large choice of items, the price is calculated automatically, it is possible to order several items in one cart, all orders are processed (semi-)automatically, the quantity of goods/services is limited. The merchant needs to know online that a payment has completed successfully. Realization. The merchant calculates the final price of the cart, gives the order unique (in its own system) identificator and offers the buyer to press a button to make payment via Platron. After going to Platron the buyer selects a payment system and makes the payment. In the process of payment Platron checks that it is still possible and necessary to accept the payment (requests Check URL), after receiving the money the merchant is informed about the payment (request of Result URL). After completing the payment the buyer is sent to Success URL or Failure URL at the merchant site, where he receives actual information on the status of his payment and instructions for receiving the order. If user comes to Success URL but the merchant does not have information on transaction status yet, the merchant requests this information from Platron. pg_order_id used Check URL implemented Result URL implemented Status check implemented Payment cancelation implemented Special Merchant Goal. Similarly to the previous scenario, but the merchant wants to customize the payment page for the buyer, keep it on its own site and wants the buyer to work with the merchant site most of the time and, if possible, not even know that Platron is used for payment. Realization. Here, in addition to usual merchant scenario, the merchant needs to realize request for the list of payment systems, offer the choice of payment systems to the buyer at its own site and validate input. AUTOGET or AUTOPOST should be used as return method from Platron to the merchant site. Request of payment systems list implemented pg_order_id used Check URL implemented Result URL implemented Status check implemented Payment revocation implemented 52

53 Payment Registry Format There is a field in Merchant parameters, which is called Registry . If it is not empty, an with transactions registry (for the past day) will be sent to this address every day. is sent at 0:10 (Moscow time) every night. The following information is stored in headers: X-Merchant-ID: Assigned Merchant ID (example: 14) X-Registry-Date: Registry date, format YYYY-MM-DD (example: ) «From» contains: [email protected] Mail subject: Platron report for merchant #<Merchant ID> [YYYY-MM-DD] The registry is contained in the message body or attachment, depending on merchant s settings in his control panel. It consists of rows of data in tab-separated format. The first line contains field names. If the field value is undefined, two TABs are put instead of value. The registry is sent even if there are no transactions during the past day. In this case only header line is included in the message body. Registry structure Field code Field name Description order_id Order ID Merchant-supplied order ID pg_payment_id Payment ID BILLNUMBER, Gate-supplied payment ID op_date Date of transaction op_time Time of transaction type Operation type 3-letter operation type: "pay" payment, "ref" refund. rev reversal mb moneyback rev_mb moneyback reversal payment_system payment system name Payment system name (taken from the List of payment systems). payment_type payment type (direct or transit) Contract type: direct direct contract between Merchant and Payment System, transit Contract between Gate and Payment System bill_amount Original bill amount Amount of the original bill submitted by the merchant bill_cur_symbol Currency of the original bill Currency Code (RUR, EUR, USD) amount Amount Transaction amount actually billed from the payer pg_commission Agent comission Platron commission ps_commission Payment system comission Payment system commission (absent if type= transit ) to_pay Amount to pay The difference between Amount and Commission currency Currency Currency Code (RUR, EUR, USD) Merchant is recommended to verify Received: headers to ensure that the registry is sent by Platron. Registry example order_id pg_payment_id op_date op_time type payment_system payment_type amount pg_commission ps_commission to_pay currency :32:56 pay WEBMONEYE direct EUR :39:41 pay TEST transit RUR :42:10 pay TEST transit RUR :42:10 ref TEST transit RUR :08:22 pay RAIFFEISEN direct RUR :15:02 pay RAIFFEISEN direct RUR