/р2рTransfer - Ukrcard

Switch to English

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

Request

Header Params

ExtSystemid

string

required

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

>= 1 characters<= 50 characters

Example:

ECOM_GOLD_BANK

string

required

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

>= 1 characters<= 30 characters

Example:

SECURE_LOGIN

password

string

required

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

>= 1 characters<= 30 characters

Example:

SECURE_PASSWORD

orderNumber

string

required

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

>= 1 characters<= 32 characters

Example:

1234

orderId

string

optional

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

>= 32 characters<= 32 characters

Example:

dbafea6c-3394-4f6a-a0d2-21d3d8e93e42

RegDate

string <date-time>

required

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

<= 19 characters

Example:

2023-09-12 12:16:00

Match pattern:

YYYY-MM-DD hh:mm:ss

x-uws-clientdn

string

required

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

<= 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

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

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

optional

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

pan

string

optional

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

<= 20 characters

expiry

string

optional

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

<= 4 characters

Example:

2412

Match pattern:

YYMM

cvc

string

optional

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

>= 3 characters<= 3 characters

Example:

123

Match pattern:

^\d+$

senderCardName

string

optional

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

<= 25 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

receiver

object

optional

Дані одержувача

receiverPAN

string

optional

Номер картки отримувача. Обов'язковий для заповнення під час виконання кредитової частини переказу transfer та a2c. Не використовується для C2A, Payment.

<= 20 characters

receiverName

string

optional

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

<= 35 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

param

object

optional

Додаткові параметри операції. Використовується, якщо ЗС необхідно передавати специфічні параметри в ПЦ

paramName

string

optional

Example:

paramValue

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

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

paramsp2p

object

optional

payerName

string

optional

payerAddress

string

optional

payerCity

string

optional

payerCountry

string

optional

payerPostalCode

string

optional

payerState

string

optional

payerDateOfBirth

string

optional

payerPhone

string

optional

payerIdType

string

optional

Тип документу
Можливі значення:

IDTP01 – Passport

IDTP0010 – Taxpayer ID (ІПН)

IDTP0016 – Company registration number (код ЄДРПОУ)
Приклад:
&emsp{"name": "payerIdType","value": "IDTP0016"}

payerIdNumber

string

optional

Дані документу
Приклад використання:
{"name": "payerIdNumber","value": "88888888"}

payerIdExpiration

string

optional

payerIdCountry

string

optional

recipientAddress

string

optional

recipientCity

string

optional

recipientCountry

string

optional

recipientPostalCode

string

optional

recipientState

string

optional

recipientDateOfBirth

string

optional

recipientPhone

string

optional

recipientIdType

string

optional

recipientIdNumber

string

optional

recipientIdExpiration

string

optional

recipientIdCountry

string

optional

payerAccountNumber

string

optional

businessApplicationIdentifier

string

optional

fundingOrPaymentTransactionTypeIndicator

string

optional

fundingOrPaymentTransactionTypeIndicator
Значення для карт НПС PROSTIR
P01 – переказ з картки ПРОСТІР на картку ПРОСТІР;
P02 – переказ з рахунку на картку ПРОСТІР (A2C);
P03 – переказ з картки ПРОСТІР на рахунок (C2A);
P04 – переказ між рахунками (для майбутнього використання);
P05 – переказ з картки ПРОСТІР на картку іншої платіжної системи;
P06 – переказ з картки іншої платіжної системи на картку ПРОСТІР;
P07 – поповнення картки готівкою (С2С);
P99 – інше.

fundingSource

string

optional

fundingSource
Значення для карт НПС PROSTIR
01 – картка;
02 – банківський рахунок фізичної особи;
12 – банківський рахунок юридичної особи;
03 – небанківський рахунок фізичної особи;
13 – небанківський рахунок юридичної особи;
04 – готівка;
05 – віртуальні активи;
06 – цифрова гривня;
07 – електронні гроші;
99 – інше

recipientName

string

optional

recipientAccountNumber

string

optional

recipientAccountType

string

optional

Recipient Account Type
Значення для карт НПС PROSTIR
Possible Data
1 – номер картки;
2 – номер рахунку;
3 – номер гаманця;
4 – готівка;
5 – інше.

payerAccountType

string

optional

Payer account type
Значення для карт НПС PROSTIR
Possible Data
1 – номер картки;
2 – номер рахунку;
3 – номер гаманця;
4 – готівка;
5 – інше.

merchantIdType

string

optional

Тип документу
Можливі значення:
IDTP01 – Passport
IDTP0010 – Taxpayer ID (ІПН)
IDTP0016 – Company registration number (код ЄДРПОУ)
Приклад використання:
{"name":"merchantIdType","value":"IDTP01"}

merchantIdNumber

string

optional

Дані документу
Приклад використання:
{"name":"merchantIdNumber","value":"ABCDXYZ124"}

payerFirstName

string

optional

Тільки для карток ПС Mastercard.
Найменування організації, компанії, юридичної особи Платника.
(Якщо у запиті використовуються теги payerFirstName та payerLastName,
то тег payerName для передачі значення Найменування організації Платника не використовується).

<= 32 characters

payerLastName

string

optional

Тільки для карток ПС Mastercard.
Дублювання найменування організації, компанії, юридичної особи Платника.
(Якщо у запиті використовуються теги payerFirstName та payerLastName,
то тег payerName для передачі значення Найменування організації Платника не використовується).

<= 32 characters

recipientFirstName

string

optional

Тільки для карток ПС Mastercard.
Найменування організації, компанії, юридичної особи Отримувача.
(Якщо у запиті використовуються теги recipientFirstName та recipientLastName,
то тег recipientName для передачі значення Найменування організації Одержувача не використовується).

<= 32 characters

recipientLastName

string

optional

Тільки для карток ПС Mastercard.
Дублювання найменування організації, компанії, юридичної особи Отримувача.
(Якщо у запиті використовуються теги recipientFirstName та recipientLastName,
то тег recipientName для передачі значення Найменування організації Одержувача не використовується).

<= 32 characters

fmparam

object

optional

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

ReceiverCNAME

string

optional

Назва Отримувача ЮО

ReceiverEDRPOU

string

optional

ЄДРПОУ Отримувача ЮО\n8 цифр

ReceiverIBAN

string

optional

IBAN Отримувача ЮО
29 символів 2 перших UA
27 - числа

SenderCNAME

string

optional

Назва Платника ЮО

SenderEDRPOU

string

optional

ЄДРПОУ Платника ЮО
8 цифр

SenderIBAN

string

optional

IBAN Платника ЮО
29 символів
2 перших UA
27 числа\n

SenderPIB

string

optional

ПІБ Платника ФО

SenderITN

string

optional

IПН Платника ФО
10 цифр

ReceiverPIB

string

optional

ПІБ Отримувача ФО

ReceiverITN

string

optional

ІПН Отримувача ФО
10 цифр

TranID

string

optional

Ідентифікатор транзакції
на стороні ЗС

additionalparams

object | null

optional

Блок для передачі додаткових параметрів переказу.

f108

string | null

optional

Двозначний числовий код з довідника F108 НБУ (Код призначення платежу).
Приклади використання: Виплата виграшів гравцям азартних ігор казино в мережі Інтернет "additionalparams":{"f108":"45"},
Повернення коштів, внесених гравцями для участі в азартних іграх (які не є виграшом) казино в мережі Інтернет "additionalparams":{"f108":"39"}

merchclientid

string | null

optional

Ідентифікатор користувача\гравця.
(внутрішній ідентифікатор користувача\гравця у кінцевого мерчанта).\nПриклад використання:
"additionalparams": { "merchclientid":"v123456789" }"

Example

{
   "orderData":{
      "amount":48000,
      "currency":980,
      "externalFee":2000,
      "description":"P2P to CHELENTANO ADRIANO"
   },
   "sender":{
      "pan":"51230000000001",
      "expiry":"2812",
      "cvc":"123",
      "senderCardName":"MORANDI GIANNI",
      "senderAddress":"Str Mihai Eminescu",
      "senderCity":"Rimini",
      "senderCountry":"978"
   },
   "receiver":{
      "receiverPAN":"55780000000001",
      "receiverName":"BERLINSCHI ALEXANDRU"
   },
   "pageData":{
      "language":"en",
      "returnUrl":"https://p2p.ukrcard.com/callback-page-from/a5a414b6-1aef-ee11-bccb-ac162d763a23/a7a414b6-1aef-ee11-bccb-ac162d763a23/8e210423-1aef-ee11-bccb-ac162d763a23",
      "failUrl":"https://p2p.ukrcard.com/callback-page-from/a5a414b6-1aef-ee11-bccb-ac162d763a23/a7a414b6-1aef-ee11-bccb-ac162d763a23/8e210423-1aef-ee11-bccb-ac162d763a23"
   },
   "param":{
      "paramName":"tran_type",
      "paramValue":"transfer"
   },
   "paramsp2p":{
      "fundingOrPaymentTransactionTypeIndicator":"C07",
      "payerName":"MORANDI GIANNI",
      "payerAccountType":"03",
      "payerAddress":"Str Mihai Eminescu ",
      "payerCity":"Rimini",
      "payerCountry":"380",
      "recipientName":"CHELENTANO ADRIANO",
      "recipientAccountType":"03"
   },
   "browserParams":{
      "userAgent":"Mozilla/5.0 (Linux; Android 13; 2201117TY Build/TKQ1.221114.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/122.0.6261.120 Mobile Safari/537.36",
      "colorDepth":24,
      "screenHeight":873,
      "screenWidth":393,
      "javaEnabled":false,
      "browserLanguage":"it-IT",
      "browserTimeZone":"Europe/Rome",
      "browserTimeZoneOffset":-60,
      "browserAcceptHeader":"application/json, text/plain, */*",
      "browserIpAddress":"212.0.113.154",
      "javascriptEnabled":true
   }
}

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/p2pTransfer' \
--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;' \
--header 'accept;' \
--header 'Content-Type: application/json' \
--data-raw '{
   "orderData":{
      "amount":48000,
      "currency":980,
      "externalFee":2000,
      "description":"P2P to CHELENTANO ADRIANO"
   },
   "sender":{
      "pan":"51230000000001",
      "expiry":"2812",
      "cvc":"123",
      "senderCardName":"MORANDI GIANNI",
      "senderAddress":"Str Mihai Eminescu",
      "senderCity":"Rimini",
      "senderCountry":"978"
   },
   "receiver":{
      "receiverPAN":"55780000000001",
      "receiverName":"BERLINSCHI ALEXANDRU"
   },
   "pageData":{
      "language":"en",
      "returnUrl":"https://p2p.ukrcard.com/callback-page-from/a5a414b6-1aef-ee11-bccb-ac162d763a23/a7a414b6-1aef-ee11-bccb-ac162d763a23/8e210423-1aef-ee11-bccb-ac162d763a23",
      "failUrl":"https://p2p.ukrcard.com/callback-page-from/a5a414b6-1aef-ee11-bccb-ac162d763a23/a7a414b6-1aef-ee11-bccb-ac162d763a23/8e210423-1aef-ee11-bccb-ac162d763a23"
   },
   "param":{
      "paramName":"tran_type",
      "paramValue":"transfer"
   },
   "paramsp2p":{
      "fundingOrPaymentTransactionTypeIndicator":"C07",
      "payerName":"MORANDI GIANNI",
      "payerAccountType":"03",
      "payerAddress":"Str Mihai Eminescu ",
      "payerCity":"Rimini",
      "payerCountry":"380",
      "recipientName":"CHELENTANO ADRIANO",
      "recipientAccountType":"03"
   },
   "browserParams":{
      "userAgent":"Mozilla/5.0 (Linux; Android 13; 2201117TY Build/TKQ1.221114.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/122.0.6261.120 Mobile Safari/537.36",
      "colorDepth":24,
      "screenHeight":873,
      "screenWidth":393,
      "javaEnabled":false,
      "browserLanguage":"it-IT",
      "browserTimeZone":"Europe/Rome",
      "browserTimeZoneOffset":-60,
      "browserAcceptHeader":"application/json, text/plain, */*",
      "browserIpAddress":"212.0.113.154",
      "javascriptEnabled":true
   }
}'

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

Example

{
    "orderParam": {
        "orderStatus": 0,
        "orderId": "677a1413-e59d-44d6-9a28-d2bc7208c27a",
        "orderVerifyFlag": 0,
        "orderAuthParam": {}
    },
    "fee": null,
    "auth3DData": {
        "paReq": null,
        "acsurl": "https://acs.alfabank.kiev.ua/acs/api/3ds2/creqbrw",
        "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ1NjVkN2IwLTc5MzMtNDQ3Yi1hMTY4LWFhYjI4OTBhODUzMiIsImFjc1RyYW5zSUQiOiI5MmNkMDdkNy0xZWRmLTRlNGEtOTM4Ny1iNzNlOTQ1YWMwNTEiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
    }
}