PayBox API · D.Karmichkin Expanded functionality when working GDS Amadeus. Expanded the list of...

PayBox API

Technical description

version 3.5

2

Contents Contents ............................................................................................................................................... 2

Version History ................................................................................................................................ 3 The Goal of the Service ................................................................................................................... 8 Payment Scenario ............................................................................................................................. 8 General Principles of Interaction Between Merchant and Paybox .................................................. 8

Methods of Direct Interaction Between Merchant and Paybox ................................................... 9

Methods of Interaction Between Paybox and Merchant through Customer’s Browser ............ 10 Merchant Settings .......................................................................................................................... 11 Payment Initialization .................................................................................................................... 13

Description ................................................................................................................................. 13

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. ............................................................................................. 16 Entry Point for Payment Initialization via User’s Browser ....................................................... 17

Entry Point for Direct Transfer of Information from the Merchant to Paybox .......................... 17 Checking the Possibility to Proceed with Payment ....................................................................... 19 Payment Result .............................................................................................................................. 21 Buyer’s Return to the Merchant’s Site ........................................................................................... 25

Notification about Refund of Payment .......................................................................................... 26 Notification about Capture for Credit Card Transactions .............................................................. 28

Testing ............................................................................................................................................ 29 Recurrent payments........................................................................................................................ 30

Initialize the recurrent Profile .................................................................................................... 30

Description ................................................................................................................................. 30 Auxiliary Requests ......................................................................................................................... 31

Receiving the List of Payment Systems and Prices ................................................................... 31 Querying Payment Status ........................................................................................................... 34

Capture Request for Credit Card Transactions .......................................................................... 36 Payment Revocation (full or partial) .......................................................................................... 37 Creation of Demand for Refund ................................................................................................. 39

Bill Cancelation before Payment ............................................................................................... 42 Payout without a Prior Payment ................................................................................................. 43

Querying of Status of Payout without Prior Payment ................................................................ 44 Cancel Payout without a Prior Payment .................................................................................... 45

List of Payment Statuses ................................................................................................................ 45

List of Payment Systems and Groups ............................................................................................ 46 List of Additional Parameters of Payment Systems....................................................................... 47 List of Currencies ........................................................................................................................... 47 List of Error Codes ......................................................................................................................... 47

List of Reasons for Payment Failure .............................................................................................. 48 Typical Integration Scenarios ........................................................................................................ 48

Donations ................................................................................................................................... 48

Simplest Merchant ..................................................................................................................... 49 Usual Merchant .......................................................................................................................... 49 Special Merchant........................................................................................................................ 49

Payment Registry Format............................................................................................................... 51

3

Version History

version

date

author

object of

changes changes

0.1.20090608

08.06.2009

A.Churyumov

documentation Initial revision

0.1.20090609

09.06.2009

A.Churyumov

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

0.1.20090611

11.06.2009

A.Churyumov

documentation Clarified Paybox’s behavior when calling Check URL Result

URL

0.1.20090618

18.06.2009

A.Churyumov

documentation

functionality

Added references to lists of payment systems and currencies.

Clarified Paybox’s handling of temporary failures of Check

URL.

Clarified the procedure of customer redirect after payment

was rejected by merchant.

Clarified Paybox’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.

0.1.20090701

01.07.2009

A.Churyumov

documentation

functionality

Added the list of member payment systems in the response to

payment system list request

0.1.20090716

16.07.2009

A.Redozubov

functionality Added paying wait time in answer on check

0.1.20090720

20.07.2009

A.Redozubov

documentation Deleted comment about not full protocol realization in Paybox

in request methods in Failure URL and Success URL

0.1.20090810

10.08.2009

A.Redozubov

documentation

functionality

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.

0.1.20090817

17.08.2009

A.Churyumov

documentation Clarifications about Paybox’s behavior for

pg_redirect_url_type=”need data”.

0.1.20090827

27.08.2009

A.Churyumov

functionality Changed reply format for check URL invocation: added

“rejected” status, renamed “pg_error_description” to

“pg_description”, changed the reaction for “error” status.

0.1.20090903

03.09.2009

functionality Changed Check URL invocation format: removed

pg_net_amount

4

S.Predein

0.1.20091026

26.10.2009

A.Churyumov

documentation Refined the requirements for amounts format, refined payment

system list.

1.0.20091029

29.10.2009

A.Churyumov

documentation

functionality

Removed notes about missing functionality. Changed version

number.

1.1.20091112

12.11.2009

A.Churyumov

A.Redozubov

functionality

documentation

Added Refund URL.

Cleared descriptions of requests and responses (pg_salt and

pg_sig).

Corrected name of Beeline payment system.

1.2.20091211

11.12.2009

I.Bakulin

functionality

Added daily sends of payment registries. Corrected the name

of “Credit Cards” payment system. Added TRANSCRED,

COMEPAY, and WEBMONEYRBANK payment systems.

1.2.20091222

22.12.2009

A.Tolmachev

functionality If Paybox is unable to identify the merchant, and therefore

does not know his secret_key and cannot sign the response

message, it returns error 101.

1.3.20100212

12.02.2010

I.Bakulin

functionality Added information about partial refunds.

1.3.20100226

26.02.2010

I.Bakulin

functionality If some data is required to pay using chosen payment system,

this data is passed in gate’s reply.

1.3.20100309

09.03.2010

A.Tolmachev

functionality Added field pg_payment_scenario in PS list.

1.3.20100408

08.04.2010

A.Tolmachev

documentation Added the list of error codes.

1.4.20100415

15.04.2010

I.Bakulin

functionality Added new mandatory field “pg_user_ip”.

1.5.20100713

13.07.2010

I.Bakulin

functionality Added API call for bill cancelation.

1.5.20100726

26.07.2010

A.Tolmachev

functionality Added restriction for the value of pg_lifetime parameter.

1.5.20100830

30.08.2010

A.Churyumov

documentation Updated list of payment systems and details about bill

cancellation by different PSs. Added info about

pg_description field max length.

1.6.20101015

15.10.2010

A.Tolmachev

functionality Changed Result URL invocation format: added

pg_user_phone.

1.6.20101020

20.10.2010

A.Tolmachev

functionality Added restriction for the minimum value of pg_lifetime

parameter.

1.6.20101110

10.11.2010

A.Tolmachev

functionality Added merchant setting site_url.

5

1.6.20101126

26.11.2010

I.Bakulin

functionality Added pg_accepted_payment_systems field.

1.6.20110210

10.02.2011

A.Churyumov

functionality

documentation

Added ability to refund partial amounts.

Added link to signature debugging page.

1.6.20110525

25.05.2011

A.Churyumov

functionality

documentation

Added refund details to refund notification. Added more

payment systems.

1.6.20110701

01.07.2011

D.Karmichkin

functionality

documentation

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_email field in payment initialization

request.

1.6.20110721

21.07.2011

D.Karmichkin

functionality

Added postponed payment functionality.

1.6.20110825

25.08.2011

A.Churyumov

functionality

Added ability to set language of payment pages.

1.7.20111216

16.12.2011

D.Karmichkin

functionality

Types of operations added to the registry.

Added payment systems.

1.7.20120228

28.02.2012

D.Karmichkin

functionality

Added testing mode

1.7.20120321

21.03.2012

D.Karmichkin

functionality Added pg_card_brand in Result URL call.

Registry format extended by adding fields that better describe

the bill.

1.7.20120425

25.04.2012

D.Karmichkin

functionality

documentation

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.

1.7.20120614

14.06.2012

D.Karmichkin

functionality

Now sending failure reason with information about

unsuccessful payment.

Added per-transaction setting of Site URL.

1.7.20120815

15.08.2012

D.Karmichkin

functionality

documentation

Added pg_auth_code parameter for bank card payments.

Added ability to query payment status by pg_order_id.

Reordered payment system list.

1.7.20130222

22.02.2013

A.Lashnev

functionality

Added pg_card_pan parameter for bank card payments.

Added ability to create payouts without a previous payment.

1.8.20130517

17.05.2013

A.Churyumov

functionality

Added ability to query status of payout without a previous

payment.

1.8.20130920 functionality Added ability to process recurrent payment.

6

D.Karmichkin Expanded functionality when working GDS Amadeus.

Expanded the list of payment systems.

Added a request to cancel payout without a previous payment.

Expanded catalog of reasons for refusal.

2.0 26.03.2014

D.Karmichkin

Qiwi on protocol QIWIREST

Protocol TINKOFFBACKCARD

Long recording on RUSSIANSTANDARD

Display the long record transaction in the administrative panel

Payboxa

Internal optimization for working with bens

Opportunity to cancel the transaction from the administrative

panel Payboxa

3.0 07.07.2014

A. Lashnev

functionality 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.

3.1 23.09.2014

A. Lashnev

functionality Added buttons send refund/reverse result to merchant in

admin.

Maestro validation cards with 19 number cards.

New payment system QBANK

3.1 06.11.2014

A. Lashnev

functionality 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.

3.2 11.11.2014

T. Muradyan

functionality,

new payment

systems

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.

3.3 12.12.2014

T. Muradyan

functionality,

new payment

systems

New PS UNISTREAM, SBRF

3.4 24.02.2015 functionality 1. The ability to customize each store and Gate own sms and

7

email templates

2. Hashing card number now given to store the query result

3.5 19.05.2015 functionality 1. The ability to create fraud filters by customer data

2. The ability to pay by JSB card

3. The ability don’t create sms and email notification to

customer (pg_need_phone_notification and

pg_need_email_notification)

4. Add parameters pg_user_contact_email,

pg_need_phone_notification and pg_need_email_notification

in result request

5. Accelerate searching transaction

6. Deleted pg_description in result request

3.5 09.07.2015 Payment

systems

1.Renamed PS SBRF as SBRFOFFLINE

2.Added new PS SBRF

3.5 22.07.2015 Payment

systems

Added new PS

1. MININTERNETBANK

2. OCEANINTERNETBANK

3.5 02.10.2015 Payment

systems

Added new PS QIWIACTIVATION

8

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 paybox.kz.

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. paybox.kz 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 Paybox

Exchange of information between merchant and Paybox 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 Paybox and merchant: names of all

parameters that concern interaction between Paybox 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 Paybox 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 Paybox.

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 http://domain.com/path/to/script.php

<?xml version="1.0" encoding="utf-8"?>

<request>

<pg_salt>9imM909TH820jwk387</pg_salt>

9

<pg_t_param>value3</pg_t_param>

<pg_a_param>value1</pg_a_param>

<pg_z_param>

<pg_q_subparam>subvalue2</pg_q_subparam>

<pg_m_subparam>subvalue1</pg_m_subparam>

</pg_z_param>

<pg_b_param>value2</pg_b_param>

<pg_sig>a8a4d5a9188f24038a14a4d65c387bf7</pg_sig>

</request>

In this example pg_sig is calculated by the formula:

pg_sig = md5(‘script.php’ + ‘;’+ pg_a_param + ‘;’ + pg_b_param + ‘;’ +

pg_salt + ‘;’+ pg_t_param + ‘;’ + pg_m_subparam + ‘;’+ pg_q_subparam +

‘;’+ secret_key);

that is

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 Paybox 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

https://www.paybox.kz/admin/sig_debug_helper.php in merchant control panel.

Methods of Direct Interaction Between Merchant and Paybox Three methods of a direct information transfer between merchant and Paybox 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:

https://www.paybox.kz/script.php?param_1=val1&param_2[subparam_1]=val2&

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>

https://www.platron.ru/admin/sig_debug_helper.php

1

0

<pg_param1>value1</pg_param1>



</request>

Irrespective of request method (GET, POST or XML) the response is always in XML format:


<response>

<pg_status>ok</pg_status>




</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 Paybox and Merchant through Customer’s Browser Paybox 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 Paybox 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.

1

1

Automatic Transfer of Information

Automatic passing of customer and information between Paybox and merchant is possible by the

following means:

1. 302 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:

<html>

<body onload=”document.forms[0].submit()”>

<form method=”POST” action=”https://www.paybox.kz/payment.php”>

<input type=”hidden” name=”pg_param1” value=”value1” />




</form>

</body>

</html>

Merchant Settings

In order to start accepting payments it is necessary to edit the following settings of the merchant

account at paybox.kz:

Name of the

merchant

Name of the merchant, will be displayed at paybox.kz pages while guiding

the customer through the payment process

Logo of the

merchant

Logo of the merchant, will be displayed at paybox.kz pages while guiding

the customer through the payment process

Data transfer

method between

merchant and

Paybox (Request

method)

This parameter sets the data transfer method only for direct requests of

Paybox 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 Paybox”

Check URL 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.

Result URL URL of script on the merchant site where result of payment is directed. If

Result URL is not defined, it is not requested.

Refund URL URL of script on the merchant site for sending notifications about refunds. If

Refund URL is not defined, it is not requested.

Capture URL 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.

Success URL URL of script on the merchant site, where buyer is directed in case of

successful payment.

Success URL GET – button, submitted with GET method.

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

1

2

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 paybox.kz 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.

Failure URL URL of script on the merchant site, where buyer is directed in case of

unsuccessful payment. May be equal to Success URL.

Failure URL

Method

GET – button, submitted by GET method.

POST – button, submitted by POST method.


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 paybox.kz 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


State URL URL of script on the merchant site, where buyer is directed to wait for a

response from the payment system.

State URL Method GET – button, submitted by GET method.



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 paybox.kz 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


Site URL 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).

Take overpayment Always when possible Paybox 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.

Send sms to

customer

This parameter shows if don’t need to send sms to customer about

transaction process (if service is allowed). Default – send.

Send email to

customer

This parameter shows if don’t need to send email to customer about

transaction process. Default – send.

Payment password

(secret_key)

Used to protect the data given by Paybox to the merchant and by the

merchant to Paybox.

1

3

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 Paybox

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 Paybox site.

2. transfer all payment details directly to Paybox, 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)

Default

value Description

pg_merchant_id Merchant identificator in Paybox. Given at signup.

pg_order_id 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 From the

merchant

settings

Check URL

(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.

pg_result_url From the

merchant

settings

Result URL

(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 Paybox

does not notify the merchant about payment result.

pg_refund_url From the

merchant

settings

Refund

URL


refunds initiated on Paybox 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

Paybox does not notify the merchant about refunds.

pg_capture_url From the

merchant


captures performed on previously authorized

1

4

settings

Capture

URL

transactions. The URL is called just after capture

command is sent to the acquiring bank. If the parameter



Paybox does not notify the merchant about captures.

pg_request_method From the

merchant

settings

Request

Method

(string[4]) GET, POST or XML – method of calling

Check URL, Result URL, Refund URL, and Capture

URL scripts.

pg_success_url From the

merchant

settings

Success

URL

(string[256]) URL to direct user to in case of successful

payment (only for online systems)

pg_failure_url From the

merchant

settings

Failure

URL

(string[256]) URL to direct user to in case of

unsuccessful payment (only for online systems)

pg_success_url_method From the

merchant

settings

Success

URL

Method

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 paybox.kz

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.






If either GET or POST method is chosen, the page

informing of unsuccessful payment is shown to the user

at paybox.kz site and suggests pressing a button in order

to return to the merchant site.


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

merchant

URL of script on the merchant site, where buyer is

directed to wait for a response from the payment system.

1

5

settings

State URL

Method

pg_state_url_method Method GET – button, submitted by GET method.






If either GET or POST method is chosen, the page

informing of unsuccessful payment is shown to the user

at paybox.kz site and suggests pressing a button in order

to return to the merchant site.


no page informing about unsuccessful payment is shown

to the user, and the user is immediately redirected to the

merchant.

pg_site_url From the

merchant

settings

Site URL

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).

pg_payment_system 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

paybox.kz site1.

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 Paybox 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: 604800 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_phone2 (int[14]) user’s phone number (starting from 79… in

Russia), necessary to identify the user. If it is not

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.

1

6

specified, the choice will be offered to user on

paybox.kz site.

pg_need_phone_notification 1 Parameter shows if don’t need send notification to

customer by sms. 0 – not send.

pg_user_contact_email2 (string[100]) User’s contact email. If passed, Paybox

will send transaction status updates to this email.

pg_need_phone_notification 1 Parameter shows if don’t need send notification to

customer by email. 0 – not send.

pg_user_ip2 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 Paybox

would be recorded.

pg_postpone_payment Setting this parameter to 1 instructs Paybox to create

postponed payment (instead of ordinary payment that is

to be paid immediately). Information about postponed

payment is available at

http://www.paybox.kz/info/postponed_payment. If

postponed payment is activated, the customer will be

redirected to a page informing him that we sent him an

email containing a link to be clicked in order to continue

with the payment. If pg_postpone_payment=1 then

pg_user_contact_email should be also passed, otherwise

Paybox will ask the customer to provide his email

address in order to postpone this payment.

pg_language ru Language of payment pages at www.paybox.kz 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

http://www.platron.ru/info/postponed_payment

http://www.platron.ru/

1

7

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 http://www.paybox.kz/payment.php or https://www.paybox.kz/payment.php URL

with POST or GET method. Example of a GET request:

http://www.paybox.kz/payment.php?pg_merchant_id=111&pg_amount=1000&pg_orde

r_id=123&pg_check_url=http://www.merchant.ru/check.php&pg_result_url=http:

//www.merchant.ru/result.php&pg_success_url=http://www.merchant.ru/thankyo

u.php&pg_failure_url=http://www.merchant.ru/failed.php&pg_description=Tick

et+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.

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 paybox.kz.

Entry Point for Direct Transfer of Information from the Merchant to Paybox In order to initialize payment transaction via direct transfer of data to Paybox the merchant should

send data to the URL http://www.paybox.kz/init_payment.php.

Paybox responds with XML like:


<response>

<pg_salt>ijoi894j4ik39lo9</pg_salt>


<pg_payment_id>15826</pg_payment_id>

<pg_redirect_url>https://www.paybox.kz/payment_params.php?customer=ccaa4

1a4f425d124a23c3a53a3140bdc15826</pg_redirect_url>

<pg_redirect_url_type>need data</pg_redirect_url_type>

<pg_sig>af8e41a4f425d124a23c3a53a3140bdc17ea0</pg_sig>

</response>

Here:

pg_payment_id Unique identificator of the payment transaction within Paybox.

Used as a key for all subsequent work with the transaction.

pg_redirect_url URL for redirecting the user. May direct either to paybox.kz or

the payment system site.

pg_redirect_url_type 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 paybox.kz or at the merchant’s

site.

pg_accepted_payment_systems If pg_redirect_url_type = payment_system, contains a list of

http://www.payprocessing.ru/payment.php

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

http://www.shop.ru/failed.php

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

http://www.platron.ru/payment_params.php?customer=ccaa41a4f425d124a23c3a53a3140bdc15826%3C/pg_redirect_url

http://www.platron.ru/payment_params.php?customer=ccaa41a4f425d124a23c3a53a3140bdc15826%3C/pg_redirect_url

1

8

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_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_redirect_url>http://paybox.local:80/ps/rapida/start_payment.php?no=939

f392abc4e847ca340b237c79cd8a817837</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>13daa252681721b5f9ae176e57cc1d70</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_error_description>Empty merchant</pg_error_description>

</response>

Here:

pg_error_code Error code

pg_error_description 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 paybox.kz where the missing parameters are to be

specified by the user.

1

9

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 Paybox 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 Paybox 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 Paybox

pg_amount Amount of the bill (in pg_currency currency), is equal to

pg_amount at the moment of payment initialization

pg_currency Currency of the bill, is equal to pg_currency at the moment of

payment initialization

pg_ps_amount Amount of the bill (in pg_ps_currency) sent to the payment

system

pg_ps_full_amount Complete amount (in pg_ps_currency currency) that will be paid

by the user, including all commissions

pg_ps_currency Currency, in which the payment will be processed in the

payment system

pg_payment_system Identificator of the payment system

Merchant parameters All of the fields earlier received from the merchant that do not

have the “pg_” prefix


pg_sig Signature

Example of the gate’s GET request to the merchant:

http://store.ru/check.php?pg_salt=8765&pg_order_id=654&pg_payment_id=765432&pg_p

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=bfc5f9d23795

2f56bd05c602d287096e&uservar1=45363456

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_system>WEBMONEYR</pg_payment_system>

<pg_amount>100.00</pg_amount>

<pg_currency>RUR</pg_currency>

<pg_ps_currency>RUR</pg_ps_currency>

2

0

<pg_ps_amount>100.00</pg_ps_amount>

<pg_ps_full_amount>100.00</pg_ps_full_amount>

<uservar1>45363456</uservar1>

<pg_sig>bfc5f9d237952f56bd05c602d287096e</pg_sig>

</request>

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_timeout>300</pg_timeout>

<pg_sig>6e952f52d23770986bd05c6fc5f902db</pg_sig>

</response>

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 Paybox timeouts waiting for

merchant’s response).


<response>


<pg_status>rejected</pg_status>

<pg_description>payment expired</pg_description>

<pg_sig>d2377096e952f5286bd05c602dbfc5f9</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_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

2

1

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_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 Paybox learns from the payment system that

payment failed, Paybox requests Result URL of the merchant and sends information about payment

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 Paybox 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, Paybox 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, Paybox 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 Paybox

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

2

2

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

transaction was paid by card.

pg_auth_code Authorization code. This parameter is passed only when


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

Paybox 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_email Customer email. Send if exist

pg_need_email_notification Need customer notification by email. Send if exist

pg_user_contact_email

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_sig Signature

2

3

Example of GET request of the merchant by Paybox, when paying by usual payment system:

http://store.ru/result.php?pg_salt=0bd68e&pg_order_id=654&pg_payment_id=765432&p

g_amount=100.0000&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=2008-12-

30+23:59:30&pg_can_reject=0&pg_user_phone=79818244116&pg_need_phone_notification

=1&[email protected]&pg_need_email_notification=1&uservar1=4536

3456&pg_sig=da61f9d237952f56bd05c602d28780b3

Example of xml request (POST with XML in pg_xml parameter) of the merchant by Paybox, when

paying by usual payment system:


<request>

<pg_salt>0bd68e</pg_salt>





<pg_net_amount>100.00</pg_net_amount>




<pg_payment_system>INPLATMTS</pg_payment_system>

<pg_result>1</pg_result>

<pg_payment_date>2008-12-30 23:59:30</pg_payment_date>

<pg_can_reject>0</pg_can_reject>

<pg_user_phone>79818244116</pg_user_phone>

<pg_need_phone_notification>1</pg_need_phone_notification>

<pg_user_contact_email>[email protected]</pg_user_contact_email>

<pg_need_email_notification>1</pg_need_email_notification>


<pg_sig>da61f9d237952f56bd05c602d28780b3</pg_sig>

</request>

Example of GET request of the merchant by Paybox, when paying by card payment system:

http://store.ru/result.php?pg_salt=0bd68e&pg_order_id=654&pg_payment_id=765432&p

g_amount=100.0000&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=2008-12-

30+23: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=79818244116&pg_need_phone_notification=1&pg_user_contact_email=t

[email protected]&pg_need_email_notification=1&uservar1=45363456&pg_sig=da61f9d237952f

56bd05c602d28780b3

2

4

Example of xml request (POST with XML in pg_xml parameter) of the merchant by Paybox, when

paying by card payment system:


<request>

<pg_salt>0bd68e</pg_salt>









<pg_payment_system>RUSSIANSTANDARD</pg_payment_system>

<pg_result>1</pg_result>

<pg_payment_date>2008-12-30 23:59:30</pg_payment_date>


<pg_card_brand>CA</pg_card_brand>

<pg_card_pan>527594******4984</pg_card_pan>

<pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash>

<pg_auth_code>014318</pg_auth_code>

<pg_captured>0</pg_captured>

<pg_user_phone>79818244116</pg_user_phone>

<pg_need_phone_notification>1</pg_need_phone_notification>

<pg_user_contact_email>[email protected]</pg_user_contact_email>

<pg_need_email_notification>1</pg_need_email_notification>


<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_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>

2

5

<pg_sig>a3fc5f602d287096ed237952f56bd5fa</pg_sig>

</response>

Response parameters list:


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_sig Signature

Rejected status may be returned by the merchant only if there was pg_can_reject=1 parameter in the

inbound request from Paybox. Otherwise, disregarding the merchant’s response, the payment is

accepted.

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 Paybox

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


pg_auth_code Authorization code. This parameter is passed only when


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

Paybox will do it itself.

2

6

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_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:

https://store.ru/success.php?pg_salt=54c6a8786f19e&pg_order_id=654&pg_payment_id

=765432&uservar1=45363456&pg_card_brand=CA&pg_card_pan=527594******4984&pg_card_

hash=022380c107141f7e11f4271d7f6412a715222c32&pg_auth_code=014318&pg_auth_code=0

14318&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 Paybox directly, while Success URL is called by customer’s browser when customer is

redirected by Paybox 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. Paybox 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 Paybox or PS side, Paybox 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,

Paybox will retry the notifications within 2 hours.

Refund URL parameters:

pg_order_id Payment ID in the merchant’s system

2

7

pg_payment_id Payment ID in Paybox’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.

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_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 Paybox:

http://store.ru/refund.php?pg_salt=gw41b38vc&pg_order_id=2614&pg_payment_id=8259

41&pg_payment_system=CREDITCARD&pg_amount=100.00&pg_currency=RUR&pg_net_amount=1

00.00&pg_ps_currency=RUR&pg_ps_full_amount=100.80&pg_refund_date=2009-09-30

15:32:30&pg_sig=afaef9d237932f56bd05c602d287df3a&uservar1=45363456

Example of XML request (POST with XML in pg_xml):


<request>

<pg_salt>gw41b38vc</pg_salt>



<pg_payment_system>CREDITCARD</pg_payment_system>

http://store.ru/refund.php?pg_salt=gw41b38vc&pg_order_id=2614&pg_payment_id=825941&pg_payment_system=CREDITCARD&pg_amount=100.00&pg_currency=RUR&pg_net_amount=100.00&pg_ps_currency=RUR&pg_ps_full_amount=100.80&pg_refund_date=2009-09-30



2

8






<pg_refund_date>2009-09-30 15:32:30</pg_refund_date>


<pg_sig>afaef9d237932f56bd05c602d287df3a</pg_sig>

</request>

After receiving refund notification merchant should reply with ok status:


<response>

<pg_salt>eyhfh42za22h</pg_salt>


<pg_sig>ea362f52d23770986bd05c6fc5f9427d</pg_sig>

</response>

List of parameters of merchant response:


pg_status ok – information received

error – error in interpreting data



pg_sig signature

Notification about Capture for Credit Card Transactions

If merchant works in auth/capture mode, Paybox notifies merchant immediately after sending

capture command to acquiring bank.

Usually capture is initiated by merchant who sends capture command to Paybox (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), Paybox sends capture command

to the acquiring bank on its own.

In order to notify merchant about the performed capture, Paybox 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, Paybox 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 Paybox’s internal register

Merchant parameters All the fields previously received from the merchant that do not have “pg_”

prefix


pg_sig Signature

2

9

Example of GET request of merchant by Paybox:

http://store.ru/onCapture.php?pg_salt=gw41b38vc&pg_order_id=2614&pg_payment_id=8

25941&pg_sig=afaef9d237932f57bd05c602d287df34&uservar1=45363456

Example of XML request (POST with XML in pg_xml):


<request>

<pg_salt>gw41b38vc</pg_salt>




<pg_sig>afaef9d237932f57bd05c602d287df34</pg_sig>

</request>

After receiving capture notification merchant should reply with ok status:


<response>

<pg_salt>eyhfh42za22h</pg_salt>


<pg_sig>ea362f52d23770986bd05c6fc5f9427d</pg_sig>

</response>

List of parameters of merchant response:


pg_status ok – information received

error – error in interpreting data



pg_sig signature

Testing

All new merchants start in testing mode, then after finishing integration and submitting of Letter of

Integration (it can be printed from https://www.paybox.kz/admin/documents.php) to Paybox the

merchant is switched over to live mode by Paybox 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

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

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

https://www.platron.ru/admin/documents.php

3

0

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 Paybox administration.

The payment transaction will not change status automatic. You must go to transactions section in

paybox, 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:

5285 0000 0000 0005

4276 0000 0000 0009

5241 0000 0000 0016

5326 0000 0000 0006

4257 0000 0000 0002

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

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 http://www.paybox.kz/make_recurring_payment.php with one of the methods of direct

request (see Methods of direct interaction between merchant and Paybox). Maximum wait time is

30 seconds. List of request parameters:

Field (required fields Default value Description

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

3

1

are marked bold)

pg_merchant_id Merchant identificator in Paybox. Given at signup.

pg_order_id Payment identificator in the merchant’s internal system.

It is recommended to keep this field unique.

pg_recurring_profile The recurring profile identificator. Has been received by

the seller in creating a profile of recurrent payments.

pg_amount Start recurring

profile payment

amount value

Payment amount, in pg_currency.

pg_result_url From the

merchant

settings

Result URL


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 Paybox

does not notify the merchant about payment result.

pg_refund_url From the

merchant

settings

Refund URL


refunds initiated on Paybox or PS side. The URL is

called just after the payment is revoked. If the parameter



Paybox does not notify the merchant about refunds.

pg_request_method From the

merchant

settings

Request Method

(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.

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_sig Signature

About a result of payment Paybox 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 Paybox, or receive the actual list of available payment systems and commissions

automatically. In the latter case the merchant needs to use direct request to Paybox that is described

below.

3

2

The merchant sends request to http://www.paybox.kz/ps_list.php or

https://www.paybox.kz/ps_list.php with one of the methods of direct request (see Methods of direct

interaction between merchant and Paybox). Maximum wait time is 30 seconds. List of request

parameters:

Parameter

(required fields are

marked bold)

Default

value

Description

pg_merchant_id (string[16]) merchant identificator

pg_amount (decimal) bill amount in merchant system in pg_currency.

pg_currency RUR (string[3]) bill currency

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 testing.


pg_sig Signature

Example of GET request:

https://www.paybox.kz/ps_list.php?pg_salt=123&pg_merchant_id=456&pg_amount=800.4

5&pg_currency=RUR&pg_sig=aec5f9d237952f83bd05c602d287098d

Example of XML request (requested by POST in pg_xml parameter):


<request>


<pg_merchant_id>456</pg_merchant_id>



<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_email field for MONEYMAIL and BANKCARDPRU that holds the email-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 Paybox will request the field from the buyer at paybox.kz.

Example of response:


<response>



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

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

3

3

<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_name>CASH</pg_name>

<pg_description>Cash: Euroset, OSMP, Elecsnet</pg_description>

<pg_payment_scenario>offline</pg_payment_scenario>



<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_name>EUROSET</pg_sub_name>

<pg_sub_description>Euroset retail

network</pg_sub_description>



<pg_sub_name>OSMP</pg_sub_name>

<pg_sub_description>OSMP/QIWI electronic

kiosks</pg_sub_description>


</pg_sub_payment_systems>


<pg_payment_system>

<pg_name>MONEYMAIL</pg_name>

<pg_description>MoneyMail system</pg_description>

<pg_payment_scenario>online</pg_payment_scenario>



<pg_required>pg_user_email</pg_required>


<pg_payment_system>

<pg_name>WEBMONEYRBANK</pg_name>

<pg_description>WebMoney</pg_description>





<pg_payment_system>

<pg_name>YANDEXMONEY</pg_name>

<pg_description>Yandex.Money system</pg_description>



3

4



<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:


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 (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.

pg_additional (string[32]) optional parameter, similar pg_required

pg_sub_name (string[32]) name of payment system in a group

pg_sub_description (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_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 paybox.kz if payment system identificator

is not specified while initializing the payment.

In case of an error, an XML for the error is returned (see Methods of direct interaction between

merchant and Paybox).

Querying Payment Status The merchant can request Paybox 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 http://www.paybox.kz/get_status.php or

https://www.paybox.kz/get_status.php by one of the methods of direct request (see Methods of

direct interaction between merchant and Paybox). Maximum wait time is 30 seconds. List of request

parameters (all fields are required):

pg_merchant_id Merchant identificator

pg_payment_id

or

Payment identificator within Paybox or within

merchant’s shop. In the latter case merchant

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

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

3

5

pg_order_id must guarantee that order_ids are unique,

otherwise Paybox will return information about

the most recent order with this order_id.


pg_sig Signature


https://www.paybox.kz/get_status.php?pg_salt=9865&pg_merchant_id=82&pg_payment_i

d=765432&pg_sig=a1b7ccc945c0a60949f6bd6383f5f768

Example of XML request (by POST, in pg_xml parameter):


<request>




<pg_sig>a1b7ccc945c0a60949f6bd6383f5f768</pg_sig>

</request>

The response to the request is an XML of the following format:


<response>




<pg_transaction_status>ok</pg_transaction_status>


<pg_create_date>2009-01-12 10:22:30</pg_create_date>

<pg_result_date>2009-01-12 10:25:07</pg_result_date>

<pg_payment_system>RUSSIANSTANDARD</pg_payment_system>

<pg_card_brand>CA</pg_card_brand>

<pg_card_pan>527594******4984</pg_card_pan>

<pg_card_hash>022380c107141f7e11f4271d7f6412a715222c32</pg_card_hash>

<pg_auth_code>014318</pg_auth_code>

<pg_captured>0</pg_captured>

<pg_sig>8380d43c7719e6ce48da0c79aa7eb2ba</pg_sig>

</response>

Here:

pg_status 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.

pg_payment_id Paybox’s payment identifier.

pg_transaction_status Payment status. See List of Payment Stati

pg_can_reject 0 or 1 – payment can or cannot be canceled. 1 is possible only if payment

3

6

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.

pg_create_date Date and time of creation of payment transaction.

pg_result_date 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.

pg_revoke_date Date and time of canceling of payment. The field is filled only when

transaction status is revoked.

pg_payment_system Identificator of payment system, which the payment has been processed (or

is to be processed) through.

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 Paybox 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 when

pg_transaction_status is failed or revoked.

pg_failure_description Same as in Result URL call (see above). Passed only when

pg_transaction_status is failed or revoked.


pg_sig Signature

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 Paybox side

from 1 to 5 days.

The merchant makes request to http://www.paybox.kz/do_capture.php or

https://www.paybox.kz/do_capture.php by one of the methods of direct request (see Methods of

direct interaction between merchant and Paybox). Maximum wait time is 30 seconds. List of request

parameters:


pg_payment_id Payment identificator within Paybox

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

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

3

7

pg_long_record Long record for air ticket sales, see additional

section for details. You can get it in technical

department.


pg_sig Signature


https://www.paybox.kz/do_capture.php?pg_salt=123&pg_merchant_id=456&pg_payment_i

d=1234567&pg_sig=7f3af9d237952f56bd05c602d2879a3c

Example of XML request (by POST, in pg_xml parameter):


<request>




<pg_sig>7f3af9d237952f56bd05c602d2879a3c</pg_sig>

</request>

The response to the request is an XML of the following format:


<response>



<pg_sig>5e1af9d237952f56bd05c602d28704ac</pg_sig>

</response>

Here:

pg_status 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.


pg_sig Signature

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 paybox.kz and automatically by

requesting the scripts http://www.paybox.kz/revoke.php or https://www.paybox.kz/revoke.php.

Parameters are passed by one of the methods of direct request (see Methods of direct interaction

between merchant and Paybox). Maximum wait time is 30 seconds. List of request parameters (all

of the parameters are required):



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

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

3

8

pg_refund_amount Amount to return. If the parameter is omitted

or set to 0, full amount is returned.


pg_sig Signature

GET request example:

https://www.paybox.kz/revoke.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=12

34567&pg_refund_amount=800&pg_sig=6dd2a9d237952f56bd05c602d2872af8

XML request example (POST with pg_xml parameter):


<request>




<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_sig>48caf9d237952f56bd05c602d28762da</pg_sig>

</response>



<response>




<pg_error_description>this transaction can’t be

revoked</pg_error_description>

<pg_sig>4df0f9d237952f56bd05c602d2873ed0</pg_sig>

</response>

Here:

pg_status Result of request processing.


pg_error_description Description of error result


pg_sig Signature

3

9

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

Paybox’s script http://www.paybox.kz/create_refund_request.php or https://www.paybox.kz/

create_refund_request.php. Parameters are passed by one of the methods of direct request (see

Methods of direct interaction between merchant and Paybox). 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_comment Reason for returning the money




pg_sig Signature


http://www.paybox.kz/create_refund_request.php?pg_salt=sdasdasd&pg_merchant_id=2

43&pg_payment_id=1172121&pg_comment=Ticket+returned&pg_refund_amount=100&pg_sig=

149b5b52ab0b5ebfa9693910769bc222

Example of XML request (POST with single pg_xml parameter):


<request>

<pg_salt>sdasdasd</pg_salt>



<pg_comment>Ticket returned</pg_comment>


<pg_sig>149b5b52ab0b5ebfa9693910769bc222</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:

http://www.platron.ru/create_refund_request.php



4

0




pg_payout_system Provider used to return the money

(MOBILEPHONE_O in this case)

pg_account Customer’s mobile phone number




pg_sig Signature


http://www.paybox.kz/create_refund_request.php?pg_salt=erewrwer&pg_merchant_id=2

54&pg_payment_id=1166045&pg_payout_system=MOBILEPHONE_O&pg_account=79031067834&p

g_comment=Ticket+returned&pg_refund_amount=100&pg_sig=17afcf9e7f84a651ba29f2903f

133314



<request>

<pg_salt>erewrwer</pg_salt>




<pg_payout_system>MOBILEPHONE_O</pg_payout_system>

<pg_account>79031067834</pg_account>


<pg_sig>17afcf9e7f84a651ba29f2903f133314</pg_sig>

</request>

b. Payout through CONTACT money transfer system:





(CONTACT_O in this case)

pg_destination_code Contact destination point code

pg_fio Full name of the recipient




pg_sig Signature


4

1

http://www.paybox.local/create_refund_request.php?pg_salt=edwedwd&pg_merchant_id

=254&pg_payment_id=1166045&pg_payout_system=CONTACT_O&pg_destination_code=xxxx&p

g_fio=Радужная+Василиса+Сергеевна&pg_comment=Ticket+returned&pg_refund_amount=10

0&pg_sig=ccfe7190cd89972a17e489fda7257c41



<request>

<pg_salt>edwedwd</pg_salt>




<pg_payout_system>CONTACT_O</pg_payout_system>

<pg_destination_code>xxxx</ pg_destination_code >

<pg_fio>Радужная Василиса Сергеевна</pg_fio>


<pg_sig>ccfe7190cd89972a17e489fda7257c41</pg_sig>

</request>

c. Payout to Yandex.Money purse





(YANDEXMONEY_O in this case)

pg_destination_account Yandex.Money purse number to be recharged.

16 digits.




pg_sig Signature


https://www.paybox.kz/create_refund_request.php?pg_salt=edwedwd&pg_merchant_id=2

54&pg_payment_id=1166045&pg_payout_system=YANDEXMONEY_O&pg_destination_account=x

xxx&pg_comment=payout+reason&pg_refund_amount=100&pg_sig=6ffe7190cd89972a17e489f

da7257c82

Example of XML request (POST in parametr pg_xml):


<request>

<pg_salt>edwedwd</pg_salt>



<pg_comment>payout reason</pg_comment>

4

2

<pg_payout_system>YANDEXMONEY_O</pg_payout_system>

<pg_destination_account>xxxx</pg_destination_account>


<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 Paybox 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 http://www.paybox.kz/cancel.php or

https://www.paybox.kz/cancel.php. Parameters are passed by one of the methods of direct request

(see Methods of direct interaction between merchant and Paybox). Maximum wait time is 30

seconds. List of request parameters (all of the parameters are required):




pg_sig Signature

GET request example:

https://www.paybox.kz/cancel.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=12

34567&pg_sig=628e300c3204c8ee398d878a5109b520

XML request example (POST with pg_xml parameter):


<request>




<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:


<response>



<pg_sig>48caf9d237952f56bd05c602d28762da</pg_sig>

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

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

4

3

</response>



<response>




<pg_error_description>transaction not found</pg_error_description>

<pg_sig>ac08f9d237952f5bc4e5c602d2873481</pg_sig>

</response>

Here:

pg_status Result of request processing.


pg_error_description Description of error result


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), Paybox 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

Paybox. It can be useful if the payment was accepted through non-Paybox 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 www.azid.ru with his login and password, navigate to “Nodes” page

https://www.azid.ru/control/nodes.php and follow online instructions in order to create a “desktop

app”.

Payout POST requests must be sent to https://www.paybox.kz/create_payout.php with the following

parameters:

Parameter name Description

node_id Merchant's node id

token 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 Paybox it is

to_node_id=2,

secret_key – secret key entered by merchant when creating the node.

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:

http://www.azid.ru/

https://www.azid.ru/control/nodes.php

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

4

4

md5(node_id+”;”+to_node_id+”;”+verifier_node_id+”;”+sha1(token_for_azid))

node_id – merchant's node id

to_node_id=2 (paybox.kz)

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 Paybox which is to be used for payout. It can be

taken from control panel at https://www.paybox.kz/admin/merchants.php. 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.

Paybox's response is json with the following fields:

Field name Description

error_code 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.

payout_id 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: “12345”

}

Example of error response:

{


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, Paybox 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

https://www.paybox.kz/admin/moneyback_transactions.php 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 https://www.paybox.kz/get_payout_status.php with parameters:



token Calculated as in the previous section

https://www.platron.ru/admin/merchants.php

https://www.platron.ru/admin/moneyback_transactions.php

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

4

5

payout_id Payout ID received from request in the previous section.

Paybox's response is json with the following fields:


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:

{


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 https://www.paybox.kz/payout_status.php with the following parameters passed by

POST:



token Calculated as in the previous section

payout_id Payout ID received from request in the previous section.

Example of successful answer:

{


payout_id: “12345”

status: “revoked”

}

Example of error:

{


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

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

4

6

change to ok or failed.

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

currency

Place of payment

system commission

Electronic money 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

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,

OSMPTRAVEL,QIWI, CONTACT, EUROPLAT, SVYAZNOY)

RUR inside

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

MOBICOMTELE2

MTS, Megafon and TELE2 cell-phone bill RUR inside

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

4

7

HANDYBANK HandyBank internet bank RUR inside

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

Testing payment systems

TEST Test payment system in fictional currency. Used for debugging of

integration with Paybox testik inside

TESTCARD Test payment system in fictional currency. Used for debugging credit

card payments through Paybox testik inside

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

EPAYKZT pg_user_email User email

List of Currencies

Identificator (value of pg_currency field) Name

RUR Russian Roubles

USD US dollars

EUR Euro

KZT Kazah Tenge

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)

4

8

* To figure out the error cause, you may use this page:

https://www.paybox.kz/admin/sig_debug_helper.php.

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

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

401 The client did not confirm their phone number

Typical Integration Scenarios

Below we describe several typical integration scenarios of merchant with Paybox. 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 Paybox, where buyer chooses payment system and gives the money out. The

collected money is periodically sent to the merchant.

https://www.platron.ru/admin/sig_debug_helper.php

4

9

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 Paybox. HTML code of the

button has only the price, description of service/good and merchant identification. After being sent

to Paybox the buyer selects payment system and completes the payment. Merchant employees learn

about the payment via the merchant account at Paybox, contact the buyer and organize delivery of

good/ service.

pg_order_id Not used

Check URL Not implemented

Result URL 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 Paybox. After

going to Paybox the buyer selects a payment system and makes the payment. In the process of

payment Paybox 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 Paybox.

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 Paybox 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 Paybox to the

merchant site.

Request of payment systems list implemented

pg_order_id used

Check URL implemented

5

0

Result URL implemented

Status check implemented

Payment revocation implemented

Payment Registry Format

There is a field in Merchant parameters, which is called “Registry email”. If it is not empty, an

email with transactions registry (for the past day) will be sent to this address every day. Email is

sent at 0:10 (Moscow time) every night.

The following information is stored in email headers:

X-Merchant-ID: Assigned Merchant ID (example: 14)

X-Registry-Date: Registry date, format YYYY-MM-DD (example: 2009-12-02)

«From» contains: [email protected]

Mail subject: Paybox 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 Paybox 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: ” email headers to ensure that the registry is sent by

Paybox.

Registry example

order_id pg_payment_id op_date op_time type payment_system payment_type amount pg_commission

ps_commission to_pay currency

289 79004 02.12.09 13:32:56 pay QIWIKZ direct 0.1300 0.0003 0.0000 0.13 EUR

291 79212 02.12.09 19:39:41 pay TEST transit 10.0000 0.0000 10.00 RUR

293 79216 02.12.09 19:42:10 pay TEST transit 10.0000 0.0000 10.00 KZT 293 79216 02.12.09 19:42:10 ref TEST transit -10.0000 0.0000 -10.00 KZT

76392 78930 02.12.09 00:08:22 pay QIWIKZ direct 1076.1400 2.5951 35.5100 1073.54 KZT

76394 78932 02.12.09 00:15:02 pay QIWIKZ direct 994.2600 2.3976 32.8100 991.86 KZT

mailto:[email protected]

PayBox API · D.Karmichkin Expanded functionality when working GDS Amadeus. Expanded the list of...

Documents

Transcript of PayBox API · D.Karmichkin Expanded functionality when working GDS Amadeus. Expanded the list of...