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_ =test@test.ru&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