/Payment

Developing

Cloud Mock

https://mock.apidog.com/m1/483896-0-default

POST

/Payment

Maintainer:Not configured

Ініціація виконання операції «платіж» зовнішньою системою, що використовує власний веб-інтерфейс з можливістю замовлення та отримання токену при успішній платіжній опекрації або виконання платіжної операції по отриманому токену.

Request

Header Params

ExtSystemid

string

required

Ідентифікатор зовнішньої системи (ЗС), яка сформувала запит. Ідентифікатор погоджується з УКРКАРТ під час реєстрації ЗС

Example:

ECOM_GOLD_BANK

string

required

Логін ЗС у системі, отриманий від УКРКАРТ при підключенні

Example:

SECURE_LOGIN

password

string

required

Пароль ЗС у системі, отриманий від УКРКАРТ при підключенні

Example:

SECURE_PASSWORD

orderNumber

string

required

Номер (ідентифікатор) операції у зовнішній системі. Значення має бути унікальним для кожної системи в її межах.

Example:

1234

orderId

string

optional

Унікальний ідентифікатор операції в системі. Призначається системою при обробці платіжного запиту.

Example:

dbafea6c-3394-4f6a-a0d2-21d3d8e93e42

RegDate

string

required

Дата/час запиту у форматі yyyy-MM-dd HH:mm:ss

Example:

2023-09-12 12:16:00

x-uws-clientdn

string

required

Зазначене значення має дорівнювати значенню, указаному в полі Common Name (CN) для сертифіката SSL клієнта

Example:

GOLDENBANK

Content-Type

string

optional

application/json;charset=UTF-8

Example:

application/json

charset

string

optional

UTF-8

Example:

UTF-8

string

required

application/json

Example:

application/json

Body Params application/json

orderData

object

required

Реєстраційні дані транзакції

amount

number

150000

required

Сума операції в мінімальних одиницях валюти. Можна використовувати операцію перевірки, як-от Debit Verify (відповідність перевірці рахунку Visa та запиту стану рахунку Mastercard) для нульової суми за допомогою автентифікації 3DS. Для цих операцій ви повинні використовувати звичайний метод /Payment з нульовою сумою. Аутентифікація 3DS буде присутня для карт MPS Visa та Mastercard. Для карт NPS Prostir це буде звичайна операція перевірки облікового запису.

<= 10000000000000000000

currency

string

optional

Код валюти транзакції ISO 4217. Якщо не вказано, вважається рівним коду валюти за умовчанням (980 - UAH)

>= 3 characters<= 3 characters

externalFee

string

optional

Сумма комісій в мінімальних одиницях валюти. Може бути використано тільки для методу p2pTransfer

<= 9 characters

description

string

required

Опис платежу

<= 512 characters

sender

object

required

Реквізити відправника/платника

pan

string

required

Номер картки відправника/платника (карта з якої здійснюється переклад/купівля). Не використовується для A2C

<= 20 characters

expiry

string

required

Дата закінчення терміну дії картки відправника/платника (карти з якої провадиться переказ/купівля). Формат дати YYMM. Не використовується для A2C

<= 4 characters

Example:

2412

Match pattern:

YYMM

cvc

string

required

CVV2/CVC2 картки відправника/платника. Не використовується для A2C

>= 3 characters<= 3 characters

Example:

123

Match pattern:

^\d+$

senderCardName

string

required

Ім'я відправника/платника (передані значення необхідно вказувати окремо 'FirstName [MidName,] LastName', з розділенням ' ' пробілом.). Необхідно виключити використання як роздільників всередині значень, що передаються в поточному тегу/параметрі, символи: кома ‘,’ та двокрапка ‘:’. Не використовується для A2C.

<= 28 characters

senderAddress

string

optional

Адреса відправника. Необхідно виключити використання як роздільників всередині значень, що передаються в поточному тегу/параметрі, символи: кома ',' і двокрапка ':'. Не використовується для A2C, Payment

<= 35 characters

senderCity

string

optional

Місто відправника. Необхідно виключити використання як роздільників всередині значень, що передаються в поточному тегу/параметрі, символи: кома ',' і двокрапка ':'. Не використовується для A2C, Payment.

<= 25 characters

Example:

Kyiv

senderCountry

string

optional

Країна відправника. Не використовується для A2C, Payment.

>= 3 characters<= 3 characters

Example:

804

senderPostalCode

string

optional

Поштовий код відправника. Не використовується для A2C, Payment.

<= 8 characters

Example:

M79019

sendercardalias

string

optional

Поле заповнюється значенням назви користувача карти, має сенс заповнення значенням при створенні токена
sendertoken = 'publish'.
Заповнення та значення, передане в поточному тегу, не контролюється.
Використовується при створенні токена.

<= 200 characters

sendertoken

string

optional

При замовленні отримання нового платіжного jwt-токена поле заповнюється значенням 'publish'.
При вимозі виконання платіжної операції з використанням платіжного токену тег заповнюється значенням платіжного jwt-токена.

<= 1000 characters

pageData

object

required

Дані сторінки зовнішньої системи

language

string

required

Мова поточної сесії сторінки

>= 2 characters<= 2 characters

Example:

returnUrl

string

required

Адреса, на яку треба перенаправити користувача за успішної оплати. Адреса повинна бути вказана повністю, включаючи протокол, що використовується (наприклад, "https://test.ua" замість test.ua). В іншому випадку, користувач буде перенаправлений за адресою за умовчанням

<= 512 characters

failUrl

string

required

Адреса, на яку потрібно перенаправити користувача у разі неуспішної оплати. Адреса повинна бути вказана повністю, включаючи протокол, що використовується (наприклад, https://test.ua замість test.ua). В іншому випадку користувач буде перенаправлений за замовчуванням

<= 512 characters

browserParams

object

required

Властивості браузера користувача

javascriptEnabled

string

required

Параметр, який вказує, чи активовано підтримку Javascript для браузера власника картки

Example:

true

userAgent

string

required

Рядок агента браузера користувача

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

Глибина кольору екрана пристрою користувача

<= 3 characters

Example:

screenHeight

string

required

Висота екрану пристрою власника картки

screenWidth

string

required

Ширина екрану пристрою власника картки

javaEnabled

boolean

required

Параметр, який вказує, чи активовано підтримку Java для браузера власника картки

Default:

true

browserLanguage

string

required

Мова браузера користувача

Example:

uk-UA

browserTimeZone

string

required

Часовий пояс браузера користувача

Example:

Europe/Kiev

browserAcceptHeader

string

required

Параметр, що інформує сервер, на який браузер відправляє запит, ті формати файлів (MIME-типи) які прийнятні для браузера як відповідь

Example:

*/*

browserIpAddress

string

required

IP-адреса браузера власника картки

>= 3 characters<= 5 characters

Example:

192.139.102.100

browserTimeZoneOffset

string

required

Зсув часового поясу браузера користувача

>= 3 characters<= 5 characters

Example:

-120

fingerprint

string

optional

Інформація, що збирається з браузера пристрою для подальшої ідентифікації

string

optional

Операционная система, используемая устройством держателя карти

osversion

string

optional

Версія операційної системи, яка використовується на пристрої держателя карти

mobile

string

optional

Параметр, який визначає пристрій власника карти мобільного

screenPrint

string

optional

Інформація про роздільну здатність екрана пристрою власника картки

plugins

string

optional

Список модулів, що підключаються, встановлених у браузері пристрою власника картки.

deviceType

string

optional

Тип пристрою, на якому запущено браузер (мобільний телефон, комп'ютер, планшет тощо).

device

string

optional

Інформація про пристрій утримувача картки (модель, версія тощо).

fmparam

object

optional

Блок для передачі списку додаткових параметрів, що використовуються для реалізації вимог регулятора щодо передачі інформації про платника в платіжній операції, і використовуватися для фінмоніторингу. Обов'язковість передачі параметрів у зазначеному тегу для кожного методу вказується у вимогах (заявці) банку - еквайра на реєстрацію терміналів.

ReceiverCNAME

string

optional

Назва отримувача (юридична особа)
(Використовуються тільки символи в кодуванні (UTF-8), без використання Unicode-ескейпів!)

ReceiverEDRPOU

string

optional

ЄДРПОУ отримувача (юридична особа) 8 цифр

>= 8 characters<= 8 characters

Match pattern:

^[0-9]

ReceiverIBAN

string

optional

IBAN-номер (юридичної особи) отримувача у форматі для України.
Має починатися з UA, далі - 2 контрольні цифри, 6 символів МФО відповідного банку, та 19 символів номера банківського рахунку. Загальна довжина — 29 символів.
Підтримуються лише IBAN, випущені українськими банками.

>= 29 characters<= 29 characters

Match pattern:

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

SenderCNAME

string

optional

Назва платника (юридична особа)
(Використовуються тільки символи в кодуванні (UTF-8), без використання Unicode-ескейпів!)

SenderEDRPOU

string

optional

ЄДРПОУ платника (юридична особа) 8 цифр

>= 8 characters<= 8 characters

SenderIBAN

string

optional

IBAN-номер платника (юридична особа) у форматі для України.
Має починатися з UA, далі - 2 контрольні цифри, 6 символів МФО відповідного банку, та 19 символів номера банківського рахунку. Загальна довжина — 29 символів.
Підтримуються лише IBAN, випущені українськими банками.

>= 29 characters<= 29 characters

Match pattern:

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

SenderPIB

string

optional

ПІБ платника (фізична особа)
(Використовуються тільки символи в кодуванні (UTF-8), без використання Unicode-ескейпів!)

SenderITN

string

optional

IПН платника (фізична особа) 10 цифр
(або номер та серію паспорту, якщо особа не має IПН)

ReceiverPIB

string

optional

ПІБ – отримувача (фізична особа)
(Використовуються тільки символи в кодуванні (UTF-8), без використання Unicode-ескейпів!)

ReceiverITN

string

optional

ІПН отримувача (фізична особа) 10 цифр
(або номер та серію паспорту, якщо особа не має IПН)

TranID

string

optional

Ідентифікатор операції у зовнішніх системах, може використовуватися як додаткова інформація для звірок, якщо цього вимагає банк еквайєр

Example

{
    "sender": {
        "cvc": "576",
        "senderCardName": "Test Test",
        "expiry": "2606",
        "pan": "5248721588681850",
        "sendercardalias": "My card for ZP",
        "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

curl --location --request POST 'https://mock.apidog.com/m1/483896-0-default/Payment' \
--header 'ExtSystemid: ECOM_GOLD_BANK' \
--header 'login: SECURE_LOGIN' \
--header 'password: SECURE_PASSWORD' \
--header 'orderNumber: 1234' \
--header 'orderId: dbafea6c-3394-4f6a-a0d2-21d3d8e93e42' \
--header 'RegDate: 2023-09-12 12:16:00	' \
--header 'x-uws-clientdn: GOLDENBANK' \
--header 'charset: UTF-8' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender": {
        "cvc": "576",
        "senderCardName": "Test Test",
        "expiry": "2606",
        "pan": "5248721588681850",
        "sendercardalias": "My card for ZP",
        "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
    }
}'

Responses

🟢200Success

application/json

Body

orderParam

object

required

Реєстраційні дані операції

orderStatus

integer

required

Стан операції

orderId

string

required

Унікальний ідентифікатор операції у системі. Автоматично надається системою при обробці запиту на реєстрацію замовлення

orderVerifyFlag

integer

required

Ознака способу автентифікації операції
0 - 3Ds автентифікація;
1 - Аутентифікація через otp пароль тільки для НПС «ПРОСТІР»
null або параметр відсутній - відсутня 3D аутентифікація

orderAuthParam

object

required

Авторизаційні параметри

fee

object | null

optional

Дані про комісію. Може бути відсутнім,

feeAmount

string

optional

Сумма комісії.

Example:

"feeAmount": "7880"

feeCurrency

string

optional

Валюта комісії.

Example:

"feeCurrency": "980"

auth3DData

object

required

Дані, необхідні для виконання процедури 3-D Secure аутентифікації емітентом.
Може бути відсутнім, якщо orderVerifyFlag = 1

acsurl

string

required

Адреса ACS емітента, на який необхідно виконати переадресацію браузера клієнта для проходження процедури 3-D Secure аутентифікації.

paReq

null

required

PaReq - повідомлення, згенероване EPG. Дане повідомлення має бути надіслано ACS url для проходження процедури 3-D Secure аутентифікації емітентом.

creq

string

required

Challenge Request message (cReq).
Повідомлення EMV 3-D Secure, що надсилається 3DS SDK або сервером 3DS, в якому від власника картки в ACS надсилається додаткова інформація для підтримки процесу аутентифікації. Він повинен бути присутнім для 3-D Secure 2, якщо потрібна перевірка власника картки.

tokenifo

object

required

Інформація по операції за участю токена

tokenid

integer

required

Внутрішній ідентифікатор
JWT платіжного токену

tokenexpiry

string

required

ISO-8601 timestamp (yyyy-mm-ddThh:mm:ss). Строк дії JWTтокену. Приклад: 2099-12-31T00:00:00.

Match pattern:

yyyy-mm-ddThh:mm:ss

token

string

optional

JWT платіжний токен

<= 800 characters

Examples

SuccessException

{
    "orderParam": {
        "orderStatus": 2,
        "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"
    }
}

🟢200OK

Modified at 2025-06-26 12:11:40

/cards/{panid}/baseparam/limits (112-Запит/зміна лімітів карти)

/Preauthorization