PURCHASE Request - Step 1
{{url}}/ecom/execute_request/payments/v3/create/purchase
Input Parameters:
Parameter
Description
Data Format
Required
Example
merchantRequestId
A unique identifier generated by the merchant's system, used to retrieve the operation status in case of an unknown error or disconnection.
string(36)
Yes
137d9304-0368-11ed-b939-0242ac120002
merchantId
Merchant ID generated in Ecom.
string(36)
Yes
137d9304-0368-11ed-b939-0242ac120002
encryptedCardNumber
Card number encrypted in JWE format using the public payment key.
string
Yes
5573670000000304 (decrypted view)
coinAmount
Payment amount.
string
Yes
2000
txnType
Transaction subtype. If specified, CVV input and verification are skipped. If not specified, CVV input and verification are required.
enum
No
Possible values: NONCVV/noncvv
desiredThreeDSMode
Indicates whether the merchant prefers to use 3DS in the purchase.
string(50)
Yes
Default: SHOULD
MUST - Payment must be processed with 3DS.
MUST_NOT - Payment must be processed without 3DS.
SHOULD - If the card supports 3DS, verification is performed.
notificationUrl
The URL to which the CallBack will be sent.
string(1000)
No
https://merchant.notification_url
notificationEncryption
Indicates whether CallBack data is encrypted.
string
No
true/false If not provided or set to false, CallBack data will be unencrypted.
date
Date and time of the payment.
string
Yes
{{currentdateT}}.00+00:00
comment
Additional transaction description provided by the merchant's customer.
string(1000)
No
///5555.25412
purpose
Payment purpose provided by the merchant.
string(255)
No
For goods
merchantComment
Additional information or comments from the merchant regarding the order.
string(255)
No
merchant Comment id 1258728c1
resultRedirectUrl
URL for redirecting the customer after 3DS authentication.
string(1000)
No
Google Help
customerData
Object containing customer details.
object
Yes
-
senderCustomerId
Sender's customer ID.
string(255)
Yes
1258728c1
senderFirstName
Sender's first name.
string(30)
the value cannot contain only numbers
cannot contain periods or other special characters
cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027
No
Ivanenko
senderLastName
Sender's last name.
string(30)
the value cannot contain only numbers
cannot contain periods or other special characters
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027
No
Ivan
senderMiddleName
Sender's middle name.
string(30)
the value cannot contain only numbers
cannot contain periods or other special characters
cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027
No
Ivanovich
senderEmail
Sender's email.
string(256)
No
mail@gmail.com
senderCountry
Sender's country code.
string(3) (ISO 3166, e.g., 804 for Ukraine)
No
804
senderRegion
Sender's region.
string(255)
No
Kyivska
senderCity
Sender's city.
string(25)
No
Kyiv
senderStreet
Sender's street.
string(35)
No
Sichovykh Striltsiv
senderAdditionalAddress
Additional sender address details (floor, house number, apartment).
string(255)
No
23
senderItn
Sender's tax identification number.
string(20)
No
123456789
senderPassport
Sender's passport number.
string(255)
No
AN123456
senderIp
Sender's IP address.
string(50)
No
123.12.12.12
senderPhone
Sender's phone number.
string(20)
No
380630000000
senderBirthday
Sender's date of birth.
string(50)
No
31.12.2000
senderGender
Sender's gender.
string(50)
No
Male
senderZipCode
Sender's postal code.
string(50)
No
49000
Output Parameters:
Parameter
Description
Data Format
Example
type
Transaction type.
string
Purchase
rrn
RRN transaction number in MPS.
string
2554256963
purpose
Payment purpose.
string
For goods
comment
Comment.
string
test
coinAmount
Payment amount.
int
2000
merchantId
Merchant ID.
string
137d9304-0368-11ed-b939-0242ac120002
operationId
Transaction ID.
string
1712844596346b9F-WwrWZpq
ecomOperationId
Transaction ID in the Ecom system.
string
8c3303e9-7396-43b8-af4e-31d9facdde9b
merchantName
Merchant name.
string
KB test terminal
approvalCode
Authorization code.
string
39203
status
Transaction status.
string
Possible values: SUCCESS, FAIL, PENDING, REQUIRED_3DS, DESIRED_THREEDS_MODE_ERROR
transactionCurrency
Payment currency.
string
980
transactionType
Transaction type in numerical form.
string
35
createDateTime
Transaction creation date.
string
2024.09.19 15:29:25.675
modificationDateTime
Transaction modification date.
string
2024.09.19 15:29:25.675
responseCode
Response details.
string
0
description
Response description.
string
approved
bankCode
Issuer bank name.
string
BANK_ALLIANCE
paymentSystem
Issuer MPS name.
string
MasterCard
productType
Terminal product type.
string
PURCHASE
notificationUrl
URL to which the CallBack is sent
string
paymentServiceType
Payment type
string
CARD/APPLE_PAY/GOOGLE_PAY
notificationEncryption
Callback data encryption feature
string
true/false If the parameter is not passed or false is passed, then the data in the CallBack will be unencrypted
cardNumberMask
Masked card number
string
5573********0304
desiredThreeDSMode
A feature that indicates whether the merchant wants to use the 3DS in the purchase or not.
string
MUST/SHOULD/MUST_NOT
threeDSMode
A parameter that indicates whether a 3DS is used in the purchase or not
string
MUST- pay with 3DS MUST_NOT- pay without 3DS
statusThreeDs
3DS holding status
string
Y - successful 3ds N - unsuccessful 3ds
threeDSServerTransId
Id of the transaction in the 3ds system
string
8a811df4-91e0-436b-a9ac-9b0772c96f28
acsTransId
Id of the transaction in the ACS system
string
3e17fabb-71e6-498e-8794-ef8c95c5ba6f
dsTransId
Transaction ID generated by Directory Server
string
12ebc556-82d3-4e35-9fb8-77ac18b050ea
eci
Electronic Commerce Indicator A code that indicates the security level of a transaction
string
02
processingMerchantId
Id of the merchant in PC
string
AE100000
processingTerminalId
Id of the terminal in the PS
string
AE100000
redirect3dsUrl
URL to redirect the client to the issuer's page for the 3DS pass
string
txnType
Under the type of transaction
enum
Possible values: NONCVV/noncvv- upon receipt of a given value of cvv input and its verification does not occur
senderCustomerId
Id of the sender's client
string
1258728c1
senderFirstName
Sender's first name
string
Ivanenko
senderLastName
Sender's last name
string
Ivan
senderMiddleName
Sender's middle name
string
Ivanovich
senderEmail
Sender's mail
string
mail@gmail.com
senderCountry
Sender's country
string
Ukraine
senderRegion
Sender's area
string
Kyivska
senderCity
Sender's city
string
Kyiv
senderStreet
Sender's street
string
Sichovykh strilʹtsiv
senderAdditionalAddress
Additional data of the sender's address (floor, house number, apartment)
string
23
senderItn
Sender's tax identification number.
string
123456789
senderPassport
Sender's passport number.
string
АН123456
senderIp
Sender's IP address.
string
123.12.12.12
senderPhone
Sender's phone number.
string
380630000000
senderBirthday
Sender's date of birth.
string
31.12.2000
senderGender
Sender's gender.
string
M
senderZipCode
Sender's postal code.
string
12000
senderBankCode
The name of the sender's issuing bank
string
BANK_ALLIANCE
senderPaymentSystem
The name of the sender's issuer
string
MasterCard
senderCardNumberMask
masked card number of the sender
string
5573********0304
Request Body Example
Example response body without 3DS
Example of response body from 3DS
Last updated