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
Pay | Go through one-step payment processing |
Block | Block funds on User’s payment card as a part of the two-step payment procedure |
Charge | Charge the amount blocked on the User card as a part of the two-step payment procedure |
Unblock | Canceling the hold of funds on the Customer's card |
Refund | Full or partial refund to the Customer’s card |
GetState | View 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.
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=12351 \
-d OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce \
--data-urlencode "PayInfo= \
PAN=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351" \
--data-urlencode "CustomFields = \
IP=23.57.26.217; \
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=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351
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=23.57.26.217;
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
<Pay OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="True" Amount="12351"/>
<Pay OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="3DS" Amount="12351" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-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 |
FinalTerminal | The 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
-d PaRes={PaRes} \
Parameter names included 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 |
PaRes | String containing 3-D Secure authentication results Identical to response from ACS | String Mandatory |
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=12351 \
-d OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce \
--data-urlencode "PayInfo= \
PAN=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351" \
--data-urlencode "CustomFields = \
IP=23.57.26.217; \
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=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351
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=23.57.26.217;
Description=MyTestTransaction
Parameter | Description | Format |
---|---|---|
IP | User IP address IPv4 or IPv6 |
String Optional |
Description | Additional payment description | String Optional |
Response
Response examples
<Block OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="True" Amount="12492"/>
<Block OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Block OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" 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 succeededFalse — operation failed3DS — 3-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 |
FinalTerminal | The 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
-d PaRes={PaRes} \
Parameter names included 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 |
PaRes | String containing 3-D Secure authentication results Identical to response from ACS | String Mandatory |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 | 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
<Charge Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Amount="12564"/>
<Charge Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="ORDER_NOT_FOUND"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
Amount | Final amount charged from User's card Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
Names of parameters in the requests are case-sensitive
Request
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 |
Response
An XML string with the Unblock node
Response examples
<Unblock Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" NewAmount="0"/>
<Unblock Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="ILLEGAL_ORDER_STATE"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed |
String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
NewAmount | Blocked amount balance in kopecks, always equals "0" Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=12351 \
-d OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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
<Refund Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" NewAmount="0"/>
<Refund Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="PROCESSING_TIME_OUT"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML string with the GetRefunds node
Response examples
<GetRefunds Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" 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="2e33a7bf-82d4-0d29-db74-24c097e53bce" Forwarded="false" State="" ErrCode="ACCESS_DENIED"/>
Parameter | Description | Format | ||
---|---|---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed |
String Mandatory |
||
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
||
Forwarded | Flag 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 |
||
FinalTerminal | FinalTerminal | The final Terminal on which the payment was made Exists, if «Forwarded=True» |
String Optional |
|
Amount | Amount | Payment amount in kopecks Exists, if «Success=True» | Integer Optional |
Integer Optional |
NewAmount | Charged amount balance after refunding Exists, if «Success=True» |
Integer Optional |
||
Item | List of returns by order Exists, if «Success=True» |
Object Optional |
||
ErrCode | ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
String Optional |
Item node attributes
Parameter | Description | Format |
---|---|---|
RefundDateTime | Refund date and time Exists, if "Success = True" and if there is a successful refund | String Optional |
RefundAmount | Refund amount Exists, if "Success = True" and if there is a successful refund | Integer Optional |
RefundNewAmount | The balance of the amount written off after the return is completed Exists, if "Success = True" and if there is a successful refund | Integer Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML with the GetState node
Response examples
<GetState Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12351" RRN="003770024290"/>
<GetState Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag (obtaining the status of). Enum:True — the order is found and the status of receivedFalse — status request failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
Forwarded | Flag 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 |
FinalTerminal | The final Terminal on which the payment was made Exists, if «Forwarded=True» |
String Optional |
Amount | Payment 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 |
ErrCode | Error 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351; \
Product=Ticket; \
Total=123.51; \
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
Parameter | Description | Format |
---|---|---|
Key | Name 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=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
Total=123.51;
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.
Parameter | Description | Format |
---|---|---|
SessionType | Payment type. It determines the number of payment stages:Pay — one-step paymentBlock — two-step payment |
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 |
Url | User 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 |
TemplateTag | Name 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 |
Language | Language 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 |
Description | Additional payment description | String 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
<Init Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Amount="12351" SessionLifeTime="60" AttemptsCount="5" SessionId="499f4ca1-76af-86c0-21ef-12b2df6b3bc8"/>
<Init Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="AMOUNT_ERROR"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — 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 |
SessionLifeTime | Lifetime 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 |
AttemptsCount | The 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 |
SessionId | Payment session ID in Payture system Exists, if «Success=True» | String [36] Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» |
String Optional |
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=499f4ca1-76af-86c0-21ef-12b2df6b3bc8 \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
SessionId | Payment 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).
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 | 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
<Charge Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Amount="12351"/>
<Charge Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="ILLEGAL_ORDER_STATE"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
Amount | Final amount charged from User's card Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML string with the Unblock node
Response examples
<Unblock Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" NewAmount="0"/>
<Unblock Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="ILLEGAL_ORDER_STATE"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
NewAmount | Blocked amount balance in kopecks, always equals "0". Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
-d Amount=12351 \
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
<Refund Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" NewAmount="2000"/>
<Refund Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="AMOUNT_ERROR"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML string with the GetRefunds node
Response examples
<GetRefunds Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" 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="2e33a7bf-82d4-0d29-db74-24c097e53bce" Forwarded="false" State="" ErrCode="ACCESS_DENIED"/>
Parameter | Description | Format | ||
---|---|---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed |
String Mandatory |
||
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
||
Forwarded | Flag 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 |
||
FinalTerminal | FinalTerminal | The final Terminal on which the payment was made Exists, if «Forwarded=True» |
String Optional |
|
Amount | Amount | Payment amount in kopecks Exists, if «Success=True» | Integer Optional |
Integer Optional |
NewAmount | Charged amount balance after refunding Exists, if «Success=True» |
Integer Optional |
||
Item | List of returns by order Exists, if «Success=True» |
Object Optional |
||
ErrCode | ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
String Optional |
Item node attributes
Parameter | Description | Format |
---|---|---|
RefundDateTime | Refund date and time Exists, if "Success = True" and if there is a successful refund | String Optional |
RefundAmount | Refund amount Exists, if "Success = True" and if there is a successful refund | Integer Optional |
RefundNewAmount | The balance of the amount written off after the return is completed Exists, if "Success = True" and if there is a successful refund | Integer Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML with the GetState node
Response examples
<GetState Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12351" RRN="003770024290"/>
<GetState Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag (obtaining the status of). Enum:True — the order is found and the status of receivedFalse — status request failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
Forwarded | Flag 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 |
FinalTerminal | The final Terminal on which the payment was made Exists, if «Forwarded=True» |
String Optional |
Amount | Payment 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 |
ErrCode | Error 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.
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 | Manage User accounts: register, update, check and delete |
Card management | Manage saved User cards: add, activate, delete and get a list of cards |
Init | Initialization 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 side | Opening the payment page on the side of the Payture payment gateway |
Pay — on Merchant side | Charge (one-step payment) or Block (two-step payment) funds on User’s payment card |
Pay — recurrent payments | Payment by a previously added card without re-entering the bank card details (recurring or recurrent payment) |
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 |
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 | Registration of Users in the Payture system. |
Update | Change the parameters of User registered previously |
Delete | Delete User registered previously |
Check | Check if User with set password and login exists in Payture payment system |
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
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | User 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 |
---|---|---|
VWUserLgn | User ID in Payture system Set by the Merchant. For example, email | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) Set by the Merchant | String [1..50] Mandatory |
PhoneNumber | User phone number Only digits. Format: [country code][operator code][subscriber number] | String Optional |
User email May be transmitted if not used as VWUserLgn | String [1..50] Optional |
Response
An XML string with the Register node
Response examples
<Register Success="True" VWUserLgn="123@ya.ru"/>
<Register Success="False" VWUserLgn="123@ya.ru" ErrCode="DUPLICATE_USER"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | User 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 |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
PhoneNumber | User phone number Only digits. Format: [country code][operator code][subscriber number] | String Optional |
User email May be transmitted if not used as VWUserLgn | String [1..50] Optional |
Response
An XML string with the Update node
Response examples
<Update Success="True" VWUserLgn="123@ya.ru"/>
<Update Success="False" VWUserLgn="123@ya.ru" ErrCode="DUPLICATE_USER"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | User 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
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
Password | Password for payment Terminal Issued with test/production access parameters | String Mandatory |
Response
An XML string with the Delete node
Response examples
<Delete Success="True" VWUserLgn="123@ya.ru"/>
<Delete Success="False" VWUserLgn="" ErrCode="ACCESS_DENIED"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | User 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 |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
Response
Response examples
<Check Success="True" VWUserLgn="123@ya.ru"/>
<Check Success="False" VWUserLgn="123@ya.ru" ErrCode="USER_NOT_FOUND"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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 | Link a bank card to the User account |
Activate | Card activation after adding it. Optional operation, used when provided by the card adding scheme |
Remove | Unlink a card from the User account |
GetList | Get a list of User's cards |
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=499f4ca1-76af-86c0-21ef-12b2df6b3bc8 \
Names of parameters in the requests are case-sensitive
The request can be sent by the GET or POST method.
Parameter | Description | Format |
---|---|---|
SessionId | Session 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).
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=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
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | Card 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
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardNumber | 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 |
SecureCode | CVC2/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 |
CardHolder | Cardholder first name and last name Latin letters and space only | String [1..30] Optional |
PhoneNumber | User phone number Only digits. Format: [country code][operator code][subscriber number] | String Optional |
User 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
<Add VWUserLgn="123@ya.ru" Success="True" CardName="521885xxxxxx5484" CardId="b6883eeb-5313-cb5b-c15d-d87675a4e094"/>
<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="b6883eeb-5313-cb5b-c15d-d87675a4e094"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-D Secure authentication required | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
CardName | Masked card number (first 6 and last 4 digits: 123456хххххх1234) Exists, if «Success=True» or «Success=3DS» | String [13..19] Optional |
CardId | Card 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 |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=b6883eeb-5313-cb5b-c15d-d87675a4e094 \
-d PaRes={PaRes} \
Parameter names included in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
MD | Unique transaction ID | String Mandatory |
PaRes | String containing 3-D Secure authentication results Identical to response from ACS | String Mandatory |
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=b6883eeb-5313-cb5b-c15d-d87675a4e094; \
Amount=101" \
Names of parameters in the requests are case-sensitive.
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | Card 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=b6883eeb-5313-cb5b-c15d-d87675a4e094;
Amount=12351
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardId | Card ID in Payture system for which activation is performed | String [36] Mandatory |
Amount | Blocked amount on the User's card in kopecks | Integer Mandatory |
Response
An XML string with Activate node
Response examples
<Activate Success="True" VWUserLgn="123@ya.ru" CardId="b6883eeb-5313-cb5b-c15d-d87675a4e094"/>
<Activate Success="False" VWUserLgn="123@ya.ru" ErrCode="CARD_NOT_FOUND"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
CardId | Card ID in Payture system Exists, if «Success=True» | String [36] Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=b6883eeb-5313-cb5b-c15d-d87675a4e094" \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | Card 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=b6883eeb-5313-cb5b-c15d-d87675a4e094
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardId | Card ID in Payture system for which activation is performed | String [36] Mandatory |
Response
An XML string with the Remove node
Response examples
<Remove Success="True" VWUserLgn="123@ya.ru" CardId="b6883eeb-5313-cb5b-c15d-d87675a4e094"/>
<Remove Success="False" VWUserLgn="123@ya.ru" ErrCode="WRONG_CARD_INFO"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
CardId | Card ID in Payture system Exists, if «Success=True» | String [36] Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal Issued with test/production access parameters | String Mandatory |
DATA | User 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 |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional 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
<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"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
Item | User card list Exists, if «Success=True» | Object Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
Item node attributes
Parameter | Description | Format |
---|---|---|
CardName | Masked card number (first 6 and last 4 digits: 123456хххххх1234) Exists, if «Success=True» or «Success=3DS» | String [13..19] Mandatory |
CardId | Card ID in Payture system Exists, if «Success=True» or «Success=3DS» | String [36] Mandatory |
CardHolder | Cardholder first name and last name Latin letters and space only | String [1..30] Mandatory |
Status | Current 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 |
NoCVV | Payment without CVV2/CVC2 is possible:true — payment is possiblefalse — payment impossible |
Boolean Mandatory |
Expired | The flag of expiry of the card:true — card has expiredfalse — 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 |
PaymentSystem | Payment system Can be added as agreed with Payture support service |
String [20] Optional |
Param | Additional card parameters Each parameter is passed in a nested Param node in the format Key={Key} Value={Value} |
Object Optional |
Possible Param node attributes
Parameter | Description | Format |
---|---|---|
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 successfulFalse — last recurring payment unsuccessfulExists, if the card was a recurring payment |
String Optional |
ExternalWallet | Card attribute:ApplePay — Apple PayGooglePayToken — tokenized Google Pay card (CRYPTOGRAM_3DS)GooglePayCard — non-tokenized Google Pay card (PAN_ONLY)SamsungPay — Samsung PayExists 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351; \
Product=Ticket; \
Total=123.51; \
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
Parameter | Description | Format |
---|---|---|
VWID | Name 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=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
Product=Ticket;
Total=123.51;
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.
Parameter | Description | Format |
---|---|---|
SessionType | Payment type. It determines the number of payment stages:Add — card registrationPay — one-step paymentBlock — two-step payment |
String Mandatory |
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
OrderId | Unique payment ID in Merchant system Mandatory, if «SessionType=Pay» or «SessionType=Block» | String [1..50] Optional |
Amount | Payment amount in kopecks Mandatory, if «SessionType=Pay» or «SessionType=Block» | Integer Optional |
Url | User 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 |
CardId | ID 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 |
TemplateTag | Name 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 |
Language | Language 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 |
PhoneNumber | User phone number Only digits. Format: [country code][operator code][subscriber number] | String Optional |
User email May be transmitted if not used as VWUserLgn | String [1..50] Optional |
|
Description | Additional payment description | String Optional |
IP | User IP address IPv4 or IPv6 |
String Optional |
Cheque | Base64 encoded JSON structure with 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 Init node
Response examples
<Init Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Amount="12351" SessionLifeTime="60" AttemptsCount="5" SessionId="499f4ca1-76af-86c0-21ef-12b2df6b3bc8" SessionType="Block"/>
<Init Success="False" ErrCode="ACCESS_DENIED"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
OrderId | Payment ID in Merchant system Exists, if «Success=True» and «SessionType=Pay» (Block). Corresponds to the value from the request | String [1..50] Optional |
Amount | Payment amount in kopecks Exists, if «Success=True». Equals to «0» (zero) if «SessionType=Add» | Integer Optional |
SessionLifeTime | Lifetime 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 |
AttemptsCount | The 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 |
SessionId | Payment session ID in Payture system Exists, if «Success=True» | String [36] Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=499f4ca1-76af-86c0-21ef-12b2df6b3bc8 \
Names of parameters in the requests are case-sensitive
The request can be sent by the GET or POST method.
Parameter | Description | Format |
---|---|---|
SessionId | Payment 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).
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=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351; \
CardNumber=4111111111100031; \
CardHolder=Ivan Ivanov; \
EMonth=12; \
EYear=22; \
SecureCode=123; \
PhoneNumber=79156783333; \
IP=23.57.26.217; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | Name 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):
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=FreePay;
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
CardNumber=4111111111100031;
CardHolder=Ivan Ivanov;
EMonth=12;
EYear=22;
SecureCode=123;
SessionType=Block;
PhoneNumber=79156783333;
IP=23.57.26.217;
AdditionalField1=Value1;
AdditionalField2=Value2
Параметр | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardId | To pay with an unregistered card, you must pass the value CardId=FreePay | String [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 |
CardNumber | 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 |
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 |
SessionType | Payment type. It determines the number of payment stages:Pay — one-step payment (default)Block — two-step payment |
String Optional |
AddCard | Flag for saving a card True — add a card. By default False | Boolean Optional |
PhoneNumber | User phone number Only digits. Format: [country code][operator code][subscriber number] | String Optional |
User email May be transmitted if not used as VWUserLgn | String [1..50] Optional |
|
IP | User 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
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12351"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12351" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-D Secure authentication required | String Mandatory |
VWUserLgn | User 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 |
MerchantOrderId | Payment 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 |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=b6883eeb-5313-cb5b-c15d-d87675a4e094; \
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351; \
SecureCode=123; \
IP=23.57.26.217; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | Name 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):
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=b6883eeb-5313-cb5b-c15d-d87675a4e094;
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
SecureCode=123;
SessionType=Block;
IP=23.57.26.217;
AdditionalField1=Value1;
AdditionalField2=Value2
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardId | Card ID in Payture system | String [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 |
SessionType | Payment type. It determines the number of payment stages:Pay — one-step payment (default)Block — two-step payment |
String Optional |
IP | User 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
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12351"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12351" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-D Secure authentication required | String Mandatory |
VWUserLgn | User 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 |
MerchantOrderId | Payment 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 |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=b6883eeb-5313-cb5b-c15d-d87675a4e094; \
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | Name of payment Terminal for recurring / recurrent payments 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):
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=b6883eeb-5313-cb5b-c15d-d87675a4e094;
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
SessionType=Block;
AdditionalField1=Value1;
AdditionalField2=Value2
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardId | Card ID in Payture system | String [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 |
SessionType | Payment type. It determines the number of payment stages:Pay — one-step payment (default)Block — two-step payment |
String Optional |
IP | User 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
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12351"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12351" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-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 |
VWUserLgn | User 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 |
MerchantOrderId | Payment 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 |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=b6883eeb-5313-cb5b-c15d-d87675a4e094 \
-d PaRes={PaRes} \
Parameter names included in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
MD | Unique transaction ID | String Mandatory |
PaRes | String containing 3-D Secure authentication results Identical to response from ACS | String Mandatory |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | 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 | 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 structure containing cheque data | String Optional |
Response
An XML string with the Charge node
Response examples
<Charge Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Amount="12351"/>
<Charge Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="ILLEGAL_ORDER_STATE"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
Amount | Final amount charged from User's card Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | 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 |
Response
An XML string with the Unblock node
Response examples
<Unblock Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" NewAmount="0"/>
<Unblock Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="ILLEGAL_ORDER_STATE"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
NewAmount | Blocked amount balance in kopecks, always equals "0" Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Password=123; \
Amount=12351" \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | Name 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=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
Password=123
Parameter | Description | Format |
---|---|---|
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 structure containing cheque data | String Optional |
Response
An XML string with the Refund node
Response examples
<Refund Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" NewAmount="7800"/>
<Refund Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" ErrCode="AMOUNT_ERROR"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — 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 after refunding in kopecks Exists, if «Success=True» | Integer Optional |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML string with the GetRefunds node
Response examples
<GetRefunds Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" 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="2e33a7bf-82d4-0d29-db74-24c097e53bce" Forwarded="false" State="" ErrCode="ACCESS_DENIED"/>
Parameter | Description | Format | ||
---|---|---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed |
String Mandatory |
||
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
||
Forwarded | Flag 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 |
||
FinalTerminal | FinalTerminal | The final Terminal on which the payment was made Exists, if «Forwarded=True» |
String Optional |
|
Amount | Amount | Payment amount in kopecks Exists, if «Success=True» | Integer Optional |
Integer Optional |
NewAmount | Charged amount balance after refunding Exists, if «Success=True» |
Integer Optional |
||
Item | List of returns by order Exists, if «Success=True» |
Object Optional |
||
ErrCode | ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
String Optional |
Item node attributes
Parameter | Description | Format |
---|---|---|
RefundDateTime | Refund date and time Exists, if "Success = True" and if there is a successful refund | String Optional |
RefundAmount | Refund amount Exists, if "Success = True" and if there is a successful refund | Integer Optional |
RefundNewAmount | The balance of the amount written off after the return is completed Exists, if "Success = True" and if there is a successful refund | Integer Optional |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
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 |
Response
An XML with the GetState node
Response examples
<GetState Success="True" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" State="Refunded" Forwarded="False" MerchantContract="Merchant" Amount="12351" RRN="003770024290" VWUserLgn="123@ya.ru" CardId="b6883eeb-5313-cb5b-c15d-d87675a4e094" PANMask="521885xxxxxx5484"/>
<GetState Success="False" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" State="" Forwarded="False" ErrCode="ORDER_NOT_FOUND"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag (obtaining the status of). Enum:True — the order is found and the status of receivedFalse — status request failed | String Mandatory |
OrderId | Payment ID in Merchant system Corresponds to the value from the request |
String [1..50] Mandatory |
Forwarded | Flag 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 |
FinalTerminal | The final Terminal on which the payment was made Exists, if «Forwarded=True» |
String Optional |
Amount | Payment 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 |
VWUserLgn | User ID in Payture system Exists, if «Success=True» | String [1..50] Optional |
CardId | Card ID in Payture system Exists, if «Success=True» | String [36] Optional |
PANMask | Masked 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 |
ErrCode | Error 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.
Parameter | Description | Format |
---|---|---|
ACSUrl | Address of 3-D Secure authentication server Exists, if «Success=3DS» | String |
PaReq | 3-D Secure authentication results Exists, if «Success=3DS» | String |
ThreeDSKey | Unique 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:
Parameter | Description | Format |
---|---|---|
TermUrl | Merchant's Url for receiving results and redirecting the Customer after 3-D Secure authentication | String Mandatory |
MD | Unique transaction ID Corresponds to ThreeDSKey parameter from response to Pay or Block request | String Mandatory |
PaReq | 3-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:
Parameter | Description | Format |
---|---|---|
MD | Unique transaction ID Corresponds to the value from the request | String |
PaRes | String containing 3-D Secure authentication results | String |
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:
- 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:
Parameter | Description |
---|---|
threeDSSessionData | Unique transaction identifier Corresponds to the ThreeDSSessionData parameter from the response to a Pay, Block, Add, MobilePay, or MobileBlock request |
creq | Corresponds 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 |
---|---|
threeDSSessionData | Unique transaction identifier Corresponds to the parameter passed in the request |
cres | Base64 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.
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:
- Request access to the Payture sandbox from the Payture support service.
- 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»;
- Include the
payture-widget.min.js
library on the page in thehead
section. Download the payture-widget.min.js library. - Include styles to the widget in the
head
section. Download widget styles. - Set the widget opening function. The necessary parameters are set in the
PaytureWidget()
constructor. - Define an event to open the widget, for example, by clicking the «Pay» button.
- If necessary, set the behavior of the site depending on the
success
argument of the function in OnTransactionCompleted. - Test the widget on a sandbox environment using test cards.
- 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()
:
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.
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)
Yandex Pay
The order in which Yandex Pay is integrated varies depending on the Payture programm interface used and the payment acceptance channel.
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
-d Checksum=true \
-d Amount=12351 \
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
<Pay OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="True" Amount="12351"/>
<Pay OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="3DS" Amount="12351" 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 succeededFalse — operation failed3DS — 3-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 |
FinalTerminal | The 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 |
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
-d Checksum=true \
-d Amount=12351 \
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
<Block OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="True" Amount="12351"/>
<Block OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Block OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Key="Merchant" Success="3DS" Amount="12351" 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 succeededFalse — operation failed3DS — 3-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 |
FinalTerminal | The 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 |
Payture eWallet
Pay
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=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351; \
PayToken={PayToken}; \
SessionType=Block; \
AdditionalField1=Value1; \
AdditionalField2=Value2" \
Names of parameters in the requests are case-sensitive
Parameter | Description | Format |
---|---|---|
VWID | Name 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):
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
CardId=FreePay;
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce;
Amount=12351;
PayToken={PayToken};
SessionType=Block;
SecureCode=123;
IP=23.57.26.217;
AdditionalField1=Value1;
AdditionalField2=Value2
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional parameter of access to private User information (User password) | String [1..50] Mandatory |
CardId | To pay with Apple Pay, Google Pay and Samsung Pay you must pass the value CardId=FreePay | String [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 |
SessionType | Payment type. It determines the number of payment stages:Pay — one-step payment (default)Block — two-step payment |
String Optional |
AddCard | Flag 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 |
IP | User 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
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="True" Amount="12351"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" Success="False" ErrCode="DUPLICATE_ORDER_ID"/>
<Pay VWUserLgn="123@ya.ru" OrderId="2e33a7bf-82d4-0d29-db74-24c097e53bce" MerchantOrderId="[CUSTOMERS_PAY]-[1715289]-[1]" Success="3DS" Amount="12351" ACSUrl="{ACSUrl}" PaReq="{PaReq}" ThreeDSKey="{ThreeDSKey}" ThreeDSVersion="1.0"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-D Secure authentication required | String Mandatory |
VWUserLgn | User 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 |
MerchantOrderId | Payment 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 |
ErrCode | Error code. See error codes Exists, if «Success=False» | String Optional |
Add
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
Parameter | Description | Format |
---|---|---|
VWID | Name 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):
VWUserLgn=123@ya.ru;
VWUserPsw=2645363;
PayToken={PayToken};
SecureCode=123;
PhoneNumber=79156783333;
AdditionalField1=Value1;
AdditionalField2=Value2
Parameter | Description | Format |
---|---|---|
VWUserLgn | User ID in Payture system | String [1..50] Mandatory |
VWUserPsw | Additional 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 |
PhoneNumber | User 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
<Add VWUserLgn="123@ya.ru" Success="True" CardName="411111xxxxxx1112" CardId="b6883eeb-5313-cb5b-c15d-d87675a4e094"/>
<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="b6883eeb-5313-cb5b-c15d-d87675a4e094" ThreeDSVersion="1.0"/>
Parameter | Description | Format |
---|---|---|
Success | Operation success flag. Enum:True — operation succeededFalse — operation failed3DS — 3-D Secure authentication required | String Mandatory |
VWUserLgn | User ID in Payture system Corresponds to the value from the request | String [1..50] Mandatory |
CardName | Masked card number (first 6 and last 4 digits: 123456хххххх1234) Exists, if «Success=True» or «Success=3DS» | String [13..19] Optional |
CardId | Card 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 |
ErrCode | Error 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.
On Merchant side
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:
- The User proceeds to the payment and selects the payment using a QR code;
- The Merchant calls GetQRCode to get a QR code;
- 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);
- 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);
- The User selects the payment using a QR code in the Bank's mobile app, scans the QR code and confirms the payment;
- 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:
- 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.
- 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).
GetQRCode
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=2e33a7bf-82d4-0d29-db74-24c097e53bce \
-d Amount=12351 \
-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,
"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 receivedfalse — 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).
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).
Payture API (P2P)
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=12351 \
-d OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce \
--data-urlencode "PayInfo= \
PAN=4111111111100031; \
EMonth=12; \
EYear=22; \
CardHolder=Ivan Ivanov; \
SecureCode=123; \
OrderId=2e33a7bf-82d4-0d29-db74-24c097e53bce; \
Amount=12351;" \
--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.
Transfer cheque with payment
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:
{
"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):
{
"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 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 | 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 | 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 | Integer Optional |
+ | + | + |
PaymentSubjectType | Payment subject type (1212): values | 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 | 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 |
+ | + | — |
Transfer cheque without payment
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
Create | Create a cheque |
CreateCorrection | Create a correction cheque |
Status | Check cheque status and get cheque information |
Create
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]:
{
"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 | 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 | 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 | 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 | 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 | Integer Optional |
+ | + | + |
PaymentSubjectType | Payment subject type (1212): values | 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 | Integer Optional |
+ | + | - |
Cheque.Content.CheckClose.Payments array element structure
Parameter | Description (tag) | Format | Orange Data | ATOL | Buhta |
---|---|---|---|---|---|
Type | Payment type: values | 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 succeededfalse — 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 |
CreateCorrection
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 | 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 | 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 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 succeededfalse — 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 |
Cheque statuses
Values
Status | Description |
---|---|
Accepted | The cheque creation request has been accepted (it is in the queue for processing or in the process of processing) |
Created | Cheque created and received from online cash registers |
Conflict | Cheque with this Id already exists |
BadRequest | The cheque creation request is not in the correct format |
Unauthorized | Failed to log in to work with online cashier |
Unknown | Status unknown, cheque not created |
Timeout | Could not get from the cashier check data for a valid time |
NotFound | Cheque with this Id does not exist |
Get status
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 succeededfalse — 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 code | Description |
---|---|
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 |
RECURRENT_PAY_UNBINDED | Recurrent pay token unbinded or expired |
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_ERROR | Error in the service response, interacting with online cashiers |
CHEQUE_DATA_EMPTY | Cheque parameters not sent in request |
CHEQUE_DATA_INVALID | Incorrect cheque parameters |
WRONG_CHEQUE_AMOUNT | Amount of cheque items does not match the amount transferred for debit |
CHEQUE_RESENDING | Cheque has already been sent |
CHEQUE_WRONG_RECIPIENT | Invalid recipient email or phone format |
CHEQUE_TIMEOUT | Cheque status was not received within the acceptable time from the service interacting with online cashiers |
CHEQUE_PARSE_ERROR | Error parsing cheque string to json |
CHEQUE_NOT_FOUND | Cheque not found |
CHEQUE_WRONG_STATUS | Cheque has a different status than expected (details depend on the context) |
CHEQUE_DUPLICATE | Duplicate 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 number | Secure code | Exp.Date | IPS | Result |
---|---|---|---|---|
5218851946955484 | 123 | 12/25 | Mastercard | Successful payment without 3DS with optional CVV |
4011111111111112 | 123 | 12/25 | Visa | Successful payment without 3DS with optional CVV |
4111111111100031 | 123 | 12/25 | Visa | Successful payment without 3DS with optional CVV |
4111111111100023 | 123 | 12/25 | Visa | Successful payment without 3DS with mandatory CVV |
5486732058864471 | 123 | 12/25 | Mastercard | Successful payment with 3DS 1.0 |
4111111111111111 | 123 | 12/25 | Visa | Successful payment with 3DS 1.0 |
2202208311110010 | 123 | 12/25 | MIR | Successful payment with 3DS 1.0 |
6390028880000000010 | 123 | 12/25 | Maestro | Successful payment with 3DS 1.0 |
4100401111100062 | 123 | 12/25 | Visa | 40 seconds timeout when blocked |
4100401111100724 | 123 | 12/25 | Visa | 40 seconds timeout when unblocked |
4100401111100328 | 123 | 12/25 | Visa | 40 seconds timeout when charged |
4100401111103025 | 123 | 12/25 | Visa | 40 seconds timeout when refunded |
Successful cards (3DS 2.0)
Card number | Exp.Date/Secure code | 3DS Version | IPS | Result |
---|---|---|---|---|
2200240607992720 | Any | 2.0 | MIR | Successful payment (Frictionless Flow). 3DS method is not required |
2200240603241437 | Any | 2.0 | MIR | Successful payment (Challenge Flow). 3DS method is not required |
2200240607564008 | Any | 2.0 | MIR | Successful payment (Frictionless Flow). 3DS method required |
2200240607136989 | Any | 2.0 | MIR | Successful payment (Challenge Flow). 3DS method required |
2200240848120503 | Any | 1.0 | MIR | Successful payment |
5492230007795070 | Any | 1.0 | Mastercard | Successful payment |
4714870000534086 | Any | 1.0 | Visa | Successful payment |
Error cards
Card number | Secure code | Exp.Date | IPS | Result |
---|---|---|---|---|
4111101000000046 | 123 | 12/25 | Visa | AMOUNT_EXCEED error when blocked if 100 rubles amount is exceeded (Amount=10001) |
3300000000000001 | 521 | 12/25 | AMOUNT_EXCEED error — insufficient funds | |
4400000000000008 | 521 | 09/11 | Visa | WRONG_EXPIRE_DATE error — invalid card expiration date |
5500000000000004 | 521 | 12/25 | Mastercard | FRAUD_ERROR error — blacklisted card number |
6600000000000001 | 374 | 12/25 | Maestro | CARD_NOT_FOUND error — nonexistent card |
4111111111100056 | 123 | 12/25 | Visa | PROCESSING_ERROR error |
4111111111100072 | 123 | 12/25 | Visa | ISSUER_BLOCKED_CARD error |
4111111111100080 | 123 | 12/25 | Visa | ISSUER_CARD_FAIL error |
4111111111100221 | 123 | 12/25 | Visa | PROCESSING_ERROR when charged |
4111111111100627 | 123 | 12/25 | Visa | PROCESSING_ERROR when unblocked |
4111111111102029 | 123 | 12/25 | Visa | PROCESSING_ERROR when refunded |
4811111111111114 | 123 | 12/25 | Visa | Unsuccessful payment with 3DS 1.0 (PROCESSING_ERROR when payment is completed) |
4711111111111115 | 123 | 12/25 | Visa | Unsuccessful 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
Код события: [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
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
Operation | Available 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
Operation | Available notifications |
---|---|
apim/Pay | Success or Fail: MerchantPay, MerchantBlock Success: EngineBlockSuccess, EngineChargeSuccess, EnginePaySuccess Fail: EngineBlockFail, EngineChargeFail, EnginePayFail |
apim/Charge | Success: EngineChargeSuccess Fail: EngineChargeFail |
apim/Refund | Success or Fail: MerchantRefund Success: EngineRefundSuccess Fail: EngineRefundFail |
apim/Unblock | Success: EngineUnblockSuccess Fail: EngineUnblockFail |
eWallet notifications
Operation | Available notifications |
---|---|
vwapi/Pay | Success: EngineBlockSuccess, EngineChargeSuccess, CustomerPaySuccess, EnginePaySuccess Fail: EngineBlockFail, EngineChargeFail, CustomerPayFail, EnginePayFail |
vwapi/Refund | Success: CustomerRefundSuccess, EngineRefundSuccess Fail: CustomerRefundFail, EngineRefundFail |
vwapi/Charge | Success: EngineChargeSuccess Fail: EngineChargeFail |
vwapi/Unblock | Success: EngineUnblockSuccess Fail: EngineUnblockFail |
vwapi/Add | Success: EngineBlockSuccess, CustomerAddSuccess Fail: EngineBlockFail, CustomerAddFail |
vwapi/RemoveCard | Success or Fail: CustomerDeleteCard |
Cheque notifications
Available notifications |
---|
ChequeSent, ChequeNotSent, ChequeAccepted, ChequeRejected, ChequeCreated, ChequeTimeout, ChequeNotAccepted |
ChargeBack notifications
Available notifications |
---|
ChargeBack |
Notification description
Name | Description | Example (Email) |
---|---|---|
EnginePaySuccess | EnginePaySuccess | Example |
EnginePayFail | EnginePayFail | Example |
EngineBlockSuccess | EngineBlockSuccess | Example |
EngineBlockFail | EngineBlockFail | Example |
EngineChargeSuccess | EngineChargeSuccess | Example |
EngineChargeFail | EngineChargeFail | Example |
EngineUnblockSuccess | EngineUnblockSuccess | Example |
EngineUnblockFail | EngineUnblockFail | Example |
EngineRefundSuccess | EngineRefundSuccess | Example |
EngineRefundFail | EngineRefundFail | Example |
MerchantBlock | MerchantBlock (Success=True/False) | Example |
MerchantPay | MerchantPay (Success=True/False) | Example |
MerchantRefund | MerchantRefund (Success=True/False) | Example |
CustomerAddSuccess | CustomerAddSuccess | Example |
CustomerAddFail | CustomerAddFail | Example |
CustomerPaySuccess | CustomerPaySuccess | Example |
CustomerPayFail | CustomerPayFail | Example |
CustomerRefundSuccess | CustomerRefundSuccess | Example |
CustomerRefundFail | CustomerRefundFail | Example |
CustomerDeleteCard | Remove card (Success=True/False) | Example |
ChequeSent | Cheque sent to User | Example |
ChequeNotSent | Cheque not sent to User | Example |
ChequeCreated | Cheque сreated | Example |
ChequeAccepted | Cheque accepted | Example |
ChequeNotAccepted | Cheque not accepted on the side of the operator of online cashier | Example |
ChequeRejected | Cheque was rejected by payment gateway | Example |
ChequeTimeout | Cheque was not sent within the allowed time | Example |
ChargeBack | Chargeback | Example |
Transaction statuses
Status | Description |
---|---|
New | The payment is registered in the gateway but has not being processed yet |
PreAuthorized3DS | The User has started the authentication on the 3-D secure protocol, hereon the payment operations have been completed |
PreAuthorizedAF | The User has started the authentication with the AntiFraud service, hereon the payment operations have been completed |
Authorized | The funds are blocked, but not charged (two-step payment) |
Voided | The funds on the card were blocked and unblocked (two-step payment) |
Charged | The funds are charged from User card |
Refunded | The 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) |
Rejected | The last payment operation was rejected |
Forwarded | The payment is forwarded to another Terminal |
Error | The last payment operation was completed with an error |
Obsolete | This 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 |