/Preauthorization - Ukrcard en

Подивится українською

The Preauthorization request is used to complete a preauthorized payment in the case of a two-phase payment.
A merchant can perform this request if it has the relevant permissions in the system.

Request

Header Params

ExtSystemid

string

required

The identifier of the external system (ES) that generated the request. The identifier agrees with UKRKART during the registration of the ES

>= 1 characters<= 50 characters

Example:

ECOM_GOLD_BANK

string

required

External system login received from UKRKARD during registration

>= 1 characters<= 30 characters

Example:

SECURE_LOGIN

password

string

required

External system password received from UKRKARD during registration

>= 1 characters<= 30 characters

Example:

SECURE_PASSWORD

orderNumber

string

required

Number (identifier) of the order in the merchant’s online
store system. It is unique for every store in the system and
is generated on the order registration

>= 1 characters<= 32 characters

Example:

1234

orderId

string

optional

Number generated by wsGate after the registration of the order.

>= 36 characters<= 36 characters

Example:

dbafea6c-3394-4f6a-a0d2-21d3d8e93e42

RegDate

string <date-time>

required

Date/time of the request in yyyy-MM-dd HH:mm:ss format

<= 19 characters

Example:

2023-09-12 12:16:00

Match pattern:

YYYY-MM-DD hh:mm:ss

x-uws-clientdn

string

required

The specified value must be equal to the value specified in the Common Name (CN) field for the client's SSL certificate

<= 500 characters

Example:

GOLDENBANK

Content-Type

string

optional

application/json;charset=UTF-8

Example:

application/json;charset=UTF-8

charset

string

optional

UTF-8

Example:

UTF-8

enum<string>

required

application/json

Allowed value:

application/json

Body Params application/json

orderData

object

required

Transaction registration data

amount

number

150000

required

Order amount in the minor denomination (for example, cents). You can use a verification operation such as Debit Verify (which is similar to a Visa account and a Mastercard account) for a zero amount for additional 3DS authentication. For these operations, you must use the primary method /Payment with a zero amount. 3DS authentication will be present for MPS Visa and Mastercard cards. For NPS Prostir cards, the primary operation will be to verify the cloud record.

<= 10000000000000000000

currency

string

optional

Payment currency code in the ISO 4217 format. If it is not indicated, it must be entered equal to the currency code according to the rules (980 - UAH)

>= 3 characters<= 3 characters

externalFee

string

optional

Fee amount in the minor denomination of the currency. This can only be done for the p2pTransfer method

<= 9 characters

description

string

required

Free form description of the order.

<= 512 characters

sender

object

required

Details of the sender/payer

pan

string

required

Card number of the sender/payer (the card from which the transfer/purchase is made). Not used for A2C

<= 20 characters

expiry

string

required

Card expiration date of the sender/payer (the card from which the transfer/purchase is made). The date format is YYMM. Not used for A2C

<= 4 characters

Example:

2412

Match pattern:

YYMM

cvc

string

required

CVV2/CVC2 of the sender/payer card. Not used for A2C

>= 3 characters<= 3 characters

Example:

123

Match pattern:

^\d+$

senderCardName

string

required

Name of sender/payer (transferred values must be specified separately 'FirstName [MidName,] LastName', separated by ' ' space.). It is necessary to exclude the use of comma ',' and colon ':' as separators inside the values passed in the current tag/parameter. Not used for A2C.

<= 25 characters

senderAddress

string

optional

Sender's address. It is necessary to exclude the use of comma ',' and colon ':' as separators inside the values passed in the current tag/parameter. Not used for A2C, Payment

<= 35 characters

senderCity

string

optional

Sender's city. It is necessary to exclude the use of comma ',' and colon ':' as separators inside the values passed in the current tag/parameter. Not used for A2C, Payment.

<= 25 characters

Example:

Kyiv

senderCountry

string

optional

Country of sender. Not used for A2C, Payment.

>= 3 characters<= 3 characters

Example:

804

senderPostalCode

string

optional

Postal code of the sender. Not used for A2C, Payment.

<= 8 characters

Example:

M79019

sendercardalias

string | null

optional

The field is filled with the value of the card username, it makes sense to fill in the value when creating the token
sendertoken = 'publish'.
The filling and the value passed in the current tag are not controlled.
Used when creating the token

sendertoken

string | null

optional

When ordering a new payment jwt token, the field is filled with the value 'publish'.
When a payment transaction is required using a payment token, the tag is filled with the value of the payment jwt token.

pageData

object

required

External system page data

language

string

required

The language of the current page session

>= 2 characters<= 2 characters

Example:

returnUrl

string

required

URL to which the customer is redirected after a successful payment. The address must be specified in full, including the protocol used (for example, "https://test.ua" instead of test.ua). Otherwise, the user will be redirected to the default address

<= 512 characters

failUrl

string

required

Web address to which the customer is redirected if the payment fails. The address must be specified in full, including the protocol used (for example, https://test.ua instead of test.ua). Otherwise, the user will be redirected by default

<= 512 characters

browserParams

object

required

User browser properties

javascriptEnabled

string

required

A parameter that indicates whether Javascript support is enabled for the cardholder's browser

Example:

true

userAgent

string

required

The user's browser agent string

Example:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.3

colorDepth

string

required

The color depth of the user's device screen

<= 3 characters

Example:

screenHeight

string

required

Screen height of the cardholder's device

screenWidth

string

required

Screen width of the cardholder's device

javaEnabled

boolean

required

A parameter that indicates whether Java support is enabled for the cardholder's browser

Default:

true

browserLanguage

string

required

User's browser language

Example:

uk-UA

browserTimeZone

string

required

User's browser time zone

Example:

Europe/Kiev

browserAcceptHeader

string

required

A parameter that informs the server to which the browser sends a request, those file formats (MIME types) that are acceptable to the browser as a response

Example:

*/*

browserIpAddress

string

required

IP address of the card holder's browser

>= 3 characters<= 5 characters

Example:

192.139.102.100

browserTimeZoneOffset

string

required

Time zone offset of the user's browser

>= 3 characters<= 5 characters

Example:

-120

fingerprint

string

optional

Information collected from the device's browser for further identification

string

optional

The operating system used by the cardholder device

osversion

string

optional

The version of the operating system used on the cardholder's device

mobile

string

optional

The parameter that determines the device of the owner of the mobile card

screenPrint

string

optional

Information about the screen resolution of the cardholder's device

plugins

string

optional

A list of plug-in modules installed in the cardholder's device browser.

deviceType

string

optional

The type of device on which the browser is running (mobile phone, computer, tablet, etc.).

device

string

optional

Card holder device information (model, version, etc.).

fmparam

object

optional

Block for transmitting a list of additional parameters used to implement the regulator's requirements for transmitting information about the payer in a payment transaction, and used for financial monitoring. The obligation to transmit parameters in the specified tag for each method is specified in the requirements (application) of the acquiring bank for registration of terminals.

ReceiverCNAME

string

optional

Recipient name (legal entity)
(Only characters in encoding (UTF-8) are used, without using Unicode escapes!)

ReceiverEDRPOU

string

optional

Recipient's EDRPOU (legal entity) 8 digits

>= 8 characters<= 8 characters

Match pattern:

^[0-9]

ReceiverIBAN

string

optional

IBAN number (legal entity) of the recipient in the format for Ukraine.
Must start with UA, followed by 2 check digits, 6 characters of the MFO of the corresponding bank, and 19 characters of the bank account number. Total length — 29 characters.
Only IBANs issued by Ukrainian banks are supported.

>= 29 characters<= 29 characters

Match pattern:

^UA\d{2}\d{6}\d{19}$

SenderCNAME

string

optional

Name of the payer (legal entity)
(Only characters in encoding (UTF-8) are used, without using Unicode escapes!)

SenderEDRPOU

string

optional

Payer's Unified State Register of Accounts (legal entity) 8 digits

>= 8 characters<= 8 characters

SenderIBAN

string

optional

IBAN number of the payer (legal entity) in the format for Ukraine.

Must start with UA, followed by 2 check digits, 6 characters of the MFO of the corresponding bank, and 19 characters of the bank account number. Total length — 29 characters.
Only IBANs issued by Ukrainian banks are supported.

>= 29 characters<= 29 characters

Match pattern:

^UA\d{2}\d{6}\d{19}$

SenderPIB

string

optional

Full name of the payer (individual)
(Only characters in encoding (UTF-8) are used, without using Unicode escapes!)

SenderITN

string

optional

Taxpayer's INN (individual) 10 digits
(or passport number and series, if the person does not have a INN)

ReceiverPIB

string

optional

Full name of the recipient (individual)
(Only characters in encoding (UTF-8) are used, without using Unicode escapes!)

ReceiverITN

string

optional

TIN of the recipient (individual) 10 digits
(or passport number and series, if the person does not have a TIN)

TranID

string

optional

Transaction identifier in external systems, can be used as additional information for reconciliations if required by the acquiring bank

Example

{
    "sender": {
        "cvc": "576",
        "senderCardName": "Test Test",
        "expiry": "2606",
        "pan": "5248721588681850",
        "sendercardalias": "My card for ZP 1",
        "sendertoken": "publish"
    },
    "orderData": {
        "amount": 30000,
        "description": "Paymnet order 12345",
        "currency": 980
    },
    "pageData": {
        "language": "uk",
        "returnUrl": "https://order.ukrcard.ua/acquiring/acquiringresult?id=8646997",
        "failUrl": "https://order.ukrcard.ua/acquiring/acquiringresult?id=8646997"
    },
    "jsonParams": {
        "disableEmail": "true",
        "disablePhone": "true"
    },
    "browserParams": {
        "javascriptEnabled": true,
        "userAgent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Mobile Safari/537.36",
        "colorDepth": 24,
        "screenHeight": 892,
        "screenWidth": 412,
        "javaEnabled": false,
        "browserLanguage": "ro-MD",
        "browserTimeZone": "Europe/Chisinau",
        "browserAcceptHeader": "*/*",
        "browserIpAddress": "94.139.152.182",
        "browserTimeZoneOffset": 120
    }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

orderParam

object

required

orderStatus

integer

required

orderId

string

required

orderVerifyFlag

integer

required

orderAuthParam

object

required

fee

null

required

auth3DData

object

required

paReq

null

required

acsurl

string

required

creq

string

required

Examples

SuccessException

{
    "orderParam": {
        "orderStatus": 1,
        "orderId": "7a7dee7f-5d0f-43f7-8d44-d0e646641743",
        "orderAuthParam": {
            "approvalCode": "951678",
            "authCode": 2
        }
    },
    "fee": null,
    "auth3DData": {
        "acsurl": null,
        "paReq": null,
        "creq": null
    },
    "tokeninfo": {
        "tokenid": "294685",
        "tokenexpiry": "2024-10-19T16:07:06",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQiOiJwYW5DbGllbnQiLCJpZCI6IjY3MGUzMGJhNzMyYjc0YmVmMmZkNjM3OCIsInBhbl9tYXNrIjoiNTEyNzQzKioqKioqMjg5MCIsImV4cGRhdGUiOiIyOTA3IiwiY29uZl9kYXRhIjoiMWViMDUwYjJhNDE5OTI2YTRjZDk1MzdjM2M4NTczODc1ODE2YTgwYmY3ZjIzMWU2OTQ1OWEzNDliZjI2MTU4YzBlMDM4ODVhMjE5YzYyNWViNThiYzVkNmMyZjIxOTFkYTkzMWJlMDE5NmNlMTIzY2IzOWU5ODgzYzZhYTFiNjgxZDhhZWZkY2I4YTk2YzRiNDA5MzI1Y2JlYTFjNzYyNDUzNDgzZTViZDJmOTdiMjk1YjViY2ZmMDUxZGQxODM3OTRmNWYwNDdmYWEyZDU4MmJiOGViMWU2ZTNlNTk2ZjVjYjQ5MzMwZDJkN2E0NGJhMTQ0MDdmODYyYjJhYjZkOSIsInN1YiI6IjI5NDY4NSNNeSBjYXJkIGZvciBaUCM1MTI3IyMjIyMjMjg5MCMiLCJleHAiOjE3MjkzNDMyMjZ9.GhQVizQxLRy-0rB-CN5ePOtTF8-6zN6rqDoKgpDnskI"
    }
}