Підключайтесь! Всі подробиці в нашому Telegram-чаті


Опис процесу передачі даних для взаємодії між Банком та Партнером у межах програми «Партнерський інстолмент»

1. Глосарій

2. Партнерський інстолмент/ Partnership Installment

3. Передача даних

4. Послідовність взаємодій

5. Опис API

6. Опис взаємодії

7. Описание методов

7.1. Pеєстрація замовлення: метод createOrder

7.1.1. Виклик Партнера з боку Банку на етапі реєстрації замовлення

7.1.2. Виклик Партнера з боку Банку для передачі параметрів для формування Гарантійного листа

7.1.3. Виклик Партнера з боку Банку для передачі Гарантійного листа в форматі BASE64

7.1.4. Виклик Партнера з боку Банку для передачі позитивного рішения Банку про можливість оформлення замовлення у розстрочку (для Партнерів, що працюють за схемою без використання Гарантійного листа)

7.2. Отримання інформації щодо замовлення: метод getOrder

7.3. Отримання Гарантійного листа для замовлення: метод getGuarantee

7.4. Скасування замовлення (за ініціативою Партнера): метод cancelOrder

7.4.1. Виклик Партнера з боку Банку на етапі опрацювання запиту на скасування замовлення

7.5. Підтвердження замовлення: метод confirmOrder

7.6. Перевірка можливості здійснення повернення товару із замовлення: метод checkReversal

7.7. Повернення товару із замовлення: метод reversalOrder

7.7.1. Виклик Партнера з боку Банку на етапі реєстрації повернення

7.8. Отримання інформації щодо повернення: метод getReversal

7.9. Отримання виписки по рахунку/IBAN: метод sendStatementTaskByAccount

7.10. Варіанти поведінки Партнера у випадку виникнення окремих статусів на методах реєстрації замовлення, скасування, повернення

1. Глосарій

Термін

Опис
Installment Бізнес-сервіс продажу Клієнтам послуги розстрочки під час купівлі товарів за кредитними картками
Банк
АТ «Сенс-Банк»
Партнер
Торговельна мережа з магазинами, в яких Клієнт Банку здійснює покупку в розстрочку
Клієнт
Клієнт Банку, у якого в Банку відкрито рахунок кредитної картки, на якому за авторизаціями покупок оформлюється розстрочка (в разі виконання умов продукту розстрочки)
Замовлення (на оформлення покупки у розстрочку)
Подія в магазині Партнера, коли покупка оформлюється, і відбувається авторизація
Гарантійний лист
Лист від Банку на адресу Партнера, відправлений будь-яким із доступних каналів, що гарантує перерахування відшкодування на рахунок Партнера суми операції купівлі Клієнта в магазині Партнера (за мінусом комісії Банку)

(к оглавлению)

2. Партнерський інстолмент/ Partnership Installment

Installment — бізнес-сервіс продажу Клієнтам послуги розстрочки за умови здійснення покупки за кредитними картками. Партнерський інстолмент — процес, що дозволяє при оформленні Клієнтом розстрочки на покупку в магазині Партнера розподілити суму покупки, списану за кредитною карткою, рівними платежами для погашення на кількість місяців, вибрану Клієнтом. Вибір кількості місяців розстрочки відбувається на боці Партнера за погодженням із Клієнтом. Комісія Клієнта за такої розстрочки відсутня.

Зазначена нижче інформація призначена для надання відомостей Партнеру щодо технічної реалізації, і описує варіанти передачі даних між Банком та Партнером у межах програми «Партнерський інстолмент».

(к оглавлению)

3. Передача даних

Сервер Банку надає програмний інтерфейс для передачі та прийому даних зашифрованим протоколом. Відправлення та отримання даних між Банком та Партнером відбувається в автоматичному режимі. Взаємодію засновано на використанні протоколу TLS 1.2 з серверними сертифікатами, що забезпечує автоматичне шифрування даних під час передачі. Прикладні дані передаються із застосуванням протоколу HTTPS у вигляді JSON-повідомлень із застосуванням базової авторизації з використанням логіна та пароля.

(к оглавлению)

4. Послідовність взаємодій

(к оглавлению)

5. Опис API

Банк за допомогою API приймає та відправляє дані HTTPS-протоколом шляхом REST-запитів. У тілі запиту передається JSON у кодуванні UTF-8:

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/SERVICE_METHOD/PARTNER_ID

де

https://mw-api-test.sensebank.kyiv.ua - хост, на якому розміщено сервіс;

            SERVICE_METHOD - метод API;

            PARTNER_ID - унікальний ідентифікатор, присвоєний Банком для ідентифікації Партнера.

Для тестового середовища PARTNER_ID=partner

Наприклад:

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

Вимоги до заголовків запитів:

- у заголовку POST запиту має бути прописано тип: ContentType: application/json;

- авторизація має бути Basic Auth і передаватися як:

Authorization: Basic login: password,

де

login: partner

password: !PaRt_Ne09_R#

API надає такі методи (SERVICE_METHOD) для оформлення розстрочки:

createOrder – реєстрація замовлення (method POST);

getOrder - отримання інформації щодо замовлення (method GET);

getGuarantee – отримання Гарантійного листа для замовлення (method GET);

cancelOrder - скасування замовлення (за ініціативою Партнера) (method POST);

confirmOrder – підтвердження замовлення (за ініціативою Партнера) (method POST);

reversalOrder – повернення товару із замовлення (method POST);

checkReversal – перевірка можливості здійснення повернення товару із замовлення (method GET);

getReversal – отримання інформації щодо повернення (method GET).

sendStatementTaskByAccount – метод отримання виписки по рахунку/IBAN(method POST).

(к оглавлению)

6. Опис взаємодії

Перед початком тестування Партнеру необхідно заповнити та передати в Банк документ з параметрами – "Заявка_ПІ_прод", шаблон документа надасть менеджер Банку.

Партнер на початковому етапі, на старті перед тестуванням з Банком, визначає, яким чином буде працювати з Банком у межах програми «Партнерський інстолмент».

Якщо Партнер планує працювати, викликаючи Банк, то послідовність така:

Якщо Партнер визначив, що працюватиме за допомогою callBack від Банку, то у разі виклику createOrder необхідно вказати коректний callBackURL – URL для надсилання рішення (коректний URL сервісу Партнера, який повинен прийняти та обробити відповідь від Банку).

Формат callBack: авторизацію використовувати Basic з передачею логіна і пароля в base64. Якщо за callBack Партнер отримує статус PURCHASE_IS_OK – це і є автоматичне підтвердження замовлення.

Нижче в описі пункти «Виклик Партнера з боку Банку» = опис callBack.

(к оглавлению)

7. Опис методів

7.1. Реєстрація замовлення: метод createOrder

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

API: https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/PARTNER_ID

HTTPS METHOD: POST

Приклад запиту:

curl -k -u "partner":"!PaRt_Ne09_R#" --header "Content-Type: application/json" --request POST --data '{"mPhone":"+380977896541","orderId":"50552717","panEnd":"9654","orderSum":"619700","orderTerm":"6", "eMailPartner":"asfaf@erger.te","callBackURL":"https:\/\/dpartnapu01.sensebank.com.ua\/v1\/alfa_postback\/"}' https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

Вхідні параметри:

мобільний номер телефону Клієнта Банку в міжнародному форматі (наприклад, +380671111111)

4 останні цифри номера картки Клієнта, за якою буде оформлено розстрочку

ІД замовлення покупки в розстрочку, унікальний в межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

сума покупки (в копійках)

строк розстрочки (в місяцях)

У параметрі зі зазначенням терміну розстрочки дозволена передача значень від 1 до 24

URL для відправлення рішення (коректний URL сервісу партнера, який повинен прийняти та обробити відповідь від банку)

код магазина Партнера

Ідентифікатор точки продажів (унікальний в межах партнера (partnerId))

найменування товару/групи товарів

orderNom містить масив, значеннями якого є об'єкти {}, які своєю чергою мають ключ, значення name: string, sum: integer (у копійках), vat: integer (у копійках)

набір додаткових параметрів

сума ПДВ (у копійках)

якщо партнеру не потрібно отримувати на e-mail інформацію, то можна вказати фейкову константу, дотримуючись формату e-mail

Вихідні параметри:

ІД замовлення покупки в розстрочку, унікальний в межах Банку

код відповіді Банку за запитом реєстрації замовлення

Текст відповіді Банку за запитом реєстрації замовлення

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

Максимально допустиме значення суми розстрочки = 200 000 UAH

Мінімально допустиме значення суми розстрочки = 500 UAH

За результатами попередніх перевірок, до реєстрації замовлення з боку Банку можливі такі варіанти негативних статусів:

statusCode
statusText
Примітка
NO_PARTNERID
«Партнер ${partnerId} не зареєстрований в системі!»
 
MATCH_ORDERID
«Замовлення з номером ${orderId} вже існує!»

INVALID_ORDERID
«Указано некоректний номер замовлення!»

INVALID_MPHONE
«Указано некоректний номер телефону»

INVALID_PANEND
«Указано некоректний номер картки»

INVALID_ORDERSUM
«Указано некоректну суму розстрочки»

INVALID_ORDERTERM
«Указано некоректний строк розстрочки»

INVALID_CALLBACKURL
«Указано некоректний URL»

ORDERSUM_EXCEEDS
«Сума розстрочки перевищує допустиме значення в ${maxOrder} UAH»
Значення ${maxOrder}" відображувати у грн
ORDERSUM_LOW
«Сума розстрочки нижче допустимого значення в ${minOrder} UAH»
Значення ${minOrder}" відображувати в грн
PAC_NOT_SUCCESS
«Транзакція Pre-authorization має неуспішний код завершення»

PAC_IS_REVERSED
«Транзакцію Pre-authorization скасовано»

PAC_DUP_COMPL
«Транзакція Pre-authorization має транзакцію завершення»

PAC_DAY_LMT_EXC
«Часовий інтервал між транзакціями предавторизації та завершення перевищує встановлену величину»

PAC_AMOUNT_EXT
«Сума транзакції завершення перевищує суму транзакції предавторизації більше, ніж на встановлену в процентах величину»

PAC_ERROR
«Помилка під час обробки правил транзакції предавторизації та завершення»

PAC_NOT_FOUND
«Для транзакції завершення не знайдено оригінальну транзакцію предавторизації»

INVALID_EMAIL
«Вказано некоректний email»
Якщо Партнерові не потрібно отримувати на email інформацію, то можна вказати фейкову константу, дотримуючись формату eMail

У разу УСПІШНОГО проходження попередніх перевірок та реєстрації замовлення можливі такі варіанти статусів:

statusCode
statusText
Примітки
IN_PROCESSING
«Замовлення в обробці!»
Замовлення створено

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

Для тестування методів можна використовувати номер телефону формату +380... (будь-який код оператора, крім 06) у параметрі mPhone.

Приклад №1 statusCode - NO_PARTNERID, statusText - ''Партнер ${partnerId} не зареєстрований у системі!'':

Примітка: відправляти запит з відсутнім/незареєстрованим partnerId.

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partn

in json:

{

"mPhone": "+380967896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p17",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "NO_PARTNERID",

    "statusText": "Партнер partn не зареєстрований у системі!",

    "messageId": "null",

    "orderId": "null"

}

Приклад №2 statusCode - MATCH_ORDERID, statusText - ''Замовлення з номером ${orderId} вже існує!'':

Примітка: Відправляти запит createOrder з orderId, що вже зареєстрований у системі банку.

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380967896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p17",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "MATCH_ORDERID",

    "statusText": "Замовлення з номером p17 вже існує!",

    "messageId": "null",

    "orderId": "null"

}

Приклад №3 statusCode - INVALID_ORDERID, statusText - "Указано некоректний номер замовлення!":

Примітка: Відправляти запит createOrder з порожнім параметром orderId.

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380967896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "INVALID_ORDERID",

    "statusText": "Указано некоректний номер замовлення!",

    "messageId": "null",

    "orderId": "null"

}

Приклад №4 statusCode - INVALID_MPHONE, statusText - "Указано некоректний номер телефону":

Примітка: Відправити запит createOrder з некоректним номером телефону (кількість символів у номері).

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "096796608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p19",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "INVALID_MPHONE",

    "statusText": "Указано некоректний номер телефону",

    "messageId": "null",

    "orderId": "null"

}

Приклад №5 statusCode - INVALID_PANEND, statusText - "Указано некоректний номер картки":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380667896608",

"panEnd": "965",

"shopId": "46546-БwfqК",

"orderId": "p15",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "INVALID_PANEND",

    "statusText": "Указано некоректний номер картки",

    "messageId": "null",

    "orderId": "null"

}

Приклад №6 statusCode - INVALID_ORDERSUM, statusText - "Указано некоректну суму розстрочки":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380667896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p15",

"orderSum": "1216.00",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "INVALID_ORDERSUM",

    "statusText": "Указано некоректну суму розстрочки",

    "messageId": "null",

    "orderId": "null"

}

Приклад №7 statusCode - INVALID_ORDERTERM, statusText - "Указано некоректний строк розстрочки":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380667896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p15",

"orderSum": "121600",

"orderTerm": "48",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "INVALID_ORDERTERM",

    "statusText": "Указано некоректний строк розстрочки",

    "messageId": "null",

    "orderId": "null"

}

Приклад №8 statusCode - INVALID_CALLBACKURL, statusText - "Указано некоректний URL":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380667896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p15",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": ""

}

out json:

{

    "statusCode": "INVALID_CALLBACKURL",

    "statusText": "Указано некоректний URL",

    "messageId": "null",

    "orderId": "null"

}

Приклад №9 statusCode - ORDERSUM_EXCEEDS, statusText - "Сума розстрочки перевищує допустиме значення в ${maxOrder} UAH":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380667896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p15",

"orderSum": "100000000",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "ORDERSUM_EXCEEDS",

    "statusText": "Сума розстрочки перевищує допустиме значення в 200000 UAH",

    "messageId": "null",

    "orderId": "null"

}

Приклад №10 statusCode - ORDERSUM_LOW, statusText - "Сума розстрочки нижче допустимого значення в ${minOrder} UAH":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380667896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p15",

"orderSum": "1",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "ORDERSUM_LOW",

    "statusText": "Сума розстрочки нижче допустимого значення в 500 UAH",

    "messageId": "null",

    "orderId": "null"

}

Приклад №11 (Успішний кейс) statusCode - IN_PROCESSING, statusText - "Замовлення в обробці!":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/createOrder/partner

in json:

{

"mPhone": "+380967896608",

"panEnd": "9654",

"shopId": "46546-БwfqК",

"orderId": "p18",

"orderSum": "121600",

"orderTerm": "9",

"eMailPartner":"test@mytestemail.com",

"callBackURL": "https://dpartnapu01.sensebank.com.ua:8243/installmentseventwo/orders"

}

out json:

{

    "statusCode": "IN_PROCESSING",

    "statusText": "Замовлення в обробці!",

    "messageId": "B8F3737EDF292C81E0539B5A8F0A34E7",

    "orderId": "p18"

}

(к оглавлению)

7.1.1 Виклик Партнера з боку Банку на етапі реєстрації замовлення

Партнер на початковому етапі узгодження налаштувань з Банком визначає для себе, яким чином він бажає виконувати покупки/списання з клієнтського рахунку.

Можливі 2 режими роботи:

При цьому в межах одного PARTNER_ID допустимий тільки 1 режим роботи.

Вхідні параметри:

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

ІД замовлення покупки в розстрочку, унікальний у межах Банку

код статусу обробки запиту Банку

текст статусу обробки запиту Банку

Вихідні параметри:

код відповіді Партнера

Варіанти статусів за callBack:

statusCode
Вид покупки
statusText
Примітка
NO_CONTRAGENT_MPHONE
Звичайна
«Клієнта з номером телефону ${contInf2Cellur} не знайдено»
Замовлення створено, помилка
NO_CARD_PANEND
Звичайна
«Картку за номером${card4Last} не знайдено»
Замовлення створено, помилка
LOW_BALANCE
Звичайна
«Недостатній баланс на картці»
Замовлення створено, помилка
INST_ALLOWED_FAIL
Звичайна
«За карткою ${card4Last} неможливо оформити розстрочку»
Замовлення створено, помилка
NO_PRODUCT
Звичайна
«Не знайдено продукт розстрочки»
Замовлення створено, помилка
SYSTEM_ERROR
Звичайна
«Виникла системна помилка!»
Замовлення створено, помилка
PURCHASE_IS_FAIL
Звичайна
«Покупка неуспішна! Замовлення не оформлено!»
Замовлення створено, помилка
PURCHASE_IS_OK
Звичайна
«Покупка успішна, відправлено Гарантійний лист»
Замовлення створено, покупка успішна
PRE_PURCHASE_IS_FAIL
Предавторизація
«Блокування коштів неуспішне! Замовлення не оформлено!»
Виникає в разі неуспішного відпрацювання предавторизації покупки
PRE_PURCHASE_IS_FAIL_EX
Предавторизація
«Блокування коштів неуспішне! Замовлення не оформлено!»
Виникає в разі неуспішного відпрацювання предавторизації покупки
PRE_PURCHASE_IS_OK
Предавторизація
«Успішне блокування коштів. Відправлено Гарантійній лист!»
Виникає в разі неуспішного відпрацювання предавторизації покупки
PURCHASE_IS_FAIL
Предавторизація
«Покупка неуспішна! Замовлення не оформлено!»
Виникає в разі неуспішного відпрацювання предавторизації покупки
PURCHASE_IS_FAIL_EX
Предавторизація
«Покупка неуспішна! Замовлення не оформлено!»
Виникає в разі неуспішного відпрацювання предавторизації покупки
PURCHASE_IS_OK
Предавторизація
«Покупка успішна! Відправлено Гарантійний лист!»
Виникає в разі успішного відпрацювання авторизації покупки
CLIENT_NO_SEND_SMS

«Клієнт не підтвердив розстрочку замовлення»

SYSTEM_ERROR

«Виникла системна помилка»

(к оглавлению)

7.1.2 Виклик Партнера з боку Банку для передачі параметрів для формування Гарантійного листа

Входящие параметры:

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

ІД замовлення покупки в розстрочку, унікальний у межах Банку

набір параметрів (в форматі json) для формування Гарантійного листа

код запиту Банку

текст запиту Банку

Вихідні параметри:

код відповіді Партнера

(к оглавлению)

7.1.3 Виклик Партнера з боку Банку для передачі Гарантійного листа в форматі BASE64

Вхідні параметри:

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

ІД замовлення покупки в розстрочку, унікальний у межах Банку

текст Гарантійного листа в форматі Base64

код запиту Банку

текст запиту Банку

текст Гарантійного листа з КЕП в форматі Base64

Вихідні параметри:

код відповіді Партнера за запитом

Приклад statusCode - PURCHASE_IS_OK, statusText - "Покупка успішна, відправлено Гарантійний лист":

in json:

{

"statusCode": "PURCHASE_IS_OK",

"statusText": "Покупка успішна, відправлено Гарантійний лист",

"messageId": "8306B9AF1BC30562E053AC112B097881"

"orderId": "123-ТЬ"

"base64PdfSigned": "Гарантійний лист з КЕП"

"base64Pdf": "Гарантійний лист (pdf)"

}

out json:

{

"statusCode": "OK",

}

(к оглавлению)

7.1.4 Виклик Партнера з боку Банку для передачі позитивного рішення Банку про можливість оформлення замовлення в розстрочку (для Партнерів, що працюють за схемою без використання Гарантійного листа)

Вхідні параметри:

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

ІД замовлення покупки в розстрочку, унікальний у межах Банку

набір параметрів замовлення (в форматі json)

код запиту Банку

текст запиту Банку

Вихідні параметри:

код відповіді Партнера

(к оглавлению)

7.2 Отримання інформації щодо замовлення — метод getOrder

Метод застосовується для отримання інформації щодо замовлення.

API: https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getOrder/PARTNER_ID?orderId= ІД_замовлення_партнер

або

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getOrder/PARTNER_ID?messageId= ІД_замовлення_банк

HTTPS METHOD: GET

Приклад запиту:

curl -k --header "Authorization: Basic dGVzdHVzZXI6dGVzdHVzZXI=" --request GET https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getOrder/partner?orderId=BF21174E7DAA4DE6E0539B5A8F0A565E

Вихідні параметри:

ІД замовлення покупки в розстрочку, унікальний у межах Банку

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

Код відповіді Банку за запитом реєстрації замовлення

Текст відповіді Банку за запитом реєстрації замовлення

мобільний номер телефону клієнта Банку в міжнародному форматі (приклад, +380671111111)

4 останні цифри номера картки клієнта, за якою буде оформлено розстрочку

сума покупки (в копійках)

строк розстрочки (в місяцях)

У параметрі зі зазначенням терміну розстрочки дозволена передача значень від 1 до 24

код магазина Партнера

найменування товару/групи товарів

orderNom містить масив, значеннями якого є об'єкти {}, які своєю чергою мають ключ, значення name: string, sum: integer (у копійках), vat: integer (у копійках)

набір додаткових параметрів

Варіанти негативних відповідей:

statusCode
statusText
Примітка
NO_PARTNERID
«Партнер ${partnerId} не зареєстрований в системі!»*

NO_APP
«Замовлення не знайдено!»*

NO_CONTRAGENT_MPHONE
«Клієнта з номером телефону $ {contInf2Cellur} не знайдено»

NO_CARD_PANEND
«Картку за номером $ {card4Last} не знайдено»

LOW_BALANCE
«Недостатній баланс на картці»

INST_ALLOWED_FAIL
«За карткою ${card4Last} неможливо оформити розстрочку»

NO_PRODUCT
«Не знайдено продукт розстрочки»

CHECK_SMS_ERROR
«Неправильний код SMS!»
Статус означає, що надіслано некоректний код SMS
PURCHASE_IS_FAIL
«Покупка неуспішна! Замовлення не оформлено!»

PURCHASE_IS_FAIL_EX
«Покупка неуспішна! Замовлення не оформлено!»

NO_IDS
«Не передано ідентифікатор замовлення»

CLIENT_NO_SEND_SMS
«Клієнт не підтвердив розстрочку замовлення»

SYSTEM_ERROR
«Виникла системна помилка!»

FINAL_CANCEL_OK
«Обробка скасування замовлення з номером $ {orderId} успішна»
Статус означає, що заявку було скасовано
MORE_ORDERID
«За замовленням ${orderId} виявлено кілька записів!»

REQUEST_NOT_MATCH
«Запит не можна опрацювати. Перевірте статус замовлення»

* Якщо замовлення не знайдено (в параметрах запиту вказані некоректний ідентифікатор Партнера або замовлення) у відповіді всі вихідні параметри будуть порожніми, крім параметрів statusCode, statusText.

У всіх інших випадках — у відповіді набір параметрів замовлення буде непустим, параметри statusCode, statusText міститимуть поточне значення статусу обробки замовлення

Варіанти позитивних відповідей:

statusCode
statusText
Примітка
INST_ALLOWED_OK
«За карткою ${card4Last} можлива розстрочка, триває перевірка»
Проміжний статус у getOreder. Означає, що перевірки пройдено і Клієнту надіслано SMS
CHECK_SMS_OK
«Перевірка коду SMS успішна!»

PURCHASE_IS_OK
«Покупка успішна, відправлено Гарантійний лист!»
Потрібно орієнтуватися на цей статус
PRE_PURCHASE_IS_OK
«Покупка успішна, відправлено Гарантійний лист!»
Потрібно орієнтуватися на цей статус (для передавторизації)
FINAL_ORDER_OK
«Товар видано клієнту»

Приклад №1 statusCode - NO_PARTNERID, statusText - ''Партнер ${partnerId} не зареєстрований в системі!'':

Запит:

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getOrder/partnr?orderId=p12

out json

{

    "messageId": "",

    "orderId": "p12",

    "statusCode": "NO_PARTNERID",

    "statusText": "Партнер partnr не зареєстрований в системі!"

}

Примітка: Увести неіснуючий в системі partner_id, наприклад, partnr замість partner

Приклад №2 statusCode - NO_APP, statusText - ''Замовлення не знайдено!'':

Запит:

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getOrder/partner?orderId=p22

out json

{

    "messageId": "B6B920264F4E07AEE053AC112B083360",

    "orderId": "",

    "statusCode": "NO_APP",

    "statusText": "Замовлення не знайдено!"

}

Приклад №3 (Успішний кейс) statusCode - INST_ALLOWED_OK, statusText - "Товар видано клієнту"":

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getOrder/partner?orderId=p11

out json:

{

    "orderAdd": "",

    "orderId": "p12",

    "messageId": "B8F3737ECEC02C81E0539B5A8F0A34E7",

    "orderVat": "",

    "orderSum": "121600",

    "orderNom": [],

    "orderTerm": "3",

    "panEnd": "9654",

    "statusText": "Товар видано клієнту",

    "mPhone": "+380977896608",

    "shopId": "46546-?wfq?",

    "statusCode": "INST_ALLOWED_OK"

 }

(к оглавлению)

7.3 Отримання Гарантійного листа для замовлення: метод getGuarantee

Метод застосовується для отримання Гарантійного листа.

Може використовуватися в разі, - коли під час відправки Гарантійного листа виникла помилка.

Працює тільки для замовлень, за якими успішно відбулася купівля.

API:

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getGuarantee/PARTNER_ID?orderId= ІД_замовлення_партнер

або

https://mw-api-test.sensebank.kyiv.ua/proc-loan-sandbox/api/PartnerInstallment/v1.0/getGuarantee/PARTNER_ID?messageId= іД_замовлення_банк

HTTPS METHOD: GET

Залежно від налаштувань Партнера, з боку Банку можливі такі варіанти відправки Гарантійного листа (або їх комбінація):

у вигляді списку параметрів;

у форматі Base64 (pdf);

на e-mail.

Вихідні параметри:

ІД замовлення покупки в розстрочку, унікальний у межах Партнера (може містити цифри, букви, символи)

У параметрі з ІД замовлення або повернення дозволено використання символів латиниці, кирилиці, цифр та спецсимволів ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz АБВГДЕЖЗИКЛМНОПРСТУФХЦЧШЩЭЮЯ абвгдежзиклмнопрстуфхцчшщэюя 0123456789-_ /|

ІД замовлення покупки в розстрочку, унікальний у межах Банку

набір параметрів (у форматі json) для формування Гарантійного листа

текст Гарантійного листа у форматі Base64

код відповіді Банку за запитом відправки Гарантійного листа

текст відповіді Банку за запитом відправки Гарантійного листа