/
Інтеграція з сайтами контрагентів для розрахунку кредитного ліміту позичальника та створення заявки на кредит

Інтеграція з сайтами контрагентів для розрахунку кредитного ліміту позичальника та створення заявки на кредит

novapay-symbol.png

Основні поняття

  • Контрагент

Юридична особа або ФОП, яка укладає договір з ТОВ «НоваПей Кредит» для надання послуг кредитування фізичних осіб через свій веб-сайт або мобільний додаток.

  • Позичальник

Фізична особа, яка оформлює кредит у ТОВ «НоваПей Кредит» для оплати товарів чи послуг, запропонованих на веб-сайті або в мобільному додатку контрагента, і зобов’язується повернути отримані кошти відповідно до умов кредитного договору.

  • ТОВ «НоваПей Кредит»

Надає кредит позичальнику. Є частиною фінансової групи NovaPay і входить до великої родини NOVA. Компанія має всі необхідні ліцензії та дозволи НБУ.

Зміст

 

 

Послідовність дій оформлення кредиту через кол-центр контрагента

  1. Позичальник на веб-сайті або в мобільному додатку контрагента залишає заявку на покупку товару в кредит, вказуючи ПІБ, номер телефону та ІПН.

  2. Кол-центр контрагента зв'язується з позичальником для уточнення деталей, розрахунку кредитного ліміту та створення заявки на кредит.

  3. Кол-центр контрагента отримує від позичальника згоду на розрахунок кредитного ліміту та необхідні дані для скорингу. Далі контрагент надсилає запит на отримання токена за допомогою API-запиту /credits/auth.

  4. NovaPay передає токен контрагенту та надсилає позичальнику OTP-пароль для підтвердження скорингу. OTP-пароль дійсний протягом 5 хвилин.

  5. Кол-центр контрагента запитує OTP-пароль у позичальника.

  6. Кол-центр контрагента вводить OTP-пароль і підтверджує намір позичальника пройти скоринг, надсилаючи API-запит /credits/check-amount.

  7. NovaPay розраховує кредитний ліміт позичальника та надсилає контрагенту відповідь із погодженням і сумою ліміту.

  8. Кол-центр контрагента консультує позичальника щодо доступного ліміту.

  9. Кол-центр контрагента погоджує холдування ліміту на суму товару та надсилає API-запит /credits/hold із сумою товару та номером замовлення.

  10. NovaPay холдує суму ліміту під замовлення позичальника.

  11. Контрагент відправляє товар позичальнику відповідно до зазначеного номера замовлення.

  12. Позичальник отримує товар і завершує оформлення кредиту.

  13. NovaPay надсилає контрагенту підтвердження статусу оформлення замовлення в кредит.

з використанням Кол-центру мерчанта-2024-12-10-172035.png

Послідовність дій оформлення кредиту через веб-сайт/мобільний додаток контрагента без кол-центру.

  1. Позичальник на веб-сайті або у мобільному додатку контрагента обирає замовлення товару з оплатою в кредит від «Нова Пошта».

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

  3. Контрагент надсилає до NovaPay API-запит /credits/auth.

  4. NovaPay передає токен контрагенту та надсилає позичальнику OTP-пароль для підтвердження скорингу. OTP-пароль дійсний протягом 5 хвилин.

  5. Позичальник вводить OTP-пароль на веб-сайті або у мобільному додатку.

  6. Контрагент надсилає до NovaPay API-запит /credits/check-amount.

  7. NovaPay розраховує кредитний ліміт позичальника та надсилає контрагенту відповідь із погодженням і сумою ліміту.

  8. Контрагент відображає на веб-сайті або у мобільному додатку доступну суму ліміту для позичальника.

  9. Позичальник підтверджує оформлення замовлення в кредит.

  10. Контрагент надсилає до NovaPay API-запит /credits/hold, включаючи суму замовлення та номер замовлення.

  11. Контрагент відправляє товар позичальнику відповідно до зазначеного номера замовлення.

  12. Позичальник отримує посилку та завершує оформлення кредиту.

  13. NovaPay надсилає контрагенту підтвердження статусу оформлення замовлення в кредит.

 

mermaid-diagram-2024-12-10-171829.png

Дані для відправки в NovaPay для прорахунку ліміту або холдуванню коштів

Назва поля

Назва в обміні

Формат

Обов’язковість

Приклад

Назва поля

Назва в обміні

Формат

Обов’язковість

Приклад

1

Номер телефону

phone

string

+

+380633627500

2

ІПН

taxpayer_id

numeric

+

3351212458

3

Прізвище

last_name

string

+

Іванов

4

Ім’я

first_name

string

+

Іван

5

По батькові

patronymic

string

-

Іванович

6

Дата народження

birth_date

date

+

1991-10-19

7

Місце народження

birth_place

string

+

м.Київ

8

Тип документу

document_type

string

+

passport

9

Серія документу

document_series

string

-, у разі біометричного документу

НЕ

10

Номер документу

document_number

numeric

+

532407

11

Соціальний статус

social_status

string[]

+

["employee"]

12

Сума доходу, міс

monthly_income

amount

+

30000.00

13

Номер замовлення

id

string

+

10265896

14

Сума замовлення для оформлення в креди

amount

amount

+

30000.00

API Gateway Access token

http request header "x-access-token: <value>"

value - персональний токен, отриманий на момент інтеграції API

Отримання токену та перевірка можливості розрахунку ліміту

POST "/credits/auth"

Server-server request payload:

{ "taxpayer_id":"3351212458", "phone":"+380633627500", "last_name":"Іванов", "first_name":"Іван", "patronymic":"Іванович", "birth_date":"1991-10-19", "birth_place":"м.Київ", "document_type":"passport", "document_series":"НЕ", "document_number":"123456", "social_status":["emplyee"], "monthly_income":"30000.00" }

Successful response:

Status code: 200 body: { "token" }

Error response:

Status code: 400 for bad request 403 for unauthorized request 500 for internal error body: { "uuid": "d05f0d5b-7fc2-4747-a8df-769e6cc070fd", - ідентифікатор помилки "type": "processing", "error": "кредитний API-токен не відповідає даним", "code": "ContragentCreditApiTokenNotMatchError" }

Розрахунок суми кредитного ліміту по клієнту

POST "/credits/check-amount"

Server-server request payload:

{ "token":"token", "otp":"5555" }

Successful response:

Status code: 200 body: { "amount" – сума ліміту }

Error response:

Status code: 400 for bad request 403 for unauthorized request 500 for internal error body: { "error": "", "uuid" – ідентифікатор запиту }

Холдування суми ліміту під замовлення

POST "/credits/hold"

Server-server request payload:

{ "token":"token", "id":"10265896", "amount":"3000.00" }

Successful response:

Status code: 200 body: { "id": "07f46c4e-3f59-4da5-a2c3-319c0aa466c9", - id холду "requested_amount": 100000, - запитувана сума "amount": 5000 - сума холду }

Error response:

Status code: 400 for bad request 403 for unauthorized request 500 for internal error body: { "error": "", "uuid" – ідентифікатор запиту }

Приклади помилок і причини

Помилка

Причина

Помилка

Причина

{ "uuid": "3949a650-203e-4726-b8ec-92734758be2d", "type": "processing", "error": "термін дії кредитного API-токена закінчився", "code": "ContragentCreditApiTokenExpiredError" }

термін дії токену закінчився

{ "uuid": "50562a86-8a70-4997-a758-b80dc77231f5", "type": "validation", "errors": [ { "keyword": "errorMessage", "dataPath": "/phone", "schemaPath": "#/properties/phone/allOf/1/errorMessage", "params": { "errors": [ { "keyword": "validPhone", "dataPath": "/phone", "schemaPath": "#/properties/phone/allOf/1/validPhone", "params": { "keyword": "validPhone" }, "message": "should pass \"validPhone\" keyword validation" } ] }, "message": "телефон не валiдний" }, { "keyword": "errorMessage", "dataPath": "/taxpayer_id", "schemaPath": "#/properties/taxpayer_id/errorMessage", "params": { "errors": [ { "keyword": "validTaxpayerId", "dataPath": "/taxpayer_id", "schemaPath": "#/properties/taxpayer_id/validTaxpayerId", "params": { "keyword": "validTaxpayerId" }, "message": "should pass \"validTaxpayerId\" keyword validation" } ] }, "message": "Невірний номер РНОКПП (ІПН" } ] }

валідація на окремі поля

{ "uuid": "89545844-1a2e-4fbc-94cf-2529bb8a6a54", "type": "processing", "error": "кредитний токен використанний", "code": "ContragentCreditApiTokenUsedError" }

токен вже використовувався для оформлення холду

{ "uuid": "c836ffc5-9be6-425c-a81d-c9ca069ce83d", "type": "processing", "error": "Можливість оформити посилку в кредит відсутня.", "code": "CreditNotAvailableError" }

відмова у кредиті

{ "uuid": "bf5700ce-800a-42b7-a276-0a7eb58cde81", "type": "processing", "error": "введено невiрний OTP-пароль", "code": "OTPCheckFailedError" }

невiрний OTP-пароль

{ "uuid": "460e7f9c-835d-4e88-9ffd-56c2cb1aa53b", "type": "processing", "error": "необхiдно пiдтвердити операцiю за допомогою OTP паролю", "code": "OTPCheckRequiredError" }

непідтверджений OTP-пароль

Callback при оформленні замовлення в кредит

POST (Контрагент надає посилання для callback)

При успішному оформленні кредиту надсилається HTTP POST запит на надану адресу наступного виду:

POST / HTTP/1.1 Connection: close Accept: application/json Content-Type: application/json X-Sign: rXWBZI5bHvFtRt/scwBRaywiz46hfWr7ZI6LtZsdoG5T5pQjoXTdGdyq2uffu27pIvEAfyRw7widv4O2LsJwmg== {"id":"your-id","amount":20000,"status":"confirmed"}

Публічний ключ для перевірки підпису

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Mowsvdp9Gu7SVQodTfT y6G/TGpMHfR5bKAtoVyyxgbovSA+3CIzCjeQJdyN7NXw3M86DxtRVG0q/0Z9gL12 JAk7L48vQ690Q248cj2GrFR/oNXHllBPZM7rK4XLZyt1EVFWOtiopElJsogzp249 /Zz/nqxdKGxpbysj7NDkjg4QxafzXPIH5Pf/J8Yo8+z8jjIbVTYmuuCzrjh6yBj5 eqHRd3JuszvDwmbFQU67gwOPrnJsMp9uQyvJXL8toIhROJKDPq5LXk2Y8wNInzOb OUdwEyo8s3kyCx7UteR1dXFFYXIIbzVsaED7dkSufAop7fok/s+sfXyK/vRFOJOF JQIDAQAB -----END PUBLIC KEY-----

Приклад генерації підпису

Приватний ключ:

-----BEGIN RSA PRIVATE KEY----- MIIBOgIBAAJBANDiE2+Xi/WnO+s120NiiJhNyIButVu6zxqlVzz0wy2j4kQVUC4Z RZD80IY+4wIiX2YxKBZKGnd2TtPkcJ/ljkUCAwEAAQJAL151ZeMKHEU2c1qdRKS9 sTxCcc2pVwoAGVzRccNX16tfmCf8FjxuM3WmLdsPxYoHrwb1LFNxiNk1MXrxjH3R 6QIhAPB7edmcjH4bhMaJBztcbNE1VRCEi/bisAwiPPMq9/2nAiEA3lyc5+f6DEIJ h1y6BWkdVULDSM+jpi1XiV/DevxuijMCIQCAEPGqHsF+4v7Jj+3HAgh9PU6otj2n Y79nJtCYmvhoHwIgNDePaS4inApN7omp7WdXyhPZhBmulnGDYvEoGJN66d0CIHra I2SvDkQ5CmrzkW5qPaE2oO7BSqAhRZxiYpZFb5CI -----END RSA PRIVATE KEY-----

Тестові дані:

{"id":"your-id","amount":20000,"status":"confirmed"}

Результуючий підпис:

rXWBZI5bHvFtRt/scwBRaywiz46hfWr7ZI6LtZsdoG5T5pQjoXTdGdyq2uffu27pIvEAfyRw7widv4O2LsJwmg==

Приклад з OpenSSL:

echo -n '{"id":"your-id","amount":20000,"status":"confirmed"}' | openssl dgst -sha1 -sign myprivate.pem |  openssl enc -base64

Довідники

Список можливих соціальних статусів позичальника:

  1. employee - найманий працівник

  2. private_entrepreneur - підприємець ФОП

  3. attorney - власна справа, адвокат, нотаріус

  4. unemployed - безробітний

  5. pensioner - пенсіонер

  6. student - студент

  7. civil_servant - держслужбовець

  8. serviceman - військовослужбовець

  9. maternity_leave - декретна відпустка

Список можливих документів позичальника:

  1. passport - паспорт громадянина України (книжка)

  2. biometric_passport - біометричний паспорт громадянина України

  3. international_passport - паспорт громадянина України для виїзду за кордон

Список статусів заявки на кредит:

  1. confirmed - кредит видано

  2. expired - холд скасовувано (автоматичне скасування заявки через 10 днів, якщо кредит не оформлено)

In NovaPay We Trust