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

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

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=12492 \
-d OrderId=08329dff-d59d-5982-0560-c166f93b0852 \
--data-urlencode "PayInfo= \
PAN=5218851946955484; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492" \
--data-urlencode "CustomFields = \
IP=20.224.22.175; \
Description=Ticket" \

Names of parameters in the requests are case-sensitive

PayInfo parameter structure

PayInfo parameter example (decoded):

PAN=5218851946955484;
EMonth=12;
EYear=22;
CardHolder=Ivan Ivanov;
SecureCode=123;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492

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

Possible key structure of the CustomFields parameter

CustomFields parameter example (decoded):

IP=20.224.22.175;
Description=MyTestTransaction

Response

An XML string with the Pay node

<Pay OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="True" Amount="12492"/>

<Pay OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>

<Pay OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="3DS" Amount="12492" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

Pay3DS

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=08329dff-d59d-5982-0560-c166f93b0852 \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

Response

Identical to response to Pay.

Block

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=12492 \
-d OrderId=08329dff-d59d-5982-0560-c166f93b0852 \
--data-urlencode "PayInfo= \
PAN=5218851946955484; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492" \
--data-urlencode "CustomFields = \
IP=20.224.22.175; \
Product=Ticket" \

Names of parameters in the requests are case-sensitive

PayInfo parameter structure

PayInfo parameter example (decoded):

PAN=5218851946955484;
EMonth=12;
EYear=22;
CardHolder=Ivan Ivanov;
SecureCode=123;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492

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

Possible key structure of the CustomFields parameter

CustomFields parameter example (decoded):

IP=20.224.22.175;
Description=MyTestTransaction

Response

<Block OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="True" Amount="12492"/>

<Block OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>

<Block OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="3DS" Amount="12725" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

An XML string with the Block node

Block3DS

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=08329dff-d59d-5982-0560-c166f93b0852 \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

Response

Identical to response to Block.

Charge

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Charge node

<Charge Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Amount="12564"/>

<Charge Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="ORDER_NOT_FOUND"/>

Unblock

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Request

Response

An XML string with the Unblock node

<Unblock Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" NewAmount="0"/>

<Unblock Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="ILLEGAL_ORDER_STATE"/>

Refund

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=12492 \
-d OrderId=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Refund node

<Refund Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" NewAmount="0"/>

<Refund Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="PROCESSING_TIME_OUT"/>

GetRefunds

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

The GetRefunds command is used to retrieve a list of refunds produced by an order

Request

curl https://sandbox3.payture.com/api/GetRefunds \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the GetRefunds node

<GetRefunds Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Forwarded="True" MerchantContract="Merchant" 
FinalTerminal="Merchant" State="Charged" Amount="300000" NewAmount="100000"> 
<Item RefundDateTime="2023.08.17 18:22:07" RefundAmount="150000" RefundNewAmount="150000"/> 
</Item> 
<Item RefundDateTime="2023.10.19 19:12:07" RefundAmount="50000" RefundNewAmount="100000"/>
</Item> 
<GetRefunds/>

<GetRefunds Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Forwarded="false" State="" ErrCode="ACCESS_DENIED"/>

Item node attributes

GetState

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML with the GetState node

<GetState Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12492" RRN="003770024290"/>

<GetState Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>

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

Integration

Init

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=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492; \
Product=Ticket; \
Total=124.92; \
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

Data parameter structure

Data parameter example (decoded):

SessionType=Pay;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492;
Total=124.92;
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.

Response

An XML string with the Init node

<Init Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Amount="12492" SessionLifeTime="60" AttemptsCount="5" SessionId="1dda5a03-6076-0e62-1d97-de65cf9b21f4"/>

<Init Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="AMOUNT_ERROR"/>

Pay

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=1dda5a03-6076-0e62-1d97-de65cf9b21f4 \

Names of parameters in the requests are case-sensitive

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

Charge

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Charge node

<Charge Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Amount="12492"/>

<Charge Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="ILLEGAL_ORDER_STATE"/>

Unblock

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Unblock node

<Unblock Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" NewAmount="0"/>

<Unblock Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="ILLEGAL_ORDER_STATE"/>

Refund

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=08329dff-d59d-5982-0560-c166f93b0852 \
-d Amount=12492 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Refund node

<Refund Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" NewAmount="2000"/>

<Refund Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="AMOUNT_ERROR"/>

GetRefunds

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

The GetRefunds command is used to retrieve a list of refunds produced by an order

Request

curl https://sandbox3.payture.com/apim/GetRefunds \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the GetRefunds node

<GetRefunds Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Forwarded="True" MerchantContract="Merchant" 
FinalTerminal="Merchant" State="Charged" Amount="300000" NewAmount="100000"> 
<Item RefundDateTime="2023.08.17 18:22:07" RefundAmount="150000" RefundNewAmount="150000"/> 
</Item> 
<Item RefundDateTime="2023.10.19 19:12:07" RefundAmount="50000" RefundNewAmount="100000"/>
</Item> 
<GetRefunds/>

<GetRefunds Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Forwarded="false" State="" ErrCode="ACCESS_DENIED"/>

Item node attributes

GetState

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML with the GetState node

<GetState Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12492" RRN="003770024290"/>

<GetState Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>

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.

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 management

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

Register

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

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
PhoneNumber=79156783333

Response

An XML string with the Register node

<Register Success="True" VWUserLgn="123@ya.ru"/>

<Register Success="False" VWUserLgn="123@ya.ru" ErrCode="DUPLICATE_USER"/>

Update

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

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
PhoneNumber=79156783333

Response

An XML string with the Update node

<Update Success="True" VWUserLgn="123@ya.ru"/>

<Update Success="False" VWUserLgn="123@ya.ru" ErrCode="DUPLICATE_USER"/>

Delete

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

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
Password=123

Response

An XML string with the Delete node

<Delete Success="True" VWUserLgn="123@ya.ru"/>

<Delete Success="False" VWUserLgn="" ErrCode="ACCESS_DENIED"/>

Check

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

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363

Response

<Check Success="True" VWUserLgn="123@ya.ru"/>

<Check Success="False" VWUserLgn="123@ya.ru" ErrCode="USER_NOT_FOUND"/>

Card management

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

Add

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.

Payture side

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=1dda5a03-6076-0e62-1d97-de65cf9b21f4 \

Names of parameters in the requests are case-sensitive

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

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

Merchant side

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=5218851946955484; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
PhoneNumber=79156783333; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardNumber=5218851946955484;
EMonth=12;
EYear=22;
CardHolder=Ivan Ivanov;
SecureCode=123;
PhoneNumber=79156783333;
AdditionalField1=Value1;
AdditionalField2=Value2

Response

An XML string with the Add node

<Add VWUserLgn="123@ya.ru" Success="True" CardName="521885xxxxxx5484" CardId="40ee0ff2-4909-0149-fbd6-e7b6323a522c"/>

<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="40ee0ff2-4909-0149-fbd6-e7b6323a522c"/>

AddSubmit3DS

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=40ee0ff2-4909-0149-fbd6-e7b6323a522c \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

Response

Identical to response to Add — Merchant side request.

Activate

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=40ee0ff2-4909-0149-fbd6-e7b6323a522c; \
Amount=101" \

Names of parameters in the requests are case-sensitive.

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=40ee0ff2-4909-0149-fbd6-e7b6323a522c;
Amount=12492

Response

An XML string with Activate node

<Activate Success="True" VWUserLgn="123@ya.ru" CardId="40ee0ff2-4909-0149-fbd6-e7b6323a522c"/>

<Activate Success="False" VWUserLgn="123@ya.ru" ErrCode="CARD_NOT_FOUND"/>

Remove

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=40ee0ff2-4909-0149-fbd6-e7b6323a522c" \

Names of parameters in the requests are case-sensitive

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=40ee0ff2-4909-0149-fbd6-e7b6323a522c

Response

An XML string with the Remove node

<Remove Success="True" VWUserLgn="123@ya.ru" CardId="40ee0ff2-4909-0149-fbd6-e7b6323a522c"/>

<Remove Success="False" VWUserLgn="123@ya.ru" ErrCode="WRONG_CARD_INFO"/>

GetList

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

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363

Response

An XML string with the GetList and the Item embedded nodes

<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"/>

Item node attributes

Possible Param node attributes

Init

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=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492; \
Product=Ticket; \
Total=124.92; \
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

DATA parameter key structure

DATA parameter example (decoded):

SessionType=Pay;
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492;
Product=Ticket;
Total=124.92;
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.

Response

An XML string with the Init node

<Init Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Amount="12492" SessionLifeTime="60" AttemptsCount="5" SessionId="1dda5a03-6076-0e62-1d97-de65cf9b21f4" SessionType="Block"/>

<Init Success="False" ErrCode="ACCESS_DENIED"/>

Pay — on Payture side

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=1dda5a03-6076-0e62-1d97-de65cf9b21f4 \

Names of parameters in the requests are case-sensitive

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

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

Pay — on Merchant side

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.

Payment with unregistered card

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=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492; \
CardNumber=5218851946955484; \
CardHolder=Ivan Ivanov; \
EMonth=12; \
EYear=22; \
SecureCode=123; \
PhoneNumber=79156783333; \
IP=20.224.22.175; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=FreePay;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492;
CardNumber=5218851946955484;
CardHolder=Ivan Ivanov;
EMonth=12;
EYear=22;
SecureCode=123;
SessionType=Block;
PhoneNumber=79156783333;
IP=20.224.22.175;
AdditionalField1=Value1;
AdditionalField2=Value2

Response

An XML string with the Pay node

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12492"/>

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="08329dff-d59d-5982-0560-c166f93b0852" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12492" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

Payment with registered card

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=40ee0ff2-4909-0149-fbd6-e7b6323a522c; \ 
OrderId=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492; \
SecureCode=123; \
IP=20.224.22.175; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=40ee0ff2-4909-0149-fbd6-e7b6323a522c;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492;
SecureCode=123;
SessionType=Block;
IP=20.224.22.175;
AdditionalField1=Value1;
AdditionalField2=Value2

Response

An XML string with the Pay node

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12492"/>

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="08329dff-d59d-5982-0560-c166f93b0852" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12492" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

Pay — recurrent payments

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=40ee0ff2-4909-0149-fbd6-e7b6323a522c; \
OrderId=08329dff-d59d-5982-0560-c166f93b0852; \
Amount=12492; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \

Names of parameters in the requests are case-sensitive

DATA parameter key structure

DATA parameter example (decoded):

VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=40ee0ff2-4909-0149-fbd6-e7b6323a522c;
OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492;
SessionType=Block;
AdditionalField1=Value1;
AdditionalField2=Value2

Response

An XML string with the Pay node

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12492"/>

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="08329dff-d59d-5982-0560-c166f93b0852" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>

<Pay VWUserLgn="123@ya.ru" OrderId="08329dff-d59d-5982-0560-c166f93b0852" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12492" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

PaySubmit3DS

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=40ee0ff2-4909-0149-fbd6-e7b6323a522c \
-d PaRes={PaRes} \

Parameter names included in the requests are case-sensitive

Response

Identical to response to Pay — on Merchant side request.

Charge

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Charge node

<Charge Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Amount="12492"/>

<Charge Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="ILLEGAL_ORDER_STATE"/>

Unblock

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the Unblock node

<Unblock Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" NewAmount="0"/>

<Unblock Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="ILLEGAL_ORDER_STATE"/>

Refund

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=08329dff-d59d-5982-0560-c166f93b0852; \
Password=123; \
Amount=12492" \

Names of parameters in the requests are case-sensitive

DATA parameter key structure

DATA parameter example (decoded):

OrderId=08329dff-d59d-5982-0560-c166f93b0852;
Amount=12492;
Password=123

Response

An XML string with the Refund node

<Refund Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" NewAmount="7800"/>

<Refund Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" ErrCode="AMOUNT_ERROR"/>

GetRefunds

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

The GetRefunds command is used to retrieve a list of refunds produced by an order

Request

curl https://sandbox3.payture.com/vwapi/GetRefunds \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d Key=Merchant \
-d OrderId=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML string with the GetRefunds node

<GetRefunds Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Forwarded="True" MerchantContract="Merchant" 
FinalTerminal="Merchant" State="Charged" Amount="300000" NewAmount="100000"> 
<Item RefundDateTime="2023.08.17 18:22:07" RefundAmount="150000" RefundNewAmount="150000"/> 
</Item> 
<Item RefundDateTime="2023.10.19 19:12:07" RefundAmount="50000" RefundNewAmount="100000"/>
</Item> 
<GetRefunds/>

<GetRefunds Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" Forwarded="false" State="" ErrCode="ACCESS_DENIED"/>

Item node attributes

GetState

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=08329dff-d59d-5982-0560-c166f93b0852 \

Names of parameters in the requests are case-sensitive

Response

An XML with the GetState node

<GetState Success="True" OrderId="08329dff-d59d-5982-0560-c166f93b0852" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12492" RRN="003770024290" VWUserLgn="123@ya.ru" CardId="40ee0ff2-4909-0149-fbd6-e7b6323a522c" PANMask="521885xxxxxx5484"/>

<GetState Success="False" OrderId="08329dff-d59d-5982-0560-c166f93b0852" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>

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.

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:

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:

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

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:

• On the merchant side — api/Pay, api/Block, api/MobilePay, api/MobileBlock, vwapi/Pay — on the Seller's side or vwapi/Add — on the Seller's side
• On the template — apim/PaySubmit, vwapi/AddSubmit or vwapi/AddSubmit. A description of the methods is available in the 3‑D Secure 2.0  on the template (RU) documentation.

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:

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:

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.

Pay

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.

Setup

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 Parameters

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

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 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
	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
	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
	A ready-made solution for Python developers. Install: pip install payture Add to Project: import payture Additional documentation on 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
	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.
	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.
	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.
	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.
	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 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.
	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.
	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.
	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.
	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.
	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.

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.

Integration

Apple Pay

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

Instructions:

• Registering a Merchant ID and receiving a Payment Processing Certificate (RU) — required to integrate Apple Pay on the Merchant's website or app
• Domain verification and receiving a Merchant Identity Certificate (RU) — only required for Apple Pay integration on the Merchant's website

Google Pay

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

Samsung Pay

Parameter for integration Samsung Pay

• Public Key (issued by technical support of Payture)

SberPay

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

API

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.

Payture API

MobilePay

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=08329dff-d59d-5982-0560-c166f93b0852 \
-d Checksum=true \
-d Amount=12492 \

Names of parameters in the requests are case-sensitive

Response

<Pay OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="True" Amount="12492"/>

<Pay OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>

<Pay OrderId="08329dff-d59d-5982-0560-c166f93b0852" Key="Merchant" Success="3DS" Amount="12492" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>

An XML string with the Pay node

MobileBlock

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=08329dff-d59d-5982-0560-c166f93b0852 \
-d Checksum=true \
-d Amount=12492 \

Names of parameters in the requests are case-sensitive