Helpful information

Technically, acceptance of the bank cards for payment always leads to the charging of funds from the Customer account, hereinafter referred to as «payment» or «transaction». A payment may be comprised of a single operation or a chain of operations.

Terms and definitions

Customer — card holder making a purchase at the Merchant’s store.

Merchant — the trading entity that sells the goods or services through the website.

Acquiring bank (Acquirer) — the bank certified to conduct the acquiring activity. It is authorized to perform the primary processing of the bank card transactions in favor of the Merchant, being the bank’s clients.

Issuing bank (Issuer) — bank that issued the Customer's card.

IPS — international payment system.

Terminal — software tool that provides automated payment acceptance. It has a set of settings that determine the rules for making a payment.

Payment page — HTML page used by the Customer to enter payment details of a bank card.

Transaction — it is a total number of coordinated actions between the cardholder and the processing center when paying online with the card.

Operation — covers the whole set of actions that result in changing the transaction status and card account balance.
Example: refund operation; funds unblock operation; charging.

One-step payment — consists on a single stage — direct charging of the customer’s card.

Two-step payment — consists of two operations — first, blocking of funds on the account and, second, completion of authorization — charging.

Blocking (also «authorization» or «hold») — pre-reservation of funds on the Customer's card.

Charging — actual debit of funds from the Customer's account.

The two-step payment charging must be initialized by the Merchant within 7 days after successful blocking. If the completion is not initialized within the required time limit, the Issuer can automatically unblock the funds on the Customer account. After that, the completion may become unavailable.

Unblock operation (also «unblock») — operation that is the reverse of a blocking. Used as part of a two-step payment.

Refund — operation that is the reverse of a charging. It is performed after charging for single-step and two-step payments.

Recurring payment — payment by a previously added card without re-entering the bank card details initiated by the Merchant. To make recurring payments, it is necessary to obtain consent from the Customer at the first payment.
Example: monthly charge of subscription fee for online cinema; automatic replenishment of a mobile phone while reducing the balance below 100 rubles.

Recurrent payment — payment by a previously added card without re-entering the bank card details initiated by the Customer.
Example: order and pay for a taxi through the app in one click.

Chargeback — the procedure of disputing the transaction by the cardholder when the amount of payment is charged without acceptance from the recipient and returned to the cardholder. After that, the recipient takes the responsibility to prove the validity of transaction.

3-D Secure (3DS) — protocol used as an additional level of security in the Internet-payments with credit and debit cards. The basic concept of the protocol is to add the online cardholder authentication to the financial authorization process.

The procedure (location) of card data input

Besides one-step / two-step classification, additional differences occur in the payment procedure depending on where the card data is entered by the customer. In one variant, the customer enters the card data on Merchant’s website, in the other one — on Payture page.

Merchant side data input

In this case, the User stays on the Merchant website during the whole payment, entering the data of his/her payment card to make the transaction. The Merchant sends the entered data in the payment request.

Important! For the security reason the major international payment systems require the party operating the payment cards data, to meet the PCI DSS security standard. In order to confirm the compliance with this standard, the organization (Merchant) needs, as a rule, to fill in the self-evaluating questionnaire (SAQ) type D and pass its verification, the receipt of which may entail additional albeit small financial and organizational outlay.

Payture side data input

In this architecture, all required data security is provided by Payture, saving Merchant efforts and expenses related to card information protection. Customer’s card details are entered at Payture gateway side, instead of Merchant’s page:

  • On the Payture payment page — in this case the Customer is on the Merchant's website only until the moment of entering his payment card data. After payment, the Customer will be informed about the results of the transaction and returned to the Merchant's page, and notifications with the payment results will be sent to the Merchant.
  • Using the payment widget — pop-up window, integrated in your web site and appears after customer clicks on «Pay» button. PCI-compliant solution includes secure payment data and e-mail fields (data is processed by Payture in accordance with security standards).

The appearance of the payment page or widget is determined by the applied template. Standard Payture templates can be changed at the request of the Merchant. The Merchant may use one or more different templates.

Using API

The interaction between the Merchant’s solution and the Payture payment gateway is based on the request-response scheme.

Request

The request with the necessary parameters is created on the client side and sent to the gateway using the GET or POST request method via the HTTPS protocol. The type of the body of the POST request is "Content-Type: application/x-www-form-urlencoded".

Request URL:

https://{Environment}.payture.com/{Interface}/{Command}

{Environment} — software environment, provided with test and commercial access parameter
{Interface} — programming interface
{Command} — command name

Response

Payment gateway gives the results of request processing synchronously in XML format, UTF-8 encoding.

Response structure:

<{Command} Key1="Value1" Key2="Value2"/>

Payture API

Payture API interface is designed for Merchants interested in a powerful and friendly solution for automated execution of e-commerce operations. Use Payture API to link your e-commerce website with Payture Payment Gateway, to ensure reliable and secure processing of your clients’ payments.

Mandatory verification

For the Payture API, payment card data is entered directly on the Merchant's website or mobile app. So for the security reasons, international payment systems require the party operating the payment cards data to meet the PCI DSS security standards. In order to confirm the compliance with this standard, the Merchant needs, as a rule, to fill in the self-evaluating questionnaire (SAQ) type D and pass the verification procedure, which may entail additional albeit small financial and organizational expenses.

3-D Secure

To ensure additional payment security, 3-D Secure authentication mechanism is available for Merchant’s convenience. The mechanism is activated on the gateway side upon Merchant’s written request after the preliminary 3-D Secure support integration.

Please note that as soon as 3-D Secure protection is activated, the format of Pay and Block operations will be modified slightly, as described in the 3-D Secure section.

Features

PayGo through one-step payment processing
BlockBlock funds on User’s payment card as a part of the two-step payment procedure
ChargeCharge the amount blocked on the User card as a part of the two-step payment procedure
UnblockCanceling the hold of funds on the Customer's card
RefundFull or partial refund to the Customer’s card
GetStateView current status of a payment

Interaction scheme

Note that when using 3-D Secure authentication, the operation order will be modified slightly, as described in the 3-D Secure section.

https://{Environment}.payture.com/api/Pay

This Pay command is used for quick one-step payments.

As a result of the processing of the request, the specified amount will be charged from the User card. The charged amount can be fully or partially refunded to User’s card via Refund command.

Request

curl https://sandbox3.payture.com/api/Pay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Amount=12314 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
--data-urlencode "PayInfo= \
PAN=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314" \
--data-urlencode "CustomFields = \
IP=91.206.196.164; \
Description=Ticket" \

Names of parameters in the requests are case-sensitive

Parameter Description Format
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Digits without floating decimal or other points
Integer
Mandatory
PayInfo Request parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory
PaytureId Payment ID in Payture AntiFraud system String [1..50]
Optional
CustomerKey Customer ID in Payture AntiFraud system String [1..50]
Optional
CustomFields Additional transaction fields
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional

PayInfo parameter structure

PayInfo parameter example (decoded):

PAN=4111111111100031;
EMonth=12;
EYear=22;
CardHolder=Ivan Ivanov;
SecureCode=123;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314

Important! The OrderId and Amount parameters are transferred twice in one request: in the main request parameters and in the PayInfo parameter.

Parameter Description Format
PAN Card number
Digits without spaces
String [13..19]
Mandatory
EMonth Month of card expiration date
2 digits
Integer
Mandatory
EYear Year of card expiration date
Last 2 digits of the year
Integer
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit) Integer
Mandatory
SecureCode CVC2/CVV2 code
3 or 4 digits. The mandatory of sending depends on the type of payment and the configuration of the payment Terminal
Integer
Optional
CardHolder Cardholder first name and last name
Latin letters and space only
String [1..30]
Optional

Possible key structure of the CustomFields parameter

CustomFields parameter example (decoded):

IP=91.206.196.164;
Description=MyTestTransaction
Parameter Description Format
IP User IP address
IPv4 or IPv6
String
Optional
Description Additional payment description String
Optional

Response

An XML string with the Pay node

Response examples

Success: True False 3DS
<Pay OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="True" Amount="12314"/>
<Pay OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
Parameter Description Format
Success Operation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
Key Name of payment Terminal
Corresponds to the value from the request
String
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS». Corresponds to the value from the request
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if there was a redirect to another Terminal
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCode Error code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/api/Pay3DS

Pay3DS command is used to complete the payment from a card protected by 3-D Secure. Performed after the Pay request and receiving the results of 3-D Secure authentication from the Issuer.

Request

curl https://sandbox3.payture.com/api/Pay3DS \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

ParameterDescriptionFormat
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
PaResString containing 3-D Secure authentication results
Identical to response from ACS
String
Mandatory

Response

Identical to response to Pay.

https://{Environment}.payture.com/api/Block

This request blocks the specified amount of cash on User’s card. The request follows the two-step payment scheme. As a result of the processing of the request, the funds will be blocked on the User card.

The blocked funds can be changed via Charge command, or unblocked via Unblock.

Request

curl https://sandbox3.payture.com/api/Block \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Amount=12314 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
--data-urlencode "PayInfo= \
PAN=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314" \
--data-urlencode "CustomFields = \
IP=91.206.196.164; \
Product=Ticket" \

Names of parameters in the requests are case-sensitive

Parameter Description Format
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Digits without floating decimal or other points
Integer
Mandatory
PayInfo Request parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory
PaytureId Payment ID in Payture AntiFraud system String [1..50]
Optional
CustomerKey Customer ID in Payture AntiFraud system String [1..50]
Optional
CustomFields Additional transaction fields
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional

PayInfo parameter structure

PayInfo parameter example (decoded):

PAN=4111111111100031;
EMonth=12;
EYear=22;
CardHolder=Ivan Ivanov;
SecureCode=123;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314

Important! The OrderId and Amount parameters are transferred twice in one request: in the main request parameters and in the PayInfo parameter.

Parameter Description Format
PAN Card number
Digits without spaces
String [13..19]
Mandatory
EMonth Month of card expiration date
2 digits
Integer
Mandatory
EYear Year of card expiration date
Last 2 digits of the year
Integer
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit) Integer
Mandatory
SecureCode CVC2/CVV2 code
3 or 4 digits. The mandatory of sending depends on the type of payment and the configuration of the payment Terminal
Integer
Optional
CardHolder Cardholder first name and last name
Latin letters and space only
String [1..30]
Optional

Possible key structure of the CustomFields parameter

CustomFields parameter example (decoded):

IP=91.206.196.164;
Description=MyTestTransaction
Parameter Description Format
IP User IP address
IPv4 or IPv6
String
Optional
Description Additional payment description String
Optional

Response

Response examples

Success: True False 3DS
<Block OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="True" Amount="12492"/>
<Block OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Block OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="3DS" Amount="12725" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

An XML string with the Block node

Parameter Description Format
Success Operation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
Key Name of payment Terminal
Corresponds to the value from the request
String
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS». Corresponds to the value from the request
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if there was a redirect to another Terminal
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCode Error code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/api/Block3DS

Block3DS command is used to complete the blocking amount from a card protected by 3-D Secure. Block3DS request is performed to complete the payment from a card protected by 3-D Secure. Performed after the Block request and receiving the results of 3-D Secure authentication from the Issuer.

Request

curl https://sandbox3.payture.com/api/Block3DS \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

ParameterDescriptionFormat
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
PaResString containing 3-D Secure authentication results
Identical to response from ACS
String
Mandatory

Response

Identical to response to Block.

https://{Environment}.payture.com/api/Charge

This request charges User’s card for the amount of cash previously blocked by Block command. The request follows the two-step payment scheme.

As a result of the processing of the request, the amount blocked during the execution of the Block command will be charged from the User card.

Important! User’s card will only be charged if the payment status is Authorized at the moment of request execution.

Request parameters

curl https://sandbox3.payture.com/api/Charge \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

Parameter Description Format
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory
Amount Charging amount in kopecks. If the parameter isn’t specified, the operation will be done for the total sum
Digits without floating decimal or other points
Integer
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional

Response

An XML string with the Charge node

Response examples

Success: True False
<Charge Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Amount="12564"/>
<Charge Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="ORDER_NOT_FOUND"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
AmountFinal amount charged from User's card
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/api/Unblock

This request or completely removes the block of amount blocked on User’s card by earlier Block command. The request follows the two-step payment scheme.

As a result of the processing of the request the blocked amount on the User card will be voided.

Important! Funds on User’s card will only be unblocked if the payment status is Authorized at the moment of request execution.

curl https://sandbox3.payture.com/api/Unblock \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

Request

ParameterDescriptionFormat
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory

Response

An XML string with the Unblock node

Response examples

Success: True False
<Unblock Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" NewAmount="0"/>
<Unblock Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="ILLEGAL_ORDER_STATE"/>
ParameterDescriptionFormat
Success Operation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
NewAmountBlocked amount balance in kopecks, always equals "0"
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/api/Refund

This request refunds the amount charged by Pay or Charge command to User’s card. The request is used both in one-step and two-step payment schemes.

As a result of the processing of the request, the charged amount will be returned (fully or partially) to the User card.

Important! User’s card will only be charged if the payment status is Charged at the moment of request execution.

Request

curl https://sandbox3.payture.com/api/Refund \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Password=123 \
-d Amount=12314 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

Parameter Description Format
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
Password Password for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount in kopecks that is to be returned. If the parameter isn’t specified, the operation will be done for the total sum
Digits without floating decimal or other points
Integer
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional

Response

An XML string with the Refund node

Response examples

Success: True False
<Refund Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" NewAmount="0"/>
<Refund Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="PROCESSING_TIME_OUT"/>
Parameter Description Format
Success Operation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
NewAmount Charged amount balance in kopecks
Exists, if «Success=True»
Integer
Optional
ErrCode Error code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/api/GetState

The GetState command is used to get the current payment status.

Request

curl https://sandbox3.payture.com/api/GetState \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory

Response

An XML with the GetState node

Response examples

Success: True False
<GetState Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12314" RRN="003770024290"/>
<GetState Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>
ParameterDescriptionFormat
SuccessOperation success flag (obtaining the status of). Enum:
True — the order is found and the status of received
False — status request failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
ForwardedFlag of payment redirection to another Terminal Boolean
Mandatory
State Payment status. See transaction statuses
Exists, if «Success=True»
String
Optional
MerchantContract Name of payment Terminal
Corresponds to the value from the request. Exists, if «Success=True»
String [1..50]
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if «Forwarded=True»
String
Optional
AmountPayment amount in kopecks
Exists, if «Success=True»
Integer
Optional
RRN Unique transaction number assigned by the acquiring Bank (Retrieval Reference Number)
Exists, if «Success=True»
String [12]
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

Payture InPay

InPay is an easy way to accept payments without saving cards. Customer’s card details are entered at Payture gateway web page and all required data security is provided by Payture, saving Merchant efforts and expenses related to card information protection.

The Customer is on the Merchant's website only until the moment of entering his payment card data. After payment, the Customer will be informed about the results of the transaction and returned to the Merchant's page, and notifications with the payment results will be sent to the Merchant.

Payment page

The Merchant can redirect the Customer to the Payture payment page or open it in an iframe on the store page or in WebView mode for a mobile application.

The appearance of the standard payment page can be changed at the request of the Merchant. For this, the Merchant needs to prepare one or more payment page templates. General and detailed information on the redirect pages for Payture InPay is available here.

Features

The payment page supports the ability to authenticate the Customer using the 3-D Secure.

Additionally, Apple Pay, Google Play, Samsung Pay and SberPay mobile payment methods can be enabled on the payment page. For this, the Merchant is required to make minimal changes — all the necessary integrations have already been implemented on the Payture side.

Standard set of e-Commerce operations for the InPay interface

Init Initialization of a one-step or two-step payment — creation of a payment session necessary for opening a payment page
Pay Opening the payment page on the side of the Payture payment gateway
Charge Charge Customer’s card for specified amount blocked earlier
Unblock Canceling the hold of funds on the Customer's card
Refund Full or partial refund to the Customer’s card
GetState View the current payment status
https://{Environment}.payture.com/apim/Init

This is a payment initialization request on Payture side. It is executed before User is redirected to the Payture payment gateway where User’s card data will be entered. The result of the request is the creation of a payment session.

Request

curl https://sandbox3.payture.com/apim/Init \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
--data-urlencode "Data= \
SessionType=Pay; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314; \
Product=Ticket; \
Total=123.14; \
Phone=79156783333; \
Description=MyTestTransaction; \
Url=https://payture.com/result?orderid={orderid}&result={success}; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
Data Payment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

Data parameter structure

Data parameter example (decoded):

SessionType=Pay;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
Total=123.14;
Product=Ticket;
Phone=79156783333;
Description=MyTestTransaction;
Url=https://payture.com/result?orderid={orderid}&result={success};
AdditionalField1=Value1;
AdditionalField2=Value2

Url parameter example (User return address):

https://server.com/result?orderid={orderid}&result={success}

Parameters {success}, {orderid} should be in lower case.

ParameterDescriptionFormat
SessionTypePayment type. It determines the number of payment stages:
Pay — one-step payment
Block — two-step payment
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Digits without floating decimal or other points
Integer
Mandatory
UrlUser return address after payment on Payture side is made. The return address can optionally pass parameters Success and OrderId
In general, you can set up via Payture support service and not send with all requests
String
Optional
Product The name of the purchase, that will be displayed on the payment page String [1..50]
Optional
Total Order amount, that will be displayed on the payment page
Use this field if you want to change the default amount format
String [1..50]
Optional
TemplateTagName of the payment page template that will be used
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used. See more about payment page template
String [1..50]
Optional
LanguageLanguage of the payment page template that will be used
Required, if multiple languages are used for the template. If the parameter is not sent, the language named «Default» is used. See more about payment page template
String [1..50]
Optional
Phone User phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
DescriptionAdditional payment descriptionString
Optional
IP User IP address
IPv4 or IPv6
String
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Init node

Response examples

Success: True False
<Init Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Amount="12314" SessionLifeTime="60" AttemptsCount="5" SessionId="b536dfd1-15f3-d372-a96d-f715cd1a1434"/>
<Init Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="AMOUNT_ERROR"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True». Corresponds to the value from the request
Integer
Optional
SessionLifeTimeLifetime of the payment session from the moment it was received in the Init response (in minutes)
Exists, if «Success=True». By default there are 60 minutes. Can be changed through Payture support service
Integer
Optional
AttemptsCountThe number of payment attempts that the Customer will have on the payment page during the current session
Exists, if «Success=True». By default there are 5 attempts. Can be changed through Payture support service
Integer
Optional
SessionIdPayment session ID in Payture system
Exists, if «Success=True»
String [36]
Optional
ErrCode Error code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/apim/Pay

This command is used to open a secure payment page on the payment gateway side. It is executed after successful session initialization command.

The request can be sent by the GET or POST method.

Request

curl https://sandbox3.payture.com/apim/Pay \
-d SessionId=b536dfd1-15f3-d372-a96d-f715cd1a1434 \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
SessionIdPayment session ID. It exists in a response to the Init request
By default the session lifetime is 60 minutes. Can be changed through Payture support service
String
Mandatory

The result of a successful operation is the opening of the payment page on the Payture side.

When the User makes a payment from the payment page will be sent a request for charge of money (in one-step payment) or for blocking specified amount (in two-step payment) on Customer’s card.

After making the payment the User will be shown the results of the payment, and through 3 seconds he will be returned to the Merchant’s site (Url parameter in Init request).

https://{Environment}.payture.com/apim/Charge

This command charges Customer’s card for the amount of cash previously blocked. The request follows the two-step payment scheme.

As a result of the processing of the request, the amount blocked during the execution of the Pay command will be charged from the Customer’s card.

Important! User’s card will only be charged if the payment status is Authorized at the moment of request execution.

Request

curl https://sandbox3.payture.com/apim/Charge \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Password=123 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory
AmountCharging amount in kopecks. If the parameter isn’t specified, the operation will be done for the total sum
Digits without floating decimal or other points
Integer
Optional
ChequeBase64-encoded JSON data structure containing information about chequeString
Optional

Response

An XML string with the Charge node

Response examples

Success: True False
<Charge Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Amount="12314"/>
<Charge Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="ILLEGAL_ORDER_STATE"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
AmountFinal amount charged from User's card
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/apim/Unblock

This request or completely removes the block of amount blocked on User’s card. The request follows the two-step payment scheme.

As a result of the processing of the request the blocked amount on the User card will be completely voided.

Important! Funds on User’s card will only be unblocked if the payment status is Authorized at the moment of request execution.

Request

curl https://sandbox3.payture.com/apim/Unblock \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Password=123 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory

Response

An XML string with the Unblock node

Response examples

Success: True False
<Unblock Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" NewAmount="0"/>
<Unblock Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="ILLEGAL_ORDER_STATE"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
NewAmountBlocked amount balance in kopecks, always equals "0".
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/apim/Refund

This command refunds the charged amount in one-step or two-step payment schemes.

As a result of the processing of the request, the charged amount will be returned (fully or partially) to the Customer’s card.

Important! Customer’s card will only be refunded if the payment status is Charged at the moment of request execution.

Request

curl https://sandbox3.payture.com/apim/Refund \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Password=123 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
-d Amount=12314 \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory
AmountAmount in kopecks that is to be returned. If the parameter isn’t specified, the operation will be done for the total sum
Digits without floating decimal or other points
Integer
Optional
ChequeBase64-encoded JSON data structure containing information about chequeString
Optional

Response

An XML string with the Refund node

Response examples

Success: True False
<Refund Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" NewAmount="2000"/>
<Refund Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="AMOUNT_ERROR"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
NewAmountCharged amount balance in kopecks
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/apim/GetState

The GetState command is used to get the current payment status.

Request

curl https://sandbox3.payture.com/apim/GetState \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory

Response

An XML with the GetState node

Response examples

Success: True False
<GetState Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12314" RRN="003770024290"/>
<GetState Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>
ParameterDescriptionFormat
SuccessOperation success flag (obtaining the status of). Enum:
True — the order is found and the status of received
False — status request failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
ForwardedFlag of payment redirection to another Terminal Boolean
Mandatory
State Payment status. See transaction statuses
Exists, if «Success=True»
String
Optional
MerchantContract Name of payment Terminal
Corresponds to the value from the request. Exists, if «Success=True»
String [1..50]
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if «Forwarded=True»
String
Optional
AmountPayment amount in kopecks
Exists, if «Success=True»
Integer
Optional
RRN Unique transaction number assigned by the acquiring Bank (Retrieval Reference Number)
Exists, if «Success=True»
String [12]
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

Payture eWallet

The Payture eWallet interface offers a range of extra features designed to streamline User experience of e-payment systems’ returning clients. eWallet provides the Merchant with extended functionality supporting to User registration and linkage of payment cards to registered User accounts.

eWallet options

The eWallet interface supports two implementation options, depending on where the payment card data is entered.

In the second case, Merchant must meet the PCI DSS security standards. In order to confirm the compliance with this standard, the Merchant needs, as a rule, to fill in the self-evaluating questionnaire (SAQ) type D and pass the verification procedure, which may entail additional albeit small financial and organizational expenses.

If you have difficulties with PCI DSS verification, access to Payture eWallet functionality «entering card data on Merchant side» will not be available to you. In this case we recommend switching to functionality «entering card data on Payture side», which does not require PCI DSS compliance.

Payment page on Payture side

If you choose to implement «entering card data on Payture side» option, you can use the standard Payture payment page or prepare your own template. You can find information on creating such pages here. You can also download ready-to-use templates for the User redirect webpages, easily customizable to your specific needs.

The Merchant can redirect the Customer to the Payture payment page or open it in an iframe on the store page or in WebView mode for a mobile application.

Standard set of e-Commerce operations for the eWallet interface

User managementManage User accounts: register, update, check and delete
Card managementManage saved User cards: add, activate, delete and get a list of cards
InitInitialization of a one-step, two-step payment or adding a card — creation of a payment session necessary for opening a payment page or page for adding card. Only for the «on the Payture side»
Pay — on Payture sideOpening the payment page on the side of the Payture payment gateway
Pay — on Merchant sideCharge (one-step payment) or Block (two-step payment) funds on User’s payment card
Pay — recurrent paymentsPayment by a previously added card without re-entering the bank card details (recurring or recurrent payment)
ChargeCharge Customer’s card for specified amount blocked earlier
UnblockCanceling the hold of funds on the Customer's card
RefundFull or partial refund to the Customer’s card
GetStateView the current payment status

Payture eWallet offers powerful functionality for client account management. With this functionality, you can create new client accounts, modify account parameters or delete accounts.

RegisterRegistration of Users in the Payture system.
UpdateChange the parameters of User registered previously
DeleteDelete User registered previously
CheckCheck if User with set password and login exists in Payture payment system
https://{Environment}.payture.com/vwapi/Register

This request is used to register a new User in Payture payment system. To use the functionality of the eWallet interface, each User must be registered in the Payture system.

The system also supports automatic User registration during new card registration. To enable this option, please contact Payture support service.

Request

curl https://sandbox3.payture.com/vwapi/Register \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
PhoneNumber=79156783333" \

Names of parameters in the requests are case-sensitive

Parameter Description Format
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAUser parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
PhoneNumber=79156783333
Parameter Description Format
VWUserLgnUser ID in Payture system
Set by the Merchant. For example, email
String [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)
Set by the Merchant
String [1..50]
Mandatory
PhoneNumberUser phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
EmailUser email
May be transmitted if not used as VWUserLgn
String [1..50]
Optional

Response

An XML string with the Register node

Response examples

Success: True False
<Register Success="True" VWUserLgn="123@ya.ru"/>
<Register Success="False" VWUserLgn="123@ya.ru" ErrCode="DUPLICATE_USER"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Update

This request is used to edit the parameters (PhoneNumber or Email) of a registered Payture User.

Request

curl https://sandbox3.payture.com/vwapi/Update \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
PhoneNumber=79156783333" \

Names of parameters in the requests are case-sensitive

Parameter Description Format
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAUser parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
PhoneNumber=79156783333
Parameter Description Format
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
PhoneNumberUser phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
EmailUser email
May be transmitted if not used as VWUserLgn
String [1..50]
Optional

Response

An XML string with the Update node

Response examples

Success: True False
<Update Success="True" VWUserLgn="123@ya.ru"/>
<Update Success="False" VWUserLgn="123@ya.ru" ErrCode="DUPLICATE_USER"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Delete

This request deletes a registered user’s account data, as well as all cards linked to his account.

Request

curl https://sandbox3.payture.com/vwapi/Delete \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
Password=123" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAUser parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
Password=123
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory

Response

An XML string with the Delete node

Response examples

Success: True False
<Delete Success="True" VWUserLgn="123@ya.ru"/>
<Delete Success="False" VWUserLgn="" ErrCode="ACCESS_DENIED"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Check

This request is used to check the user's registration in the payment system Payture.

Request

curl https://sandbox3.payture.com/vwapi/Check \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363" \

Names of parameters in the requests are case-sensitive

Parameter Description Format
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAUser parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363
Parameter Description Format
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory

Response

Response examples

Success: True False
<Check Success="True" VWUserLgn="123@ya.ru"/>
<Check Success="False" VWUserLgn="123@ya.ru" ErrCode="USER_NOT_FOUND"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

This section describes functionality for client card management in eWallet system (linking cards to client accounts, activating cards, deleting cards and more).

Add Link a bank card to the User account
ActivateCard activation after adding it. Optional operation, used when provided by the card adding scheme
RemoveUnlink a card from the User account
GetListGet a list of User's cards
https://{Environment}.payture.com/vwapi/Add

This request is used to register a new card in Payture system.

Please note that in some cases (when this is assumed by the card adding scheme), you must not only add the card, but also activate it. Payments using a registered card are only possible after activation. As a rule, for activation a small amount is blocked and then canceled.

The card can be added not only by the Add command, but also with a payment.

Card registration can be performed at Merchant’s webpage or via Payture gateway payment form, depending on whether the Merchant is PCI DSS compliant.

https://{Environment}.payture.com/vwapi/Add

This command is used to open a secure add card page on the payment gateway side. It is executed after successful session initialization command.

Interaction scheme

Add Request

curl https://sandbox3.payture.com/vwapi/Add \
-d SessionId=b536dfd1-15f3-d372-a96d-f715cd1a1434 \

Names of parameters in the requests are case-sensitive

The request can be sent by the GET or POST method.

Parameter Description Format
SessionIdSession ID, returned in response to the Init command
By default the session lifetime is 60 minutes. Can be changed through Payture support service
String [36]
Mandatory

The result of a successful operation is the opening of the add card page on the Payture side.

After adding a card the User will be shown the results, and through 3 seconds he will be returned to the Merchant’s site (Url parameter in Init request).

This command is used to register a new payment card on Merchant’s webpage.

Interaction scheme

Note that when using 3-D Secure authentication, the operation order will be modified slightly, as described in the 3-D Secure section.

Add request

curl https://sandbox3.payture.com/vwapi/Add \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=VWMerchantside \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardNumber=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
PhoneNumber=79156783333; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATACard parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardNumber=4111111111100031;
EMonth=12;
EYear=22;
CardHolder=Ivan Ivanov;
SecureCode=123;
PhoneNumber=79156783333;
AdditionalField1=Value1;
AdditionalField2=Value2
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardNumberCard number
Digits without spaces
String [13..19]
Mandatory
EMonthMonth of card expiration date
2 digits
Integer
Mandatory
EYearYear of card expiration date
Last 2 digits of the year
Integer
Mandatory
SecureCodeCVC2/CVV2 code
3 or 4 digits. The mandatory of sending depends on the card registration scheme and the configuration of the payment Terminal
Integer
Optional
CardHolderCardholder first name and last name
Latin letters and space only
String [1..30]
Optional
PhoneNumberUser phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
EmailUser email
May be transmitted if not used as VWUserLgn
String [1..50]
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Add node

Response examples

Success: True False 3DS
<Add VWUserLgn="123@ya.ru" Success="True" CardName="521885xxxxxx5484" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475"/>
<Add VWUserLgn="123@ya.ru" Success="False" ErrCode="WRONG_CARD_INFO"/>
<Add VWUserLgn="123@ya.ru" Success="3DS" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0" CardName="521885xxxxxx5484" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
CardNameMasked card number (first 6 and last 4 digits: 123456хххххх1234)
Exists, if «Success=True» or «Success=3DS»
String [13..19]
Optional
CardIdCard ID in Payture system
Exists, if «Success=True» or «Success=3DS»
String [36]
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/AddSubmit3DS

AddSubmit3DS command is used to complete the verification process of the Customer when you add a card protected by 3-D Secure. Performed after the Add — Merchant side request and receiving the results of 3-D Secure authentication from the Issuer.

Used only when entering card data on the Merchant side.

Request

curl https://sandbox3.payture.com/vwapi/AddSubmit3DS \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d MD=9e3c39fd-c5f1-0efd-4d96-10097ea6c475 \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

ParameterDescriptionFormat
MDUnique transaction IDString
Mandatory
PaResString containing 3-D Secure authentication results
Identical to response from ACS
String
Mandatory

Response

Identical to response to Add — Merchant side request.

https://{Environment}.payture.com/vwapi/Activate

The request is used to activate the card previously registered in the system Payture and pending activation. This method is used if the add scheme is used for checking the card, which involves blocking a small amount.

When prompted, the User must input the exact amount blocked on his card. If the blocked amount is specified correctly, the card will be activated and the amount will be unblocked. If the blocked amount is specified incorrectly, the blocked amount can only be unblocked upon a separate request.

Request

curl https://sandbox3.payture.com/vwapi/Activate \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475; \
Amount=101" \

Names of parameters in the requests are case-sensitive.

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATACard parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475;
Amount=12314
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardIdCard ID in Payture system for which activation is performedString [36]
Mandatory
AmountBlocked amount on the User's card in kopecksInteger
Mandatory

Response

An XML string with Activate node

Response examples

Success: True False
<Activate Success="True" VWUserLgn="123@ya.ru" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475"/>
<Activate Success="False" VWUserLgn="123@ya.ru" ErrCode="CARD_NOT_FOUND"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
CardIdCard ID in Payture system
Exists, if «Success=True»
String [36]
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Remove

This command is used to remove the selected card (activated or non-activated) from the User’s card list.

Request

curl https://sandbox3.payture.com/vwapi/Remove \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATACard parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardIdCard ID in Payture system for which activation is performedString [36]
Mandatory

Response

An XML string with the Remove node

Response examples

Success: True False
<Remove Success="True" VWUserLgn="123@ya.ru" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475"/>
<Remove Success="False" VWUserLgn="123@ya.ru" ErrCode="WRONG_CARD_INFO"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
CardIdCard ID in Payture system
Exists, if «Success=True»
String [36]
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/GetList

This GetList command fetches the list of payment cards registered by the selected User in Payture system. GetList does not return deleted and expired cards.

The maximum number of cards in the GetList response: 20. Cards are sorted by the date of the last successful charging or blocking of funds.

Request

curl https://sandbox3.payture.com/vwapi/GetList \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAUser parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory

Response

An XML string with the GetList and the Item embedded nodes

Response examples

Success: True False
<GetList Success="True" VWUserLgn="123@ya.ru">
  <Item CardName="411111xxxxxx1112" CardId="e5dfa016-27e0-45bb-8167-44299642b529" CardHolder="Ivan Ivanov" Status="NotActive" NoCVV="false" Expired="false" ExpMonth="12" ExpYear="2022" PaymentSystem="Visa"/>
    <Param Key="ExternalWallet" Value="ApplePay" />
    <Param Key="CAVV" Value="/oasQvoGZxvwxyU5V/RYMAACAAA=" />
    <Param Key="BindingOrderId" Value="d5f8531f-308b-4470-96c9-e56be812896b" />
    <Param Key="LastSuccess" Value="2019.08.17 18:22:07" />
    <Param Key="LastSuccessOrderId" Value="4b7638ef-c1bf-4e8b-8530-9bc13825c1d8" />
  </Item>
  <Item CardName="411111xxxxxx1111" CardId="001f2def-64e9-4cef-ae02-aa2bd9508a8b" CardHolder="Ivan Ivanov" Status="IsActive" NoCVV="true" Expired="false" ExpMonth="12" ExpYear="2022" PaymentSystem="Visa">
    <Param Key="LastSuccess" Value="2019.06.24 12:42:14"/>
    <Param Key="LastSuccessOrderId" Value="4b7638ef-c1bf-4e8b-8530-9bc13825c1d8" />
    <Param Key="LastLessSecureCode:VWMerchantTest" Value="True"/>
    <Param Key="BindingOrderId" Value="a760d6a6-4c6f-4687-95c2-e1c7dcc8151f"/>
  </Item>
</GetList>
<GetList Success="False" VWUserLgn="123@ya.ru" ErrCode="WRONG_USER_PARAMS"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
ItemUser card list
Exists, if «Success=True»
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

Item node attributes

ParameterDescriptionFormat
CardNameMasked card number (first 6 and last 4 digits: 123456хххххх1234)
Exists, if «Success=True» or «Success=3DS»
String [13..19]
Mandatory
CardIdCard ID in Payture system
Exists, if «Success=True» or «Success=3DS»
String [36]
Mandatory
CardHolderCardholder first name and last name
Latin letters and space only
String [1..30]
Mandatory
StatusCurrent card status:
IsActive — card is active (payment, delete card requests are available)
NotActive — card is non-active (activate card, delete card requests are available)
NotActive3DS — card enrolled in 3-D Secure and is non-active (activate card, delete card requests are available)
String
Mandatory
NoCVVPayment without CVV2/CVC2 is possible:
true — payment is possible
false — payment impossible
Boolean
Mandatory
ExpiredThe flag of expiry of the card:
true — card has expired
false — card has not expired
Boolean
Mandatory
ExpMonth Month of card expiration date
2 digits. Can be added as agreed with Payture support service
Integer
Optional
ExpYear Year of card expiration date
4 digits. Can be added as agreed with Payture support service
Integer
Optional
PaymentSystemPayment system
Can be added as agreed with Payture support service
String [20]
Optional
ParamAdditional card parameters
Each parameter is passed in a nested Param node in the format Key={Key} Value={Value}
Object
Optional

Possible Param node attributes

ParameterDescriptionFormat
BindingOrderId Payment ID (order number) for which the card was added
Exists, if the card was added with the payment
String [1..50]
Optional
LastSuccess Date and time of the last successful charging in a one-step payment or blocking funds in a two-step payment
Exists, if the card was a successful payment
String
Optional
LastSuccessOrderId OrderId of the last successful charging in a one-step payment or blocking funds in a two-step payment
Can be added as agreed with Payture support service
String
Optional
LastLessSecureCode:VWID Terminal name and sign of success of the last payment without CVV2/CVC2 (recurring payment):
True — last recurring payment successful
False — last recurring payment unsuccessful
Exists, if the card was a recurring payment
String
Optional
ExternalWallet Card attribute:
ApplePay — Apple Pay
GooglePayToken — tokenized Google Pay card (CRYPTOGRAM_3DS)
GooglePayCard — non-tokenized Google Pay card (PAN_ONLY)
SamsungPay — Samsung Pay
Exists for cards from Apple Pay, Google Play or Samsung Pay wallets
String
Optional
CAVV Cardholder Authentication Verification Value
Exists for cards from Apple Pay, Google Play or Samsung Pay wallets
String
Optional
https://{Environment}.payture.com/vwapi/Init

This is an initialization request for adding a card or making a payment on Payture side. It is executed before User is redirected to the Payture payment gateway where User’s card data will be entered. The result of the request is the creation of a payment session.

Request

curl https://sandbox3.payture.com/vwapi/Init \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
SessionType=Pay; \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314; \
Product=Ticket; \
Total=123.14; \
Description=MyTestTransaction; \
PhoneNumber=79156783333; \
Url=https://payture.com/result?orderid={orderid}&result={success}; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATA Payment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

SessionType=Pay;
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
Product=Ticket;
Total=123.14;
Description=MyTestTransaction;
PhoneNumber=79156783333;
Url=https://payture.com/result?orderid={orderid}&result={success};
AdditionalField1=Value1;
AdditionalField2=Value2

Url parameter example (User return address):

https://server.com/result?orderid={orderid}&result={success}

Parameters {success}, {orderid} should be in lower case.

ParameterDescriptionFormat
SessionTypePayment type. It determines the number of payment stages:
Add — card registration
Pay — one-step payment
Block — two-step payment
String
Mandatory
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
OrderIdUnique payment ID in Merchant system
Mandatory, if «SessionType=Pay» or «SessionType=Block»
String [1..50]
Optional
AmountPayment amount in kopecks
Mandatory, if «SessionType=Pay» or «SessionType=Block»
Integer
Optional
UrlUser return address after payment is made. The return address can optionally pass parameters Success and OrderId
In general, you can set up via Payture support service and not send with all requests
String
Optional
CardIdID of the registered User card in the status «IsActive», which will be selected on the payment page
Exists, if «SessionType=Pay» or «SessionType=Block»
String [36]
Optional
Product The name of the purchase, that will be displayed on the payment page String [1..50]
Optional
Total Order amount, that will be displayed on the payment page
Use this field if you want to change the default amount format
String [1..50]
Optional
TemplateTagName of the payment page template that will be used
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used. See more about payment page template
String [1..50]
Optional
LanguageLanguage of the payment page template that will be used
Required, if multiple languages are used for the template. If the parameter is not sent, the language named «Default» is used. See more about payment page template
String [1..50]
Optional
PhoneNumberUser phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
EmailUser email
May be transmitted if not used as VWUserLgn
String [1..50]
Optional
DescriptionAdditional payment descriptionString
Optional
IPUser IP address
IPv4 or IPv6
String
Optional
ChequeBase64 encoded JSON structure with cheque dataString
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Init node

Response examples

Success: True False
<Init Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Amount="12314" SessionLifeTime="60" AttemptsCount="5" SessionId="b536dfd1-15f3-d372-a96d-f715cd1a1434" SessionType="Block"/>
<Init Success="False" ErrCode="ACCESS_DENIED"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderIdPayment ID in Merchant system
Exists, if «Success=True» and «SessionType=Pay» (Block). Corresponds to the value from the request
String [1..50]
Optional
AmountPayment amount in kopecks
Exists, if «Success=True». Equals to «0» (zero) if «SessionType=Add»
Integer
Optional
SessionLifeTimeLifetime of the payment session from the moment it was received in the Init response (in minutes)
Exists, if «Success=True». By default there are 60 minutes. Can be changed through Payture support service
Integer
Optional
AttemptsCountThe number of payment attempts that the Customer will have on the payment page during the current session
Exists, if «Success=True». By default there are 5 attempts. Can be changed through Payture support service
Integer
Optional
SessionIdPayment session ID in Payture system
Exists, if «Success=True»
String [36]
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Pay

This request is used to open a secure payment page on the payment gateway side. It is executed after successful session initialization command.

At the payment page User can choose a previously registered card or enter the data of a new card.

Interaction scheme

Request

curl https://sandbox3.payture.com/vwapi/Pay \
-d SessionId=b536dfd1-15f3-d372-a96d-f715cd1a1434 \

Names of parameters in the requests are case-sensitive

The request can be sent by the GET or POST method.

ParameterDescriptionFormat
SessionIdPayment session ID. It exists in a response to the Init command
By default the session lifetime is 60 minutes. Can be changed through Payture support service
String
Mandatory

The result of a successful operation is the opening of the payment page on the Payture side.

When the User makes a payment from the payment page will be sent a request for charge of money (in one-step payment) or for blocking specified amount (in two-step payment) on Customer’s card.

After making the payment the User will be shown the results of the payment, and through 3 seconds he will be returned to the Merchant’s site (Url parameter in Init request).

https://{Environment}.payture.com/vwapi/Pay

The command is used to make a payment when entering payment card data directly on the Merchant's web page or mobile app. The payment can be made in one one-step (SessionType=Pay) or in two-step (SessionType=Block).

Two payment scenarios are identified: payment with registered card and unregistered card.

Interaction scheme

Note that when using 3-D Secure authentication, the operation order will be modified slightly, as described in the 3-D Secure section.

Pay command for charging or blocking amount from a previously unregistered card. The request must pass the Customer's Bank card details.

Request

curl https://sandbox3.payture.com/vwapi/Pay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=VWMerchantside \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardId=FreePay; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314; \
CardNumber=4111111111100031; \
CardHolder=Ivan Ivanov; \
EMonth=12; \
EYear=22; \
SecureCode=123; \
PhoneNumber=79156783333; \
IP=91.206.196.164; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAPayment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=FreePay;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
CardNumber=4111111111100031;
CardHolder=Ivan Ivanov;
EMonth=12;
EYear=22;
SecureCode=123;
SessionType=Block;
PhoneNumber=79156783333;
IP=91.206.196.164;
AdditionalField1=Value1;
AdditionalField2=Value2
ПараметрDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardIdTo pay with an unregistered card, you must pass the value CardId=FreePayString [36]
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit) Integer
Mandatory
CardNumberCard number
Digits without spaces
String [13..19]
Mandatory
EMonthMonth of card expiration date
2 digits
Integer
Mandatory
EYearYear of card expiration date
Last 2 digits of the year
Integer
Mandatory
SecureCode CVC2/CVV2 code
3 or 4 digits. The mandatory of sending depends on the type of payment and the configuration of the payment Terminal
Integer
Optional
CardHolderCardholder first name and last name
Latin letters and space only
String [1..30]
Optional
SessionTypePayment type. It determines the number of payment stages:
Pay — one-step payment (default)
Block — two-step payment
String
Optional
AddCardFlag for saving a card
True — add a card. By default False
Boolean
Optional
PhoneNumberUser phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
EmailUser email
May be transmitted if not used as VWUserLgn
String [1..50]
Optional
IPUser IP address
IPv4 or IPv6
String
Optional
Cheque Base64 encoded JSON structure containing cheque data String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Pay node

Response examples

Success: True False 3DS
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12314"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
MerchantOrderIdPayment ID in Payture system
Additional payment ID assigned by the Payture system. Contains the number of the payment attempt
String [1..50]
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS». Corresponds to the value from the request
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

Pay command for charging or blocking amount from registered card. The card must be in «IsActive» status. The request must pass the ID of the previously added card — CardId.

Request

curl https://sandbox3.payture.com/vwapi/Pay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=VWMerchantside \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475; \ 
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314; \
SecureCode=123; \
IP=91.206.196.164; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAPayment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
SecureCode=123;
SessionType=Block;
IP=91.206.196.164;
AdditionalField1=Value1;
AdditionalField2=Value2
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardIdCard ID in Payture systemString [36]
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit) Integer
Mandatory
SecureCode CVC2/CVV2 code
3 or 4 digits. The mandatory of sending depends on the type of payment and the configuration of the payment Terminal
Integer
Optional
SessionTypePayment type. It determines the number of payment stages:
Pay — one-step payment (default)
Block — two-step payment
String
Optional
IPUser IP address
IPv4 or IPv6
String
Optional
Cheque Base64 encoded JSON structure containing cheque data String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Pay node

Response examples

Success: True False 3DS
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12314"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
MerchantOrderIdPayment ID in Payture system
Additional payment ID assigned by the Payture system. Contains the number of the payment attempt
String [1..50]
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS». Corresponds to the value from the request
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Pay

The command is used to make a payment on a previously registered card without the User's participation (recurring payment) or to make a one-click payment without re-entering the card details (recurrent payment). The card must be in «IsActive» status.

Payment does not require CVV2/CVC2 transmission and 3-D Secure authentication.

Recurring or recurring payments can be made either in the "On Merchant side" or "On Payture side" integration option.

Request

curl https://sandbox3.payture.com/vwapi/Pay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=VWMerchantside \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

Parameter Description Format
VWIDName of payment Terminal for recurring / recurrent payments
Issued with test/production access parameters
String
Mandatory
DATAPayment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=9e3c39fd-c5f1-0efd-4d96-10097ea6c475;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
SessionType=Block;
AdditionalField1=Value1;
AdditionalField2=Value2
Parameter Description Format
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardIdCard ID in Payture systemString [36]
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit) Integer
Mandatory
SessionTypePayment type. It determines the number of payment stages:
Pay — one-step payment (default)
Block — two-step payment
String
Optional
IPUser IP address
IPv4 or IPv6
String
Optional
Cheque Base64 encoded JSON structure containing cheque data String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Pay node

Response examples

Success: True False 3DS
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12314"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required. Authentication may be required for recurrent payments, depending on the Terminal configuration. For recurring payments, 3DS verification is not performed
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
MerchantOrderIdPayment ID in Payture system
Additional payment ID assigned by the Payture system. Contains the number of the payment attempt
String [1..50]
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS». Corresponds to the value from the request
Integer
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/PaySubmit3DS

PaySubmit3DS request is used to complete the payment from a card protected by 3-D Secure. Performed after the Pay — on Merchant side request and receiving the results of 3-D Secure authentication from the Issuer.

Used only when entering card data on the Merchant side.

Request

curl https://sandbox3.payture.com/vwapi/PaySubmit3DS \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d MD=9e3c39fd-c5f1-0efd-4d96-10097ea6c475 \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

ParameterDescriptionFormat
MDUnique transaction IDString
Mandatory
PaResString containing 3-D Secure authentication results
Identical to response from ACS
String
Mandatory

Response

Identical to response to Pay — on Merchant side request.

https://{Environment}.payture.com/vwapi/Charge

This request charges Customer’s card for the amount of cash previously blocked. The request follows the two-step payment scheme.

As a result of the processing of the request, the amount blocked during the execution of the Pay command will be charged from the Customer’s card.

Important! User’s card will only be charged if the payment status is Authorized at the moment of request execution.

Request

curl https://sandbox3.payture.com/vwapi/Charge \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
-d Password=123 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory
AmountCharging amount in kopecks. If the parameter isn’t specified, the operation will be done for the total sum
Digits without floating decimal or other points
Integer
Optional
Cheque Base64 encoded JSON structure containing cheque dataString
Optional

Response

An XML string with the Charge node

Response examples

Success: True False
<Charge Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Amount="12314"/>
<Charge Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="ILLEGAL_ORDER_STATE"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
AmountFinal amount charged from User's card
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Unblock

This request or completely removes the block of amount blocked on User’s card. The request follows the two-step payment scheme.

As a result of the processing of the request the blocked amount on the User card will be completely voided.

Important! Funds on User’s card will only be unblocked if the payment status is Authorized at the moment of request execution.

Request

curl https://sandbox3.payture.com/vwapi/Unblock \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
-d Password=123 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory

Response

An XML string with the Unblock node

Response examples

Success: True False
<Unblock Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" NewAmount="0"/>
<Unblock Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="ILLEGAL_ORDER_STATE"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
NewAmountBlocked amount balance in kopecks, always equals "0"
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Refund

This command refunds the charged amount in one-step or two-step payment schemes.

As a result of the processing of the request, the charged amount will be returned (fully or partially) to the Customer’s card.

Important! Customer’s card will only be refunded if the payment status is Charged at the moment of request execution.

Request

curl https://sandbox3.payture.com/vwapi/Refund \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=Merchant \
--data-urlencode "DATA= \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Password=123; \
Amount=12314" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
Data Refund parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
Password=123
ParameterDescriptionFormat
PasswordPassword for payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory
Amount Amount in kopecks that is to be returned. If the parameter isn’t specified, the operation will be done for the total sum
Digits without floating decimal or other points
Integer
Optional
Cheque Base64 encoded JSON structure containing cheque data String
Optional

Response

An XML string with the Refund node

Response examples

Success: True False
<Refund Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" NewAmount="7800"/>
<Refund Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" ErrCode="AMOUNT_ERROR"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
NewAmountCharged amount balance after refunding in kopecks
Exists, if «Success=True»
Integer
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/GetState

The GetState command is used to get the current payment status.

Request

curl https://sandbox3.payture.com/vwapi/GetState \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
KeyName of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderIdUnique payment ID in Merchant systemString [1..50]
Mandatory

Response

An XML with the GetState node

Response examples

Success: True False
<GetState Success="True" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12314" RRN="003770024290" VWUserLgn="123@ya.ru" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475" PANMask="521885xxxxxx5484"/>
<GetState Success="False" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>
ParameterDescriptionFormat
SuccessOperation success flag (obtaining the status of). Enum:
True — the order is found and the status of received
False — status request failed
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
ForwardedFlag of payment redirection to another Terminal Boolean
Mandatory
State Payment status. See transaction statuses
Exists, if «Success=True»
String
Optional
MerchantContract Name of payment Terminal
Corresponds to the value from the request. Exists, if «Success=True»
String [1..50]
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if «Forwarded=True»
String
Optional
AmountPayment amount in kopecks
Exists, if «Success=True»
Integer
Optional
RRN Unique transaction number assigned by the acquiring Bank (Retrieval Reference Number)
Exists, if «Success=True»
String [12]
Optional
VWUserLgnUser ID in Payture system
Exists, if «Success=True»
String [1..50]
Optional
CardIdCard ID in Payture system
Exists, if «Success=True»
String [36]
Optional
PANMaskMasked card number (first 6 and last 4 digits: 123456хххххх1234)
Exists, if «Success=True»
String [13..19]
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

3-D Secure 1.0

To ensure additional security for Customer cards, 3-D Secure authentication mechanism is available for Merchant’s convenience.

The procedure for payment and funds blocking requests for cards protected by 3-D Secure 1.0 is non-standard. Please see below for detailed description.

Procedure of 3-­D Secure authentication for customer cards

When receiving a request to make a payment or add a card, Payture gateway verifies if the card is protected by 3-D Secure authentication system.

If a customer card is protected by 3-D Secure, the value of Success attribute used in synchronous response to Block, Pay or Add commands is set to «3DS». In this case, ACSUrl, PaReq and ThreeDSKey attributes will also be added to the response.

ParameterDescriptionFormat
ACSUrlAddress of 3-D Secure authentication server
Exists, if «Success=3DS»
String
PaReq3-D Secure authentication results
Exists, if «Success=3DS»
String
ThreeDSKeyUnique transaction ID (MD)
Exists, if «Success=3DS»
String

Executing authentication procedure

Sample request form

<body onload="document.form.submit()">
    <form name="form" action="{ACSUrl}" method="post">
        <input type="hidden" name="TermUrl" value="{TermUrl}" />
        <input type="hidden" name="MD" value="{ThreeDSKey}" />
        <input type="hidden" name="PaReq" value="{PaReq}" />
    </form>
</body>

Upon receiving the response from the gateway, the Merchant redirects the User to the Issuer’s page for additional authentication, using POST request to address specified in ACSUrl attribute (corresponds to ACSUrl parameter from response to Pay or Block request). The following parameters are passed in the request:

ParameterDescriptionFormat
TermUrlMerchant's Url for receiving results and redirecting the Customer after 3-D Secure authenticationString
Mandatory
MDUnique transaction ID
Corresponds to ThreeDSKey parameter from response to Pay or Block request
String
Mandatory
PaReq3-D Secure authentication results
Corresponds to PaReq parameter from response to Pay or Block request
String
Mandatory

Getting authentication result

Return of the User by POST request to the address specified in the TermUrl parameter value. The following parameters are passed in the request body:

ParameterDescriptionFormat
MDUnique transaction ID
Corresponds to the value from the request
String
PaResString containing 3-D Secure authentication resultsString

Payment completion

Finally, in order to charge or block funds on a 3-D Secure card, the Merchant must send the authentication results received from the issuing Bank to the payment gateway. The results are passed in a Pay3DS or Block3DS request for the Payture API and in PaySubmit3DS or AddSubmit3DS for Payture eWallet.

3-D Secure 2.0

The procedure for processing requests for authentication using the 3-D Secure 2.0 Protocol differs from the first version of the 3-D Secure Protocol. The main feature of the 3-D Secure 2.0 protocol and the difference from the first version is the possibility of Frictionless authentication.

  • Frictionless Flow is a 3-D Secure authentication process without the participation of the card holder. For the Buyer, the payment process looks like a payment without 3DS, and for the Seller, the payment remains protected by 3-D Secure
  • Challenge Flow is a 3-D Secure authentication with cardholder verification. For the Merchant, the verification process is similar to 3DS 1.0.

Deciding to do Frictionless or Challenge authentication is accepted by the issuing bank based on an analysis of the transaction parameters, including information about the Buyer’s browser.

Browser parameters are collected by the Merchant and transmitted before making a payment. However, the issuer may request the ability to collect browser parameters independently. To do this, the 3-D Secure 2.0 protocol uses the 3DS Method, which allows you to open a hidden iframe in the Buyer’s browser to collect browser parameters.

Pre-authentication

Pre-authentication is performed to check the 3-D protocol version Secure and the need to use the 3DS method. For pre-authentication, use the api/PreAuth request (Payture API) or vwapi/PreAuth (Payture eWallet). A description of the methods is available in the documents 3‑D Secure 2.0 on the Merchant side (RU) and 3‑D Secure 2.0  on the template (RU).

Execution of the 3DS method

If the PreAuth response contains the ThreeDSServerTransId, ThreeDSMethodURL and ThreeDSMethodNotificationURL parameters, then it is necessary to execute the 3DS method - opening a hidden iframe in the client’s browser, with the help of which the browser data is automatically transferred to the issuing bank’s server.

Otherwise (if the PreAuth response does not contain the ThreeDSServerTransId, ThreeDSMethodURL and ThreeDSMethodNotificationURL parameters, or at least one of these parameters does not have a value), opening the hidden iframe is not required - proceed to the next step.

Example responses from the apim/PreAuth (Payture API) and vwapi/PreAuth (Payture eWallet) methods is available in the documents 3‑D Secure 2.0 on the Merchant side (RU) and 3‑D Secure 2.0  on the template (RU).

Making a payment (adding a card)

To pay or add a card, the following methods are used:

If the issuing bank has authorized the operation under the Frictionless Flow scenario, then the payment is executed without verification by the Buyer. In the response to the payment request (adding a card), “Success=True” is transmitted and there are no 3DS parameters, which indicates that funds have been debited or blocked on the Buyer’s card. The payment process is complete.

If verification of the Buyer is necessary, the operation takes place according to the Challenge Flow scenario. The further procedure differs depending on whose party processes the card data. More information is available in the documents 3‑D Secure 2.0 on the Merchant side (RU) and 3‑D Secure 2.0  on the template (RU).

Buyer Verification (Challenge Flow only)

Example HTML form

<html><head><title></title></head>
 <body onload="setTimeout(document.forms['form'].submit(), 10000)">
 <form name='form' action='{ACSUrl}' method='post'>
 <input type='hidden' name='creq' value='{CReq}'>
 <input type='hidden' name='threeDSSessionData' value='{ThreeDSSessionData}'>
 </form>
</body></html>

If authentication is required, the Seller redirects the Buyer to the issuing bank’s page. The Buyer is verified on the issuing bank's page, usually by entering an SMS code.

For redirection, a POST request is used to the address specified in the ACSUrl parameter. Passed parameters:

Parameter Description
threeDSSessionDataUnique transaction identifier
Corresponds to the ThreeDSSessionData parameter from the response to a Pay, Block, Add, MobilePay, or MobileBlock request
creqCorresponds to the CReq parameter from the response to a Pay, Block, Add, MobilePay or MobileBlock request

When performing a transaction on the Payture side after completing the verification, ACS redirects the Buyer with a POST request to the Payture return template. And from the return template, the Buyer returns to the Seller’s website (similar to the 3DS 1.0 scenario).

When performing a seller-side operation after verification is completed, ACS returns the Buyer with a POST request to the address specified in the ChallengeNotificationUrl parameter. The following parameters are passed in the request:

Parameter Description
threeDSSessionDataUnique transaction identifier
Corresponds to the parameter passed in the request
cresBase64 encoded string containing the results of 3-D Secure authentication

Completing payment (only for Challenge Flow on the Seller's side)

To complete the debiting or blocking of funds on a card protected by 3-D Secure, the Merchant must transfer the authentication results received from ACS to the payment gateway.

For the Payture API, the results are sent in a Pay3DS or Block3DS request. For Payture eWallet — in PaySubmit3DS or AddSubmit3DS. A description of the methods is available in the 3‑D Secure 2.0 on the Merchant side (RU).documentation.

Payture Widget

Payment widget is pop-up window, integrated in your web site and appears after customer clicks on «Pay» button. PCI-compliant solution includes secure payment data and e-mail fields. It is also mobile device adopted.

To make a test payment, click «Pay» button.

To test the widget, use test cards. The result for this widget is always a successful payment without 3DS.
For example, the card number 4111 1111 1111 1111. Expiry date, CVC2/CVV2 and card holder — any.
The sent cheque is not a fiscal document and serves only to demonstrate the widget.

Example of a head section on a widget page:

<head>
    <script type="text/javascript" src="path/to/widget/payture-widget.min.js" ></script>
    <link rel="stylesheet" type="text/css" href="path/to/widget/widgetStyles.css">
</head>

Example of opening a widget when you click «Pay»:

<button id="start_widget" onclick="openWidget()">Pay</button>

To install the widget on the site, the Merchant must perform the following steps:

  1. Request access to the Payture sandbox from the Payture support service.
  2. By default, the widget uses standard Payture templates. If the Merchant wants to change the appearance of the templates, you need to prepare and send to support the template of the payment form (Type=Pay) and the template with the results of the operation (Type=Return), which opens after 3DS-check. The Merchant can create his own templates from scratch or change the standard templates for the payture widget. You can get information about creating templates and examples of templates for the widget here in the section «Payture widget templates»;
  3. Include the payture-widget.min.js library on the page in the head section. Download the payture-widget.min.js library.
  4. Include styles to the widget in the head section. Download widget styles.
  5. Set the widget opening function. The necessary parameters are set in the PaytureWidget() constructor.
  6. Define an event to open the widget, for example, by clicking the «Pay» button.
  7. If necessary, set the behavior of the site depending on the success argument of the function in OnTransactionCompleted.
  8. Test the widget on a sandbox environment using test cards.
  9. Get commercial access parameters from Payture support service and switch to the production environment.

Widget opening function example:

function openWidget() {
    var widget = new PaytureWidget({
        Key : "Merchant_Widget",
        Amount : 20,
        Product : "Payment for order No. 1",
        Domain : 2,
        CustomParams : 
        {
            TemplateTag : "Default",
            Language : "ENG",
            Name : "Ivan Ivanov",
            Delivery : "Customer pickup"
        },
        ChequeParams : 
        {  
            Positions:[  
               {  
                  Quantity: 1.000,
                  Price: 10.00,
                  Tax: 2,
                  Text: "Tea"
               },
               {  
                  Quantity : 2.000,
                  Price : 5.00,
                  Tax: 2,
                  Text: "Pie"
               }
            ],
            CustomerContact : "",
            Message: "Cheque Payture"
        }, 
        OnTransactionCompleted : function(success) { 
            alert( success );  
            }
    });
}

Widget parameters for constructor PaytureWidget():

Parameter Description Format
Key Name of payment Terminal String
Mandatory
Amount Payment amount in rubles up to 2 digits after the dot Float
Mandatory
Product The name of the purchase, that will be displayed in the payment widget
Inserted into the placeholder {Product} of the widget template
String [1..50]
Optional
Domain The number indicating the gateway URL:
1 – The main address of production environment (default)
2 – Sandbox environment: https://sandbox3.payture.com
Integer
Optional
Session Payment type:
Pay – one-step payment (default)
Block – two-step payment
String
Optional
CustomParams Contains the name and language of the widget template used, as well as any additional parameters of the Merchant (for example, the name of the payer and the description of delivery): String
Optional
TemplateTag Name of the widget template that will be used
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used. See more about payment page template
Language Language of the widget
Required, if multiple languages are used for the template. If the parameter is not sent, the language named «Default» is used. See more about payment page template
ChequeParams Cheque params. Corresponds to Cheque parameter.
Below is the minimum set of parameters for the cheque:
String
Optional
Positions Cheque item list:
⦁ Text (Item name)
⦁ Quantity
⦁ Price
⦁ Tax (VAT Rate)
Attention! The sum of all Cheque items must match the Amount from the request.
For a detailed description of these options, see here
CustomerContact Phone in the format 79165554444 or Email of the User to send the cheque, where the cheque will be sent if the User does not specify the sending address in the widget
Message The subject of the message or string in the SMS message
In general, you can set up default value via Payture support service
OnTransactionCompleted A function called after a transaction completes before closing the widget.
Has one argument success — result of operation. True — successful payment, False — unsuccessful payment
Function
Optional

SDK

You can use the SDK to make it easier to integrate your payment solution into your Merchant site.

In the SDK you can find ready-made solutions for different programming languages. For use and integration into your systems, you can contact Payture Payture support.

Node.js Node.js is a ready-made module for Node.js developers. Easy and convenient installation with npm:
npm install payture-official
Add to project:
var payture = require('payture-official');
Additional documentation on GitHub
Payture Node.js Github
C Sharp CSharpPaytureAPI — ready library available for download from NuGet. For installation it is convenient to use NuGet Manager from Visual Studio, or install via the NuGet console by command:
Install-Package CSharpPaytureAPI
Add to project:
using CSharpPayture;
Additional documentation on GitHub
Payture CSharp Github
Golang Go is a compiled multithreaded programming language developed by Google.
Add to project:
Go Get "github.com/Payture/Go-Payture-official/payture"
Additional documentation on GitHub
Payture Golang Github
Python A ready-made solution for Python developers.
Install:
pip install payture
Add to Project:
import payture
Additional documentation on GitHub
Payture Python Github

Modules

To facilitate the integration of the payment solution on the store website, you can use ready-made payment modules.

We do not support the operation of third-party applications, all updates can be viewed at the download link.

Developer Description Install
Payture 1C-Bitrix is an automated content management system. Product is intended for creation and developing of corporate projects for companies and organizations, information, news and reference portals, online-shops and for other types of websites. Bitrix
Payture Bitrix24 is a public cloud platform for managing business and communications within a company. It offers a wide range of work organization tools, including task management, project management, customer relationship management (CRM), internal communications, and more. For support, please contact the developer. Bitrix24
Simpla A program module that fully integrates online-shop with CMS Simpla. Simpla is a free online-shop management system that has the maximum functionality. Already 63054 licensed installations. Bitrix
Payture OpenCart is a free content management system, oriented on online-shop creation. Software is written in PHP language, platform can be installed on every web-server with PHP and MySQL support. This CMS is suitable for everybody who needs simple and stable online-shop engine. Great advantage of this online-shop management system is attractive interface. Opencart
Payture UberCart is a program module with open code, that fully integrates online-shop with CMS Drupal. Drupal is an online-shop management system that has the maximum functionality. It’s a free software, that is secured by GPL license and it’s being developed by programmers from all over the world. Programming language is PHP, databases are MySQL, PostgreSQL etc. Suitable for any kinds of complexity apps. Drupal
Payture Drupal Commerce is a program module with open code, that fully integrates online-shop with CMS Drupal. Drupal is an online-shop management system that has the maximum functionality. It’s a free software, that is secured by GPL license and it’s being developed by programmers from all over the world. Programming language is PHP, databases are MySQL, PostgreSQL etc. Suitable for any kinds of complexity apps. Drupal
Payture Joomla! VirtueMart is a program module, that fully integrate online-shop with CMS Joomla!. Joomla! is a content management system, written in PHP and JavaScript languages. It uses MySQL as a database. It’s a free software, distributed by GNU CPL license. CMS allows to create wonderful and dynamic sites without any kinds of deep knowledges in web-developing. Joomla
Payture Woocommerce is a program module with open code, that fully integrate online-shop with CMS WordPress. WordPress is a content management system with open code, written in PHP language. WordPress is universal and the most popular CMS in the world.It is suitable for any kinds of resources, from blogs to online-shops. The default payment currency is RUB, to add other currencies, please contact Payture Support. Wordpress
Payture Readyscript module. Readyscript has gathered the best opportunities and features existing on CMS market. The site automatically adapts, hiding or rebuilding some secondary blocks, which leads to maintaining usability of the site on screens of different sizes. This all is included into the standard design. Readyscript
VirtualityCMS VirtualityCMS will help you and your customers to always be there, get the latest offers and increase loyalty with the help of built-in marketing tools. VirtualityCMS implements a multi-currency system that allows you to download suppliers' prices in any currency, the prices will automatically be converted into your main currency. In the admin panel, prices will be indicated in the currency of the supplier, and for customers on the site in the main currency. To manage VirtualityCMS, you don't need to sit at your office or at home in front of your computer, you can manage your online store, accept orders and payments from anywhere in the world, all you need is a mobile gadget and Internet access. VirtualityCMS provides you with all modern solutions for successful website management. Module installation instructions. Integration done by a partner. For support, contact VirtualityCMS. VirtualityCMS
Webasyst Webasyst replaces many disparate services and applications and all company business processes in a single secure system. Webasyst applications solve the problems of all developing companies - from taking orders through marketplaces and analyzing the customer base (CRM) to corporate knowledge base, customer support and forecasting cash gaps. Webasyst

Pay Services

Payture lets Customers to make payments by cards that are stored in the Apple Pay, Google Pay, Samsung Pay and SberPay wallet.

Payture offers various options for integrating Apple Pay, Google Play, Samsung Pay and SberPay. Integration is possible for all interfaces: Payture API, Payture InPay and Payture eWallet, both when accepting payments on the Payture payment page, and on the Merchant's website or mobile app.

The order in which Apple Pay is integrated varies depending on the Payture programm interface used and the payment acceptance channel.

Instructions:

The order in which Google Pay is integrated varies depending on the Payture programm interface used and the payment acceptance channel.

Parameter for integration Samsung Pay

  • Public Key (issued by technical support of Payture)

The order in which Yandex Pay is integrated varies depending on the Payture programm interface used and the payment acceptance channel.

SberPay allows you to pay for purchases with one touch with cards in the Sberbank Online app

Payture lets customers to make payments by cards that are stored in the Apple Pay, Google Pay and Samsung Pay wallet. Mobile Pay provides Merchants an additional possibility of receiving payments by debit and credit cards.

https://{Environment}.payture.com/api/MobilePay

This request is used for quick one-step client payments using the Apple Pay, Google Pay, Samsung Pay mobile payment systems.

Request

curl https://sandbox3.payture.com/api/MobilePay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d PayToken={PayToken} \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
-d Checksum=true \
-d Amount=12314 \

Names of parameters in the requests are case-sensitive

Parameter Description Format
PayToken Payment data:
for Apple Pay — paymentData from PKPaymentToken encoded in Base64
for Google Pay — Token from paymentData encoded in Base64
for Samsung Pay — paymentCredential encoded in Base64
String
Mandatory
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Required for Google Pay. Amount must match the amount in the token.
For Samsung Pay and Apple Pay it is used only for «Checksum=True» (for Samsung Pay and Apple Pay the payment amount is used from the token)
Integer
Optional
SecureCode CVV2/CVC2 code
Required when paying with a non-tokenized card via Google Pay
Integer
Optional
CustomFields Additional transaction fields
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Optional
Checksum The flag used to check that the amounts in the Apple Pay or Samsung Pay tokens and the Amount parameter match up to 100 kopecks Boolean
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional

Response

Response examples

Success: True False 3DS
<Pay OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="True" Amount="12314"/>
<Pay OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

An XML string with the Pay node

Parameter Description Format
Success Operation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
Key Name of payment Terminal
Corresponds to the value from the request
String
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS»
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if there was a redirect to another Terminal
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCode Error code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/api/MobileBlock

This request blocks the specified amount on User’s card that has been added to Apple Pay, Google Pay or Samsung Pay.

Request

curl https://sandbox3.payture.com/api/MobileBlock \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d PayToken={PayToken} \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
-d Checksum=true \
-d Amount=12314 \

Names of parameters in the requests are case-sensitive

Parameter Description Format
PayToken Payment data:
for Apple Pay — paymentData from PKPaymentToken encoded in Base64
for Google Pay — Token from paymentData encoded in Base64
for Samsung Pay — paymentCredential encoded in Base64
String
Mandatory
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Required for Google Pay. Amount must match the amount in the token.
For Samsung Pay and Apple Pay it is used only for «Checksum=True» (for Samsung Pay and Apple Pay the payment amount is used from the token)
Integer
Optional
SecureCode CVV2/CVC2 code
Required when paying with a non-tokenized card via Google Pay
Integer
Optional
CustomFields Additional transaction fields
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Optional
Checksum The flag used to check that the amounts in the Apple Pay or Samsung Pay tokens and the Amount parameter match up to 100 kopecks Boolean
Optional
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional

Response

Response examples

Success: True False 3DS
<Block OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="True" Amount="12314"/>
<Block OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Block OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Key="Merchant" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

An XML string with the Block node

Parameter Description Format
Success Operation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
Key Name of payment Terminal
Corresponds to the value from the request
String
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS»
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
FinalTerminalThe final Terminal on which the payment was made
Exists, if there was a redirect to another Terminal
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCode Error code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Pay

The vwapi/Pay request with PayToken is used to make a payment using Apple Pay, Google Pay or Samsung Pay systems.

The request is used both in one-step (SessionType=Pay) and two-step (SessionType=Block) payment schemes.

Request

curl https://sandbox3.payture.com/vwapi/Pay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=VWMerchantside \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
CardId=FreePay; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314; \
PayToken={PayToken}; \
SessionType=Block; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAPayment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=FreePay;
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad;
Amount=12314;
PayToken={PayToken};
SessionType=Block;
SecureCode=123;
IP=91.206.196.164;
AdditionalField1=Value1;
AdditionalField2=Value2
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
CardIdTo pay with Apple Pay, Google Pay and Samsung Pay you must pass the value CardId=FreePayString [36]
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
For the current request, the payment amount is always used from the request (not from the token). The amount must match the value in the token
Integer
Optional
PayToken Payment data:
for Apple Pay — paymentData from PKPaymentToken encoded in Base64
for Google Pay — Token from paymentData encoded in Base64
for Samsung Pay — paymentCredential encoded in Base64
String
Mandatory
SessionTypePayment type. It determines the number of payment stages:
Pay — one-step payment (default)
Block — two-step payment
String
Optional
AddCardFlag for saving a card
True — add a card. By default False
Boolean
Optional
SecureCode CVV2/CVC2 code
Required when paying with a non-tokenized card via Google Pay
Integer
Optional
IPUser IP address
IPv4 or IPv6
String
Optional
Cheque Base64 encoded JSON structure containing cheque data String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Pay node

Response examples

Success: True False 3DS
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12314"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12314" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
MerchantOrderIdPayment ID in Payture system
Additional payment ID assigned by the Payture system. Contains the number of the payment attempt
String [1..50]
Mandatory
Amount Payment amount in kopecks
Exists, if «Success=True» or «Success=3DS». Corresponds to the value from the request
Integer
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional
https://{Environment}.payture.com/vwapi/Add

The vwapi/Add request with PayToken is used to bind a card from Apple Pay, Google Pay or Samsung Pay before making recurring payments.

Request

curl https://sandbox3.payture.com/vwapi/Add \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d VWID=VWMerchantside \
--data-urlencode "DATA= \
VWUserLgn=123@ya.ru; \
VWUserPsw=2645363; \
PayToken={PayToken}; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

ParameterDescriptionFormat
VWIDName of payment Terminal
Issued with test/production access parameters
String
Mandatory
DATAPayment parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
PayToken={PayToken};
SecureCode=123;
PhoneNumber=79156783333;
AdditionalField1=Value1;
AdditionalField2=Value2
ParameterDescriptionFormat
VWUserLgnUser ID in Payture systemString [1..50]
Mandatory
VWUserPswAdditional parameter of access to private User information (User password)String [1..50]
Mandatory
PayToken Payment data:
for Apple Pay — paymentData from PKPaymentToken encoded in Base64
for Google Pay — Token from paymentData encoded in Base64
for Samsung Pay — paymentCredential encoded in Base64
String
Mandatory
SecureCode CVV2/CVC2 code
Required when paying with a non-tokenized card via Google Pay
Integer
Optional
PhoneNumberUser phone number
Only digits. Format: [country code][operator code][subscriber number]
String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

An XML string with the Add node

Response examples

Success: True False 3DS
<Add VWUserLgn="123@ya.ru" Success="True" CardName="411111xxxxxx1112" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475"/>
<Add VWUserLgn="123@ya.ru" Success="False" ErrCode="WRONG_CARD_INFO"/>
<Add VWUserLgn="123@ya.ru" Success="3DS" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" CardName="411111xxxxxx1112" CardId="9e3c39fd-c5f1-0efd-4d96-10097ea6c475" ThreeDSVersion="1.0"/>
ParameterDescriptionFormat
SuccessOperation success flag. Enum:
True — operation succeeded
False — operation failed
3DS3-D Secure authentication required
String
Mandatory
VWUserLgnUser ID in Payture system
Corresponds to the value from the request
String [1..50]
Mandatory
CardNameMasked card number (first 6 and last 4 digits: 123456хххххх1234)
Exists, if «Success=True» or «Success=3DS»
String [13..19]
Optional
CardIdCard ID in Payture system
Exists, if «Success=True» or «Success=3DS»
String [36]
Optional
ACSUrl Address of 3-D Secure authentication server
Exists, if «Success=3DS»
String
Optional
PaReq Payment authentication request
Exists, if «Success=3DS»
String
Optional
ThreeDSKey Unique transaction ID (MD)
Exists, if «Success=3DS»
String
Optional
ThreeDSVersion Version of the 3-D Secure protocol:
1.0 — first
2.1 — second
Exists, if «Success=3DS»
String
Optional
AddInfo Additional payment parameters that can be added to the payment gateway response as agreed with Payture support service
A description of the format and possible parameters is available here
Object
Optional
ErrCodeError code. See error codes
Exists, if «Success=False»
String
Optional

Quick payment system

Quick payment system is a service of the Bank of Russia's payment system. The Payture functionality allows the User to pay for purchases using a QR code via the quick payment system. The list of participating banks is available on the website: sbp.nspk.ru/participants. Questions and answers here: sbp.nspk.ru/faq.

This section is about when payment (displaying a QR code) is made on Merchant side.

Payment procedure

Payments via the quick payment system are made only in a one-step scheme. Funds are charged from the account and to the account, even if there are no cards linked to them.

The payment procedure is as follows:

  1. The User proceeds to the payment and selects the payment using a QR code;
  2. The Merchant calls GetQRCode to get a QR code;
  3. The response contains a URL that must be encoded into a QR code (QR lifetime is 72 hours). On a mobile device, using this link it is possible to directly open the bank application (if the User has a bank application that supports payment by QR);
  4. The Merchant displays the QR code and/or link and waits for the payment result (there are two ways to get the payment result: using the standard status request (GetState) and/or in notifications from the payment gateway);
  5. The User selects the payment using a QR code in the Bank's mobile app, scans the QR code and confirms the payment;
  6. Payture sends the Merchant a notification with the payment results:
  • EnginePaySuccess — successful payment;
  • EnginePayFail — unsuccessful payment or payment time expired (72 hours).

Recommendations for using the status request

If the Merchant uses a GetState status request to get the payment result, we recommend using the following scheme:

  1. The Merchant starts requesting the status 15 seconds after the QR code is displayed:
  • for the first 30 seconds every 3 seconds;
  • for the next 120 seconds every 5 seconds;
  • further, with the increased intervals.
  1. The status request is called before the Charged or Rejected statuses are received. The order in this case can accept the following statuses:
  • Pending — waiting for payment by the User;
  • Charged — successful payment;
  • Rejected — unsuccessful payment or payment time expired (72 hours).

The GetState method is described in the section Payture API, Payture InPay and Payture eWallet.

Refund

The refund is performed using the standard Refund command (see the section Payture API, Payture InPay and Payture eWallet).

https://{Environment}.payture.com/ncapi/GetQRCode

Method for getting a QR code for payment via quick payment system.

Request

curl https://sandbox3.payture.com/ncapi/GetQRCode \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d PaymentKey=Merchant \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
-d Amount=12314 \
-d AdditionalField1=Value1 \
-d AdditionalField2=Value2 \

Names of parameters in the requests are case-sensitive.

Parameter Description Format
PaymentKey Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Digits without floating decimal or other points
Integer
Mandatory
Cheque Base64-encoded JSON data structure containing information about cheque String
Optional
Additional parameters Any additional parameters from the Merchant
There may be several additional parameters. Each parameter is passed separately

Optional

Response

JSON format.

Response examples

Success: True False
{
    "Success": true,
    "ErrCode": "NONE",
    "OrderId": "ca6db0c6-546e-4a75-a4c1-7ac7e6b428c1",
    "QRCodeId": "AD10004QCI3EQ5S19N689BOA45F54714",
    "QRCodePayload": "https://qr.nspk.ru/AD10004QCI3EQ5S19N689BOA45F54714?type=02&bank=100000000015&sum=2725&cur=RUB&crc=2D98"
}
{
    "Success": false,
    "ErrCode": "ACCESS_DENIED",
    "OrderId": "6bd5fe4b-0ee9-4f23-9f7d-36f0c5a764cb",
    "QRCodeId": null,
    "QRCodePayload": null
}
Parameter Description Format
Success Indicates whether the operation was successful. Take the values:
true — operation succeeded, QR code received
false — operation failed
Boolean
Mandatory
ErrCode Error code. See error codes String
Mandatory
OrderId Payment ID in Merchant system
Corresponds to the value from the request
String [1..50]
Mandatory
QRCodeId QR code ID in the quick payment system
Exists, if «Success=True»
String [1..32]
Mandatory
QRCodePayload URL to encode into a QR code
Exists, if «Success=True»
String [1..999]
Mandatory

P2P transfers

The functionality of P2P transfers (transfer from card to card) allows you to transfer funds from one card of the international payment systems Visa and Mastercard to another.

Technically, on the side of payment systems, the transfer scheme is implemented in two stages. The first stage is the charge of funds from the source card. The second stage is the replenishment of the receiver card. The translation interface offered by Payture allows you to implement this functionality in one step (executing the Pay method).

Payture P2P Scheme

When making a transfer from the payer (cardholder-source) will be charged a commission, which is prescribed in the contract for P2P transfer. Thus, in the amount field when making a payment, the amount to be credited to the receiving card is indicated. The commission for the transfer is deducted from the source card.

The ability to transfer from card to card is supported in interface Payture API (via API).

https://{Environment}.payture.com/api/Pay

API method for P2P transfers almost completely corresponds to api/Pay, the difference is you add a parameter CardTo (card number-receiver) in CustomFields. If you add such a parameter, the payment automatically becomes a P2P transfer.

Request

curl https://sandbox3.payture.com/api/Pay \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d Amount=12314 \
-d OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad \
--data-urlencode "PayInfo= \
PAN=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=b1d3b0d8-7d43-92d8-0cf7-ffc494c3d7ad; \
Amount=12314;" \
--data-urlencode "CustomFields= \
CardTo=4242424242424242;" \

Names of parameters in the requests are case-sensitive

Important! The OrderId and Amount parameters are transferred twice in one request: in the main request parameters and in the PayInfo parameter, after the URL Encoding.

Parameter Description Format
Key Name of payment Terminal
Issued with test/production access parameters
String
Mandatory
OrderId Unique payment ID in Merchant system String [1..50]
Mandatory
Amount Amount of payment in kopecks (or other minimum terminal currency unit)
Digits without floating decimal or other points
Integer
Mandatory
PayInfo Request parameters
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory
CustomFields Parameter for transmitting the receiver card number. May also contain additional transaction fields
URL Encoded string, containing the key pairs and their values, separated by the symbol «;» (semicolon). The keys and values are separated by the symbol «=» (equal)
String
Mandatory
PaytureId Payment ID in Payture AntiFraud system String [1..50]
Optional
CustomerKey Customer ID in Payture AntiFraud system String [1..50]
Optional

PayInfo parameter key structure

Corresponds to the same in Payture API Pay

CustomFields parameter key structure

CustomFields parameter example (decoded):

CardTo=4111111111100031;
Parameter Description Format
CardTo Card number to which the transfer will be made (receiving card)
Digits without spaces
String [13..19]
Mandatory

Response

Corresponds to the same in Payture API Pay

Online cash registers (54 Federal law)

54 Federal law establishes new rules for using cash register equipment (the “CRE”) by entities and individual entrepreneurs. Under the law, taxpayers are required to file all fiscal documents, including fiscal cash receipts and strict reporting forms, with the FTS via Internet.

To transfer information by cheque, it is necessary to convert JSON to a Base64 string and enclose it in the Cheque parameter when requesting Block / Pay / Init / Refund (partial) / Charge (partial) in any integration option with a payment gateway.

An example of a Cheque with a minimal set of parameters:

JSON Base64
{
  "Positions":[
    {
      "Quantity":1.0,
      "Price":27.25,
      "Tax":2,
      "Text":"Pie"
    }
  ],
  "CustomerContact":"user@mail.com"
}
ewogICJQb3NpdGlvbnMiOlsKICAgIHsKICAgICAgIlF1YW50aXR5IjoxLjAsCiAgICAgICJQcmljZSI6MjcuMjUsCiAgICAgICJUYXgiOjIsCiAgICAgICJUZXh0IjoiUGllIgogICAgfQogIF0sCiAgIkN1c3RvbWVyQ29udGFjdCI6InVzZXJAbWFpbC5jb20iCn0=

An example of a Cheque with the max set of parameters (FFD 1.2):

Orange Data JSON Base64

АТОЛ JSON Base64

Buhta JSON Base64

{
  "Positions":[
    {
      "Quantity":2.0,
      "Price":27.25,
      "Tax":2,
      "Text":"Pie",
      "AdditionalAttribute":"Additional Attribute of Positions",
      "AgentType":127,
      "AgentInfo":{
        "PaymentAgentOperation":"Payment Agent Op.",
        "PaymentAgentPhoneNumbers":["+79260000004"],
        "PaymentOperatorName":"ООО \"Technology\"",
        "PaymentOperatorAddress":"Москва, Zorge 29",
        "PaymentOperatorINN":"2306935781",
        "PaymentOperatorPhoneNumbers":["+79260000003"],
        "PaymentTransferOperatorPhoneNumbers":["+79260000002"]
      },
      "CustomsDeclarationNumber":"Declaration number",
      "Excise":1.00,
      "ManufacturerCountryCode":"643",
      "PaymentMethodType":3,
      "PaymentSubjectType":10,
      "ItemCode":"010460406000600021N4N57RSCBUZTQ\u001d2403004002910161218\u001d1724010191ffd0\u001d92tIAF/YVoU4roQS3M/m4z78yFq0fc/WsSmLeX5QkF/YVWwy8IMYAeiQ91Xa2z/fFSJcOkb2N+uUUmfr4n0mOX0Q==",
      "SupplierINN":"7203305114",
      "SupplierInfo":{
        "Name":"Supplier Name",
        "PhoneNumbers":["+79990000009"]
      },
      "QuantityMeasurementUnit": 10
    }
  ],
  "CustomerContact":"79991234567",
  "Payments":[
    {
      "Type":2,
      "Amount":54.50
    }
  ],
  "Message":"Cheque Payture",
  "Group":"main",
  "TemplateTag":"Default",
  "TemplateLang":"Default",
  "AdditionalMessages":[
    {
      "Key":"Name",
      "Value":"Value"
    }
  ],
  "AdditionalAttribute":"Add.Attr.cheque",
  "AdditionalUserAttribute":{
    "Name":"Name of Additional User Attribute",
    "Value":"Value of Additional User Attribute"
  },
  "AutomatNumber":"1258",
  "Customer":"Ivanov Ivan Ivanovich",
  "CustomerINN":"142702309610",
  "PaymentAgentOperation":"Payment Agent Op.",
  "PaymentAgentPhoneNumbers":["+79260000003"],
  "PaymentOperatorName":"OOO \"Chamomile\"",
  "PaymentOperatorAddress":"Moscow, Durova 10",
  "PaymentOperatorINN":"9715225506",
  "PaymentOperatorPhoneNumbers":["+79260000002","+74957870002"],
  "PaymentTransferOperatorPhoneNumbers":["+79260000001"],
  "SettlementAddress":"Moscow, Zolotaya 72",
  "SettlementPlace":"https://site.ru/",
  "SupplierPhoneNumbers":["+74957870004"]
}
ewogICJQb3NpdGlvbnMiOlsKICAgIHsKICAgICAgIlF1YW50aXR5IjoyLjAsCiAgICAgICJQcmljZSI6MjcuMjUsCiAgICAgICJUYXgiOjIsCiAgICAgICJUZXh0IjoiUGllIiwKICAgICAgIkFkZGl0aW9uYWxBdHRyaWJ1dGUiOiJBZGRpdGlvbmFsIEF0dHJpYnV0ZSBvZiBQb3NpdGlvbnMiLAogICAgICAiQWdlbnRUeXBlIjoxMjcsCiAgICAgICJBZ2VudEluZm8iOnsKICAgICAgICAiUGF5bWVudEFnZW50T3BlcmF0aW9uIjoiUGF5bWVudCBBZ2VudCBPcC4iLAogICAgICAgICJQYXltZW50QWdlbnRQaG9uZU51bWJlcnMiOlsiKzc5MjYwMDAwMDA0Il0sCiAgICAgICAgIlBheW1lbnRPcGVyYXRvck5hbWUiOiLQntCe0J4gXCJUZWNobm9sb2d5XCIiLAogICAgICAgICJQYXltZW50T3BlcmF0b3JBZGRyZXNzIjoi0JzQvtGB0LrQstCwLCBab3JnZSAyOSIsCiAgICAgICAgIlBheW1lbnRPcGVyYXRvcklOTiI6IjIzMDY5MzU3ODEiLAogICAgICAgICJQYXltZW50T3BlcmF0b3JQaG9uZU51bWJlcnMiOlsiKzc5MjYwMDAwMDAzIl0sCiAgICAgICAgIlBheW1lbnRUcmFuc2Zlck9wZXJhdG9yUGhvbmVOdW1iZXJzIjpbIis3OTI2MDAwMDAwMiJdCiAgICAgIH0sCiAgICAgICJDdXN0b21zRGVjbGFyYXRpb25OdW1iZXIiOiJEZWNsYXJhdGlvbiBudW1iZXIiLAogICAgICAiRXhjaXNlIjoxLjAwLAogICAgICAiTWFudWZhY3R1cmVyQ291bnRyeUNvZGUiOiI2NDMiLAogICAgICAiUGF5bWVudE1ldGhvZFR5cGUiOjMsCiAgICAgICJQYXltZW50U3ViamVjdFR5cGUiOjEwLAogICAgICAiSXRlbUNvZGUiOiIwMTA0NjA0MDYwMDA2MDAwMjFONE41N1JTQ0JVWlRRXHUwMDFkMjQwMzAwNDAwMjkxMDE2MTIxOFx1MDAxZDE3MjQwMTAxOTFmZmQwXHUwMDFkOTJ0SUFGL1lWb1U0cm9RUzNNL200ejc4eUZxMGZjL1dzU21MZVg1UWtGL1lWV3d5OElNWUFlaVE5MVhhMnovZkZTSmNPa2IyTit1VVVtZnI0bjBtT1gwUT09IiwKICAgICAgIlN1cHBsaWVySU5OIjoiNzIwMzMwNTExNCIsCiAgICAgICJTdXBwbGllckluZm8iOnsKICAgICAgICAiTmFtZSI6IlN1cHBsaWVyIE5hbWUiLAogICAgICAgICJQaG9uZU51bWJlcnMiOlsiKzc5OTkwMDAwMDA5Il0KICAgICAgfSwKICAgICAgIlF1YW50aXR5TWVhc3VyZW1lbnRVbml0IjogMTAKICAgIH0KICBdLAogICJDdXN0b21lckNvbnRhY3QiOiI3OTk5MTIzNDU2NyIsCiAgIlBheW1lbnRzIjpbCiAgICB7CiAgICAgICJUeXBlIjoyLAogICAgICAiQW1vdW50Ijo1NC41MAogICAgfQogIF0sCiAgIk1lc3NhZ2UiOiJDaGVxdWUgUGF5dHVyZSIsCiAgIkdyb3VwIjoibWFpbiIsCiAgIlRlbXBsYXRlVGFnIjoiRGVmYXVsdCIsCiAgIlRlbXBsYXRlTGFuZyI6IkRlZmF1bHQiLAogICJBZGRpdGlvbmFsTWVzc2FnZXMiOlsKICAgIHsKICAgICAgIktleSI6Ik5hbWUiLAogICAgICAiVmFsdWUiOiJWYWx1ZSIKICAgIH0KICBdLAogICJBZGRpdGlvbmFsQXR0cmlidXRlIjoiQWRkLkF0dHIuY2hlcXVlIiwKICAiQWRkaXRpb25hbFVzZXJBdHRyaWJ1dGUiOnsKICAgICJOYW1lIjoiTmFtZSBvZiBBZGRpdGlvbmFsIFVzZXIgQXR0cmlidXRlIiwKICAgICJWYWx1ZSI6IlZhbHVlIG9mIEFkZGl0aW9uYWwgVXNlciBBdHRyaWJ1dGUiCiAgfSwKICAiQXV0b21hdE51bWJlciI6IjEyNTgiLAogICJDdXN0b21lciI6Ikl2YW5vdiBJdmFuIEl2YW5vdmljaCIsCiAgIkN1c3RvbWVySU5OIjoiMTQyNzAyMzA5NjEwIiwKICAiUGF5bWVudEFnZW50T3BlcmF0aW9uIjoiUGF5bWVudCBBZ2VudCBPcC4iLAogICJQYXltZW50QWdlbnRQaG9uZU51bWJlcnMiOlsiKzc5MjYwMDAwMDAzIl0sCiAgIlBheW1lbnRPcGVyYXRvck5hbWUiOiJPT08gXCJDaGFtb21pbGVcIiIsCiAgIlBheW1lbnRPcGVyYXRvckFkZHJlc3MiOiJNb3Njb3csIER1cm92YSAxMCIsCiAgIlBheW1lbnRPcGVyYXRvcklOTiI6Ijk3MTUyMjU1MDYiLAogICJQYXltZW50T3BlcmF0b3JQaG9uZU51bWJlcnMiOlsiKzc5MjYwMDAwMDAyIiwiKzc0OTU3ODcwMDAyIl0sCiAgIlBheW1lbnRUcmFuc2Zlck9wZXJhdG9yUGhvbmVOdW1iZXJzIjpbIis3OTI2MDAwMDAwMSJdLAogICJTZXR0bGVtZW50QWRkcmVzcyI6Ik1vc2NvdywgWm9sb3RheWEgNzIiLAogICJTZXR0bGVtZW50UGxhY2UiOiJodHRwczovL3NpdGUucnUvIiwKICAiU3VwcGxpZXJQaG9uZU51bWJlcnMiOlsiKzc0OTU3ODcwMDA0Il0KfQ==
{
  "Positions":[
    {
      "Quantity":2.0,
      "Price":27.25,
      "Tax":2,
      "Text":"Pie",
      "AdditionalAttribute":"Additional Attribute of Positions",
      "PaymentMethodType":3,
      "PaymentSubjectType":10,
      "ItemCode":"010460406000600021N4N57RSCBUZTQ\u001d2403004002910161218\u001d1724010191ffd0\u001d92tIAF/YVoU4roQS3M/m4z78yFq0fc/WsSmLeX5QkF/YVWwy8IMYAeiQ91Xa2z/fFSJcOkb2N+uUUmfr4n0mOX0Q==",
      "SupplierINN":"7203305114",
      "SupplierInfo":{
        "Name":"Supplier Name",
        "PhoneNumbers":["+79990000009"]
      },
      "QuantityMeasurementUnit": 10
    }
  ],
  "CustomerContact":"79991234567",
  "Payments":[
    {
      "Type":2,
      "Amount":54.50
    }
  ],
  "Message":"Cheque Payture",
  "Group":"main",
  "TemplateTag":"Default",
  "TemplateLang":"Default",
  "AdditionalMessages":[
    {
      "Key":"Name",
      "Value":"Value"
    }
  ],
      "PaymentAgentOperation":"Payment Agent Op.",
      "PaymentAgentPhoneNumbers":["+79260000003"],
      "PaymentOperatorName":"ООО \"Technology\"",
      "PaymentOperatorAddress":"Москва, Zorge 29",
      "PaymentOperatorINN":"9715225506",
      "PaymentOperatorPhoneNumbers":["+79260000002"],
      "PaymentTransferOperatorPhoneNumbers":["+79260000001"],
      "SupplierPhoneNumbers":["+74957870004"]
}
ewogICJQb3NpdGlvbnMiOlsKICAgIHsKICAgICAgIlF1YW50aXR5IjoyLjAsCiAgICAgICJQcmljZSI6MjcuMjUsCiAgICAgICJUYXgiOjIsCiAgICAgICJUZXh0IjoiUGllIiwKICAgICAgIkFkZGl0aW9uYWxBdHRyaWJ1dGUiOiJBZGRpdGlvbmFsIEF0dHJpYnV0ZSBvZiBQb3NpdGlvbnMiLAogICAgICAiUGF5bWVudE1ldGhvZFR5cGUiOjMsCiAgICAgICJQYXltZW50U3ViamVjdFR5cGUiOjEwLAogICAgICAiSXRlbUNvZGUiOiIwMTA0NjA0MDYwMDA2MDAwMjFONE41N1JTQ0JVWlRRXHUwMDFkMjQwMzAwNDAwMjkxMDE2MTIxOFx1MDAxZDE3MjQwMTAxOTFmZmQwXHUwMDFkOTJ0SUFGL1lWb1U0cm9RUzNNL200ejc4eUZxMGZjL1dzU21MZVg1UWtGL1lWV3d5OElNWUFlaVE5MVhhMnovZkZTSmNPa2IyTit1VVVtZnI0bjBtT1gwUT09IiwKICAgICAgIlN1cHBsaWVySU5OIjoiNzIwMzMwNTExNCIsCiAgICAgICJTdXBwbGllckluZm8iOnsKICAgICAgICAiTmFtZSI6IlN1cHBsaWVyIE5hbWUiLAogICAgICAgICJQaG9uZU51bWJlcnMiOlsiKzc5OTkwMDAwMDA5Il0KICAgICAgfSwKICAgICAgIlF1YW50aXR5TWVhc3VyZW1lbnRVbml0IjogMTAKICAgIH0KICBdLAogICJDdXN0b21lckNvbnRhY3QiOiI3OTk5MTIzNDU2NyIsCiAgIlBheW1lbnRzIjpbCiAgICB7CiAgICAgICJUeXBlIjoyLAogICAgICAiQW1vdW50Ijo1NC41MAogICAgfQogIF0sCiAgIk1lc3NhZ2UiOiJDaGVxdWUgUGF5dHVyZSIsCiAgIkdyb3VwIjoibWFpbiIsCiAgIlRlbXBsYXRlVGFnIjoiRGVmYXVsdCIsCiAgIlRlbXBsYXRlTGFuZyI6IkRlZmF1bHQiLAogICJBZGRpdGlvbmFsTWVzc2FnZXMiOlsKICAgIHsKICAgICAgIktleSI6Ik5hbWUiLAogICAgICAiVmFsdWUiOiJWYWx1ZSIKICAgIH0KICBdLAogICAgICAiUGF5bWVudEFnZW50T3BlcmF0aW9uIjoiUGF5bWVudCBBZ2VudCBPcC4iLAogICAgICAiUGF5bWVudEFnZW50UGhvbmVOdW1iZXJzIjpbIis3OTI2MDAwMDAwMyJdLAogICAgICAiUGF5bWVudE9wZXJhdG9yTmFtZSI6ItCe0J7QniBcIlRlY2hub2xvZ3lcIiIsCiAgICAgICJQYXltZW50T3BlcmF0b3JBZGRyZXNzIjoi0JzQvtGB0LrQstCwLCBab3JnZSAyOSIsCiAgICAgICJQYXltZW50T3BlcmF0b3JJTk4iOiI5NzE1MjI1NTA2IiwKICAgICAgIlBheW1lbnRPcGVyYXRvclBob25lTnVtYmVycyI6WyIrNzkyNjAwMDAwMDIiXSwKICAgICAgIlBheW1lbnRUcmFuc2Zlck9wZXJhdG9yUGhvbmVOdW1iZXJzIjpbIis3OTI2MDAwMDAwMSJdLAogICAgICAiU3VwcGxpZXJQaG9uZU51bWJlcnMiOlsiKzc0OTU3ODcwMDA0Il0KfQ==
{
  "Positions":[
    {
      "Quantity":2.0,
      "Price":27.25,
      "Tax":2,
      "Text":"Pie",
      "PaymentMethodType":3,
      "PaymentSubjectType":10
    }
  ],
  "CustomerContact":"79991234567",
  "Payments":[
    {
      "Type":2,
      "Amount":54.50
    }
  ],
  "Message":"Cheque Payture",
  "Group":"main",
  "TemplateTag":"Default",
  "TemplateLang":"Default",
  "AdditionalMessages":[
    {
      "Key":"Name",
      "Value":"Value"
    }
  ]
}
ewogICJQb3NpdGlvbnMiOlsKICAgIHsKICAgICAgIlF1YW50aXR5IjoyLjAsCiAgICAgICJQcmljZSI6MjcuMjUsCiAgICAgICJUYXgiOjIsCiAgICAgICJUZXh0IjoiUGllIiwKICAgICAgIlBheW1lbnRNZXRob2RUeXBlIjozLAogICAgICAiUGF5bWVudFN1YmplY3RUeXBlIjoxMAogICAgfQogIF0sCiAgIkN1c3RvbWVyQ29udGFjdCI6Ijc5OTkxMjM0NTY3IiwKICAiUGF5bWVudHMiOlsKICAgIHsKICAgICAgIlR5cGUiOjIsCiAgICAgICJBbW91bnQiOjU0LjUwCiAgICB9CiAgXSwKICAiTWVzc2FnZSI6IkNoZXF1ZSBQYXl0dXJlIiwKICAiR3JvdXAiOiJtYWluIiwKICAiVGVtcGxhdGVUYWciOiJEZWZhdWx0IiwKICAiVGVtcGxhdGVMYW5nIjoiRGVmYXVsdCIsCiAgIkFkZGl0aW9uYWxNZXNzYWdlcyI6WwogICAgewogICAgICAiS2V5IjoiTmFtZSIsCiAgICAgICJWYWx1ZSI6IlZhbHVlIgogICAgfQogIF0KfQ==

Cheque parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Positions Cheque item list (1059)
Description of the Positions see below
Array of objects
Mandatory
+ + +
CustomerContact User's Email or Phone format 79995554444 or +79995554444 to send the cheque (1008) String [1..32]
Mandatory
+ + +
Payments Payments
By default, the payments is equal to the Amount of the request, the type is Non-cash
Description of the Payments see below
Array of objects
Optional
+ + +
Message The subject of the email or string in the SMS message
In general, you can set up default value via Payture support service and not send with all requests
String [1..50]
Optional
+ + +
Group The group of devices that will be used to generate the cheque
In general, you can set up default value via Payture support service and not send with all requests
String [1..32]
Optional
+ + +
TemplateTag The name of the cheque template
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used
In general, you can set up default value via Payture support service and not send with all requests
String
Optional
+ + +
TemplateLang Language of the cheque template
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used
In general, you can set up default value via Payture support service and not send with all requests
String
Optional
+ + +
AdditionalMessages Allows to add any parameters to the cheque template in the placeholder with the name of the Key
Description of the AdditionalMessages see below. Max length 1000 characters
Array of objects
Optional
+ + +
AdditionalAttribute Additional Attribute (1192) String [1..16]
Optional
+
AdditionalUserAttribute Additional User Attribute (1084)
Description of the AdditionalUserAttribute see below
Object
Optional
+
AgentType Agent Type (1057). Used only for FFD 1.05: values
A number from 1 to 127 (bit field), where the bit number indicates that the Merchant:
Bit Description
0Bank payment agent
1Bank payment subagent
2Payment agent
3Payment subagent
4Agent
5Commissioner
6Another agent

In general, you can set up default value via Payture support service and not send with all requests
Integer
Optional
+ +
AutomatNumber Automat number (1036) String [1..20]
Optional
+
Customer Customer (Client) (1227) String [1..243]
Optional
+
CustomerINN Customer's (client's) TIN (1228) String [10..12]
Optional
+ +
PaymentAgentOperation Payment Agent Operation (1044)
In general, you can set up default value via Payture support service and not send with all requests
String [1..24]
Optional
+
PaymentAgentPhoneNumbers Payment Agent Phone Numbers in format +79995554444 (1073)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+
PaymentOperatorName Payment Operator Name (1026)
In general, you can set up default value via Payture support service and not send with all requests
String [1..64]
Optional
+
PaymentOperatorAddress Payment Operator Address (1005)
In general, you can set up default value via Payture support service and not send with all requests
String [1..243]
Optional
+
PaymentOperatorINN Payment Operator ITN (1016)
In general, you can set up default value via Payture support service and not send with all requests
String [10..12]
Optional
+
PaymentOperatorPhoneNumber Payment Operator Phone Number in format +79995554444 (1074)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+
PaymentTransferOperatorPhoneNumbers Payment Transfer Operator Phone Numbers in format +79995554444 (1075)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+
SettlementAddress Settlement address (1009) String [1..243]
Optional
+
SettlementPlace Settlement place (1187)
This parameter can be used to specify the site where the cheque is generated
String [1..243]
Optional
+
SupplierPhoneNumbers Supplier Phone Numbers in format +79995554444 (1171)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+ +

Cheque.Positions array element structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Quantity Quantity (1023)
Decimal number with an accuracy of 3 characters after the point
Float
Mandatory
+ + +
Price Price in rubles of the product including all discounts and extra charges (1079)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
+ + +
Tax VAT Rate (1199): values
Orange Data/ATOL:
1VAT rate 20%
2VAT rate 10%
3VAT rate calc. 20/120
4VAT rate calc. 10/110
5VAT rate 0%
6       VAT is not charged
Buhta:
1VAT rate 20%
2VAT rate 10%
5VAT rate 0%
1000VAT rate 12%
Integer
Mandatory
+ + +
Text Item name (1030) String [1..128]
Mandatory
+ + +
AdditionalAttribute Additional Attribute of the subject of calculation (1191) String [1..64]
Optional
+ +
AgentType Agent type for the subject of calculation (1222): values
A number from 1 to 127 (bit field), where the bit number indicates that the user who provides the service to the Customer (client) is:
Bit Description
0Bank payment agent
1Bank payment subagent
2Payment agent
3Payment subagent
4Agent
5Commissioner
6Another agent
Integer
Optional
+ +
AgentInfo Agent info (1223)
Description of the AgentInfo see below
Object
Optional
+
CustomsDeclarationNumber Customs declaration number (1231) String [1..32]
Optional
+
Excise Excise (1229)
Decimal number with an accuracy of 2 characters after the point
Float
Optional
+
ManufacturerCountryCode Manufacturer country code (1230) String [1..3]
Optional
+
PaymentMethodType Payment method type (1214): values
Number from 1 to 7:
1100% prepayment
2Partial prepayment
3Advance payment
4Full settlement
5Partial settlement and credit
6Transfer on credit
7Loan payment
Integer
Optional
+ + +
PaymentSubjectType Payment subject type (1212): values
Number from 1 to 13:
1Товар
2Подакцизный товар
3Работа
4Услуга
5Ставка азартной игры
6Выигрыш азартной игры
7Лотерейный билет
8Выигрыш лотереи
9Предоставление РИД
10Платеж
11Агентское вознаграждение
12Составной предмет расчета
13Иной предмет расчета
14Имущественное право
15Внереализационный доход
16Иные платежи и взносы
17Торговый сбор
18Курортный сбор
19Залог
20Расход
21Взносы на обязательное пенсионное страхование ИП
22Взносы на обязательное пенсионное страхование
23Взносы на обязательное медицинское страхование ИП
24Взносы на обязательное медицинское страхование
25Взносы на обязательное социальное страхование
26Платеж казино
27Выдача денежных средств
30АТНМ (не имеющем кода маркировки)
31АТМ (имеющем код маркировки)
32ТНМ
33ТМ
Integer
Optional
+ + +
NomenclatureCode Nomenclature code (1162) (base64 encode array from 1 to 32 byte). Used only for FFD 1.05 String
Optional
+ + +
ItemCode Marking code (2000) (the value read by the scanner). Used only for FFD 1.2 String
Optional
+ +
SupplierINN Supplier ITN (1226) String [10..12]
Optional
+ +
SupplierInfo Supplier info (1224)
Description of the SupplierInfo see below
Object
Optional
+ +
UnitOfMeasurement Unit of measurement (1197). Used only for FFD 1.05 String [1..16]
Optional
+
QuantityMeasurementUnit Unit of measurement of the object of calculation (2108) (number from 0 to 255). Used only for FFD 1.2 Integer
Optional
+ +

Cheque.Payments array element structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Type Payment type: values
Number from 1 to 16:
1Cash (1031)
2Non-cash (1081)
14Advance payment (1215)
15Subsequent payment (on credit) (1216)
16Consideration (1217)
Integer
Mandatory
+ + +
Amount Payment amount in rubles
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
+ + +

Cheque.AdditionalMessages array element structure

Parameter Description Format Orange Data ATOL Buhta
Key Name of parameter String
Mandatory
+ + +
Value Value of parameter String
Mandatory
+ + +

Cheque.AdditionalUserAttribute parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Name Name of Additional User Attribute (1085) String [1..64]
Mandatory
+
Value Value of Additional User Attribute (1086) String [1..175]
Mandatory
+

Cheque.Positions.AgentInfo parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
PaymentAgentOperation Payment Agent Operation (1044)
In general, you can set up default value via Payture support service and not send with all requests
String [1..24]
Optional
+
PaymentAgentPhoneNumbers Payment Agent Phone Numbers in format +79995554444 (1073)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+
PaymentOperatorName Payment Operator Name (1026)
In general, you can set up default value via Payture support service and not send with all requests
String [1..64]
Optional
+
PaymentOperatorAddress Payment Operator Address (1005)
In general, you can set up default value via Payture support service and not send with all requests
String [1..243]
Optional
+
PaymentOperatorINN Payment Operator ITN (1016)
In general, you can set up default value via Payture support service and not send with all requests
String [10..12]
Optional
+
PaymentOperatorPhoneNumber Payment Operator Phone Number in format +79995554444 (1074)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+
PaymentTransferOperatorPhoneNumbers Payment Transfer Operator Phone Numbers in format +79995554444 (1075)
In general, you can set up default value via Payture support service and not send with all requests
Array of strings [1..19]
Optional
+

Cheque.Positions.SupplierInfo parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Name Name of Supplier(1225)
A string of up to (239-N) characters, where N is the number of characters in the PhoneNumbers field + 4 characters per number
String
Mandatory
+ +
PhoneNumbers Supplier Phone Numbers (1171) Array of strings [1..19]
Optional
+ +

Request Payture ApiCheque
The request with the necessary parameters is created on the client side and sent to the gateway using the POST request method via the HTTPS protocol. The type of the body of the request is "Content-Type: application/json".

https://{Environment}.payture.com/apicheque/{Command}

where {Host} – payment gateway host, {Command} – command name.

Response Payture ApiCheque
Payment gateway gives the results of request processing synchronously in JSON format, UTF-8 encoding.

The Merchant may transfer cheques online cash without making a payment, using a programming interface Payture ApiCheque.

To transfer a cheque, it is necessary to form a data structure consisting of cheque items in the form of an array of objects and contact information in JSON format.

Features

CreateCreate a cheque
CreateCorrectionCreate a correction cheque
StatusCheck cheque status and get cheque information
https://{Environment}.payture.com/apicheque/Create

The Create request is used to create a cheque without payment.

Create is an asynchronous request, after which the cheque is queued for processing. In addition to the cheque data, the Merchant sends a unique document identifier, using which he can later request the status of the cheque. This identifier must be unique within the company. To transfer the cheque, you need to form a data structure in the form of JSON.

Request

An example of a Cheque with a minimal set of parameters [JSON]:

{
  "Key":"Merchant",
  "Password":"1234",
  "Cheque":{
    "Id":"6363901578517681941",
    "INN":"7702684259",
    "Content":{
      "Type":1,
      "Positions":[
        {
          "Quantity":1,
          "Price":27.25,
          "Tax":1,
          "Text":"Pie"
        }
      ],
      "CheckClose":{
        "Payments":[
          {
            "Type":2,
            "Amount":27.25
          }
        ]
      },
      "CustomerContact":"user@mail.com"
    }
  }
}

An example of a Cheque with the max set of parameters (FFD 1.2) [JSON]:

Orange Data ATOL Buhta
{
  "Key":"Merchant",
  "Password":"1234",
  "Message":"Cheque Payture",
  "TemplateTag":"Default",
  "TemplateLang":"Default",
  "AdditionalMessages":[
    {
      "Key":"Name",
      "Value":"Value"
    }
  ],
  "Cheque":{
    "Id":"636390157851768146941",
    "INN":"7710140679",
    "Group":"main",
    "Content":{
      "Type":1,
      "Positions":[
        {
          "Quantity":1,
          "Price":27.25,
          "Tax":1,
          "Text":"Pie",
          "AdditionalAttribute":"Additional Attribute of Positions",
          "AgentType":127,
          "AgentInfo":{
            "PaymentAgentOperation":"Payment Agent Op.",
            "PaymentAgentPhoneNumbers":["+79260000004"],
            "PaymentOperatorName":"ООО \"Technology\"",
            "PaymentOperatorAddress":"Москва, Zorge 29",
            "PaymentOperatorINN":"2306935781",
            "PaymentOperatorPhoneNumbers":["+79260000003"],
            "PaymentTransferOperatorPhoneNumbers":["+79260000002"]
          },
          "CustomsDeclarationNumber":"Declaration number",
          "Excise":1.00,
          "ManufacturerCountryCode":"643",
          "PaymentMethodType":3,
          "PaymentSubjectType":10,
          "ItemCode":"010460406000600021N4N57RSCBUZTQ\u001d2403004002910161218\u001d1724010191ffd0\u001d92tIAF/YVoU4roQS3M/m4z78yFq0fc/WsSmLeX5QkF/YVWwy8IMYAeiQ91Xa2z/fFSJcOkb2N+uUUmfr4n0mOX0Q==",
          "SupplierINN":"7203305114",
          "SupplierInfo":{
            "Name":"Supplier Name",
            "PhoneNumbers":["+79990000009"]
          },
          "QuantityMeasurementUnit": 10
        }
      ],
      "CheckClose":{
        "Payments":[
          {
            "Type":2,
            "Amount":27.25
          }
        ],
        "TaxationSystem":1
      },
      "CustomerContact":"79991234567",
      "AdditionalAttribute":"Add.Attr.cheque",
      "AdditionalUserAttribute":{
        "Name":"Name of Additional User Attribute",
        "Value":"Value of Additional User Attribute"
      },
      "AutomatNumber":"1258",
      "Customer":"Ivanov Ivan Ivanovich",
      "CustomerINN":"142702309610",
      "PaymentAgentOperation":"Payment Agent Op.",
      "PaymentAgentPhoneNumbers":["+79260000003"],
      "PaymentOperatorName":"ООО \"Chamomile\"",
      "PaymentOperatorAddress":"Moscow, Durova 10",
      "PaymentOperatorINN":"9715225506",
      "PaymentOperatorPhoneNumbers":["+79260000002"],
      "PaymentTransferOperatorPhoneNumbers":["+79260000001"],
      "SettlementAddress":"Moscow, Zolotaya 72",
      "SettlementPlace":"https://site.ru/",
      "SupplierPhoneNumbers":["+74957870004"]
    }
  }
}
{
  "Key":"Merchant",
  "Password":"123",
  "TemplateTag":"Default",
  "Message":"Cheque Payture",
  "TemplateLang":"Default",
  "AdditionalMessages":[
    {
      "Key":"Name",
      "Value":"Value"
    }
  ],
  "Cheque":{
    "Id":"{{$timestamp}}",
    "INN":"5544332219", 
    "Group":"main",
    "Content":{
      "Type":1,
      "Positions":[
        {
          "Quantity":1,
          "Price":27.25,
          "Tax":1,
          "Text":"Pie",
          "AdditionalAttribute":"Additional Attribute of Positions",
          "PaymentMethodType":7,
          "PaymentSubjectType":1,
          "ItemCode":"MDEwNDYwNzQyODY3OTA5MDIxNmVKSWpvV0g1NERkVSA5MWZmZDAgOTJzejZrU1BpckFwZk1CZnR2TGJvRTFkbFdDLzU4aEV4UVVxdjdCQmtabWs0PQ=",
          "SupplierINN":"5544332219",
          "SupplierInfo":{
            "Name":"Supplier Name",
            "PhoneNumbers":["+79990000009"]
          },
          "QuantityMeasurementUnit": 10
        }
      ],
      "CheckClose":{
        "Payments":[
          {
            "Type":2,
            "Amount":27.25
          }
        ],
        "TaxationSystem":1
      },
      "CustomerContact":"user@mail.com",
      "PaymentAgentOperation":"Payment Agent Op.",
      "PaymentAgentPhoneNumbers":["+79260000003"],
      "PaymentOperatorName":"ООО \"Chamomile\"",
      "PaymentOperatorAddress":"Moscow, Durova 10",
      "PaymentOperatorINN":"9715225506",
      "PaymentOperatorPhoneNumbers":["+79260000002"],
      "PaymentTransferOperatorPhoneNumbers":["+79260000001"],
      "SupplierPhoneNumbers":["+74957870004"]
    }
  }
}
{
  "Key":"Merchant",
  "Password":"123",
  "Message":"Cheque Payture",
  "TemplateTag":"Default",
  "TemplateLang":"Default",
   "AdditionalMessages":[
    {
      "Key":"Name",
      "Value":"Value"
    }
  ],
  "Cheque":{
    "Id":"{{$timestamp}}",
    "INN":"140840021970",
    "Group":"main",
    "Content":{
      "Type":2,
      "Positions":[
        {
          "Quantity":1,
          "Price":11,
          "Tax":1,
          "Text":"Pie",
          "PaymentMethodType":7,
          "PaymentSubjectType":1
        }
      ],
      "CheckClose":{
        "Payments":[
          {
            "Type":1,
            "Amount":11
          }
        ]
      },
      "CustomerContact":"roman@test.com"
    }
  }
}
```
Parameter Description Format Orange Data ATOL Buhta
Key Name of Terminal
Issued with test/production access parameters
String
Mandatory
+ + +
Password Password for requests apiecheque
Issued with test/production access parameters
String
Mandatory
+ + +
Cheque Cheque information
Description of the Cheque see below
Object
Mandatory
+ + +
Message The subject of the email or string in the SMS message
String [1..50]
Optional
+ + +
TemplateTag Name of the cheque template
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used
In general, you can set up default value via Payture support service and not send with all requests
String
Optional
+ + +
TemplateLang Language of the cheque template
Required, if the Merchant uses several templates. If the parameter is not sent, the template named «Default» is used
In general, you can set up default value via Payture support service and not send with all requests
String
Optional
+ + +
AdditionalMessages Allows to add any parameters to the cheque template in the placeholder with the name of the Key
Description of the AdditionalMessages see below. Max length 1000 characters
Array of objects
Optional
+ + +

Cheque.AdditionalMessages array element structure

Parameter Description Format Orange Data ATOL Buhta
Key Name of parameter String
Mandatory
+ + +
Value Value of parameter String
Mandatory
+ + +

Cheque parameter structure

Parameter Description Format Orange Data ATOL Buhta
Id Unique cheque ID String [1..64]
Mandatory
+ + +
INN ITN of the organization for which the cheque is created String [10..12]
Mandatory
+ + +
Content Cheque information
Description of the Content see below
Object
Mandatory
+ + +
Group The group of devices that will be used to generate the cheque
Default «main»
String [1..32]
Optional
+ + +

Cheque.Content parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Type Type of document (1054): values
Orange Data/Атол:
1Income
2Income return
3Expense
4Expense return
Buhta:
1Income
2Income return
Integer
Mandatory
+ + +
Positions Cheque item list (1059)
Description of the Positions see below
Array of objects
Mandatory
+ + +
CheckClose Container with information about the taxation system and cheque closing parameters
Description of the CheckClose see below
Object
Mandatory
+ + +
CustomerContact User's Email or Phone format 79995554444 or +79995554444 to send the cheque (1008) String [1..32]
Mandatory
+ + +
AgentType Agent Type (1057). Used only for FFD 1.05: values
A number from 1 to 127 (bit field), where the bit number indicates that the Merchant:
Bit Description
0Bank payment agent
1Bank payment subagent
2Payment agent
3Payment subagent
4Agent
5Commissioner
6Another agent
Integer
Optional
+ + -
AdditionalUserAttribute Additional User Attribute (1084)
Description of the AdditionalUserAttribute see below
Object
Optional
+ - -
AdditionalAttribute Additional Attribute (1192) String [1..16]
Optional
+ - -
AutomatNumber Automat number (1036) String [1..20]
Optional
+ - -
Customer Customer (Client) (1227) String [1..243]
Optional
+ - -
CustomerINN Customer's (client's) TIN (1228) String [10..12]
Optional
+ - -
PaymentAgentOperation Payment Agent Operation (1044)
String [1..24]
Optional
+ + -
PaymentAgentPhoneNumbers Payment Agent Phone Numbers in format +79995554444 (1073)
Array of strings [1..19]
Optional
+ + -
PaymentOperatorName Payment Operator Name (1026)
String [1..64]
Optional
+ + -
PaymentOperatorAddress Payment Operator Address (1005)
String [1..243]
Optional
+ + -
PaymentOperatorINN Payment Operator ITN (1016)
String [10..12]
Optional
+ + -
PaymentOperatorPhoneNumber Payment Operator Phone Number in format +79995554444 (1074)
Array of strings [1..19]
Optional
+ + -
PaymentTransferOperatorPhoneNumbers Payment Transfer Operator Phone Numbers in format +79995554444 (1075)
Array of strings [1..19]
Optional
+ + -
SettlementAddress Settlement address (1009) String [1..243]
Optional
+ - -
SettlementPlace Settlement place (1187)
This parameter can be used to specify the site where the cheque is generated
String [1..243]
Optional
+ - -
SupplierPhoneNumbers Supplier Phone Numbers in format +79995554444 (1171)
Array of strings [1..19]
Optional
+ - -

Cheque.Content.AdditionalUserAttribute parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Name Name of Additional User Attribute (1085) String [1..64]
Mandatory
+ - -
Value Value of Additional User Attribute (1086) String [1..175]
Mandatory
+ + -

Cheque.Content.Positions array element structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Quantity Quantity (1023)
Decimal number with an accuracy of 3 characters after the point
Float
Mandatory
+ + +
Price Price in rubles of the product including all discounts and extra charges (1079)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
+ + +
Tax VAT Rate (1199): values
Orange Data/ATOL:
1VAT rate 20%
2VAT rate 10%
3VAT rate calc. 20/120
4VAT rate calc. 10/110
5VAT rate 0%
6       VAT is not charged
Buhta:
1VAT rate 20%
2VAT rate 10%
5VAT rate 0%
1000VAT rate 12%
Integer
Mandatory
+ + +
Text Item name (1030) String [1..128]
Mandatory
+ + +
AdditionalAttribute Additional Attribute of the subject of calculation (1191) String [1..64]
Optional
+ + -
AgentType Agent type for the subject of calculation (1222): values
A number from 1 to 127 (bit field), where the bit number indicates that the user who provides the service to the Customer (client) is:
Bit Description
0Bank payment agent
1Bank payment subagent
2Payment agent
3Payment subagent
4Agent
5Commissioner
6Another agent
Integer
Optional
+ + -
AgentInfo Agent info (1223)
Description of the AgentInfo see below
Object
Optional
+ - -
CustomsDeclarationNumber Customs declaration number (1231) String [1..32]
Optional
+ - -
Excise Excise (1229)
Decimal number with an accuracy of 2 characters after the point
Float
Optional
+ - -
ManufacturerCountryCode Manufacturer country code (1230) String [1..3]
Optional
+ + +
PaymentMethodType Payment method type (1214): values
Number from 1 to 7:
1100% prepayment
2Partial prepayment
3Advance payment
4Full settlement
5Partial settlement and credit
6Transfer on credit
7Loan payment
Integer
Optional
+ + +
PaymentSubjectType Payment subject type (1212): values
Number from 1 to 13:
1Товар
2Подакцизный товар
3Работа
4Услуга
5Ставка азартной игры
6Выигрыш азартной игры
7Лотерейный билет
8Выигрыш лотереи
9Предоставление РИД
10Платеж
11Агентское вознаграждение
12Составной предмет расчета
13Иной предмет расчета
14Имущественное право
15Внереализационный доход
16Иные платежи и взносы
17Торговый сбор
18Курортный сбор
19Залог
20Расход
21Взносы на обязательное пенсионное страхование ИП
22Взносы на обязательное пенсионное страхование
23Взносы на обязательное медицинское страхование ИП
24Взносы на обязательное медицинское страхование
25Взносы на обязательное социальное страхование
26Платеж казино
27Выдача денежных средств
30АТНМ (не имеющем кода маркировки)
31АТМ (имеющем код маркировки)
32ТНМ
33ТМ
Integer
Optional
+ + +
NomenclatureCode Nomenclature code (1162) (base64 encode array from 1 to 32 byte). Used only for FFD 1.05 String
Optional
+ + +
ItemCode Marking code (2000) (the value read by the scanner). Used only for FFD 1.2 String
Optional
+ + -
SupplierINN Supplier ITN (1226) String [10..12]
Optional
+ + -
SupplierInfo Supplier info (1224)
Description of the SupplierInfo see below
Object
Optional
+ + -
UnitOfMeasurement Unit of measurement (1197). Used only for FFD 1.05 String [1..16]
Optional
+ - -
QuantityMeasurementUnit Unit of measurement of the object of calculation (2108) (number from 0 to 255). Used only for FFD 1.2 Integer
Optional
+ + -

Cheque.Content.Positions.AgentInfo parameter structure

Parameter Description Format Orange Data ATOL Buhta
PaymentAgentOperation Payment Agent Operation (1044)
String [1..24]
Optional
+ - -
PaymentAgentPhoneNumbers Payment Agent Phone Numbers in format +79995554444 (1073)
Array of strings [1..19]
Optional
+ - -
PaymentOperatorName Payment Operator Name (1026)
String [1..64]
Optional
+ - -
PaymentOperatorAddress Payment Operator Address (1005)
String [1..243]
Optional
+ - -
PaymentOperatorINN Payment Operator ITN (1016)
String [10..12]
Optional
+ - -
PaymentOperatorPhoneNumber Payment Operator Phone Number in format +79995554444 (1074)
Array of strings [1..19]
Optional
+ - -
PaymentTransferOperatorPhoneNumbers Payment Transfer Operator Phone Numbers in format +79995554444 (1075)
Array of strings [1..19]
Optional
+ - -

Cheque.Content.Positions.SupplierInfo parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Name Name of Supplier (1225)
A string of up to (239-N) characters, where N is the number of characters in the PhoneNumbers field + 4 characters per number
String
Mandatory
+ + -
PhoneNumbers Supplier Phone Numbers (1171) Array of strings [1..19]
Optional
+ + -

Cheque.Content.CheckClose parameter structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Payments Payments
Description of the Payments see below
Array of objects
Mandatory
+ + +
TaxationSystem Taxation System (1055): values
Number from 0 to 5:
0Common, ОСН
1Simplified income, УСН (Income)
2Simplified income minus expenses, УСН
3Tax on imputed income, ЕНВД
4Unified agricultural tax, ЕСН
5Patent system of taxation
Integer
Optional
+ + -

Cheque.Content.CheckClose.Payments array element structure

Parameter Description (tag) Format Orange Data ATOL Buhta
Type Payment type: values
Number from 1 to 16:
1Cash (1031)
2Non-cash (1081)
14Advance payment (1215)
15Subsequent payment (on credit) (1216)
16Consideration (1217)
Integer
Mandatory
+ + +
Amount Payment amount in rubles
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
+ + +

Response

Successful response example [JSON]:

{ 
  "Success":true,
  "ErrCode":"NONE",
  "ErrMessages":null,
  "Status":"Accepted"
}

Example of response when receiving an error from the online class service [JSON]:

{
  "Success":true,
  "ErrCode":"NONE",
  "ErrMessages":[
    "Неизвестная группа"
  ],
  "Status":"BadRequest"
}
Parameter Description Format
Success Flag of successful processing of the request by the payment gateway:
true — operation succeeded
false — operation failed
Boolean
Mandatory
ErrCode Payment gateway error code String
Mandatory
Status Cheque status. See cheque statuses String
Mandatory
ErrMessages Error messages received from the online cashier service
Transmitted if received from the online cashier service
Array of strings
Optional
https://{Environment}.payture.com/apicheque/CreateCorrection/

The CreateCorrection request is used to create a correction cheque without payment.

CreateCorrection is an asynchronous request, after which the cheque is queued for processing. In addition to the cheque data, the Merchant sends a unique document identifier, using which he can request the status of the cheque. This identifier must be unique within the company. To transfer the cheque, you need to form a data structure in the form of JSON.

Request

An example of request body (minimum parameter set) [JSON]:

{
  "Key":"Merchant",
  "Password":"1234",
  "Body":{
    "Id":"pprcrnyf236wc4bu38uw",
    "Inn":"7710140679",
    "Content":{
      "Type":1,
      "TotalSum":100,
      "CashSum":0,
      "ECashSum":100,
      "Description":"Correction description",
      "CauseDocumentDate":"2019-09-17T00:00:00",
      "CauseDocumentNumber":"22000070248"
    }
  }
}

An example of request body (max parameter set) [JSON]:

{
  "Key":"Merchant",
  "Password":"1234",
  "Body":{
    "Id":"tf73q69ft3rfs4ep2yld3v",
    "Inn":"7710140679",
    "Group":"main",
    "Content":{
      "Type":1,
      "TotalSum":100,
      "CashSum":0,
      "ECashSum":100,
      "TaxationSystem":1,
      "Description":"Correction description",
      "CauseDocumentDate":"2019-09-17T00:00:00",
      "CauseDocumentNumber":"22000070249",
      "CorrectionType":0,
      "PrepaymentSum":0,
      "PostpaymentSum":0,
      "OtherPaymentTypeSum":0,
      "Tax1Sum":20,
      "Tax2Sum":0,
      "Tax3Sum":0,
      "Tax4Sum":0,
      "Tax5Sum":0,
      "Tax6Sum":0
    }
  }
}
Parameter Description Format
Key Name of Terminal
Issued with test/production access parameters
String
Mandatory
Password Password for requests apiecheque
Issued with test/production access parameters
String
Mandatory
Body Container with information about the check
Description of the Body see below
Object
Mandatory

Body parameter structure

Parameter Description Format
Id Unique cheque ID String [1..64]
Mandatory
INN ITN of the organization for which the cheque is created String [10..12]
Mandatory
Content Cheque information
Description of the Content see below
Object
Mandatory
Group The group of devices that will be used to generate the cheque
Default «main»
String [1..32]
Optional

Body.Content parameter structure

Parameter Description (tag) Format
Type Type of document (1054): values
Number (only 1 or 3):
1Income
3Expense
Integer
Mandatory
TotalSum Amount of calculation in rubles specified in the cheque (1020)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
CashSum Amount of the cheque in cash in rubles (1031)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
ECashSum Amount of the cheque non-cash in rubles (1081)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
TaxationSystem Taxation System (1055): values
Number from 0 to 5:
0Common, ОСН
1Simplified income, УСН (Income)
2Simplified income minus expenses, УСН
3Tax on imputed income, ЕНВД
4Unified agricultural tax, ЕСН
5Patent system of taxation
Integer
Optional
Description Description correction (1177) String [1..244]
Mandatory
CauseDocumentDate Date of the document grounds for correction (1178)
String (ISO8601 format). The time must be 00:00:00
String
Mandatory
CauseDocumentNumber Document number of the basis for correction (1179) String [1..32]
Mandatory
CorrectionType Correction Type (1173): values
Number from 0 to 1:
0Independently
1By prescription

Default 0
Integer
Mandatory
PrepaymentSum Amount of the cheque in rubles prepayment (offset advance and (or) previous payments) (1215)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
PostpaymentSum Amount of the cheque in rubles postpaid (on credit) (1216)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
OtherPaymentTypeSum Amount of the cheque in rubles counter provision (1217)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
Tax1Sum Amount of VAT cheque in rubles at the rate of 20% (1102)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
Tax2Sum Amount of VAT cheque in rubles at the rate of 10% (1103)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
Tax3Sum Amount of VAT cheque in rubles at the rate of 0%(1104)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
Tax4Sum Amount of calculation in rubles on the cheque without VAT (1105)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
Tax5Sum Amount of VAT cheque in rubles by calc. rate 20/120 (1106)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
Tax6Sum Amount of VAT cheque in rubles by calc. rate 10/110 (1107)
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory

Response

Successful response example [JSON]:

{ 
  "Success":true,
  "ErrCode":"NONE",
  "ErrMessages":null,
  "Status":"Accepted"
}

Example of response when receiving an error from the online class service [JSON]:

{
  "Success":true,
  "ErrCode":"NONE",
  "ErrMessages":[
    "Отсутсвует поле 'CauseDocumentNumber'"
  ],
  "Status":"BadRequest"
}
Parameter Description Format
Success Flag of successful processing of the request by the payment gateway:
true — operation succeeded
false — operation failed
Boolean
Mandatory
ErrCode Payment gateway error code String
Mandatory
Status Cheque status. See cheque statuses String
Mandatory
ErrMessages Error messages received from the online cashier service
Transmitted if received from the online cashier service
Array of strings
Optional
StatusDescription
AcceptedThe cheque creation request has been accepted (it is in the queue for processing or in the process of processing)
CreatedCheque created and received from online cash registers
ConflictCheque with this Id already exists
BadRequestThe cheque creation request is not in the correct format
UnauthorizedFailed to log in to work with online cashier
UnknownStatus unknown, cheque not created
TimeoutCould not get from the cashier check data for a valid time
NotFoundCheque with this Id does not exist
https://{Environment}.payture.com/apicheque/Status/

The Status request is used to get the current status of the cheque and information about the cheque.

Request

An example of request body [JSON]:

{ 
  "Key":"Merchant",
  "Password":"1234",
  "Id":"6363737176995117182",
  "OrderId":""
}
Parameter Description Format
Key Name of Terminal
Issued with test/production access parameters
String
Mandatory
Password Password for requests apiecheque
Issued with test/production access parameters
String
Mandatory
Id Document ID String [1..64]
Optional*
OrderId Payment ID in Merchant system
Can be used if a cheque was sent with a payment
String [1..50]
Optional*

*At least one of the optional parameters must be specified. If Id is passed in the request, the search will perform on this parameter.

Response

Response example [JSON]:

{
  "Success":true,
  "ErrCode":null,
  "Cheques":[
    {
      "Sended":false,
      "Cheque":{
        "Content":{
          ...
        },
        "Id":"1568707129",
        "DeviceSN":"0578050005001542",
        "DeviceRN":"0000000400054952",
        "FSNumber":"9999078900001341",
        "OFDName":"ООО \"Ярус\" (\"ОФД-Я\")",
        "OFDWebsite":"www.ofd-ya.ru",
        "OFDINN":"7728699517",
        "FNSWebsite":"www.nalog.ru",
        "CompanyINN":"7710140677",
        "CompanyName":"ООО «Chamomile»",
        "DocumentNumber":8750,
        "ShiftNumber":3420,
        "DocumentIndex":945,
        "ProcessedAt":"2019-09-17T10:58:00",
        "Change":0.0,
        "FP":"671302447"
      },
      "ErrCode":null,
      "Link":"https://sandbox3.payture.com/c/?i=brBv&h=t9FlDSndYcqI0sU8+NnyaA",
      "Status":"Created"
    }
  ]
}
Parameter Description Format
Success Flag of successful processing of the request by the payment gateway:
true — operation succeeded
false — operation failed
Boolean
Mandatory
ErrCode Payment gateway error code String
Mandatory
Cheques List of cheques for this request
Exists, if «Success=True»
Description of the Cheques see below
Array of objects
Optional

Cheques array element structure

Parameter Description Format
Sended Sign send a cheque
Sending does not always mean delivery of the check to the User
Boolean
Mandatory
Status Cheque status. See cheque statuses String
Mandatory
Cheque Fiscal details of the cheque
Exists, if «Status=Created»
Description of the Cheque see below
Object
Optional
Link Link to the cheque
Exists, if «Status=Created»
String
Optional
ErrCode Exists if an internal error occurred while adding the current check data in response to this request String
Optional

Cheques.Cheque parameter structure

Parameter Description Format
Content Cheque details. Corresponds to the Content parameter in сheque creation requests.
Varies depending on cheque type:
for common cheque — parameter Cheque.Content from Create request
for correction cheque — parameter Body.Content from CreateCorrection request
Object
Mandatory
Id Cheque ID
Corresponds to the value from the request
String [1..64]
Mandatory
DeviceSN Serial number of the device that punched the cheque String [1..20]
Mandatory
DeviceRN Registration number of the device that punched the cheque String [1..20]
Mandatory
FSNumber A number of the fiscal drive String [1..16]
Mandatory
OFDName OFDN ame String [1..256]
Mandatory
OFDWebsite OFD Website String [1..58]
Mandatory
OFDINN OFD ITN String [1..12]
Mandatory
FNSWebsite FNS Website String [1..256]
Mandatory
CompanyINN Company ITN String [1..12]
Mandatory
CompanyName Company Name String [1..256]
Mandatory
DocumentNumber A number of the fiscal document Integer
Mandatory
ShiftNumber Shift Number Integer
Mandatory
DocumentIndex Document Index Integer
Mandatory
ProcessedAt Time of registration of the fiscal document
String (ISO8601 format)
String
Mandatory
Change Change in rubles
Decimal number with an accuracy of 2 characters after the point
Float
Mandatory
FP Fiscal sign String [1..10]
Mandatory

Error codes

Error codeDescription
NONE The transaction was completed without errors
ACCESS_DENIED Access from the current IP address or with the indicated parameters is denied
AMOUNT_ERROR The transaction amount is invalid
AMOUNT_EXCEED The transaction amount exceeds the available card balance
API_NOT_ALLOWED The given API is not allowed to be used
CARD_EXPIRED The card is expired
CARD_NOT_FOUND The card is not found
COMMUNICATE_ERROR An error occurred while transferring the data to the GPS (Global Payment Systems)
CURRENCY_NOT_ALLOWED The currency is not allowed for the Merchant
CUSTOMER_NOT_FOUND The customer is not found
DUPLICATE_ORDER_ID The order number has already been used earlier
DUPLICATE_PROCESSING_ORDER_ID The order number has already been used earlier in the processing
DUPLICATE_CARD The card has already been registered
DUPLICATE_USER The User has already been registered
EMPTY_RESPONSE Empty response from the processing
EMAIL_ERROR An error occurred while transferring the email
FRAUD_ERROR Invalid transaction according to the AntiFraud filter settings
FRAUD_ERROR_BIN_LIMIT The card (BIN, mask) limit exceeded according to the AntiFraud filter settings
FRAUD_ERROR_BLACKLIST_BANKCOUNTRY The country of the given BIN is blacklisted or is not in the list of the approved countries
FRAUD_ERROR_BLACKLIST_AEROPORT The airport is blacklisted
FRAUD_ERROR_BLACKLIST_USERCOUNTRY The country of the given IP is blacklisted or is not in the list of the approved countries
FRAUD_ERROR_CRITICAL_CARD The card number (BIN, mask) is entered in the blacklist of the AntiFraud filter
FRAUD_ERROR_CRITICAL_CUSTOMER The IP-address is entered in the blacklist of the AntiFraud filter
FRAUD_ERROR_IP The IP-address is blacklisted
FRAUD_INTERNAL_ERROR An error of the AntiFraud filter
ILLEGAL_ORDER_STATE An attempt to perform an illegal operation for current payment status
INTERNAL_ERROR Wrong transaction format according to the network
INVALID_PAYTUREID Wrong fingerprint of the device
INVALID_SIGNATURE Wrong signature of the request
ISSUER_BLOCKED_CARD The cardholder is trying to make an operation which prohibited by its bank issuer or internal error occurred
ISSUER_CARD_FAIL The Issuer blocked the Internet transactions
ISSUER_FAIL The cardholder attempts to make a transaction not allowed by the Issuer or an internal issuer error occurred
ISSUER_LIMIT_FAIL The cardholder attempts to make a transaction, exceeding the Issuer’s limits on the amount or number of operations at a definite period of time
ISSUER_LIMIT_AMOUNT_FAIL The cardholder attempts to make a transaction for amount, exceeding the (daily) limit set by the Issuer
ISSUER_LIMIT_COUNT_FAIL The limit on the number of transactions exceeded: the client had made the maximum authorized number of transactions during a limited cycle and attempted to make another one
ISSUER_TIMEOUT Connection with Issuer has been failed
MERCHANT_FORWARD The transaction was forwarded to other Terminal
MERCHANT_RESTRICTION Merchant limit exceeded or transactions for Merchant were prohibited
MPI_CERTIFICATE_ERROR MPI service error (payment gate)
MPI_RESPONSE_ERROR MPI service error (IPS)
ORDER_NOT_FOUND The transaction is not found
ORDER_TIME_OUT Payment (session) is timed out
PAYMENT_ENGINE_ERROR An internal communication error in processing
PROCESSING_ACCESS_DENIED Access processing is prohibited
PROCESSING_ERROR Common system error, registered by the payment network or the Issuer
PROCESSING_FRAUD_ERROR Processing declines the transaction according to the AntiFraud filter settings
PROCESSING_TIME_OUT The response from processing is timed out
PROCESSING_ERROR_CODE_FAIL_CONVERT Unable to convert processing error code
REFUSAL_BY_GATE Refusal from the gateway to perform an operation
THREE_DS_ATTEMPTS_FAIL An attempt of 3DS authorization is failed
THREE_DS_AUTH_ERROR An error 3DS authorization
THREE_DS_ERROR An error 3DS payment
THREE_DS_FAIL An error 3DS service
THREE_DS_NOT_ATTEMPTED 3D SecureCode has not been entered
THREE_DS_NOTENROLLED The card is not enrolled in 3DS system
THREE_DS_TIME_OUT 3D SecureCode is timed out
THREE_DS_USER_AUTH_FAIL Wrong 3D SecureCode
UNKNOWN_STATE Unknown transaction status
USER_NOT_FOUND The User is not found
WRONG_AUTHORIZATION_CODE Wrong activation code
WRONG_CARD_INFO Wrong card details
WRONG_CONFIRM_CODE Wrong confirmation code
WRONG_CVV Wrong CVV
WRONG_EXPIRE_DATE Wrong card expired date
WRONG_PAN Wrong card number
WRONG_CARDHOLDER Wrong cardholder name
WRONG_PARAMS Wrong set or format of parameters
WRONG_PAY_INFO Wrong PayInfo parameter (the parameter is formed incorrectly or the cryptogram is broken)
WRONG_PHONE Wrong phone
WRONG_USER_PARAMS The User is not found
RECURRING_PAY_NOT_FOUND Recurrent payment not found
WRONG_BINDING_PAYMENT Error making recurring payment
INSTALLMENT_NOT_ALLOWED Installment not allowed for debit cards
OTHER_ERROR An error occurred while unforeseen cases
OFD_ERRORError in the service response, interacting with online cashiers
CHEQUE_DATA_EMPTYCheque parameters not sent in request
CHEQUE_DATA_INVALIDIncorrect cheque parameters
WRONG_CHEQUE_AMOUNTAmount of cheque items does not match the amount transferred for debit
CHEQUE_RESENDINGCheque has already been sent
CHEQUE_WRONG_RECIPIENTInvalid recipient email or phone format
CHEQUE_TIMEOUTCheque status was not received within the acceptable time from the service interacting with online cashiers
CHEQUE_PARSE_ERRORError parsing cheque string to json
CHEQUE_NOT_FOUNDCheque not found
CHEQUE_WRONG_STATUSCheque has a different status than expected (details depend on the context)
CHEQUE_DUPLICATEDuplicate cheque

Test cards

In the course of technical integration with the Payture payment gateway, the Merchant should use the gateway sandbox and the parameters of test cards.

Parameters of test cards

Cardholder: any name (Latin), but at least three characters (example: Test)

Sandbox service address: https://sandbox3.payture.com

Successful cards (3DS 1.0)

Card numberSecure codeExp.DateIPSResult
521885194695548412312/25MastercardSuccessful payment without 3DS with optional CVV
401111111111111212312/25VisaSuccessful payment without 3DS with optional CVV
411111111110003112312/25VisaSuccessful payment without 3DS with optional CVV
411111111110002312312/25VisaSuccessful payment without 3DS with mandatory CVV
548673205886447112312/25MastercardSuccessful payment with 3DS 1.0
411111111111111112312/25VisaSuccessful payment with 3DS 1.0
220220831111001012312/25MIRSuccessful payment with 3DS 1.0
639002888000000001012312/25MaestroSuccessful payment with 3DS 1.0
410040111110006212312/25Visa40 seconds timeout when blocked
410040111110072412312/25Visa40 seconds timeout when unblocked
410040111110032812312/25Visa40 seconds timeout when charged
410040111110302512312/25Visa40 seconds timeout when refunded

Successful cards (3DS 2.0)

Card numberExp.Date/Secure code3DS VersionIPSResult
2200240607992720Any2.0MIRSuccessful payment (Frictionless Flow). 3DS method is not required
2200240603241437Any2.0MIRSuccessful payment (Challenge Flow). 3DS method is not required
2200240607564008Any2.0MIRSuccessful payment (Frictionless Flow). 3DS method required
2200240607136989Any2.0MIRSuccessful payment (Challenge Flow). 3DS method required
2200240848120503Any1.0MIRSuccessful payment
5492230007795070Any1.0MastercardSuccessful payment
4714870000534086Any1.0VisaSuccessful payment

Error cards

Card numberSecure codeExp.DateIPSResult
411110100000004612312/25VisaAMOUNT_EXCEED error when blocked if 100 rubles amount is exceeded (Amount=10001)
330000000000000152112/25AMOUNT_EXCEED error — insufficient funds
440000000000000852109/11VisaWRONG_EXPIRE_DATE error — invalid card expiration date
550000000000000452112/25MastercardFRAUD_ERROR error — blacklisted card number
660000000000000137412/25MaestroCARD_NOT_FOUND error — nonexistent card
411111111110005612312/25VisaPROCESSING_ERROR error
411111111110007212312/25VisaISSUER_BLOCKED_CARD error
411111111110008012312/25VisaISSUER_CARD_FAIL error
411111111110022112312/25VisaPROCESSING_ERROR when charged
411111111110062712312/25VisaPROCESSING_ERROR when unblocked
411111111110202912312/25VisaPROCESSING_ERROR when refunded
481111111111111412312/25VisaUnsuccessful payment with 3DS 1.0 (PROCESSING_ERROR when payment is completed)
471111111111111512312/25VisaUnsuccessful payment with 3DS 1.0 (PROCESSING_ERROR when payment is completed)

Notifications

The notifications are the asynchronous responses from Payture on the request results.

Upon receiving the Merchant request for execution of operation, for which the notification is provided, the gateway confirms acceptance of the request and closes the connection after the synchronous response. Then, after processing the request, the gateway sends the results of the operation using the notification method, chosen by the Merchant.

The notifications contain all the obligatory parameters of the original request (except for the payment card details, the card number is replaced with a masked one and transmitted in the CardName parameter), and the Notification parameter (string-type) that determines the notification event.

Notification methods

Notification examples

Type: Email HTTP POST
Код события: [EnginePaySuccess]
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EnginePaySuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [08.05.2019 15:36:27]
ErrCode: [NONE]
OrderId: [e83f0323-fca0-0f91-9db9-393523563bc5]
Amount: [12677]
MerchantId: [1]
Is3DS=False&ForwardedTo=NotForwarded&Notification=EnginePaySuccess&MerchantContract=Merchant&Success=True&TransactionDate=08.05.2019+15%3A36%3A27&ErrCode=NONE&OrderId=e83f0323-fca0-0f91-9db9-393523563bc5&Amount=12677&MerchantId=1
  • HTTP POST — HTTP POST request. By default, a request is sent once. If necessary, through the Payture support service, you can set the number of repeated attempts to send notifications and the period between them (repeated attempts are made if the response «200 OK» was not received). The body of the request will consist of a Url Encoded string, containing the key pairs and their values, separated by the symbol «&» (ampersand). The keys and values are separated by the symbol «=» (equal).
  • Email — Email message. The message is sent one time.

Notification activation order

When connecting the test access to the payment gateway, the Merchant sends a connection request to the Payture support service. The request, among others, should contain the selected notification method, the notification receiving address, the operations for which the selected notification method should be used.

When passing to the commercial operation, all the notification method parameters are set, by default, similar to the corresponding parameters of the test access.

Any modification is made according to the Merchant request to the Payture support service.

Extra security

Examples of notifications when using encryption

Encrypted Decrypted
DATA=4Rk65RLgsa7fUBoB72rz3TwrL3nHouyDQf91kK2eAPEEIp9DYqPFm0AnJh2eQBTcPVsfG9F8XzGtMu0zUuuxU%2FNxUVaxGDFw54n3kb5d%2FdnUMU2HaGeFTHGm%2F2p9JwmtTow82ZszX9e10u07a9x5xmn%2B3VXRJNttFcsiDBCuH3qdEmBYo9EhOVROjngki1aGucw0ZL3ifY4MEPbQrj0IWWcQ3LBGe2jhcaXc6iAGyKiDQZKymW0PwDvc3YAO29POzP0YB7tJtwPjIJgr%2FOSt31030P7hCtjM2XYjGPN4iy%2Fi2CV5bCw8ve01ZWP8XkPF
Is3DS=False;ForwardedTo=NotForwarded;Notification=EnginePaySuccess;MerchantContract=Merchant;Success=True;TransactionDate=08.05.2020 17:21:24;ErrCode=NONE;OrderId=ea2209f1-c062-700a-a0f7-41055f23f027;Amount=12495;MerchantId=1

At the Merchant’s will, in order to increase payment safety, for HTTP POST notification method in the request AES-256-ECB algorithm encryption may be applied. In this case the request will have the single DATA parameter with indication, for its value, of the encrypted string, containing the key pairs and their values, separated by the symbol «;» (semicolon).

The keys and values are separated by the symbol «=» (equal). The encryption keys are exchanged at the stage of connection, and are replaced in the process of interconnection, on the initiative of any of the parties.

Payture API notifications

OperationAvailable notifications
api/Pay Success: EngineBlockSuccess, EngineChargeSuccess, EnginePaySuccess
Fail: EnginePayFail, EngineBlockFail, EngineChargeFail
api/Block Success: EngineBlockSuccess
Fail: EngineBlockFail
api/Charge Success: EngineChargeSuccess
Fail: EngineChargeFail
api/Refund Success: EngineRefundSuccess
Fail: EngineRefundFail
api/Unblock Success: EngineUnblockSuccess
Fail: EngineUnblockFail

InPay notifications

OperationAvailable notifications
apim/PaySuccess or Fail: MerchantPay, MerchantBlock
Success: EngineBlockSuccess, EngineChargeSuccess, EnginePaySuccess
Fail: EngineBlockFail, EngineChargeFail, EnginePayFail
apim/ChargeSuccess: EngineChargeSuccess
Fail: EngineChargeFail
apim/RefundSuccess or Fail: MerchantRefund
Success: EngineRefundSuccess
Fail: EngineRefundFail
apim/UnblockSuccess: EngineUnblockSuccess
Fail: EngineUnblockFail

eWallet notifications

OperationAvailable notifications
vwapi/Pay Success: EngineBlockSuccess, EngineChargeSuccess, CustomerPaySuccess, EnginePaySuccess
Fail: EngineBlockFail, EngineChargeFail, CustomerPayFail, EnginePayFail
vwapi/RefundSuccess: CustomerRefundSuccess, EngineRefundSuccess
Fail: CustomerRefundFail, EngineRefundFail
vwapi/ChargeSuccess: EngineChargeSuccess
Fail: EngineChargeFail
vwapi/UnblockSuccess: EngineUnblockSuccess
Fail: EngineUnblockFail
vwapi/AddSuccess: EngineBlockSuccess, CustomerAddSuccess
Fail: EngineBlockFail, CustomerAddFail
vwapi/RemoveCardSuccess or Fail: CustomerDeleteCard

Cheque notifications

Available notifications
ChequeSent, ChequeNotSent, ChequeAccepted, ChequeRejected, ChequeCreated, ChequeTimeout, ChequeNotAccepted

ChargeBack notifications

Available notifications
ChargeBack

Notification description

NameDescriptionExample (Email)
EnginePaySuccessEnginePaySuccess Example
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EnginePaySuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [09.08.2018 12:58:16]
ErrCode: [NONE]
OrderId: [636694163154551367]
Amount: [3500]
EnginePayFailEnginePayFail Example
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EnginePayFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [09.08.2018 14:30:01]
ErrCode: [AMOUNT_EXCEED]
OrderId: [636694218513740423]
Amount: [232]
EngineBlockSuccessEngineBlockSuccess Example
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EngineBlockSuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [09.08.2018 13:02:35]
ErrCode: [NONE]
OrderId: [636694166050528637]
Amount: [2500]
EngineBlockFailEngineBlockFail Example
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EngineBlockFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [09.08.2018 14:30:01]
ErrCode: [AMOUNT_EXCEED]
OrderId: [636694218513740423]
Amount: [232]
EngineChargeSuccessEngineChargeSuccess Example
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EngineChargeSuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [09.08.2018 14:25:08]
ErrCode: [NONE]
OrderId: [636694215634212517]
Amount: [300]
EngineChargeFailEngineChargeFail Example
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [EngineChargeFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [09.08.2018 14:31:33]
ErrCode: [PROCESSING_ERROR]
OrderId: [636694219488092941]
Amount: [2800]
EngineUnblockSuccessEngineUnblockSuccess Example
Is3DS: [False]
NewAmount: [0]
OrderId: [636694215745929202]
Amount: [1400]
Notification: [EngineUnblockSuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [09.08.2018 14:25:19]
ErrCode: [NONE]
EngineUnblockFailEngineUnblockFail Example
Is3DS: [False]
NewAmount: [1900]
OrderId: [636694219992986858]
Amount: [1900]
Notification: [EngineUnblockFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [09.08.2018 14:32:24]
ErrCode: [PROCESSING_ERROR]
EngineRefundSuccessEngineRefundSuccess Example
Is3DS: [False]
NewAmount: [0]
OrderId: [636694215684050471]
Amount: [800]
Notification: [EngineRefundSuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [09.08.2018 14:25:13]
ErrCode: [NONE]
EngineRefundFailEngineRefundFail Example
Is3DS: [False]
NewAmount: [200]
OrderId: [636694220420935985]
Amount: [200]
Notification: [EngineRefundFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [09.08.2018 14:33:06]
ErrCode: [PROCESSING_ERROR]
MerchantBlockMerchantBlock (Success=True/False) Example
SessionId: [43bb096a-f8ed-4dcf-824f-035b5f3a7b86]
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [MerchantBlock]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 14:50:42]
ErrCode: [NONE]
OrderId: [d424050f-4e22-40be-85ee-19fcc1646688]
Amount: [102]
MerchantPayMerchantPay (Success=True/False) Example
SessionId: [ab157c83-5a9d-4dde-b5f4-c8b448e607ff]
Is3DS: [False]
ForwardedTo: [NotForwarded]
Notification: [MerchantPay]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 14:49:26]
ErrCode: [NONE]
OrderId: [17f76c0c-177f-46cb-b35c-620ed5b1189c]
Amount: [102]
MerchantRefundMerchantRefund (Success=True/False) Example
Is3DS: [False]
NewAmount: [0]
OrderId: [b3ee1dd0-8fa3-41d7-96e7-537822b45d5a]
Amount: [102]
Notification: [MerchantRefund]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 14:51:43]
ErrCode: [NONE]
CustomerAddSuccessCustomerAddSuccess Example
CardNumber: [411111xxxxxx0023]
CardId: [2770521a-597f-4a8d-b283-d9f5f8257589]
VWUserLgn: [101@ya.ru]
CardHolder: [CARD HOLDER]
OrderId: [[CUSTOMERS_ADD]-[9416342]]
Amount: [101]
ExpDate: [12/2018]
Notification: [CustomerAddSuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 12:21:30]
ErrCode: [NONE]
CustomerAddFailCustomerAddFail Example
CardNumber: [411111xxxxxx0080]
CardId: []
VWUserLgn: [101@ya.ru]
CardHolder: [CARD HOLDER]
ExpDate: [12/2018]
Notification: [CustomerAddFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [10.08.2018 12:20:35]
ErrCode: [ISSUER_CARD_FAIL]
CustomerPaySuccessCustomerPaySuccess Example
Is3DS: [False]
SessionId: [b7d55d5b-c323-4f9f-9dc4-4e864011b0c9]
CardNumber: [411111xxxxxx0023]
CardId: [d85a6a7f-f908-4f02-a8bfdd9d33561213]
VWUserLgn: [101@ya.ru]
ForwardedTo: [NotForwarded]
Notification: [CustomerPaySuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 14:02:27]
ErrCode: [NONE]
OrderId: [1fb56e1f-a533-407d-bca3-cc2c8ef87f04]
Amount: [102]
CustomerPayFailCustomerPayFail Example
Is3DS: [False]
SessionId: [1c3ab2b6-944e-489f-a686-c977c6d9fbde]
CardNumber: [330000xxxxxx0001]
CardId: [87ee56bd-ec6e-4932-a8cbc85c81437824]
VWUserLgn: [101@ya.ru]
ForwardedTo: [NotForwarded]
Notification: [CustomerPayFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [10.08.2018 14:08:20]
ErrCode: [AMOUNT_EXCEED]
OrderId: [2031feb6-f2e6-4c21-be67-c669b9786027]
Amount: [102]
CustomerRefundSuccessCustomerRefundSuccess Example
Is3DS: [False]
NewAmount: [0]
OrderId: [6075f4c6-a1d0-4366-a4ca-3100625bafa6]
Amount: [102]
Notification: [CustomerRefundSuccess]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 14:09:36]
ErrCode: [NONE]
CustomerRefundFailCustomerRefundFail Example
Is3DS: [False]
NewAmount: [102]
OrderId: [80cc7ce0-b2da-46bb-96e7-02416cdb7bc7]
Amount: [102]
Notification: [CustomerRefundFail]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [10.08.2018 14:10:32]
ErrCode: [PROCESSING_ERROR]
CustomerDeleteCardRemove card (Success=True/False) Example
DeleteDate: [10.08.2018 12:30:50]
CardNumber: [411111xxxxxx0023]
CardId: [6fd5fa99-7e26-4637-84a4-8cc90d49c4d1]
VWUserLgn: [101@ya.ru]
CardHolder: [CARD HOLDER]
ExpDate: [12/2018]
Notification: [CustomerDeleteCard]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [10.08.2018 12:30:50]
ErrCode: [NONE]
ChequeSentCheque sent to User Example
OrderId: []
ChequeId: [bfh7k8f3j582c17d]
Type: [Pay]
Status: [Created]
Cheque: [Чек в Base64]
Notification: [ChequeSent]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [15.08.2018 19:02:53]
ErrCode: [NONE]
MerchantId: [140]
ChequeNotSentCheque not sent to User Example
OrderId: []
ChequeId: [bfh7k8f3j582c17d]
Type: [Pay]
Status: []
Cheque: [Чек в Base64]
Notification: [ChequeNotSent]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [15.08.2018 19:02:53]
ErrCode: [NONE]
ChequeCreatedCheque сreated Example
OrderId: []
ChequeId: [bfh7k8f3j582c17d]
Type: [Pay]
Status: [Created]
Cheque: [Чек в Base64]
Notification: [ChequeCreated]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [15.08.2018 19:02:52]
ErrCode: [NONE]
MerchantId: [140]
ChequeAcceptedCheque accepted Example
OrderId: [dfe29039-c795-44aa-8297-ae61e7102fc9]
ChequeId: []
Type: [Pay]
Status: [Accepted]
Cheque: []
Notification: [ChequeAccepted]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [15.08.2018 16:48:04]
ErrCode: [NONE]
MerchantId: [140]
ChequeNotAcceptedCheque not accepted on the side of the operator of online cashier Example
OrderId: [dfe29039-c795-44aa-8297-ae61e7102fc9]
ChequeId: []
Type: [Pay]
Status: [NotAccepted]
Cheque: []
Notification: [ChequeNotAccepted]
MerchantContract: [Merchant]
Success: [True]
TransactionDate: [15.08.2018 16:48:04]
ErrCode: [NONE]
ChequeRejectedCheque was rejected by payment gateway Example
OrderId: []
ChequeId: []
Type: [Pay]
Status: [Unknown]
Cheque: []
Notification: [ChequeRejected]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [15.08.2018 16:27:26] ErrCode: []
ChequeTimeoutCheque was not sent within the allowed time Example
OrderId: [dfe29039-c795-44aa-8297-ae61e7102fc9]
ChequeId: [636699484844436085331]
Type: [Normal]
Status: [Accepted]
Cheque: []
Notification: [ChequeTimeout]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [15.08.2018 16:54:05]
ErrCode: [CHEQUE_TIMEOUT]
ChargeBackChargeback Example
OrderId: [17f76c0c-177f-46cb-b35c-620ed5b1189c]
Amount: [1500]
ChargeBackDate: [27.08.2018 12:17:26]
CardHolder: [CARD HOLDER]
PANMask: [411111xxxxxx0080]
Notification: [ChargeBack]
MerchantContract: [Merchant]
Success: [False]
TransactionDate: [15.08.2018 16:27:26]
ErrCode: []

Transaction statuses

StatusDescription
NewThe payment is registered in the gateway but has not being processed yet
PreAuthorized3DSThe User has started the authentication on the 3-D secure protocol, hereon the payment operations have been completed
PreAuthorizedAFThe User has started the authentication with the AntiFraud service, hereon the payment operations have been completed
AuthorizedThe funds are blocked, but not charged (two-step payment)
VoidedThe funds on the card were blocked and unblocked (two-step payment)
ChargedThe funds are charged from User card
RefundedThe funds have been fully returned to the User card (in case of partial refund, the payment remains in the Charge status, but its amount changes)
RejectedThe last payment operation was rejected
ForwardedThe payment is forwarded to another Terminal
ErrorThe last payment operation was completed with an error
ObsoleteThis status is received by a payment attempt for which the authentication process using the 3-D Secure protocol has not been completed and a new payment attempt was made (the status of an early attempt changes from PreAuthorized3DS to Obsolete). Payment attempts are available in the Payture InPay and Payture eWallet interfaces