Specification for the interaction of the merchant

Payment on the payment processing page

To pay on the payment processing page, you need to redirect to the page of the processing center, with POST data.

Production url: https://****.procard-ltd.com/api/

POST params:

Parameter	Type	Required	Description	Value
operation	String	+	Type of transaction	Purchase
merchant_id	String	+	ID merchant, issued by processing
amount	Float	+	The amount of the transaction. Example: 500.00
signature	String	+	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
			The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, currency_iso, description separated by “;” (semicolon) in UTF-8 encoding.
			The order of parameters during concatenation is important!
order_id	String	+	Unique transaction number on the merchant side. If the operation is duplicated, the merchant receives an error.
currency_iso	String	+	Currency of payment	UAH
description	String	+	Purpose of payment. It is displayed on the payment page when entering payment details. Displayed in the account statement and registries
add_params	Array	+	An array of additional parameters. Additional parameters are then turned to the merchant in the callback call
approve_url	String	+	Redirect URL in case payment is successful
decline_url	String	+	Redirect URL in case payment is unsuccessful
cancel_url	String	+	Redirect URL in case the user refuses to make a payment
callback_url	String	+	URL to which information about the result of the payment will come
redirect	Integer		1 / 0 - defaults to 1, if the parameter is 0, then the client will not receive redirects, but will receive the url of the payment page
auth_type	Integer		Default 1 - purchase, 2 - Pre-authorization
secure_type	Integer		Transaction Security Pass Type. The list of possible values see in Dictionary. secure_type parameter values
language	String		Payment page language Default ua - Ukrainian, ru - Russian, en - English
client_first_name	String		Client's first name
client_last_name	String		Client's last name
client_id	String		Client's ID in merchant system
phone	String		Client's phone
email	String		Client's email address

A description of additional request parameters add_params can be found in following section.

Request example:

{
    "operation": "Purchase",
    "merchant_id": "jnmx9smJQmSejKoR3rIgm5Pj7QG",
    "order_id": "1685444702348",
    "amount": 100,
    "currency_iso": "UAH",
    "description": "Оплата замовлення",
    "auth_type": 1,
    "signature": "113d991b5c3b9d0be6c4a589b9d154d8",
    "language": "ua",
    "add_params": {
        "data": "123",
        "SenderName": "Петренко Петро Петрович"
    },
    "approve_url": "http://merchant.site/1/approved",
    "decline_url": "http://merchant.site/1/declined",
    "cancel_url": "http://merchant.site/1/canceled",
    "callback_url": "http://merchant.site/callback",
    "client_first_name": "Olga",
    "client_last_name": "Petrenko",
    "email": "[email protected]",
    "phone": "+380112223344"
}

Success response example if "redirect": 0:

{
  "result": 0,
  "url": "https://procard-ltd.com/payment/pay?payment=3a95bdaae73a7388b3a3750023a817a897b43f2295315f2b6e0e12e3db0ced2e6475c2b080dec&lang=ukr"
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Other error codes see Dictionary. System Error Codes

Callback call to send notification of payment status

Data is sent to the URL specified in the payment parameters in the field callback_url.

Data is sent to the merchant's server in JSON format

Parameters:

Parameter	Type	Description	Values
merchantAccount	String	Merchant ID
orderReference	String	Merchant system transaction ID
amount	Float	Transaction amount
currency	String	Transaction currency
phone	String	The customer's phone number (if received from the merchant in the payment request)
createdDate	String	Payment Date in format YYYY-MM-DD HH:II:SS
		Example: 2018-12-14 12:01:26
cardPan	String	Masked PAN Card
		Example: 535277******0298
cardType	String	Card type	Visa MasterCard
fee	Float	Transaction fee
transactionId	String	Transaction ID on the PC side
type	String	Event type. Example: payment
add_params	Array	An array of additional parameters received from the merchant in the payment request
recToken	String	Token for recurring payment.
transactionStatus	String	Transaction Status	Approved - Successfully Declined - Renouncement NEEDS-CLARIFICATION - Requires clarification of the payment status. You need to check the payment status (Operation Check) or contact technical support
reason	String	Result code description
reasonCode	String	Operation result code. The list of codes can be found in Dictionary. Answer Codes
merchantSignature	String	In order to confirm the validity of the data, a control signature using the merchant's SecretKey is generated and transmitted in the HMAC_SHA512 request.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, orderReference, amount, currency separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

Example of a successful purchase callback:

{
  "merchantAccount": "vZmxaalkjdsfGWt5ApLojM8ENzCz",
  "orderReference": "1685453241304",
  "amount": "2.23",
  "operation": "Purchase",
  "currency": "UAH",
  "phone": "+38 (011) 222-33-44",
  "createdDate": "2023-05-30 16:27:21",
  "cardPan": "403021******9287",
  "cardType": "Visa",
  "fee": "0.02",
  "transactionId": 195660162,
  "type": "payment",
  "recToken": "b8e61cd175c51237cf58342377592ff8d465f25ed50288a5f3ef9a01517c3bc1",
  "add_params": {
    "secure_type": "1",
    "lifetime": "1685539641",
    "AReqDetails.browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
    "AReqDetails.browserColorDepth": "24",
    "AReqDetails.browserIP": "10.253.2.159",
    "AReqDetails.browserLanguage": "ru",
    "AReqDetails.browserScreenHeight": "1080",
    "AReqDetails.browserScreenWidth": "1920",
    "AReqDetails.browserTZ": "-120",
    "AReqDetails.browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36",
    "AReqDetails.browserJavaEnabled": "true",
    "AReqDetails.notificationUrl": "https://procard-ltd.com/payment/check3ds?payment=0cc44844b30ae8a0273e6c7b010ce34f86e8729fea2b6f7b628c92232ed33eb06475f9b999c03",
    "AReqDetails.deviceChannel": "02",
    "AReqDetails.threeRIInd": "",
    "CReqDetails.WindowWidth": "1024",
    "CReqDetails.WindowHeight": "768",
    "merchantName": "merchant",
    "RRN": "001206018623"
  },
  "transactionStatus": "Approved",
  "reason": "ОПЕРАЦИЯ РАЗРЕШЕНА",
  "reasonCode": "1",
  "pcTransactionID": "1206018623",
  "pcApprovalCode": "7E06C0 A",
  "merchantSignature": "fc55cd12476b1a67de74d42dfc3625f1"
}

Example of a purchase rejection callback:

{
    "merchantAccount": "vZmxaalkjdsfGWt5ApLojM8ENzCz",
    "orderReference": "1685454851406",
    "amount": "202.23",
    "operation": "Purchase",
    "currency": "UAH",
    "phone": "+38 (011) 222-33-44",
    "createdDate": "2023-05-30 16:54:11",
    "cardPan": "403021******9287",
    "cardType": "Visa",
    "fee": "1.82",
    "transactionId": 195662868,
    "type": "verify",
    "recToken": "",
    "transactionStatus": "Declined",
    "reason": "НА СЧЕТЕ НЕ ХВАТАЕТ ДЕНЕГ",
    "reasonCode": "76",
    "pcTransactionID": "1206054482",
    "pcApprovalCode": "145036 A",
    "merchantSignature": "34b4d87da1828419ca79ab909b443eb9"
}

Verify Operation

To check the card, it is necessary to redirect the user to the page of the payment gateway using the POST method at the url https://****.procard-ltd.com/api/ with the following parameters:

Parameter	Type	Description
operation	String	operation type "Verify"
merchant_id	String	merchant identifier
amount	float	Amount of operation. Example: 500.00. Allowed 0
currency_iso	String	Payment currency. Example: UAH
order_id	String	This is a unique transaction number. It is generated on the side of the merchant. It must be unique throughout the work.
approve_url	String	URL to which the user will be redirected in case of a successful operation
decline_url	String	URL to which the user will be redirected in case of unsuccessful operation
cancel_url	String	URL to which the user will be redirected if the operation is canceled
callback_url	String	URL to which information about the payment result and the generated token for further recurring payment will be received
redirect	Integer	1 / 0 - defaults to 1, if the parameter is 0, then the client will not receive redirects, but will receive the url of the payment page
language	String	Payment page language Default ua - Ukrainian, ru - Russian, en - English
secure_type	Integer	Transaction Security Pass Type. The list of possible values see in Dictionary. secure_type parameter values
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string subject to HMAC_SHA512 is generated by concatenating merchant_id, order_id, amount, currency_iso parameters separated by ";" (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

A description of additional request parameters add_params can be found in following section.

According to the results of the operation, the merchant receives a Callback call to the specified callback_url, in which the recToken parameter is returned - a token for further recurring payments.

Request example:

{
    "operation": "Verify",
    "merchant_id": "BO_671a8709e74a7c9",
    "amount": 0,
    "currency_iso": "UAH",
    "order_id": "9ba9990f-fea5-495d-a20a-ae4e7ffb68e3",
    "approve_url": "http://merchant.site/1/approved",
    "decline_url": "http://merchant.site/1/declined",
    "cancel_url": "http://merchant.site/1/canceled",
    "callback_url": "http://merchant.site/callback",
    "redirect": 0,
    "language": "ua",
    "signature": "9f882fdd69c7ddfa992d89c5493a61fc",
    "add_params": {
      "SenderName": "Петренко Петро Петрович"
    }
}

Success response example if "redirect": 0:

{
  "result": 0,
  "url": "https://procard-ltd.com/payment/pay?payment=3a95bdaae73a7388b3a3750023a817a897b43f2295315f2b6e0e12e3db0ced2e6475c2b080dec&lang=ukr"
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Recurrent payments RecPayment (payment by token)

Production url: https://****.procard-ltd.com/api/

To make a recurring payment send a POST request with the following parameters:

Parameter	Type	Required	Description
operation	String	+	Required value for this operation RecPayment
merchant_id	String	+	Merchant ID
amount	Float	+	The amount of the transaction. Example: 500.00
recurring_token	String	+	Token received from PC
order_id	String	+	Unique order number in the merchant system
description	String	+	Purpose of payment
currency_iso	String	+	Currency. Currently only "UAH"
callback_url	String		URL to which information about the payment result and the generated token for further recurring payment will be received
auth_type	Integer		1 - purchase, 2 - pre-authorization. The default is 1.
signature	String	+	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
			The string subject to HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, recurring_token, currency_iso, description separated by “;” (semicolon) in UTF-8 encoding.
			The order of parameters during concatenation is important!

To support the possibility of performing authorization according to the 3DS2 protocol, the following parameters must be additionally transferred to add_params:

Parameter	Type	Required	Description
AReqDetails.OrderID		+	ID of the order
AReqDetails.browserAcceptHeader		+	The content of the payer's browser HTTP headers. The maximum value is 2048 characters
AReqDetails.browserColorDepth		+	A value representing the bit depth of the color palette for displaying images, in bits per pixel. The maximum value is 2 characters. Possible values: 1 - 1 bit; 4 - 4 bits; 8 - 8 bits; 15 - 15 bits; 16 - 16 bits; 24 - 24 bits ; 32 - 32 bits; 48 - 48 bits
AReqDetails.browserIP		+	Browser IP address. Possible value formats: An IPv4 address is specified as four groups of numbers in decimal notation, separated by the character "." For example: 100.12.123.255. An IPv6 address is specified as eight groups of numbers in hexadecimal notation separated by ":". For example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
AReqDetails.browserLanguage		+	Browser language as specified in IETF BCP47. The maximum value is 8 characters
AReqDetails.browserScreenHeight		+	The total height (in pixels) of the screen displayed to the payer. The maximum value is 6 characters
AReqDetails.browserScreenWidth		+	The total width (in pixels) of the screen displayed to the payer. The maximum value is 6 characters
AReqDetails.browserTZ		+	The time difference between UTC and the local time of the payer's browser . Maximum value - 5 characters
AReqDetails.browserUserAgent		+	The content of the User-Agent HTTP header. The maximum value is 2048 characters
AReqDetails.browserJavaEnabled		+	Ability to execute JavaScript in the payer's browser . Possible values: true false
AReqDetails.threeRIInd		+	The type of request that the merchant performs without the participation of the cardholder (recurring payments). Possible values: 01 (recurring payment/transfer); 02 (partial payment); 03 (adding a card); 04 (saving card information); 05 (account identification) records); 80-99 (values reserved for DS use)
AReqDetails.notificationUrl			The URL of the service provider to send CRes.
AReqDetails.deviceChannel		+	The type of device from which the transaction was initiated. Possible values: 01 - merchant's mobile application (App-based); 02 - user's browser (Browser); 03 - online store (3DS Requestor) Currently, only the value is available: 02 - user's browser (Browser).
CReqDetails.WindowWidth		+	The width of the browser window (in pixels) in which pages of the merchant site are displayed
CReqDetails.WindowHeight		+	The height of the browser window (in pixels) in which pages of the merchant site are displayed

The following parameters come in response:

Parameter	Type	Description	Value
code	Integer	Response code	0 - success
message	String/Integer	Response message	Pay attention that the message can be string or number!
status	String	Operation result	APPROVED - successfully DECLINED - operation failed

A description of additional request parameters add_params can be found in following section.

Request example:

{
    "operation": "RecPayment",
    "merchant_id": "TEST_TRADER_2",
    "amount": 3,
    "recurring_token": "052e03dfaab55b6ac1511fee0c552d43ca0818a5ea081b9d06d7df3a1d4e7b8b",
    "order_id": "1686217047097325",
    "description": "Recurrent payment",
    "currency_iso": "UAH",
    "auth_type": 1,
    "signature": "0cf3324fd88d7fe880012c9892ecab1b",
    "add_params": {
      "SenderName": "Петренко Петро Петрович"
    }
}

Success response example:

{
    "code": 0,
    "message": "OK",
    "status": "APPROVED"
}

"status":"APPROVED" - means that the operation was completed successfully

3DS2 response example:

{
    "code": 2002,
    "message": "Need 3DS",
    "status": "INPROCESSING",
    "3ds":true,
    "version":2,
    "d3AcsUrl":"https://acs2-test.procard-ltd.com/",
    "d3CReq":"eyJhY3NUcmFuc0lEIjoiMWZhNTE2N2EtMjQ2My00NWY2LWE2N2MtNDdmZDg2NTI3ZTQ0IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIzNDIzNjdmNi1hZWVjLTRjOWYtYTYyNi0wNjFlMWEyMzQyZGMiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDMiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0",
    "converted_status":9,
    "reasonCode":5100
}

"status":"INPROCESSING" - means that the operation needs 3DS autorization

To verify 3ds, you need to post the form with the d3_creq parameter to d3_acs_url:

<form name="MPIform" action='${d3AcsUrl}' method="POST">
    <input type="hidden" name="creq" value='${d3CReq}'>
</form>

To complete the payment process, if parameter notificationUrl was sent, you must perform "Confirm 3DS Verification".

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Operation failure response example:

{
    "code": 58,
    "message": 58,
    "status": "DECLINED"
}

58 - operation failure code. The list of codes can be found in Dictionary. Answer Codes

Operation Reverse

To reverse payment send a POST request to url https://****.procard-ltd.com/api/reverse with the following parameters:

Parameter	Type	Description
merchant_id	String	Merchant identifier
order_id	String	The unique number of the operation, which was sent in the payment request
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

JSON is returned in response with the following parameters:

Parameter	Type	Description
code	Integer	Response code (1 - success) If the request fails, it contains code from the Dictionary. System Error Codes If the operation fails, it contains code from the Dictionary. Answer Codes
message	String	Text message with query result

Request example:

{
    "merchant_id": "TEST_TRADER_2",
    "signature": "52903ab3f2e17e90990131873d508a4d",
    "order_id": "1686299645210695"
}

Success response example:

{
    "code": 1,
    "message": "ОПЕРАЦИЯ РАЗРЕШЕНА"
}

"code": 1 - means that the operation was successfully

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Operation Complete

To complete payment send a POST request to url https://****.procard-ltd.com/api with the following parameters:

Parameter	Type	Description
operation	String	Complete
merchant_id	String	Merchant identifier
order_id	String	This is the unique transaction number that was sent in the purchase request.
amount	Float	Charged Amount
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

JSON is returned in response with the following parameters:

Parameter	Type	Description
code	Integer	Response code (0 - success). (see Dictionary. System Error Codes)
message	String	Text message with query result

Request example:

{
    "operation": "Complete",
    "merchant_id": "vZmxaajdkbOGWt5ApLojM8ENzCz",
    "signature": "ccfeb05f64643c84beca2e0b179d5c81",
    "order_id": "1686657185399",
    "amount": 2.23
}

Success response example:

{
    "code": 0,
    "message": "Платеж успешно подтвержден"
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Operation Check

To check the payment status send a POST request to url https://****.procard-ltd.com/api/check with the following parameters:

Parameter	Type	Description
merchant_id	String	Merchant identifier
order_id	String	This is a unique transaction number that was sent in a payment request
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

JSON is returned in response.

Success response with the following parameters:

Parameter	Type	Description
code	Integer	0 - successful
message	String	Text message with query result
reasonCode	String	Operation response code. (see Dictionary. Answer Codes)
reason	String	Answer Description
merchantAccount	String	Merchant ID
orderReference	String	Merchant system transaction ID
amount	String	Amount
currency	String	Payment currency
phone	String	Phone number
createdDate	String	Payment date
cardPan	String	Masked card number
cardType	String	Card type
fee	String	Payment commission
transactionId	BigInteger	Transaction ID
transactionStatus	String	Operation Status (see Dictionary. Payment Statuses) If the status is NEEDS-CLARIFICATION, please repeat this request after a while or contact technical support
pcTransactionID	String	Transaction ID in the processing center. The parameter is optional!
pcApprovalCode	String	Authorization code. The parameter is optional!
rrn	String	Reference Retrieval Number

Unsuccessful response with the following parameters:

Parameter	Type	Description
code	Integer	Response code (Dictionary. System Error Codes)
message	String	Text message with query result

Request example:

{
    "merchant_id": "vZmxaajdkbOGWt5ApLojM8ENzCz",
    "order_id": "1686657185399",
    "signature": "c0cf536eb79bf25793bb7996d3839088"
}

Success response for success operation example:

{
    "code": 0,
    "merchantAccount": "vZmxaajdkbOGWt5ApLojM8ENzCz",
    "orderReference": "1686662094017",
    "amount": "2.50",
    "currency": "UAH",
    "phone": "+38 (011) 222-33-44",
    "createdDate": "2023-06-13 16:14:55",
    "cardPan": "403021******9287",
    "cardType": "Visa",
    "fee": "0.02",
    "transactionId": 197387938,
    "transactionStatus": "APPROVED",
    "reason": "ОПЕРАЦИЯ РАЗРЕШЕНА",
    "reasonCode": "1",
    "rrn": "1234567890",
    "pcTransactionID": "1226920964",
    "pcApprovalCode": "88509F A"
}

Success response for unsuccessful operation example:

{
    "code": 0,
    "merchantAccount": "vZmxaajdkbOGWt5ApLojM8ENzCz",
    "orderReference": "5018440306",
    "amount": "16.00",
    "currency": "UAH",
    "phone": "+38 (011) 222-33-44",
    "createdDate": "2023-06-13 10:17:41",
    "cardPan": "537541******4408",
    "cardType": "MasterCard",
    "fee": "0.14",
    "transactionId": 197355512,
    "transactionStatus": "DECLINED",
    "reason": "АВТОРИЗАЦИЯ ОТКЛОНЕНА",
    "reasonCode": "5"
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Operation P2PCredit

To replenish the card send a POST request to url https://****.procard-ltd.com/api with the following parameters:

Parameter	Type	Description
operation	String	transaction type “P2PCredit”
merchant_id	String	merchant identifier
order_id	String	This is a unique transaction number. It is generated on the side of the merchant. It must be unique throughout the work.
amount	Float	The sum of the operation must be a fractional number, with two decimal places. Example: 100.50
currency_iso	String	Transaction currency. Currently only “UAH” is available
card_number	String	Recipient card number.
token	String	Token, can be used instead of the recipient card
visa_alias	String	Instead of a card or token, VisaAlias can be specified If a phone number is used as an alias, it must be provided according to the ITU-T E.164 (2010) Example (phone number): 380670000000
visa_alias_type	String	Alias type. Required if visa_alias is specified
add_params	String	An array with additional parameters for identifying the sender and recipient of transfers. See Dictionary. List of additional fields to identify sender and recipient of transfers
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string subject to HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, card_number/token, currency_iso separated by “;” (semicolon) in UTF-8 encoding
		If visa_alias specified parameter card_number need to be empty string
		The order of parameters during concatenation is important!

Possible values for the visa_alias_type parameter:

• 01 - phone number,
• 02 - email address,
• 03 - national identifier,
• 04 - IBAN (international bank account number)

List of additional parameters for clients with external anti-fraud systems:

Parameter	Description	Value
BrowserIP	Client browser IP address	IPv4 address only: * 220.38.220.38
UserAccountID	Identity number of user account
Fingerprint	Fingerprint

Example of additional parameters:

{
  "add_params": {
    "BrowserIP": "127.0.0.1",
    "UserAccountID": "123315483215",
    "Fingerprint": "asdwsascaw2s1d5ww5a"
  }
}

A description of additional request parameters add_params can be found in following section.

JSON is returned in response with the following parameters:

Parameter	Type	Description	Value
code	Integer	Request result code 0 - successful 12 - operation fail Other codes see Dictionary. System Error Codes
message	String/Integer	Message with query result Pay attention that the message can be string or number!
status	String	Transaction Statuses	APPROVED - translation successful DECLINED - Translation failed ON-PAYMENT - An application for transfer is being processed, it is necessary to request an additional status
transactionID	Integer	Transaction ID in the payment system
approvalCode	Integer	Authorization code
rrn	String	Reference Retrieval Number

Success response example:

{
"code":0,
"message":"OK",
"status":"APPROVED",
"transactionID":"2814211",
"approvalCode":"371623 A",
"rrn":"1234567890"
}

"status":"APPROVED" - means that the operation was completed successfully

Request failure response example:

{
"code":-4,
"message":"Неверная подпись"
}

Operation failure response example:

{
"code":12,
"message":58,
"status":"DECLINED"
}

58 - operation failure code. The list of codes can be found in Dictionary. Answer Codes

Get Aliаs Information

To get alias information you need to send POST request to url https://procard-ltd.com/alias/getinfo with the following parameters:

Parameter	Type	Description
merchantId	String	merchant identifier
alias	String	VisaAlias. If a phone number is used as an alias, it must be provided according to the ITU-T E.164 (2010). Example (phone number): 380670000000
aliasType	String	Alias type
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string subject to HMAC_SHA512 is generated by concatenating the parameters merchant_id, alias, aliasType separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

Possible values for the aliasType parameter:

• 01 - phone number,
• 02 - email address,
• 03 - national identifier,
• 04 - IBAN (international bank account number)

JSON is returned in response with the following parameters:

Parameter	Type	Description
code	Integer	Response code (0 - alias found, 1 - not found). Other codes see Dictionary. System Error Codes
recipientName	String	Recipient name
recipientPrimaryAccountNumber	String	Masked card number
issuerName	String	Bank issuer name

Request example:

{
    "merchantId": "BO_54141bee2e62426",
    "alias": "380670000000",
    "aliasType": "01",
    "signature": "299544b24eb5c623301c83fc1c30b953"
}

Success response example - alias found:

{
    "code": 0,
    "recipientName": "Perto Pertrenko",
    "recipientPrimaryAccountNumber": "516911******8886",
    "issuerName": "UA Bank 1"
}

Success response example - alias not found:

{
    "code": 1,
    "recipientName": "",
    "recipientPrimaryAccountNumber": "",
    "issuerName": ""
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Get Balance Operation

To get operation balance send a POST to the url https://****.procard-ltd.com/api/balance request with the following parameters:

Parameter	Type	Description
merchant_id	String	merchant identifier
date	String	Date and time of request in any format
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, date separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

JSON is returned in response.

Success response with the following parameters:

Parameter	Type	Description
mk_deposit	Float	Mastercard Limit
visa_deposit	Float	Visa Limit
mk_available	Float	Available Balance Mastercard
visa_available	Float	Available Visa Balance

Unsuccess response with the following parameters:

Parameter	Type	Description
code	Integer	Response code (Dictionary. System Error Codes)
message	String	Text message with query result

Request example:

{
    "merchant_id": "TEST_TRADER_2",
    "date": "2023-05-19 15:44:16",
    "signature": "5270d398dd09866a90b9131b447d8684"
}

Success response example:

{
    "mk_deposit": 9999999,
    "visa_deposit": 9999999,
    "mk_available": 9999999,
    "visa_available": 9999999
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Operation P2PDebit

To debit funds from the card you should redirect the user to the payment gateway page using the POST method with the following parameters:

Parameter	Type	Description
operation	String	Operation type "P2PDebit"
merchant_id	String	Merchant identifier
order_id	Integer	This is a unique transaction number. It is generated on the side of the merchant. It must be unique throughout the work.
amount	Float	The sum of the operation must be a fractional number, with two decimal places. Example: 100.50
currency_iso	String	Transaction currency. Currently only “UAH” is available
description	String	Purpose of payment
approve_url	String	URL to which the user will be redirected in case of a successful operation
decline_url	String	URL to which the user will be redirected in case of unsuccessful operation
cancel_url	String	URL to which the user will be redirected if the operation is canceled
callback_url	String	URL to which information about the result of the payment will come
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string subject to HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, currency_iso, description, approve_url, decline_url, cancel_url separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

Information about additional fields for identifying the sender and recipient of transfer can be found in the corresponding directory.

A description of additional request parameters add_params can be found in following section.

Operation PurchaseOnMerchant

To pay on the merchant’s payment page you should send a POST-request with the following data.

Production url: https://****.procard-ltd.com/api/

POST parameters:

Parameter	Type	Description	Value
operation	String	Type of transaction	PurchaseOnMerchant
merchant_id	String	merchant identifier
amount	Float	The amount of the transaction. Example: 500.00
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, currency_iso, description separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!
order_id	String	Unique transaction number on the merchant side. If the operation is duplicated, the merchant receives an error.
currency_iso	String	Currency of payment	UAH
description	String	Purpose of payment. It is displayed on the payment page when entering payment details. Displayed in the account statement and registries
add_params		An array with additional parameters. Additional parameters are then returned to the merchant in a callback call
token	String	Token for debiting from a card without transferring card details. Either a token or card details must be passed.
card_num	String	Card number
card_exp_month	String	Validity of MM card
card_exp_year	String	YY card expiration date
card_cvv	String	CVV2 code, in case of operation without CVV specify -1
card_holder	String	Card owner. Optional field
phone	String	Customer Phone Number Optional field
auth_type	Integer	Type of payment 1 - Purchase - purchase (by default) 2 - PreAuth - blocking funds on the card
secure_type	String	Transaction Security Pass Type. The list of possible values see in Dictionary. secure_type parameter values
callback_url	String	URL to which information about the result of the payment will come

To support the possibility of performing authorization according to the 3DS2 protocol, the following parameters must be additionally transferred to add_params:

Parameter	Type	Required	Description
AReqDetails.OrderID	String	+	ID of the order
AReqDetails.browserAcceptHeader	String	+	The content of the payer's browser HTTP headers. The maximum value is 2048 characters
AReqDetails.browserColorDepth	String	+	A value representing the bit depth of the color palette for displaying images, in bits per pixel. The maximum value is 2 characters. Possible values: 1 - 1 bit; 4 - 4 bits; 8 - 8 bits; 15 - 15 bits; 16 - 16 bits; 24 - 24 bits ; 32 - 32 bits; 48 - 48 bits
AReqDetails.browserIP	String	+	Browser IP address. Possible value formats: An IPv4 address is specified as four groups of numbers in decimal notation, separated by the character "." For example: 100.12.123.255. An IPv6 address is specified as eight groups of numbers in hexadecimal notation separated by ":". For example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
AReqDetails.browserLanguage	String	+	Browser language as specified in IETF BCP47. The maximum value is 8 characters
AReqDetails.browserScreenHeight	String	+	The total height (in pixels) of the screen displayed to the payer. The maximum value is 6 characters
AReqDetails.browserScreenWidth	String	+	The total width (in pixels) of the screen displayed to the payer. The maximum value is 6 characters
AReqDetails.browserTZ	String	+	The time difference between UTC and the local time of the payer's browser . Maximum value - 5 characters
AReqDetails.browserUserAgent	String	+	The content of the User-Agent HTTP header. The maximum value is 2048 characters
AReqDetails.browserJavaEnabled	Boolean	+	Ability to execute JavaScript in the payer's browser . Possible values: true false
AReqDetails.threeRIInd	String	+	The type of request that the merchant performs without the participation of the cardholder (recurring payments). Possible values: 01 (recurring payment/transfer); 02 (partial payment); 03 (adding a card); 04 (saving card information); 05 (account identification) records); 80-99 (values reserved for DS use)
AReqDetails.notificationUrl	String	+	The URL of the service provider to send CRes.
AReqDetails.deviceChannel	String	+	The type of device from which the transaction was initiated. Possible values: 01 - merchant's mobile application (App-based); 02 - user's browser (Browser); 03 - online store (3DS Requestor) Currently, only the value is available: 02 - user's browser (Browser).
CReqDetails.WindowWidth	String	+	The width of the browser window (in pixels) in which pages of the merchant site are displayed
CReqDetails.WindowHeight	String	+	The height of the browser window (in pixels) in which pages of the merchant site are displayed

To support the possibility of performing antifraud check, the following parameters must be additionally transferred to add_params:

Parameter	Type	Required	Description
BrowserIP	String	+	Browser IP address. Possible value formats: An IPv4 address is specified as four groups of numbers in decimal notation, separated by the character "." For example: 100.12.123.255. An IPv6 address is specified as eight groups of numbers in hexadecimal notation separated by ":". For example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
UserAccountID	String	+	Identifier of the transacting user’s Browser Account ID.
Fingerprint	String	+	Platform-calculated device fingerprint.

A description of additional request parameters add_params can be found in following section.

Answer:

Parameter	Type	Description	Value
status	String	Payment status	Dictionary. Payment Statuses
code	Integer	Response code	Dictionary. Answer Codes
order_id	String	Unique order number in the merchant system
amount	Float	Amount of payment
fee	Float	Commission
currency	String	Payment currency
token	String	Token for subsequent payments. Token will be returned if payment is successful
		- If it is necessary to perform authorization according to the 3DS1 protocol, the following parameters will be returned:
d3_acs_url	String	Acs URL of the server to which the user must be sent for verification
d3_md	String	The unique identifier that must be transmitted to the ACS server
d3_pareq	String	Request to transfer to ACS server
		- If it is necessary to perform authorization according to the 3DS2 protocol, the following parameters will be returned:
d3_acs_url	String	Acs URL of the server to which the user must be sent for verification
d3_creq	String	Request to transfer to ACS server
transaction_key	String	Transaction key that must be used to confirm payment
transaction_id	String	Transaction ID
rrn	String	Reference Retrieval Number
signature	String	Operation signature

If the response code returns 2001, a 3DS verification is required.

To verify 3ds, you should use the POST method to send a form with the parameters d3_md, d3_pareq, term_url to d3_acs_url.

term_url - merchant url to return from 3DS verification.

<form name="MPIform" action='${d3_acs_url}' method="POST">
<input type="hidden" name="PaReq" value='${d3_pareq}'>
<input type="hidden" name="MD" value='${d3_md}'>
<input type="hidden" name="TermUrl" value='${term_url}'>
</form>

If the response code returns 2002, a 3DS2 verification is required.

To verify 3ds, you need to post the form with the d3_creq parameter to d3_acs_url.

<form name="MPIform" action='${d3_acs_url}' method="POST">
    <input type="hidden" name="creq" value='${d3_сreq}'>
</form>

To complete the payment process, you must perform "Confirm 3DS Verification".

The confirmation of 3DS Verification

To complete the payment on the merchant's payment page after executing 3DS, it is necessary to send a POST request with the following data

Production url: https://****.procard-ltd.com/api/

Parameter	Type	Description	Value
operation	String	Type of transaction	Complete3DS
transaction_key	String	The transaction key previously received in response to the payment request
merchant_id	String	Merchant identifier
		- If authorization was performed using the 3DS1 protocol, transfer the parameters:
d3ds_md	String	ID received after redirect from ACS server
d3ds_pares	String	Message received after redirect from ACS server
		- If authorization was performed using the 3DS2 protocol, transfer the parameters:
d3ds_cres	String	Message received after redirect from ACS server
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, transaction_key, d3ds_md, d3ds_pares separated by “;” (semicolon) in UTF-8 encoding.
		If d3ds_cres is passed, empty lines should be added as d3ds_md, d3ds_pares in the signature.
		The order of parameters during concatenation is important!

Answer:

Parameter	Type	Description	Value
status	String	Payment status	Dictionary. Payment Statuses
code	Integer	Response code	Dictionary. Answer Codes
order_id	String	Unique order number in the merchant system
amount	Float	Amount of payment
fee	Float	Commission
currency	String	Payment currency
card_pan	String	Masked card number
cardType	String	Card type	Visa MasterCard
transaction_id	String	Transaction ID
rrn	String	Reference Retrieval Number

Getting a token for Masterpass

Production url: https://****.procard-ltd.com/api/mptoken

To make a payment with Masterpass, you need to send a POST request with the following data:

Parameter	Type	Description
msisdn	String	Masterpass wallet phone number in format 380XXXXXXXXX
client_id	String	Customer ID in MasterPass

The response comes in an object in JSON format with the following parameters:

Parameter	Type	Description
res	Integer	Query result (0 - success)
msg	String	Error message
token	String	Token for transferring to the mfs library
reference_no	String	Unique Request Number

Making a payment through Masterpass

Production url: https://****.procard-ltd.com/api

To receive a guest token send a POST request with the following data.

Parameter	Type	Description	Value
operation	String	Type of transaction	PurchaseMasterpass
merchant_id	String	merchant identifier
amount	Float	Amount of payment in the format 1.00
order_id	String	Unique transaction number on the merchant side. If the operation is duplicated, the merchant receives an error.
currency_iso	String	Currency	UAH
description	String	Payment Description
approve_url	String	Redirect URL after successful payment (in case of 3DS confirmation on the ProcardPay page)
decline_url	String	Redirect URL after a failed payment (in case of 3DS confirmation on the ProcardPay page)
cancel_url	String	Redirect URL after cancellation of payment (in case of 3DS confirmation on the ProcardPay page)
callback_url	String	URL to which callback about payment status will be sent
add_params[wallet]	String	Wallet sign	masterpass
add_params[msisdn]	String	Masterpass wallet phone number in 380XXXXXXXXX format
add_params[token]	String	Token received from MasterPass server
add_params[card_name]	String	Alias cards received from MasterPass server
add_params[client_id]	String	Merchant ID in MasterPass
add_params[ret_ref_no]	String	Unique transaction number received from MasterPass server
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, currency_iso, description separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

The response comes in an object in JSON format with the following parameters:

If a transaction requires 3DS confirmation:

Parameter	Type	Description
code	Integer	Response code
status	String	Transaction status, if 3DS verification is required, the status will be 3ds
d3AcsUrl	String	url to redirect client to check 3ds
d3Md	String	Cryptogram for transferring to a 3DS host
d3Pareq	String	Request to transfer to 3DS host
transaction_key	String	3DS transaction key
TermUrl	String	Url to redirect after entering the verification code on the 3DS page
		By default, the url to the ProcardPay page, you can specify your URL to check 3DS, then after passing 3DS you need to call the "Confirm 3DS Verification" method

To complete the payment process, you must perform "Confirm 3DS Verification".

Payment on the payment splitting processing page

To pay on the payment processing page redirect to the page of the processing center, with POST data.

Production url: https://****.procard-ltd.com/api/

POST parameters:

Parameter	Type	Description	Value
operation	String	Type of transaction	Purchase
merchant_id	String	merchant identifier
amount	Float	The amount of the transaction. Example: 500.00
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, order_id, amount, currency_iso, description separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!
order_id	String	Unique transaction number on the merchant side. If the operation is duplicated, the merchant receives an error.
currency_iso	String	Currency of payment	UAH
description	String	Purpose of payment. It is displayed on the payment page when entering payment details. Displayed in the account statement and registries
add_params	Array	An array with additional parameters. Additional parameters are then returned to the merchant in a callback call
split	String	Sign of payment splitting	0 - не расщеплять 1 - расщеплять
split_rules	Array	An array with splitting rules that contains the identifiers of the submerchant and amount.
		The amount of splits must match the amount of payment.
		Example:
		split_rules[0][sub_merchant_id]=test1&split_rules[0][amount]=100.00&split_rules[1][sub_merchant_id]=test2&split_rules[1][amount]=50.00&.......&split_rules[n][sub_merchant_id]=testn&split_rules[n][amount]=10.00
approve_url	String	Redirect URL in case payment is successful
decline_url	String	Redirect URL in case payment is unsuccessful
cancel_url	String	Redirect URL in case the user refuses to make a payment
callback_url	String	URL to which information about the result of the payment will come

Card range information

To get card range information send POST data to url https://****.procard-ltd.com/api/bas

Parameter	Type	Description	Value
merchant_id	String	merchant identifier
range	String	First 9 digits of card number
signature	String	In order to confirm the validity of the data, a verification signature must be generated and transmitted in the HMAC_SHA512 request using the SecretKey merchant.
		The string to be HMAC_SHA512 is generated by concatenating the parameters merchant_id, range separated by “;” (semicolon) in UTF-8 encoding.
		The order of parameters during concatenation is important!

The response comes in an object in JSON format.

Success response with the following parameters (set of parameters depends on service level):

Field Name	Type	Attribute Description	Level 1 (Base)	Level 2 (Full)
code	Integer	Error code. If 0 - success	X	X
minRange	Integer	Account Range Minimum	X	X
maxRange	Integer	Account Range Maximum	X	X
brandCd	String	Brand Indicator	X	X
issuerBin	String	Issuer BIN	X	X
binLength	String	BIN Length	X	X
sharedBinInd	String	Shared BIN Indicator	X	X
posdomesticOnlyInd	String	Domestic-Use-Only Flag	X	X
onlineGamblBlockInd	String	Online Gambling Block	X	X
binRangePaymentAccountType	String	Token Indicator	X	X
issuerBillingCurrCd	String	Issuer Billing Currency		X
accountCtryAlpha2Code	String	Issuer Country Code		X
platformCd	String	Product Platform		X
productId	String	Product ID		X
productIdName	String	Product Name		X
accountFundingSourceCd	String	Account Funding Source		X
accountFundingSourceSubtypeCd	String	Account Funding Source Subtype		X
accountBusName	String	Issuer Name		X

Unsuccessful response with the following parameters:

Parameter	Type	Description
code	Integer	Error code (Dictionary. System Error Codes)
message	String	Error text message

Request example:

{
    "merchant_id": "jnmx9smJQmSejKoR3rIgm5Pj7QG",
    "range": "473118560",
    "signature": "babf4304e88d9a6e000c167cfcdc9e5a"
}

Success response example:

{
    "minRange": 473118550,
    "maxRange": 473118569,
    "brandCd": "VISA",
    "issuerBin": 473118,
    "binLength": 6,
    "sharedBinInd": "N",
    "posdomesticOnlyInd": "N",
    "onlineGamblBlockInd": "Y",
    "binRangePaymentAccountType": "P",
    "issuerBillingCurrCd": "USD",
    "accountCtryAlpha2Code": "UA",
    "platformCd": "CN",
    "productId": "F",
    "productIdName": "Visa Classic",
    "accountFundingSourceCd": "D",
    "accountFundingSourceSubtypeCd": null,
    "accountBusName": "JSC CB PRIVATBANK",
    "code": 0
}

Request failure response example:

{
    "code": -4,
    "message": "Неверная подпись"
}

Additional request parameters

The request must also pass the following additional parameters to add_params:

Parameter	Type	Required	Description
SenderName or RecipientName (for P2PCredit)	String	+	Sender's full name in Cyrillic. Example: Петренко Петро Петрович
IdentityNumber	String	+	Tax identity number