# API для кредитора
# End-to-end API
Данная схема взаимодействия предполагает полноценное обслуживание заемщика на стороне Mandarin - от оформления и подписания до последующего внесения платежей и работы с просрочкой
# Введение
XML API Smart Contract Processor (он же SCP) обеспечивает для разработчика приложений возможность автоматического заключения унифицированных договоров при посредничестве платформы Mandarin.
# - Точка входа
Точка входа SCP API:
https://api.psp.io/life-backend/scpapi
Для разработки, тестирования и боевой эксплуатации используются одни и те же точки входа.
При этом Вам нужно запросить настройку тестового магазина для отправки заявок при разработке и тестировании.
# - Точка входа в ПО партнёра
Для интеграции с системой компания-партнер должна создать собственную точку входа, обеспечивающую работу по интерфейсу SCP API (опкоды 790-796).
При начале совместной работы, ПО партнёра регистрируется в SCP, который должен иметь возможность передать в ПО партнёра информационный запрос. Информация об адресе точки входа в ПО партнёра передаётся уполномоченному сотруднику Mandarin для включения в whitelist (возможно включение диапазона).
# - Способ отправки запроса
Передача и прием XML-запросов осуществляется методом HTTP POST, с указанием
Content-Type: application/xml.
В теле (body) http-запроса располагается собственно запрос к API, который должен
представлять собой корректный XML, начинающийся с дескриптора <?xml version="1.0" encoding="utf-8"?>.
В случае отправки запроса из среды PHP рекомендуется использовать следующий образец кода:
\$url = (URL сервера SCP);
\$ch = curl_init();
curl_setopt(\$ch, CURLOPT_URL, \$url);
curl_setopt(\$ch, CURLOPT_POST, 1);
curl_setopt(\$ch, CURLOPT_POSTFIELDS, \$xml);
curl_setopt(\$ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(\$ch, CURLOPT_HEADER, false);
curl_setopt(\$ch, CURLOPT_CONNECTTIMEOUT, 120);
curl_setopt(\$ch, CURLOPT_TIMEOUT, 120);
curl_setopt(\$ch, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));
\$response = curl_exec(\$ch);
curl_close(\$ch);
return \$response;
где:
$ch – дескриптор сURL;
$xml – переменная, содержащая сформированный XML-запрос.
# - Схема взаимодействия
# - Workflow заключения контракта в SCP API
В настоящее время в SCP API реализован процесс заключения единственного типа
контракта – потребительского кредитования (contract_type=1). В нем участвуют
следующие компоненты:
платежная страница (ПС) – фрейм на веб-сайте онлайн-магазина (мерчанта), открывающийся по кнопке «Оплатить в кредит» и предлагающий пользователю (покупателю) ввести свой емейл в качестве логина для перехода к следующим этапам.
личный кабинет (ЛК) на веб-сайте Мандарин, обеспечивающий заполнение (и контроль) анкеты пользователя, выбор подходящего кредитного предложения и подписание кредитного договора с выбранным кредитором.
платежный шлюз – сервер системы, обеспечивающий проведение и учет платежей (как с карточки покупателя, так и с расчетного счета кредитора).
информационный шлюз – сервер системы, обеспечивающий хранение и выдачу служебной информации о всех сущностях системы (например, скоринговых параметров покупателя или расчетного счета конкретного кредитора).
контрактный шлюз – сервер системы, поддерживающий процедуру заключения контрактов через SCP API.
Процесс оформления потребительского кредита состоит из следующих этапов:
1. Регистрация заявки на получение потребительского кредита, заполнение анкеты заемщика
2. Сбор кредитных предложений по заявке
В ЛК пользователь проверяет существующую заявку (из какого магазина, на какую сумму, и т.д.), заполняет недостающие поля (например, предельную ставку по кредиту) и подтверждает свое намерение получить кредит (кнопка «Получить кредитные предложения). ЛК направляет в контрактный шлюз запрос (опкод 790), содержаший дополненную информацию о заявке. Заявка переводится из статуса неподтвержденной в статус активной, кредиторам рассылается уведомление (тот же запрос, с опкодом 790, но уже от имени системы) с целью сбора кредитных предложений. В случае, если у магазина активирован функционал онлайн-оформления, заявка будет включать в себя фото или сканы документов (две страницы паспорта, и сэлфи заемщика с паспортом).
Далее в течение установленного в системе срока (от 30 секунд до 10 минут) выдерживается пауза, в течение которой кредиторы имеют возможность направить в адрес системы пакеты кредитных предложений (опкод 791). По окончании периода сбора предложений, заемщик выбирает одно из них, по которому подписывает кредитный договор.
При необходимости, кредитор может запросить сканы всех документов, когда-либо загруженных для заявки (в том числе для предыдущих попыток, когда по заявке было отказано по причине "Неудовлетворительное качество фотографий"), с помощью запроса с опкодом 796.
3. Подписание кредитного договора
В составе кредитного предложения содержится поле «ссылка на текст договора». Текст договора выводится на экран, пользователю предоставляется возможность подписать его через СМС (на телефон, указанный в анкете пользователя). По кнопке «Подписать» ЛК производит проверку платежеспособности пользователя путем предавторизации суммы первоначального платежа (запрос к платежному шлюзу). В случае, если первоначальный платеж в кредитном предложении не предусмотрен, производится предавторизация суммы в 1 рубль, с последующей отменой.
Если кредитору в силу принятого порядка оформления кредита требуется информация об успешной предавторизации первоначального платежа, ЛК производит его уведомление (опкод 792 PutProposal, Result=Preauth).
Если предавторизация проходит успешно, ЛК отправляет в контрактный шлюз запрос (опкод 794, GetConfirm) на отправку пин-кода по СМС. Контрактный шлюз проверяет соответствие параметров запроса (ContractorSiteID и ContractProposalID) имеющимся предложениям, и в случае совпадения формирует уникальный идентификатор контракта – ContractID – представляющий собой конкатенацию из дополненного до 10 знаков номера заявки, ContractorSiteID и ContractProposalID (пример: 0000000123-999999-0001-9876). Примечание: в текущей версии SCP этот код носит справочный характер, в дальнейшем он станет основным идентификатором при работе с подписанными контрактами.
Получив СМС с пин-кодом, пользователь вводит его в соответствующую экранную форму. ЛК отправляет в контрактный шлюз запрос (опкод 794, PutConfirm), содержащий полученный пин-код. В случае положительного ответа (message=OK) контрактного шлюза договор считается подписанным.
Контрактный шлюз может работать в двух режимах: либо самостоятельно высылать СМС, либо перенаправлять 794 запрос кредитору, для генерации пин-кода на его стороне. В первом случае после совпадения пин-кода контрактный шлюз высылает кредитору уведомление о подписании договора, и ждет его подтверждения (согласия), во втором случае – высылает полученный пин-код, и тоже ждет подтверждения. В том и в другом варианте подтверждение 794 PutConfirm являются согласием кредитора с выдачей кредита.
После подписания кредитного договора контрактный шлюз отправляет в платежный шлюз колбэк, содержащий номер платежной транзакции и статус success, означающий, что платеж в кредит указанной в транзакции суммы завершен. Платежная страница получает информацию об изменении статуса (путем регулярного опроса CheckState или через колбэк) и уведомляет об оплате магазин.
4. Оплата первоначального взноса и тела кредита
В случае, если на предыдущем этапе был предавторизован первоначальный платеж, ЛК производит списание этой суммы в пользу магазина. Затем ЛК производит списание суммы кредита со счета кредитора в системе.
5. Просмотр текущего состояния платежей по кредиту
# Описание API контрактного шлюза
# - Перечень операций контрактного шлюза
| Операция (опкод) | Действия контрактного шлюза | Действия клиентской подсистемы SCP (на стороне кредитора) |
|---|---|---|
| 790 ContractRequest | Регистрирует заявку на кредит. Объединяет заявку с данными заемщика, полученными из информационного шлюза. В случае, если магазин передает онлайн-заявки, хранит фотографии документов. Передаёт заявку, включающую параметры займа и анкету заёмщика, кредиторам. | Принимает запрос и вызывает процедуру подготовки предложений Требуется уложиться в срок, указанный в поле ActualUntil. |
| 791 ContractProposals | Принимает запрос, сохраняет полученные предложения в информационном шлюзе | Передаёт предложения о заключении займа или отказ. В одном информационном пакете может быть несколько предложений. В случае отказа сообщается его причина (поле RejectCause) |
| 794 ContractSign | Принимает запрос, формирует пин-код и передает его по СМС для подписания договора. После подписания уведомляет кредитора о том, что заемщик подписал договор. | Принимает сообщение о подписании договора и в синхронном режиме подтверждает его заключение. Ответ message=OK означает, что договор вступает в силу, и кредитные средства могут быть перечислены со счета кредитора на счет онлайн-магазина. |
| 796 DocumentScan | По запросу от кредитора (то есть опционально), возвращает сканы всех документов, когда-либо загруженных для заявки. | При необходимости, использует эту информацию для решения о предложении займа (791 запрос). |
# - Общий формат запросов и ответов SCP API
Запросы в системе представляют собой XML-строки, содержащие стандартный заголовок:
<request>
<Opcode>790</Opcode>
<SiteID>111111-1111</SiteID>
<timestamp>1471836223</timestamp>
<hash>5b504cc034c09160fadc4950b287aed3</hash>
<contract_type>1</contract_type>
<Action>GetProposals</Action>
...
</request>
Здесь:
Opcode – один из операционных кодов, перечисленных выше
SiteID – идентификатор магазина и/или заимодавца, в формате: шесть цифр – код клиента/организации, четыре цифры – код веб-сайта (веб-сервиса)
timestamp – unix-timestamp момента формирования запроса в вызывающей системе (т.е. число секунд, прошедших с 1.01.1970), используемый для расчета hash и авторизации доступа
hash – контрольное значение для авторизации, рассчитываемое по формуле:
hash = md5('secret-Opcode-SiteID-timestamp'), где secret – секретный код, назначенный конкретному магазину (SiteID)
Action – символьный код конкретного действия, совершаемого в рамках операции
Вслед за заголовком идут изменяющиеся элементы запроса, согласно описанным далее схемам.
Ответы в SCP API соответствуют следующему формату:
<response>
<date>2016-11-15T05:08:43+00:00</date>
<message>OK</message>
<code>000</code>
<result>
...
</result>
</response>
Код 000 и message=OK означают успешное завершение операции. В случае ошибки
возвращается код, отличный от 000, а в параметре message – сообщение об ошибке.
В поле result содержится вложенный XML с результатами операции, содержимое
которого разное для разных опкодов.
# - Запрос предложений на заключение договора (Опкод 790 ContractRequest)
На первом этапе основное приложение направляет вызов в SCP, с передачей данных о заемщике и требуемых условий договора. На втором этапе SCP производит рассылку запросов в системы кредиторов, согласно имеющемуся реестру партнеров.
[стандартный заголовок, SiteID = продавец]
Action = GetProposals
1. ContractRequest
1.1. ContractType - строка из классификатора, всегда равна 1
1.2. MerchantSiteID – идентификатор магазина в системе (дублирует SiteID из
заголовка в случае прямого запроса от магазина к шлюзу, однако в большинстве
случаев запрос производится от имени платежной системы, поэтому ее SiteID и
MerchantSiteID не совпадают)
1.3. ContractRequestID - идентификатор запроса на заключение договора.
Назначается инфошлюзом автоматически (т.е. он не передается в запросе
магазина, а передается только кредитору)
1.4. Created – момент создания запроса в формате yyyy-MM-dd hh:mm:ss+hh:mm
1.5. ActualUntil – предельный срок предоставления предложения, в том же
формате
1.6. ReservedUntil – предельный срок резервирования товара или услуги, в том
же формате
1.7. OrderID - уникальный идентификатор заказа внутри магазина (опциональный)
1.8. OrderDescription – описание заказа (перечень товаров, услуг, или иной
текст; опциональный)
1.9. Status - строка из классификатора (зарезервировано)
1.10. TransactionSiteID – идентификатор сайта, инициировавшего платеж в кредит
1.11. TransactionID – идентификатор транзакции в платежном шлюзе
1.12. Repeated – признак повторной заявки (в случае, если ранее на нее уже был
отказ)
1.13. RegionIP – регион заявителя, установленный по IP
1.14. LoanSpecification - специфические параметры, актуальные для конкретного
контракта; множественная секция, т.к. одна заявка может содержать несколько
разных наборов условий, например, несколько разных сроков кредита
1.14.1. Maturity – срок кредита в месяцах; может быть пустым, в этом случае
кредитор должен отправить предложения по всем приемлемым для себя срокам
1.14.2. Amount – сумма кредита *)
1.14.3. MinimalFirstPayment - минимальный начальный платёж в процентах от суммы
(от 0 до 100). Опциональный.
1.14.4. MaximalYearPercent - максимальная полная цена займа в годовых процентах
1.14.5. Purpose – цель кредита (необязательный)
1.14.6. ProductType – тип кредита (необязательный)
1.15. Person – Сведения о физическом лице – заёмщике. В дальнейшем
идентифицируется по PersonID. Поля описаны в схемах Person, Document и Address в
разделе 4.
1.16. Card – сведения о кредитной карте (необязательный)
1.16.1. Holder
1.16.2. Number
1.16.3. Expiration
1.17. ScanDocumentsAvailable - индикатор, загружены ли сканы документов заемщика (для онлайн-оформления).
1.18. DocumentScan - секция, хранящая сканы документов заемщика (для онлайн-оформления).
1.18.1. Type - тип документа. Возможные значения: passport_main (страница паспорта с фотографией); passport_registration_address (страница паспорта с постоянной регистрацией); selfie (сэлфи заемщика с документом).
1.18.2. Filename - имя и расширение файла.
1.18.3. CreatedAt - дата загрузки файла.
1.18.4. AttemptsCount - счетчик попыток предоставления скана документа.
1.18.5. Data - изображение (размером до 7 Мб), закодированное в Base64.
Примечание. Суммой кредита в этом документе называется общая стоимость товара (услуги). Она состоит из:
начального платежа, поступающего с карты покупателя, и
займа, поступающего со счета кредитора.
Во всех спецификациях сумма кредита включает в себя начальный платеж, поэтому к ней обязательно прилагается второй параметр – размер начального платежа в процентах.
Пример полного запроса, который посылается контрактным шлюзом кредиторам:
<request>
<Opcode>790</Opcode>
<SiteID>111111-1111</SiteID>
<timestamp>1479178288</timestamp>
<hash>22e636af803be898a79b68e23792d633</hash>
<contract_type>1</contract_type>
<Action>GetProposals</Action>
<ContractRequest>
<AttemptsCount>1</AttemptsCount>
<ContractType></ContractType>
<MerchantSiteID>111111-1111</MerchantSiteID>
<ContractRequestID>59</ContractRequestID>
<Created>2016-11-07 15:30:00+00:00</Created>
<ActualUntil>2016-11-15 07:52:27.793000+00:00</ActualUntil>
<ReservedUntil>2016-11-20 09:00:00+00:00</ReservedUntil>
<OrderID>003</OrderID>
<OrderDescription>something</OrderDescription>
<Status></Status>
<TransactionSiteID></TransactionSiteID>
<TransactionID></TransactionID>
<Repeated></Repeated>
<RegionIP></RegionIP>
<LoanSpecification>
<Maturity>3</Maturity>
<Amount>50000.0</Amount>
<Purpose></Purpose>
<ProductType></ProductType>
<MinimalFirstPayment></MinimalFirstPayment>
<MaximalYearPercent>60.0</MaximalYearPercent>
</LoanSpecification>
<Person>
<rucitizenship>True</rucitizenship>
<OGRNIP>303456789012345</OGRNIP>
<DocScan>
<ScanNum>1</ScanNum>
<scanFileID></scanFileID>
<ScanName>первая страница</ScanName>
<DocumentType>
<RFNSPDocid>21</RFNSPDocid>
</DocumentType>
</DocScan>
<DocScan>
<ScanNum>2</ScanNum>
<scanFileID></scanFileID>
<ScanName>вторая страница</ScanName>
<DocumentType>
<RFNSPDocid>21</RFNSPDocid>
</DocumentType>
</DocScan>
<fotoFileID></fotoFileID>
<Document>
<Docnum>543987</Docnum>
<Docissuingdate>2011-01-01</Docissuingdate>
<Docissuercode>770-001</Docissuercode>
<Docseria>7709</Docseria>
<DocumentType>
<RFNSPDocid>21</RFNSPDocid>
</DocumentType>
<Docissuer>УПРАВЛЕНИЕ ФЕДЕРАЛЬНОЙ МИГРАЦИОННОЙ СЛУЖБЫ РОССИИ ПО
ГОР.МОСКВЕ</Docissuer>
</Document>
<Document>
<Docnum>987654</Docnum>
<Docissuingdate>2015-08-17</Docissuingdate>
<Docissuercode></Docissuercode>
<Docseria>111</Docseria>
<DocumentType>
<RFNSPDocid>22</RFNSPDocid>
</DocumentType>
<Docissuer></Docissuer>
</Document>
<Email>sharikov\@narod.com</Email>
<Agreement>
<microcreditLiability>True</microcreditLiability>
</Agreement>
<Phone>+79024731438</Phone>
<FinanceInfo>
<MainIncome>120000</MainIncome>
<LivingStatus>
<Code>1</Code>
</LivingStatus>
<CreditExpenses>150000</CreditExpenses>
<WageDate>2016-09-30</WageDate>
</FinanceInfo>
<CardInfo>
<BIN>405060</BIN>
<Cardtype>
<Code>1</Code>
</Cardtype>
<Cardholder>POLIGRAF SHARIKOV</Cardholder>
<Expiration>2018-05</Expiration>
<PAN>1234</PAN>
</CardInfo>
<Name>Полиграф</Name>
<Car>
<Brand>Ford</Brand>
<RuCarNumber>A123AA199</RuCarNumber>
<ProductionYear>2008</ProductionYear>
<Model>Focus</Model>
</Car>
<Car>
<Brand>Ford</Brand>
<RuCarNumber>A124AA199</RuCarNumber>
<ProductionYear>2015</ProductionYear>
<Model>Kuga</Model>
</Car>
<Address>
<city_type>город</city_type>
<state_name>-</state_name>
<house>д. 10</house>
<street_name>Садовая Б.</street_name>
<street>ул. Б.Садовая</street>
<np_type>-</np_type>
<building_name>-</building_name>
<city>г. Москва</city>
<AddressType>
<Code>2</Code>
</AddressType>
<house_name>10</house_name>
<reg_date>2010-01-01</reg_date>
<state>-</state>
<np>-</np>
<flat>кв. 20</flat>
<region_name>Москва</region_name>
<flat_type>квартира</flat_type>
<rupostindex>125047</rupostindex>
<flat_name>20</flat_name>
<street_type>улица</street_type>
<city_name>Москва</city_name>
<house_type>дом</house_type>
<building>-</building>
<state_type>-</state_type>
<region>г. Москва</region>
<BuildingClass>
<Code>3</Code>
</BuildingClass>
<np_name>-</np_name>
<rawaddress>Москва, Большая Садовая, 10, кв. 20</rawaddress>
<building_type>-</building_type>
<region_type>город</region_type>
<living_date>2011-07-25</living_date>
</Address>
<Address>
<city_type>город</city_type>
<state_name>-</state_name>
<house>д. 10</house>
<street_name>Садовая Б.</street_name>
<street>ул. Б.Садовая</street>
<np_type>-</np_type>
<building_name>-</building_name>
<city>г. Москва</city>
<AddressType>
<Code>1</Code>
</AddressType>
<house_name>10</house_name>
<reg_date>2010-01-01</reg_date>
<state>-</state>
<np>-</np>
<flat>кв. 13</flat>
<region_name>Москва</region_name>
<flat_type>квартира</flat_type>
<rupostindex>125047</rupostindex>
<flat_name>13</flat_name>
<street_type>улица</street_type>
<city_name>Москва</city_name>
<house_type>дом</house_type>
<building>-</building>
<state_type>-</state_type>
<region>г. Москва</region>
<BuildingClass>
<Code>1</Code>
</BuildingClass>
<np_name>-</np_name>
<rawaddress>Москва, Большая Садовая, 10, кв. 13</rawaddress>
<building_type>-</building_type>
<region_type>город</region_type>
<living_date>2011-07-25</living_date>
</Address>
<SNILS>13738699108</SNILS>
<LoanInfo>
<AverageLoanMaturity>18.0</AverageLoanMaturity>
<MinLoanPercent>14.0</MinLoanPercent>
<AverageLoanPercent>16.0</AverageLoanPercent>
<CreditHistoryUser>Mandarin</CreditHistoryUser>
<MaxLoanMaturity>24.0</MaxLoanMaturity>
<MaxLoanAmount>100000.0</MaxLoanAmount>
<PaidLoans>0</PaidLoans>
<ActiveLoans>2</ActiveLoans>
<DaysLeftReject>0</DaysLeftReject>
<CreditHistoryConsent>True</CreditHistoryConsent>
<InBlackList>False</InBlackList>
<CreditHistoryExpireDate>2016-10-30</CreditHistoryExpireDate>
<MaxLoanPercent>18.0</MaxLoanPercent>
<CreditHistoryConsentDate>2016-09-30</CreditHistoryConsentDate>
<MinLoanMaturity>12.0</MinLoanMaturity>
<AverageLoanAmount>75000.0</AverageLoanAmount>
<MinLoanAmount>50000.0</MinLoanAmount>
<DaysLeftLast>100</DaysLeftLast>
<CreditHistoryPurpose>1</CreditHistoryPurpose>
</LoanInfo>
<BirthPlace>Москва</BirthPlace>
<Citizenship>
<CountryCode>643</CountryCode>
</Citizenship>
<Family>Шариков</Family>
<PersonID>24</PersonID>
<Phones>
<PhoneCode>+7495</PhoneCode>
<PhoneNumber>2504010</PhoneNumber>
<PhoneType>
<Code>1</Code>
</PhoneType>
</Phones>
<Phones>
<PhoneCode>+7495</PhoneCode>
<PhoneNumber>2501040</PhoneNumber>
<PhoneType>
<Code>2</Code>
</PhoneType>
</Phones>
<FamilyInfo>
<MaritalStatus>
<Code>2</Code>
</MaritalStatus>
<DependentsNumber>2</DependentsNumber>
</FamilyInfo>
<Sex>муж</Sex>
<BirthDay>1975-05-19</BirthDay>
<isLivingOnRegistration>True</isLivingOnRegistration>
<INNFL>123456789012</INNFL>
<OKTMO>45320000</OKTMO>
<JobInfo>
<OccupationType>ловец</OccupationType>
<OccupationPost>менеджер</OccupationPost>
<OccupationExperience>16</OccupationExperience>
<ProfessionalExperience>16</ProfessionalExperience>
<OccupationIndustry>сервис</OccupationIndustry>
<EmployerType>госпредприятие</EmployerType>
<EmployerIndustry>сервис</EmployerIndustry>
<EmployerName>Очистка</EmployerName>
</JobInfo>
<Education>
<Code>1</Code>
</Education>
<Patronim>Полиграфович</Patronim>
</Person>
<Card>
<Holder></Holder>
<Number></Number>
<Expiration></Expiration>
</Card>
<ScanDocumentsAvailable>True</ScanDocumentsAvailable>
<DocumentScan>
<Type>passport_main</Type>
<Filename>scan1.jpg</Filename>
<CreatedAt>2021-03-19T15:00:46.763336</CreatedAt>
<AttemptsCount>1</AttemptsCount>
<Data>QUFBCg==</Data>
</DocumentScan>
<DocumentScan>
<Type>passport_registration_address</Type>
<Filename>scan2.jpg</Filename>
<CreatedAt>2021-03-19T15:01:23.634684</CreatedAt>
<AttemptsCount>1</AttemptsCount>
<Data>YmJiCg==</Data>
</DocumentScan>
<DocumentScan>
<Type>selfie</Type>
<Filename>scan3.jpg</Filename>
<CreatedAt>2021-03-19T15:02:17.536733</CreatedAt>
<AttemptsCount>1</AttemptsCount>
<Data>ZaqiCg==</Data>
</DocumentScan>
</ContractRequest>
</request>
Ответ на запрос со стороны сервиса кредитора:
<response>
<date>2016-11-15T05:08:43+00:00</date>
<message>OK</message>
<code>000</code>
<result>
<GetProposals>OK</GetProposals>
</result>
</response>
# - Передача предложений на заключение договора (Опкод 791 ContractProposal)
В течение времени актуальности запроса на заключение договора система кредитора может отправить предложение (оферту) на выдачу кредита. Это делается запросом в SCP следующего формата:
[стандартный заголовок, SiteID = кредитор]
Action = PutProposals (единственный вариант)
1. ContractProposals – контейнер для предложений
1.1. ContractProposal – предложение (можно представить несколько разных
вариантов)
1.1.1. AttemptsCount - счетчик повторных запросов. Для корректной обработки
нужно отправлять то же значение, которое было получено в последнем запросе "790
ContractRequest". Заемщик видит в личном кабинете только предложения с текущим
номером AttemptsCount.
1.1.2. ContractType - строка из классификатора, всегда равна 1
1.1.3. MerchantSiteID – идентификатор магазина в системе, для которого
действительно предложение
1.1.4. ContractRequestID - идентификатор запроса на заключение договора
1.1.5. ContractorSiteID - идентификатор кредитора в шлюзе xxxxxx-yyyy
(может дублировать SiteID из заголовка,если кредитор работает с системой
непосредственно, но может и отличаться, если кредитор пользуется промежуточной
системой скоринга)
1.1.6. ContractProposalID - уникальный идентификатор предложения внутри
информационной системы кредитора
1.1.7. Created - момент создания запроса в формате yyyy-MM-dd hh:mm:ss+hh:mm
1.1.8. Status - строка из классификатора (зарезервировано)
1.1.9. ContractTextURL – ссылка на текст кредитного договора по данному
предложению
1.1.10. RejectCause – развернутая причина отказа (например, «заемщику меньше 21
года»)
1.1.11. LoanSpecification - специфические параметры, актуальные для конкретного
займа (Loan)
1.1.11.1. LoanType – тип кредита; в настоящее время поддерживается только
месячный аннуитет – AnnualMonth
1.1.11.2. PurchaseAmount – сумма покупки (кредит вместе с начальным платежом)
1.1.11.3. LoanAmount – сумма кредита.
1.1.11.4. LoanFirstPayment – размер начального платежа в единицах (0.1, а не
10%)
1.1.11.5. LoanYearPercent - ставка годовых в процентах
1.1.11.6. ReturnDate – дата возврата займа(кратна 30 дням с даты выдачи займа)
1.1.11.7. AnnualPayment – сумма аннуитетного платежа (в случае AnnualMonth типа
кредита – ежемесячного)
1.1.11.8. AnnualPeriods – количество периодов, на который выдается займ (в
случае AnnualMonth - месяцев)
1.1.11.9. LoanLimit – лимит (максимальная сумма) кредита, доступного данному
пользователю в соответствии со скорингом (в случае, если запрошенная в заявке
790 сумма кредита превышает лимит, и кредитное предложение выставлено на
максимально допустимую сумму, это поле позволяет понять, почему сумма кредита не
соответствует запрошенной)
1.1.11.10. PaymentsPlan – таблица в JSON формате, содержашая платежный календарь
по кредиту при условии его оформления в день заявки.
1.1.11.11. LoanID - уникальный идентификатор предложения внутри кредитора
(опционально, основным идентификатором является ContractProposalID).
1.1.12. Person
1.1.12.1. PersonID – идентификатор физического лица, для которого действительно
данное предложение
В случае отсутствия предложений (отказа конкретному физическому лицу, или
невозможность удовлетворить запрошенным условиям) секция LoanSpecification может
быть опущена, равно как и ненужные в этом случае поля.
Пример запроса:
<request>
<Opcode>791</Opcode>
<SiteID>111111-1111</SiteID>
<timestamp>1471836223</timestamp>
<hash>37c6a6d390ba38bb28a02ffe5f44b58d</hash>
<contract_type>1</contract_type>
<Action>PutProposals</Action>
<ContractProposals>
<ContractProposal>
<AttemptsCount>1</AttemptsCount>
<ContractType>1</ContractType>
<MerchantSiteID>111111-1111</MerchantSiteID>
<ContractRequestID>60</ContractRequestID>
<ContractorSiteID>999999-9991</ContractorSiteID>
<ContractProposalID>1003</ContractProposalID>
<Created>2016-11-16 17:38:00+05:00</Created>
<Status>0</Status>
<ContractTextURL>http://localhost:8080/contract-1003.html</ContractTextURL>
<RejectCause></RejectCause>
<LoanSpecification>
<LoanID>1003</LoanID>
<LoanType>AnnualMonth</LoanType>
<PurchaseAmount>50000.00</PurchaseAmount>
<LoanAmount>45000.00</LoanAmount>
<LoanFirstPayment>0.1</LoanFirstPayment>
<LoanYearPercent>45.0</LoanYearPercent>
<AnnualPayment>16677.00</AnnualPayment>
<AnnualPeriods>3</AnnualPeriods>
<ReturnDate>2017-02-16</ReturnDate>
</LoanSpecification>
<Person>
<PersonID>24</PersonID>
</Person>
</ContractProposal>
<ContractProposal>
<ContractType>1</ContractType>
<MerchantSiteID>111111-1111</MerchantSiteID>
<ContractRequestID>61</ContractRequestID>
<ContractorSiteID>999999-9991</ContractorSiteID>
<ContractProposalID>1004</ContractProposalID>
<Created>2016-11-16 17:38:00+05:00</Created>
<Status>0</Status>
<ContractTextURL>http://localhost:8080/contract-1003.html</ContractTextURL>
<RejectCause></RejectCause>
<LoanSpecification>
<LoanID>1004</LoanID>
<LoanType>AnnualMonth</LoanType>
<PurchaseAmount>50000.00</PurchaseAmount>
<LoanAmount>45000.00</LoanAmount>
<LoanFirstPayment>0.1</LoanFirstPayment>
<LoanYearPercent>45.0</LoanYearPercent>
<AnnualPayment>16677.00</AnnualPayment>
<AnnualPeriods>3</AnnualPeriods>
<ReturnDate>2017-02-16</ReturnDate>
</LoanSpecification>
<Person>
<PersonID>24</PersonID>
</Person>
</ContractProposal>
</ContractProposals>
</request>
Пример успешного ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<external_result_info>
<result_error>0</result_error>
<result_status>0</result_status>
<result_message>Accepted proposals from [u'004299-0004'] for
[u'27419']</result_message>
<result_type>0</result_type>
<result_source>0</result_source>
</external_result_info>
<date>2019-10-15T12:59:09+00:00</date>
<message>OK</message>
<code>000</code>
<result>
<proposal>
<message>OK</message>
<ContractProposalID>0000027419-004299-0002-2741641</ContractProposalID>
</proposal>
</result>
</response>
Пример ответа с ошибкой:
<response>
<date>2016-11-15T17:30:17+00:00</date>
<message>OK</message>
<code>000</code>
<result>
<proposal>
<message>OK</message>
<ContractProposalID>1003</ContractProposalID>
</proposal>
<proposal>
<message>ContractRequestID 61 not found</message>
<ContractProposalID>1004</ContractProposalID>
</proposal>
</result>
</response>
# - Подписание выбранного контракта (Опкод 794 ContractSign)
Выдача кредита пользователю должна быть подтверждена согласием именно этого пользователя, а не лица, работающего в веб-интерфейсе; для этого служит авторизация по СМС, отправленном на телефон, указанный в анкете пользователя. Такая авторизация считается подписанием выбранного контракта (кредитного предложения) и осуществляется с помощью операции 794 ContractSign.
Подписание контракта производится в синхронном режиме: после отправки в контрактный шлюз запроса с указанием пин-кода сразу же приходит уведомление о подписании-неподписании контракта.
[стандартный заголовок, SiteID магазина]
Action:
GetConfirm – запрос генерации пин-кода и его отправки по СМС пользователю
(поля ContractProposalPIN и ContractProposalSigned при этом не заполняются)
PutConfirm – передача введенного пользователем пин-кода и получение
подтверждения о его совпадении (используется поле ContractProposalPIN); передача
сообщения о подписании контракта кредитору и получение его согласия
(используется поле ContractProposalSigned)
ContractProposal – предложение (в случае магазина - едини
1.1. ContractType - строка из классификатора, всегда равна 1
1.2. MerchantSiteID - идентификатор магазина в платежном шлюзе xxxxxx-yyyy
1.3. ContractRequestID - идентификатор запроса на заключение договора
1.4. ContractorSiteID - идентификатор кредитора в шлюзе xxxxxx-yyyy
1.5. ContractProposalID - уникальный идентификатор предложения внутри
информационной системы кредитора
1.6. Message – текст сообщения СМС, к которому будет добавлен сгенеренный
пинкод (по умолчанию используется: «Ваш ПИН-код для подписания договора»)
1.7. ContractProposalPIN – пин-код, введенный пользователем
1.8. ContractProposalSigned – уведомление о подписании контракта, высылаемое
кредитору; ответ кредитора message=OK на 794 запрос PutConfirm означает
подтверждение подписания контракта и вступление его в силу (является основанием
для платежа)
Пример запроса GetConfirm:
<request>
<Opcode>794</Opcode>
<SiteID>111111-1111</SiteID>
<timestamp>1471836223</timestamp>
<hash>5b504cc034c09160fadc4950b287aed3</hash>
<contract_type>1</contract_type>
<Action>GetConfirm</Action>
<ContractProposal>
<ContractType>1</ContractType>
<MerchantSiteID>111111-1111</MerchantSiteID>
<ContractRequestID>60</ContractRequestID>
<ContractorSiteID>999999-9991</ContractorSiteID>
<ContractProposalID>1003</ContractProposalID>
<Message>Ваш пинкод для подписания кредитного договора под 46% годовых на 3
месяца на сумму 24000</Message>
</ContractProposal>
</request>
Ответ в случае какой-либо ошибки:
<?xml version="1.0" encoding="utf-8"?>
<response>
<date>2016-11-16T07:33:10+00:00</date>
<message> ContractRequestID 60 has already signed Proposal 1003</message>
<code>000</code>
</response>
Ответ в случае успешной операции:
<response>
<date>2016-11-09T17:25:47+00:00</date>
<message>OK</message>
<code>000</code>
<result>OK - send PIN to +79010010200</result>
</response>
Пример запроса PutConfirm от ЛК к контрактному шлюзу:
<request>
<Opcode>794</Opcode>
<SiteID>111111-1111</SiteID>
<timestamp>1471836223</timestamp>
<hash>5b504cc034c09160fadc4950b287aed3</hash>
<contract_type>1</contract_type>
<Action>PutConfirm</Action>
<ContractProposal>
<ContractType>1</ContractType>
<MerchantSiteID>111111-1111</MerchantSiteID>
<ContractRequestID>60</ContractRequestID>
<ContractorSiteID>999999-9991</ContractorSiteID>
<ContractProposalID>1003</ContractProposalID>
<ContractProposalPIN>16016</ContractProposalPIN>
</ContractProposal>
</request>
Пример ответа в случае успешной операции:
<response>
<date>2016-11-09T17:32:27+00:00</date>
<message>OK</message>
<code>000</code>
<result>OK - sign contract 1003</result>
</response>
Пример ответа в случае несовпадения ПИН-кодов:
<response>
<date>2016-11-09T18:30:26+00:00</date>
<message>PIN not match</message>
<code>000</code>
</response>
Пример ответа в случае отказа кредитора акцептовать подписание контракта:
<response>
<date>2016-11-16T07:47:20+00:00</date>
<message>Contractor not accept sign: [contractor message]</message>
<code>000</code>
</response>
В случае ошибки с вводом ПИН-кода повторный ввод ПИН-кода возможен только через новый запрос GetConfirm, попытка повторно переслать ПИН-код вызовет ошибку:
<response>
<date>2016-11-16T07:51:48+00:00</date>
<message>PIN not generate</message>
<code>000</code>
</response>
# Онлайн-оформление
# - Общее описание онлайн-оформления
Функционал онлайн-оформления включается для конкретного мерчанта (магазина). В процессе оформления пользователь обязан загрузить сканы документов, которые передаются на сервер Mandarin в составе заявки на кредит (790 ContractRequest). Если загружены все три типа документов (passport_main - страница паспорта с фотографией, passport_registration_address - страница паспорта с постоянной регистрацией, selfie - сэлфи с документом), то сервер проставляет в заявке признак ScanDocumentsAvailable = true.
Кредитор, получив заявку на кредит (790 ContractRequest), определяет, загружены ли сканы документов заемщика, по значению признака ScanDocumentsAvailable = true.
Затем кредитор может сделать запрос с опкодом 796 DocumentScan, который возвращает для заявки все доступные фотографии (размер до 7 Мб), закодированные в Base64. Внутри каждого блока документов указано значение AttemptsCount, которое увеличивается на 1 при каждой новой загрузке фотографии. Это позволит видеть историчность пакета документов, даже после отказа по причине "Неудовлетворительное качество фотографий" и повторной отправки заявки с новыми документами. Для каждой новой заявки на кредит (790 ContractRequest), заемщик должен прикрепить новые фотографии.
# - Запрос предложений на заключение договора (Опкод 790 ContractRequest)
Заявка на кредит для онлайн-оформления включает в себя несколько секций DocumentScan:
<?xml version="1.0" encoding="utf-8"?>
<request>
<Opcode>790</Opcode>
<SiteID>000479-0001</SiteID>
<timestamp>1584521686</timestamp>
<hash></hash>
<contract_type>1</contract_type>
<Action>GetProposals</Action>
<ContractRequest>
<ContractRequestID>28058</ContractRequestID>
<LoanSpecification>
<Amount>1000.00</Amount>
<MaximalYearPercent>55.00</MaximalYearPercent>
</LoanSpecification>
<Person>
<PersonID>35452</PersonID>
</Person>
<ScanDocumentsAvailable>True</ScanDocumentsAvailable>
<DocumentScan>
<Type>passport_main</Type>
<Filename>scan1.jpg</Filename>
<CreatedAt>2021-03-19T15:00:46.763336</CreatedAt>
<AttemptsCount>1</AttemptsCount>
<Data>QUFBCg==</Data>
</DocumentScan>
<DocumentScan>
<Type>passport_registration_address</Type>
<Filename>scan2.jpg</Filename>
<CreatedAt>2021-03-19T15:01:23.634684</CreatedAt>
<AttemptsCount>1</AttemptsCount>
<Data>YmJiCg==</Data>
</DocumentScan>
<DocumentScan>
<Type>selfie</Type>
<Filename>scan3.jpg</Filename>
<CreatedAt>2021-03-19T15:02:17.536733</CreatedAt>
<AttemptsCount>1</AttemptsCount>
<Data>ZaqiCg==</Data>
</DocumentScan>
...
</ContractRequest>
</request>
Количество секций DocumentScan не ограничено. Поле Filename содержит имя и расширение файла. В поле CreatedAt - дата загрузки файла. Поле AttemptsCount представляет собой счетчик попыток предоставления скана документа. В поле Data содержится изображение (размером до 7 Мб), закодированное в Base64. Список значений для поля Type:
passport_main- страница паспорта с фотографией;passport_registration_address- страница паспорта с постоянной регистрацией;selfie- сэлфи заемщика с документом.
# - Запрос всех сканов документов заемщика (Опкод 796 DocumentScan)
Запрос, с помощью которого можно получить сканы всех документов, когда-либо загруженных для заявки.
Пример запроса:
<?xml version="1.0" encoding="utf-8"?>
<request>
<Opcode>796</Opcode>
<SiteID>000479-0001</SiteID>
<timestamp>1584521686</timestamp>
<hash></hash>
<contract_type>1</contract_type>
<Action>GetScanDocuments</Action>
<ContractRequestID>28058</ContractRequestID>
</request>
Пример успешного ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<external_result_info>
<result_error>0</result_error>
<result_status>0</result_status>
<result_message>OK</result_message>
<result_type>0</result_type>
<result_source>0</result_source>
</external_result_info>
<date>2020-03-19T15:00:49+00:00</date>
<message>OK</message>
<code>000</code>
<result>
<ContractRequest>
<DocumentScan>
<Data>QUFBCg==</Data>
<AttemptsCount>10</AttemptsCount>
<Type>passport_main</Type>
<CreatedAt>2020-03-19T15:00:46.763336</CreatedAt>
<Filename>scan1.jpg</Filename>
</DocumentScan>
<DocumentScan>
<Data>YmJiCg==</Data>
<AttemptsCount>10</AttemptsCount>
<Type>passport_registration_address</Type>
<CreatedAt>2020-03-19T15:00:46.763336</CreatedAt>
<Filename>scan2.jpg</Filename>
</DocumentScan>
<ContractRequestID>28058</ContractRequestID>
</ContractRequest>
</result>
</response>
Пример ответа с ошибкой:
<?xml version="1.0" encoding="utf-8"?>
<response>
<date>2020-03-19T15:04:32+00:00</date>
<message>Error: Scans not found</message>
<code>001</code>
<external_result_info>
<result_error>1</result_error>
<result_status>1</result_status>
<result_message>Scans not found</result_message>
<result_type>0</result_type>
<result_source>0</result_source>
</external_result_info>
</response>
# Broker API
В рамках данной схемы взаимодействия Mandarin выступает в качестве классического брокера и доводит клиента до подписание. Все дальнейшее взаимодействие по обслуживанию займов и рассрочек осуществляется на стороне кредитора.
# Введение
Данный раздел находится в разработке