Ukrcard
  1. UAPI методи
Ukrcard
  • Default module
    • Вступ
    • Початок роботи
    • Вебхуки та оновлення статусу
    • Загальні концепції
    • Особистий кабінет торговця
    • Payments API методи
      • Рецепти
      • Довідка
        • Потоки обробки транзакцій
        • Коди відповідей
        • Тестові дані
        • Налаштування та використання сервісу callback
      • E-Commerce еквайринг
        • /Payment
        • /Preauthorization
        • /CancelPreauthorization
        • /Completion
        • /ConfirmExt
        • /Reverse
        • /Refund
        • /Verify
      • Грошові перекази
        • /р2рTransfer
        • /Confirm
        • /ConfirmExt
        • /Reverse
        • /Refund
        • /Verify
      • Платежі з цифрового гаманця
      • Платіжні операції з використанням токенів
        • /Payment
        • /Preauthorization
        • /p2pTransfer
        • /Confirm
        • /ConfirmExt
        • /Panbytoken
      • Apple Pay
        • /PaymentAppleD
        • /PaymentAppleE
        • /p2pTransferAppleD
        • /p2pTransferAppleE
      • Google Pay
        • /PaymentGoogleD
        • /PaymentGoogleE
        • /p2pTransferGoogleD
        • /p2pTransferGoogleE
    • UAPI методи
      • Визначення
      • Рецепти
      • Картки та рахунки (UAPI)
        • /cards/issuacevirtualcard (140-Запит видачі віртуальної картки)
        • /cards/issuacephysicalcard (141-Запит видачі фізичної картки)
        • /cards/{panid}/baseparam/status (111-Запит/зміна статусу картки)
        • /cards/getcarddataecom (138-Запит даних картки для eCommerce)
        • /cards/setpin (137-Запит на встановлення PIN картки)
        • /cards/changepin (136-Замовлення зміни PIN картки)
        • /cards/gettransactions (122-Запит історії транзакцій)
        • /cards/registryvirtualcard (Запит реєстрації віртуальної карти)
        • /cards/{panid}/baseparam/limits (112-Запит/зміна лімітів карти)
    • Schemas
      • E-Commerce еквайринг
        • Payment Request
      • UAPI методи
        • registryvirtualcard
  1. UAPI методи

Рецепти

1. Віртуальні карти#

1.1. Визначення#

Instant (миттєва) карта — це платіжна карта, яка видається клієнту (особі) одразу при його зверненні до емітента. Може бути фізичною - з реквізитами на пластику без імені або віртуальною – з реквізитами у смартфоні клієнта. Фізична карта – виготовляється емітентом завчасно. Віртуальна карта – створюється емітентом безпосередньо при зверненні клієнта або завчасно.
Віртуальна карта (Virtual Card) — це цифрова картка без пластика, яка існує у смартфоні (в додатку) та призначена для безпечних онлайн-покупок, безконтактних оплат (Apple/Google Pay) та переказів. Така карта має ті ж самі реквізити (номер, CVV, термін дії), що й фізична карта. 

1.2.Cтворення та видачі віртуальних карт клієнтам емітента#

Технологія створення та видачі віртуальних карт клієнтам визначається у залежності від конфігурації карткового бек-офісу емітента (Card back Office,CBO).

1.2.1. Технологія створення та видачі віртуальних карт клієнтам емітента з бек-офісом СBO1:#

Підготовка до створення (випуску) віртуальних карт:
Реєстрація карткових продуктів у бек-офісі емітента: виконується працівником емітента. При реєстрації вказуються наступні дані:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
ознака віртуальних карт (imagetype='V'),
метод видачі карти клієнту (UAPI-запит видачі віртуальної карти ),
метод активації карти (UAPI-запит зміни статусу карти на "Активна"),
Реєстрація карткових продуктів віртуальних карт в УКРКАРТ: виконується працівником УКРКАРТ за заявкою емітента. В заявці емітент вказує наступні дані продукту:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
та інші
Створення (випуск) віртуальних карт:
Віртуальні карти створюються працівником УКРКАРТ за заявкою емітента: пакетами, завчасно
В заявці на створення (випуск) пакета віртуальних карт емітент вказує:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
валюту карт та їх картрахунків (currencyno),
термін дії карт у місяцях (mounts),
кількість карт
Заявки на створення (випуск) пакета віртуальних карт виконуються працівником УКРКАРТ. При створенні для кожної віртуальної карти визначаються наступні дані:
тип продукту (prodtype),
номер (pan) та номер випуску (mbr=0) карти*,*
ідентифікатор карти (panid),
ідентифікатор картрахунку карти (accountno),
код валюти карти та її картрахунку (currencyno),
термін дії карти (expdate),
ознака віртуальної карти (imagetype='V'),
метод видачі карти клієнту (UAPI-запит видачі віртуальної карти ),
метод активації карти (UAPI-запит зміни статусу карти на "Активна"),
статус видачі карти клієнту (deliverystatus=0, не видана клієнту)
статус карти (crd_stat=0-Не активна)
Список створених згідно заявки віртуальних карт, з визначеними для них даними, відправляється емітенту
Емітент, наданий йому список створених віртуальних карт, з визначеними для них даними, завантажує до своєї бази даних з ознакою "Не надана клієнту" (Delivered to customer = "No")
Реєстрація клієнта емітентом:
Клієнт має отримувати віртуальні картки через доступний йому застосунок емітента (WEB\Mobile App)
Клієнт реєструється у застосунку емітента: повідомляє свої персональні дані і номер свого смартфону.
Застосунок емітента виконує ідентифікацію клієнта та реєструє його персональні дані та номер його смартфону у базі даних бек-офісу емітента.
Видача клієнту віртуальної карти з картрахунком:
Кінцевий алгоритм виконання операції застосунком емітента визначається самим емітентом. Наведений нижче алгоритм є рекомендаційним:
Застосунок отримує запит клієнта "Видати віртуальну карту з картрахунком".
Застосунок за даними запиту клієнта та його персональними даними формує і відправляє UAPI-запит PUT ../cards/issuacevirtualcard . В UAPI-запиті застосунок вказує наступні дані:
тип продукту (prodtype),
валюта карти та її картрахунку (currencyno),
номер смартфона клієнта (authmobphone)
Приклад:
"virtualcard": {
"prodtype": "M6",
"currencyno": 980,
"authmobphone": "3805044433321"
}
UAPI-сервер за даними URL визначає UAPI-метод issuacevirtualcard і передає йому UAPI-запит,
UAPI-метод:
виконує UAPI-запит і встановлює для карти ознаку "Видана клієнту" (Delivered to customer = "Yes")
реєструє UAPI-операцію "70-Видача віртуальної карти клієнту",
формує UAPI-відповідь,
відправляє UAPI-відповідь UAPI-серверу,
UAPI-сервер відправляє UAPI-відповідь застосунку емітента, де, у т.ч., вказує наступні дані:
номер карти (pan),
ідентифікатор карти (panid),
тип продукту (prodtype),
валюта карти та її картрахунку (currencyno),
номер картрахунку (accountno),
iban картрахунку (iban)
термін діїї карти (expdate)
Застосунок емітента за даними UAPI-відповіді:
реєструє видачу віртуальної карти клієнту у базі даних застосунку та\або у базі даних бек-офісу емітента,
повідомляє клієнту номер виданої йому віртуальної карти.
Процесинговий центр УКРКАРТ:
Зареєстрована процесинговим центром UAPI-операція "70-Видача віртуальної карти клієнту" разом з іншими зареєстрованими операціями з картами та картрахунками емітента, включається до чергового файлу "Виписка операцій процесингового центру (Extract)"
Відправляє файл "Виписка операцій процесингового центру (Extract)" до бек-офісу емітента.
Бек-офіс емітента:
Отримує і обробляє файл "Виписка операцій процесингового центру (Extract)", у т.ч. і операцію "70-Видача віртуальної карти клієнту"
При обробці операції "70-Видача віртуальної карти клієнту", емітент, наприклад:
Може нараховувати комісію за видачу віртуальної карти,
Реєструвати видану клієнту віртуальну карту у клієнтському договорі. При цьому клієнт, що отримав карту, та його договір, визначаються за вказаним у записі операції номером смартфону (authmobphone),
та т.і.

1.2.2. Технологія створення та видачі віртуальних карт клієнтам емітента з бек-офісом СBO2:#

Підготовка до створення (випуску) віртуальних карт:
Реєстрація карткових продуктів у картковому бек-офісі BCZCard: виконується працівником емітента. При реєстрації вказуються наступні дані:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
ознака віртуальних карт (imagetype='V'),
метод видачі карти клієнту (deliverymethod=2 =>UAPI-запит видачі віртуальної карти ),
дані субпродукту:
метод активації карти (issuemethod=4 =>UAPI-запит зміни статусу карти на "Активна"),
ідентифікатор дизайну карт (designid)
Реєстрація карткових продуктів віртуальних в УКРКАРТ: виконується працівником УКРКАРТ за заявкою емітента. В заявці емітент вказує наступні дані продукту:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
та інші
Створення у картковому бек-офісі BCZCard типових договорів для віртуальних карт, де вказуються:
валюта типового договору (currencyno),
ідентифікатори карткових продуктів (prefix) типового договору з ідентифікаторами шаблонів їх карт (authcontractct)
Створення (випуск) віртуальних карт:
Віртуальні карти створюються у картковому бек-офісі BCZCard працівником емітента: пакетами, завчасно
При створенні(випуску) пакета віртуальних карт працівник емітента вказує:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
валюту карт та їх картрахунків (currencyno),
термін дії карт у місяцях (mounts),
кількість карт
Створення (випуск) пакета віртуальних карт ініціюється працівником емітента і автоматично виконується картковим бек-офісом BCZCard. При створенні для кожної віртуальної карти визначаються наступні дані:
тип продукту (prodtype),
номер (pan) та номер випуску (mbr=0) карти*,*
ідентифікатор карти (panid),
ідентифікатор картрахунку карти (accountno),
код валюти карти та її картрахунку (currencyno),
термін дії карти (expdate),
ознака віртуальної карти (imagetype='V'),
метод видачі карти клієнту (deliverymethod=2 =>UAPI-запит видачі віртуальної карти ),
метод активації карти (issuemethod=4 =>UAPI-запит зміни статусу карти на "Активна"),
статус видачі карти клієнту (deliverystatus=0, не видана клієнту)
статус карти (crd_stat=0-Не активна)
Список створених емітентом віртуальних карт, з визначеними для них даними, зберігається у базі даних карткового бек-офісу BCZCard
Пакет створених емітентом віртуальних карт, з визначеними для них даними, картковий бек-офіс BCZCard відправляє до УКРКАРТ у файлі Refresh(оффлайн)
Реєстрація клієнта емітентом:
Клієнт має отримувати віртуальні картки через доступний йому застосунок емітента (WEB\Mobile App)
Клієнт реєструється у застосунку емітента: повідомляє свої персональні дані і номер свого смартфону.
Застосунок емітента виконує ідентифікацію клієнта та реєструє його персональні дані та номер його смартфону у базі даних карткового бек-офісу BCZCard.
Видача клієнту віртуальної карти з картрахунком:
Кінцевий алгоритм виконання операції застосунком емітента визначається самим емітентом. Наведений нижче алгоритм є рекомендаційним:
Застосунок отримує запит клієнта "Видати віртуальну карту з картрахунком".
Застосунок за даними запиту клієнта та його персональними даними формує і відправляє UAPI-запит PUT ../cards/issuacevirtualcard . В UAPI-запиті застосунок вказує наступні дані:
тип продукту (prodtype),
валюта карти та її картрахунку (currencyno) у типовому договорі BCZCard*,*
номер смартфона клієнта (authmobphone),
ідентифікатор шаблону карти (authcontractct) у типовому договорі BCZCard
Приклад:
"virtualcard": {
"prodtype": "M6",
"currencyno": 980,
"authmobphone": "3805044433321",
"authcontractct": "NMY"
}
UAPI-сервер за даними URL визначає UAPI-метод issuacevirtualcard і передає йому UAPI-запит,
UAPI-метод:
за даними UAPI-запиту знаходить у базі даних УКРКАРТ довільну,ще не видану клієнтам, віртуальну карту,
встановлює для знайденої карти ознаку "Видана клієнту" (Delivered to customer = "Yes")
реєструє UAPI-операцію "70-Видача віртуальної карти клієнту",
формує UAPI-відповідь,
відправляє UAPI-відповідь UAPI-серверу,
UAPI-сервер відправляє UAPI-відповідь застосунку емітента, де, у т.ч., вказує наступні дані:
номер карти (pan),
ідентифікатор карти (panid),
тип продукту (prodtype),
валюта карти та її картрахунку (currencyno),
номер картрахунку (accountno),
iban картрахунку (iban)
термін діїї карти (expdate)
Застосунок емітента за даними UAPI-відповіді:
реєструє видачу віртуальної карти клієнту у базі даних застосунку та\або у базі даних бек-офісу емітента,
повідомляє клієнту номер виданої йому віртуальної карти.
Процесинговий центр УКРКАРТ:
Зареєстрована процесинговим центром UAPI-операція "70-Видача віртуальної карти клієнту" разом з іншими зареєстрованими операціями з картами та картрахунками емітента, включається до чергового файлу "Виписка операцій процесингового центру (Extract)"
Відправляє файл "Виписка операцій процесингового центру (Extract)" до карткового бек-офісу емітента.
Картковий бек-офіс емітента BCZCard:
Отримує і обробляє файл "Виписка операцій процесингового центру (Extract)", у т.ч. і операцію "70-Видача віртуальної карти клієнту"
При обробці операції "70-Видача віртуальної карти клієнту" створюється НОВИЙ клієнтський договір:
типовий договір визначається за вказаним в UAPI-запиті ідентифікатором шаблону карти (authcontractct),
клієнт договору, як власник віртуальної карти, визначається за вказаним в UAPI-запиті номером смартфону (authmobphone)

1.2.3. Технологія створення та видачі віртуальних карт клієнтам емітента з бек-офісом СBO3:#

Підготовка до створення (випуску) віртуальних карт:
Реєстрація карткових продуктів у бек-офісі емітента (наприклад, в "АБС Б2"): виконується працівником емітента. При реєстрації вказуються наступні дані:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
ознака віртуальних карт (imagetype='V'),
метод видачі карти клієнту (deliverymethod=2 =>UAPI-запит видачі віртуальної карти ),
дані субпродукту:
метод активації карти (issuemethod=4 =>UAPI-запит зміни статусу карти на "Активна"),
ідентифікатор дизайну карт (designid)
Реєстрація карткових продуктів у застосунку BCZConn: виконується працівником УКРКАРТ. При реєстрації вказуються наступні дані:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
ознака віртуальних карт (imagetype='V'),
метод видачі карти клієнту (deliverymethod=2 =>UAPI-запит видачі віртуальної карти ),
дані субпродукту:
метод активації карти (issuemethod=4 =>UAPI-запит зміни статусу карти на "Активна"),
ідентифікатор дизайну карт (designid)
Реєстрація карткових продуктів віртуальних в УКРКАРТ: виконується працівником УКРКАРТ за заявкою емітента. В заявці емітент вказує наступні дані продукту:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
та інші
Реєстрація карткових продуктів віртуальних карт:
у застосунку BCZConn: виконується працівником УКРКАРТ,
у процесинговому центрі УКРКАРТ: виконується працівником УКРКАРТ за заявкою емітента.
В заявці емітент вказує наступні дані:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
ознаку віртуальних карт (imagetype='V') та інші
Створення у застосунку BCZConn типових договорів для віртуальних карт, де вказуються:
валюта типового договору (currencyno),
ідентифікатори карткових продуктів (prefix) типового договору з ідентифікаторами шаблонів їх карт (authcontractct)
Створення (випуск) віртуальних карт:
Віртуальні карти створюються у застосунку BCZConn працівником УКРКАРТ: пакетами, завчасно
При створенні(випуску) пакету віртуальних карт працівник УКРКАРТ вказує:
ідентифікатор карткового продукту (prefix),
тип продукту (prodtype),
валюту карт та їх картрахунків (currencyno),
термін дії карт у місяцях (mounts),
кількість карт
Створення (випуск) пакета віртуальних карт ініціюється працівником УКРКАРТ і автоматично виконується застосунком BCZConn. При створенні для кожної віртуальної карти визначаються наступні дані:
тип продукту (prodtype),
номер (pan) та номер випуску (mbr=0) карти*,*
ідентифікатор карти (panid),
ідентифікатор картрахунку карти (accountno),
код валюти карти та її картрахунку (currencyno),
термін дії карти (expdate),
ознака віртуальної карти (imagetype='V'),
метод видачі карти клієнту (deliverymethod=2 =>UAPI-запит видачі віртуальної карти ),
метод активації карти (issuemethod=4 =>UAPI-запит зміни статусу карти на "Активна"),
статус видачі карти клієнту (deliverystatus=0, не видана клієнту)
статус карти (crd_stat=0-Не активна)
Застосунок BCZConn:
пакет створених віртуальних карт, з визначеними для них даними:
відправляє до УКРКАРТ: у файлі Refresh,
відправляє до бек-офісу емітента: у файлі
Бек-офіс емітента:
завантажує дані віртуальних карт до своєї бази даних
Список створених віртуальних карт, з визначеними для них даними, зберігається у базі даних застосунку BCZConn і у базі даних бек-офісу емітента
Реєстрація клієнта емітентом:
Клієнт має отримувати віртуальні картки через доступний йому застосунок емітента (WEB\Mobile App)
Клієнт реєструється у застосунку емітента: повідомляє свої персональні дані і номер свого смартфону.
Застосунок емітента виконує ідентифікацію клієнта та реєструє його персональні дані та номер його смартфону у базі даних бек-офісу емітента (наприклад, "АБС Б2").
Видача клієнту віртуальної карти з картрахунком:
Кінцевий алгоритм виконання операції застосунком емітента визначається самим емітентом. Наведений нижче алгоритм є рекомендаційним:
Застосунок отримує запит клієнта "Видати віртуальну карту з картрахунком".
Застосунок за даними запиту клієнта та його персональними даними формує і відправляє UAPI-запит PUT ../cards/issuacevirtualcard . В UAPI-запиті застосунок вказує наступні дані:
тип продукту (prodtype),
валюта карти та її картрахунку (currencyno) у типовому договорі BCZConn*,*
номер смартфона клієнта (authmobphone),
Приклад:
"virtualcard": {
"prodtype": "M6",
"currencyno": 980,
"authmobphone": "3805044433321"
}
UAPI-сервер за даними URL визначає UAPI-метод issuacevirtualcard і передає йому UAPI-запит,
UAPI-метод:
виконує UAPI-запит і встановлю для карти ознаку "Видана клієнту" (Delivered to customer = "Yes")
реєструє UAPI-операцію "70-Видача віртуальної карти клієнту",
формує UAPI-відповідь,
відправляє UAPI-відповідь UAPI-серверу,
UAPI-сервер відправляє UAPI-відповідь застосунку емітента, де, у т.ч., вказує наступні дані:
номер карти (pan),
ідентифікатор карти (panid),
тип продукту (prodtype),
валюта карти та її картрахунку (currencyno),
номер картрахунку (accountno),
iban картрахунку (iban)
термін діїї карти (expdate)
Застосунок емітента за даними UAPI-відповіді:
реєструє видачу віртуальної карти клієнту у базі даних застосунку,
передає інформацію про видачу віртуальної карти клієнту до бек-офісу емітента (наприклад, "АБС Б2"),
повідомляє клієнту номер виданої йому віртуальної карти.
Бек-офіс емітента (наприклад, "АБС Б2"):
отримає від застосунку емітента інформацію про видачу віртуальної карти клієнту,
реєструє видачу віртуальної карти клієнту,
відправляє до застосунку BCZConn Issue-документ, де вказує:
тип операції "Реєстрація видачі віртуальної (неіменної) карти клієнту" (p_operation.p_Description=14.1 \ 14.2),
номер віртуальної карти (p_pan=pan, з UAPI-відповіді),
код валюти валюти віртуальної карти та її картрахунку
(p_ccy=currencyno, з UAPI-відповіді ),
номер картрахунку (p_ext_account_num=accountno, з UAPI-відповіді)
дані клієнта (деталі у документі BCZConn-B2 v 0.30.pdf)
інші дані (деталі у документі BCZConn-B2 v 0.30.pdf)
Процесинговий центр УКРКАРТ:
Зареєстрована процесинговим центром UAPI-операція "70-Видача віртуальної карти клієнту" разом з іншими зареєстрованими операціями з картами та картрахунками емітента, включається до чергового файлу "Виписка операцій процесингового центру (Extract)"
Відправляє файл "Виписка операцій процесингового центру (Extract)" до застосунку BCZConn.
Застосунок BCZConn:
Отримує і обробляє файл "Виписка операцій процесингового центру (Extract)", у т.ч. і операцію "70-Видача віртуальної карти клієнту".
Примітка. При цьому реєстрація видачі віртуальної карти клієнту НЕ ВИКОНУЄТЬСЯ.
Modified at 2026-02-16 09:08:05
Previous
Визначення
Next
/cards/issuacevirtualcard (140-Запит видачі віртуальної картки)
Built with