Mandarin

# Business API для кредитора

# Содержание

# История изменений

Дата Версия Изменения Автор
2019-10-25 0.1 Первоначальная версия. Максим Почиль
2019-12-05 0.2 Добавлены примеры из бизнес-задач кредиторов. Максим Почиль
2020-05-28 0.3 Обновлены примеры по аутентификации. Максим Почиль
2020-06-16 0.4 Обновлены примеры. Максим Почиль
2020-08-27 0.5 Обновлен раздел по аутентификации. Максим Почиль

# Общая информация

# Аутентификация

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Токен действует в течение 36 000 секунд (10 часов). Если срок действия истек, токен нужно запросить еще раз.

Запрос на получение токена

Включает в себя обязательные form-data параметры, которые передаются в теле запроса (параметры application.client_id и application.client_secret неизменны для приложения и хранятся на стороне клиента).

Параметр Описание Пример
grant_type Грант авторизации (всегда равен client_credentials). client_credentials
client_id Идентификатор клиента (равен значению application.client_id, предоставленному Mandarin). VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret Секретный ключ-пароль клиента (равен значению application.client_secret, предоставленному Mandarin). uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope Запрашиваемые скоупы (области доступа):
  • transactions.read - "Чтение транзакций",
  • loans.read - "Чтение займов",
  • repayment_applications.read - "Чтение заявлений на досрочное погашение".
  • payments_accounting.read - "Чтение графиков погашения".
Разделитель - пробел.
Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.		 transactions.read
loans.read
repayment_applications.read
payments_accounting.read
curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=transactions.read loans.read repayment_applications.read payments_accounting.read'

Ответ

Параметр Описание Пример
access_token Токен (ключ доступа). VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in Срок действия токена (в секундах). Всегда равен 36 000 секунд (10 часов). 36000
token_type Тип токена (всегда равен Bearer). Bearer
scope Разрешенные скоупы (области доступа):
  • transactions.read - "Чтение транзакций",
  • loans.read - "Чтение займов",
  • repayment_applications.read - "Чтение заявлений на досрочное погашение".
  • payments_accounting.read - "Чтение графиков погашения".
Разделитель - пробел.
Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.		 transactions.read
loans.read
repayment_applications.read
payments_accounting.read
{
    "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "transactions.read loans.read repayment_applications.read payments_accounting.read"
}

Использование токена

Указывается в headers каждого запроса, в поле Authorization, после зарезервированного слова Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

# Базовые принципы

API реализовано в соответствии с принципами REST API.

API оперирует ресурсами, которые представляют сущности - объекты бизнес-логики (бизнес-модели, доме́нные модели, модели предметной области). Существует два основных типа ресурсов: ресурс коллекции и ресурс сущности.

Ресурсы коллекций названы во множественном числе, например: /transactions.

Ресурс сущности — это ресурс конкретной сущности в какой-то коллекции. Доступ к нему осуществляется всегда через ресурс коллекции и по уникальному номеру, например:

/transactions/{{id}}

API использует JSON как для ответов, так и для запросов (если это применимо). Ответы API стандартизированы.

Ответы ресурсов коллекции всегда содержат поле, названное так же, как и сам ресурс, и содержащее массив бизнес моделей. Если в ответ на запрос данных нет, то массив будет пустой. Например, если это ответ ресурса /transactions, то ответ будет такой:

{ 
   "transactions": [ 
      { {{transaction_model}} }, 
      { ... }, 
      { ... } 
   ] 
}

Допустимые параметры запроса:

  • filter_by - выборка по заданным полям и условиям;

  • sort_by - список полей (через запятую) для сортировки в порядке “по убыванию” (добавив минус - перед названием поля, можно переключить порядок сортировки на “по возрастанию”). По умолчанию отсортирован по id;

  • limit_to - ограничить количество сущностей, выдаваемое за один раз; число, по умолчанию 50;

  • cursor - испльзуется для получения следующей/предыдущей части выдачи, имеет приоритет над остальными запросами, то есть, если передаётся cursor, то остальные параметры игнорируются.

Параметр filter_by формируется следующим образом: список полей и значений, по которому нужно отфильтровать сущности, операторы сравнения (=, >, >=, <, <=, возможно использование оператора IN), фильтры объединяются знаком амперсанда: & (который обозначает логический оператор AND).

Формируется следующая строка:

field_name1=value1&field_name2 in value2_1,value2_2&field_name3>=value3_1&field_name3<value3_2

Например, mw_type=transaction&opcode in 1,3&updated>=2019-10-01&updated<2019-10-31.

После чего эта строка URL-энкодится и передаётся как значение параметра filter_by:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31

Параметры верхнего уровня sort_by и limit_to и их значения не URL-энкодятся.

Пример результирующего query-string:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

Ответы ресурсов коллекции всегда содержат вложенный объект пагинации (курсор). Объект курсора всегда содержит поля:

  • count - количество сущностей в текущем ответе.

  • total - общее количество сущностей по данному запросу (с такими фильтрами и т.д.).

  • next - указатель на следующую страницу выдачи (null, если такая страница не существует).

  • prev - указатель на предыдущую страницу выдачи (null, если такая страница не существует).

Пример запроса, который вернет первые 100 сущностей:

GET /transactions?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

{
   "transactions": [ ... ],
   "cursor": {
      "count": 100,
      "next": "aad0f17a6af11672",
      "prev": "f0bb6887c3b2f501",
      "total": 4200
   }
}

Пример запроса для получения последующих 100 сущностей (в параметр cursor подставлено значение из поля ответа next):

GET /transactions?cursor=aad0f17a6af11672

Ответы ресурсов сущностей всегда содержат поле, названное так же, как и сам ресурс, но в единственном числе, например:

GET /transactions/12345

{ 
   "transactions": { 
      {{transaction_model}} 
   } 
}

Для каждого ресурса, для которого требуется поиск, реализован суб-ресурс /search, например: /transactions/search. Этот ресурс принимает один-единственный параметр: q, значением которого является строка поиска.

Суб-ресурс поиска также выдаёт результаты частями. Для получения следующей части выдачи, если она нужна, следует отправить запрос с курсором на родительский ресурс, а не на ресурс поиска.

# Получение списка транзакций

Точка входа для кредиторов (legacy)

GET https://api.psp.io/common/api/v2/clients/{{cid_кредитора}}/transactions

Точка входа с использованием OAuth 2.0

GET https://api.psp.io/payment-gateway/v3/transactions

Запрос на данную точку входа позволяет получить список транзакций кредитора (например, платежи по займу).

Для выполнения требуется скоуп transactions.read.

Каждая транзакция содержит opcode - тип транзакции (число).

Значение opcode Наименование Описание
1 Purchase Платеж (одностадийная оплата)
2 Refund Отмена платежа
3 Rebill Платеж рекуррентный (автосписание)
4 PreAuth Авторизация (в том числе с использованием токена карты)
5 Reversal Отмена авторизации
6 ConfirmAuth Платеж (завершение расчетов в рамках авторизованной суммы)
22 RefundAFT Отмена платежа AFT
472 MoneySend Выплата

# Пример 1. Получить список успешных платежей кредитору 117, созданных за определенный период (12.08.2019)

Формируем критерии отбора:

  • cid кредитора = 117 (прописывается в url).

  • updated >= 2020-02-12T00:00:00Z (в UTC, точность - до секунды).

  • updated < 2020-02-13T00:00:00Z (в UTC, точность - до секунды).

  • status = success (оставляем только успешные платежи-погашения).

  • mw_type = transaction (позволяет убрать списания для привязки карт и оставить только погашения).

Объединяем критерии символом амперсанда &: updated>=2020-02-12T00:00:00Z&updated<2020-02-13T00:00:00Z&status=success&mw_type=transaction

После операции "urlencode": updated%3E%3D2020-02-12T00%3A00%3A00Z%26updated%3C2020-02-13T00%3A00%3A00Z%26status%3Dsuccess%26mw_type%3Dtransaction

Вставляем в запрос критерии отбора. Результат приведен ниже.

Запрос

GET https://api.psp.io/common/api/v2/clients/117/transactions?filter_by=updated%3E%3D2020-02-12T00%3A00%3A00Z%26updated%3C2020-02-13T00%3A00%3A00Z%26status%3Dsuccess%26mw_type%3Dtransaction

Ответ

{
	"cursor": {
		"count": 50,
		"prev": null,
		"total": 129,

		"next": "8fdce98f0d6a59348c93434040ac3eefa01a793e4788669eceb2c4f7b9f0e82e"
	},
	"transactions": [{
			"account_id": 659,
			"amount": 1508.01,
			"amount_converted": 1508.01,
			"authcode": "278645",
			"card_type": "1",
			"ccadress": null,
			"channel_id": 52,
			"client_id": 117,
			"contract_id": "0000015765-000117-0003-1576571",
			"contract_token": null,
			"created": "2019-08-12T12:31:16.604476Z",
			"cs0": null,
			"cs1": "794653521b404175a9f74d8dd744ba35",
			"cs2": "contract_payment",
			"cs3": "contract_payment",
			"cs4": "0000015765-000117-0003-1576571",
			"cs5": null,
			"cs6": null,
			"cs7": null,
			"cs8": null,
			"cs9": null,
			"currency_id": 643,
			"currency_id_converted": 643,
			"customer_info": {
                "email": "test@test.ru",
                "phone": "+79111111111"
            },
			"email": "test@test.ru",
			"gw_node_id": null,
			"hash": "b73afd403ab32b8e60597422cd6545f7",
			"id": 22943496,
			"instrument_id": null,
			"instrument_type_id": 1,
			"ip": "213.87.136.44",
			"is_aft": false,
			"lang": "en",
			"md": "386897229-F8B525197310CD0D",
			"mw_id": "79465352-1b40-4175-a9f7-4d8dd744ba35",
			"mw_merchant_id": 512,
			"mw_node_id": null,
			"mw_timestamp_created": "2019-08-12T12:31:16.604511Z",
			"mw_type": "transaction",
			"opcode": 1,
			"order_id": "0000015765-000117-0003-1576571_12_08_2019",
			"pan": "492950******6878",
			"pan_id": "de70658a4012ae7ac6823dba2faf3e9c",
			"phone": "+79111111111",
            "price": {
                "counterparty_total_price": 0,
                "mandarin_total_price": 22.62
            },
			"product_descr": "Оплата заказа №0000015765-000117-0003-1576571_12_08_2019",
			"product_id": 1,
			"rebill_from": null,
			"rebill_status": null,
			"rebill_statusreason": null,
			"reference_id": null,
			"remote_id": "0A39CB0167BE394E",
			"remote_id2": null,
			"remote_id3": null,
			"remote_id4": null,
			"remote_id5": null,
			"remote_id_ext": null,
			"remotely_processed": "2019-08-12T12:31:35.364927Z",
			"request_id": null,
			"response_code": 0,
			"rrn": "922491310354",
			"secure_mode": 1,
			"site_id": 3,
			"site_notified": null,
			"status": "success",
            "status_changes_counter": 284594911,
            "subprovider_id": null,
            "terminal_id": null,
			"termurl": null,
			"updated": "2019-08-12T12:31:35Z"
		},
		{
			"еще 49 элементов": "с такой же структурой"
		}
	]
}

Получить следующие 50 элементов можно запросом:

GET https://api.psp.io/common/api/v2/clients/117/transactions?cursor=8fdce98f0d6a59348c93434040ac3eefa01a793e4788669eceb2c4f7b9f0e82e

Общее количество страниц можно узнать, разделив total на count: 129/50 = 2 полных страницы на 50 элементов, и еще третья страница на 29 элементов.

# Пример 2. Получить список успешных платежей кредитору 117 по договору 0000015765-000117-0003-1576571, по 10 транзакций на странице

Формируем критерии отбора:

  • client_id = 117 (прописывается в url).

  • contract_id = 0000015765-000117-0003-1576571.

  • status in success (показываем только успешные).

  • mw_type in transaction (в случае привязки карты mw_type in binding, в случае платежa mw_type in transaction).

Объединяем критерии символом амперсанда &: contract_id=0000015765-000117-0003-1576571&status in success&mw_type in transaction

После операции "urlencode": contract_id%3D0000015765-000117-0003-1576571%26status%20in%20success%26mw_type%20in%20transaction

Вставляем в запрос параметр limit_to=10 и критерии отбора:

GET https://api.psp.io/common/api/v2/clients/117/transactions?limit_to=10&filter_by=contract_id%3D0000015765-000117-0003-1576571%26status%20in%20success%26mw_type%20in%20transaction

Структура ответа аналогична той, которая использована в примере 1.

Получение следующих 10 элементов - с помощью параметра cursor, аналогично примеру 1.

# Поиск по транзакциям

Точка входа для кредиторов (legacy)

GET https://api.psp.io/common/api/v2/clients/{{cid_кредитора}}/transactions/search

Точка входа с использованием OAuth 2.0

GET https://api.psp.io/payment-gateway/v3/transactions/search

Для выполнения требуется скоуп transactions.read.

Данный запрос позволяет осуществить поиск транзакций, удовлетворяющих заданным критериям поиска.

Поиск осуществляется по следующим полям (поля указаны в порядке убывания приоритета):

  • id.

  • rrn.

  • remote_id.

  • email.

  • phone.

  • pan.

  • cs1 (идентификатор транзакции).

  • cs2-cs9 (пользовательские поля, передаваемые при создании транзакции через API).

# Пример 3. Получить список транзакций, содержащих значение 22491310

Критерий отбора: 22491310

После операции "urlencode": 22491310

Запрос: https://api.psp.io/common/api/v2/clients/117/transactions/search?q=22491310

Ответ аналогичен ответу в примере 1. Содержит все транзакции, у которых в указанном списке полей содержится значение 22491310 (полностью или частично). Например, в список войдут транзакции c RRN = 922491310115, 922491310118, 922491310354, с адресом email = test@test.ru, c телефоном +79111111111.

# Получение списка займов

Точка входа для кредиторов (legacy)

GET https://api.psp.io/common/api/v2/clients/{{cid_кредитора}}/loans

Точка входа с использованием OAuth 2.0

GET https://api.psp.io/life-backend/api/v3/loans

Для выполнения требуется скоуп loans.read.

Данный запрос позволяет получить список займов.

Для получения информации по конкретному займу необходимо отправить GET-запрос вида: https://api.psp.io/life-backend/api/v2/loans/

Например, https://api.psp.io/common/api/v2/clients/117/loans/0000021521-000117-0003-2152116 хранит информацию о займе.

Параметр Описание и возможные значения Пример
accounting_period_for _leads_settlement Последний день месяца, за который будет перечислена оплата за лидов 2019-04-30
annual_percentage_rate Процент ПСК 36.777
attempts_count Количество запросов предложений кредитора 1
autopayment_is_enabled Автоплатеж включен true
autopayment_payment_id Идентификатор автоплатежа f696daae-c412-49d7-bd75-da23731d46ee
cbr_unique_id Уникальный идентификатор договора (УИД) Банка России (opens new window), который заполняется на момент подписания займа 82eb3106-a1b8-11ea-9a8f-0242ac120008-5
contract_id Номер договора займа 0000034186-000117-0003-3418671
customer Клиент
customer.additional_phones[] Массив номеров телефонов клиента
customer. additional_phones[].number Номер телефона +79000000000
customer. additional_phones[].type Тип номера: WORK, MOBILE, HOME MOBILE
customer.addresses[] Массив адресов клиента
customer. addresses[].address_line Полный адрес г Москва, пр-т Мира, д 4 к 1, кв 24
customer.addresses[].type Тип адреса: REGISTRATION, RESIDENTIAL REGISTRATION
customer.birth_date Дата рождения 1991-02-06
customer.birth_place Место рождения Москва
customer.citizenship Гражданство Россия
customer.earnings Сумма дохода 80000
customer.email Email test@test.ru
customer.employment_position Должность Рядовой работник
customer.employment_type Тип занятости Постоянно работаю
customer.id Идентификатор клиента 20905
customer. ident_operation_started_at Время старта операции идентификации 2019-04-30T17:58:32.263476Z
customer. ident_operation_updated_at Время обновления результатов идентификации 2019-04-30T18:05:37.974395Z
customer. ident_person_verification_error Индикатор наличия ошибки при идентификации null
customer. ident_person_verification_finished Индикатор окончания процесса идентификации true
customer.ident_person_verified Индикатор успешности проверки персональных данных:
null - ответ от СМЭВ еще не получен,
true - идентификация успешна,
false - идентификация неуспешна		 true
customer.ident_transaction_id Идентификатор транзакции идентификации 3d01b707-3871-4c50-8b04-10a3a0146654
customer.job Работодатель Мосгортранс
customer.name Имя Полиграф
customer.passport_issue_date Дата выдачи 2011-02-22T00:00:00Z
customer.passport_issuer Кем выдан Отделом УФМС России по гор. Москве по району Басманный
customer.passport_issuer_code Код подразделения 770-004
customer.passport_number Номер паспорта 222222
customer.passport_series Серия паспорта 1111
customer.patronymic Отчество Полиграфович
customer.phone Телефон 79999999999
customer.request_attempt Номер запроса предложений от кредитора 1
customer.sex Пол MALE
customer.surname Фамилия Шариков
customer.taxpayer_number ИНН клиента null
customer_id Идентификатор клиента 20905
downpayment_amount Сумма первоначального взноса 0
id Идентификатор займа 568426
interest_rate Процентная ставка займа 41.7
is_test Тестовый займ FALSE
lender Кредитор
lender.id Идентификатор кредитора 15450
lender.tin ИНН кредитора 7744001930
lender_alias Псевдоним кредитора Gorgarant
lender_id Идентификатор (CID) кредитора 15450
lender_site_id Site id кредитора 1
loan_amount Сумма займа 16800
loan_request_id Идентификатор заявки на займ 21523
maturity_in_months Срок займа в месяцах 12
merchant Идентификатор мерчанта
merchant.id Идентификатор (CID) мерчанта 6071
merchant.tin ИНН мерчанта 7716899328
merchant_id Идентификатор (CID) мерчанта 6071
merchant_site_id Site id мерчанта 1
monthly_payment Ежемесячный платеж 1735.98
next_payment_amount Сумма следующего платежа 1736
next_payment_at Дата следующего платежа 2019-10-30T20:59:59Z
original_documents _received Индикатор, получены ли оригиналы документов true
original_documents _received_at Дата получения оригиналов документов 2019-05-07
overdue_amount Сумма просрочки 9457.92
overdue_started_at Дата начала просрочки 2019-05-30T21:00:00Z
paidout_at Дата выплаты null
payment_balance Баланс -9457.92
payment_url Ссылка на страницу оплаты займа для клиента https://pay.psp.io/LWeueriw
payment_url_token Токен для аутентификации на странице оплаты LWeueriw
planned_paidout_time Планируемая дата выплаты 2020-04-30
ready_for_purchase _settlement Индикатор возможности перечисления заемных средств мерчанту true
received_documents_info Детализация по полученным документами от мерчанта null
scanned_documents_received Индикатор, получены ли сканы документов FALSE
scanned_documents_received_at Дата получения сканов документов null
settlement_after _original_documents Индикатор, указывающий, что заемные средства будут перечислены только после получения оригиналов документов FALSE
signed_at Дата подписания 2019-04-30T18:17:23.526294Z
stage Этап Confirm
status Статус Overdue

# Пример 4. Получить список просроченных займов кредитора 117, подписанных за определенный период (30.04.2019)

Формируем критерии отбора:

  • client_id = 117 (прописывается в url).

  • signed_at >= 2019-08-12T00:00:00Z (в UTC, точность - до секунды).

  • signed_at < 2019-08-13T00:00:00Z (в UTC, точность - до секунды).

  • stage in Confirm (оставляем только активные займы, исключая выплаченные и отмененные).

  • status in Overdue (оставляем только просроченные займы).

Объединяем критерии символом амперсанда &: signed_at>=2019-08-12T00:00:00Z&signed_at<2019-08-13T00:00:00Z&stage in Confirm&status in Overdue

После операции "urlencode": signed_at%3E%3D2019-08-12T00%3A00%3A00Z%26signed_at%3C2019-08-13T00%3A00%3A00Z%26stage%20in%20Confirm%26status%20in%20Overdue

Вставляем в запрос критерии отбора. Результат приведен ниже.

Запрос

GET https://api.psp.io/common/api/v2/clients/117/loans?filter_by=signed_at%3E%3D2019-08-12T00%3A00%3A00Z%26signed_at%3C2019-08-13T00%3A00%3A00Z%26stage%20in%20Confirm%26status%20in%20Overdue

Ответ

{
	"cursor": {
		"count": 25,
		"prev": null,
		"total": 25,
		"next": "f4884b32f97c506ae8e087926abab95340bc2824e948c505fe2dd12bdc4efb9a"
	},
	"loans": [{
		"accounting_period_for_leads_settlement": "2019-08-31",
		"annual_percentage_rate": 36.777,
		"attempts_count": 1,
		"autopayment_is_enabled": true,
		"cbr_unique_id": "82eb3106-a1b8-11ea-9a8f-0242ac120008-5",
		"contract_id": "0000034186-000117-0003-3418671",
		"customer": {
			"additional_phones": [{
					"number": "+79777777777",
					"type": "HOME"
				},
				{
					"number": "+79777777777",
					"type": "MOBILE"
				},
				{
					"number": "+79111111111",
					"type": "WORK"
				}
			],
			"addresses": [{
					"address_line": "Московская обл, Дмитровский р-н, г Яхрома, ул Рабочая, д 8В",
					"type": "REGISTRATION"
				},
				{
					"address_line": "Московская обл, Дмитровский р-н, г Яхрома, ул Рабочая, д 8В",
					"type": "RESIDENTIAL"
				}
			],
			"birth_date": "1988-12-20",
			"birth_place": "гор.Набережные Челны",
			"citizenship": "Россия",
			"earnings": 150000,
			"email": "test@test.ru",
			"employment_position": "Руководитель/Зам. Руководителя организации",
			"employment_type": "Постоянно работаю",
			"id": 24162,
			"ident_operation_started_at": "2019-08-12T18:29:33.019914Z",
			"ident_operation_updated_at": "2019-08-12T18:35:38.749724Z",
			"ident_person_verification_error": null,
			"ident_person_verification_finished": true,
			"ident_person_verified": true,
			"ident_transaction_id": "d1856dc6-a7b6-4aae-a819-97d1d0855340",
			"job": "ООО ДОБРЫЙ СОСЕД",
			"name": "Полина",
			"passport_issue_date": "2014-12-26T00:00:00Z",
			"passport_issuer": "ОТДЕЛЕНИЕ В КОМСОМОЛЬСКОМ Р-НЕ ОТДЕЛА УФМС РОССИИ ПО РЕСПУБЛИКЕ ТАТАРСТАН Г.НАБЕРЕЖНЫЕ ЧЕЛНЫ",
			"passport_issuer_code": "160-013",
			"passport_number": "222222",
			"passport_series": "1111",
			"patronymic": "Полиграфовна",
			"phone": "+79777777777",
			"request_attempt": 1,
			"sex": "FEMALE",
			"surname": "Шарикова",
			"taxpayer_number": null
		},
		"customer_id": 36257,
		"downpayment_amount": 24187.5,
		"id": 953422,
		"interest_rate": 36.8,
		"is_test": false,
		"lender": {
			"id": 117,
			"tin": "7722342510"
		},
		"lender_alias": "Gorgarant",
		"lender_id": 117,
		"lender_site_id": 3,
		"loan_amount": 24187.5,
		"loan_request_id": 34186,
		"maturity_in_months": 12,
		"merchant": {
			"id": 5799,
			"tin": "7706230753"
		},
		"merchant_id": 5799,
		"merchant_site_id": 1,
		"monthly_payment": 2439.61,
		"next_payment_amount": 2440,
		"next_payment_at": "2020-07-01T20:59:59Z",
		"original_documents_received": true,
		"original_documents_received_at": "2019-08-25",
		"overdue_amount": 0,
        "overdue_amount": 7095.97,
        "paidout_at": null,
        "payment_balance": -7095.97,
		"payment_url": "https://pay.mandarin.life/RtJpLeA7",
		"payment_url_token": "RtJpLeA7",
		"planned_paidout_time": "2020-08-12",
		"ready_for_purchase_settlement": true,
		"received_documents_info": null,
		"scanned_documents_received": false,
		"scanned_documents_received_at": null,
		"settlement_after_original_documents": false,
		"signed_at": "2019-08-12T18:43:44.782708Z",
		"stage": "Confirm",
		"status": "Ok",
	}, {
		"еще 9 элементов": "с такой же структурой"
	}]
}

# Запрос заявлений на досрочное погашение

Точка входа для кредиторов (legacy)

GET https://api.psp.io/common/api/v2/clients/{{cid_кредитора}}/repayment_applications

Точка входа с использованием OAuth 2.0

GET https://api.psp.io/life-backend/api/v3/repayment_applications

Для выполнения требуется скоуп repayment_applications.read.

Данный запрос позволяет получить список всех заявлений на досрочное погашение по данному кредитору.

Как в остальных запросах, поддерживается фильтрация по дате. После выполнения этого запроса, кредитор обычно получает обновленный график платежей (см. Пример 6).

Кроме того, есть запрос для получения заявлений на досрочное погашение по конкретному займу:

GET https://api.psp.io/common/api/v2/clients/{{cid_кредитора}}/loans/{{contract_id}}/repayment_applications

Например, GET https://api.psp.io/common/api/v2/clients/117/loans/0000013184-004296-0001-1318410/repayment_applications

# Пример 5. Получить список заявлений на досрочное погашение, созданных за определенный период (25.03.2019)

Формируем критерии отбора:

  • cid кредитора = 117 (прописывается в url).

  • sign_time >= 2019-03-25T00:00:00Z (в UTC, точность - до секунды).

  • sign_time < 2019-03-26T00:00:00Z (в UTC, точность - до секунды).

  • status = signed (оставляем только заявления, подписанные клиентом).

Объединяем критерии символом амперсанда &: sign_time>=2019-03-25T00:00:00Z&sign_time<2019-03-26T00:00:00Z&status=signed

После операции "urlencode": sign_time%3E%3D2019-03-25T00%3A00%3A00Z%26sign_time%3C2019-03-26T00%3A00%3A00Z%26status%3Dsigned

Вставляем в запрос критерии отбора. Результат приведен ниже.

Запрос

GET https://api.psp.io/common/api/v2/clients/117/repayment_applications?filter_by=sign_time%3E%3D2020-02-12T00%3A00%3A00Z%26sign_time%3C2020-02-13T00%3A00%3A00Z%26status%3Dsigned

Ответ

{
    "cursor": {
        "count": 2,
        "next": null,
        "prev": null,
        "total": 2
    },
    "repayment_applications": [
        {
            "amount": 0,
            "contract_id": "0000029324-000117-0003-2932471",
            "description": null,
            "id": 3260,
            "payment_time": "2020-02-23T00:00:00Z",
            "processing_state": "executed",
            "sign_time": "2020-02-12T17:28:32Z",
            "status": "signed",
            "type": "partial_period"
        },
        {
            "amount": 25067.89,
            "contract_id": "0000032394-000117-0003-32394412",
            "description": null,
            "id": 3261,
            "payment_time": "2020-02-26T00:00:00Z",
            "processing_state": "executed",
            "sign_time": "2020-02-12T18:58:06Z",
            "status": "signed",
            "type": "full_repayment"
        }
    ]
}

# Запрос графика погашения

Точка входа для кредиторов (legacy)

GET https://api.psp.io/common/api/v2/clients/{{cid_кредитора}}/loans/{{contract_id}}/payments_accounting

Точка входа с использованием OAuth 2.0

GET https://api.psp.io/life-backend/api/v3/loans/{{contract_id}/payments_accounting

Для выполнения требуется скоуп payments_accounting.read.

Данный запрос вернет актуальный график платежей по займу, указанному в url.

В случае полного досрочного погашения, сумма платежа учитывается в параметрах scheduled_payment_* при условии, что заявление подписано и не было просрочено.

В случае частичного досрочного погашения, сумма, фактически использованная для него, учитывается в параметрах payment_*.

Параметр Описание Комментарий
date Дата учета
extra_payment Фактический платеж в счет частичного досрочного погашения Не используется
overdue_interest_fee Пени на просроченные проценты Не применяется
overdue_period Индикатор наличия просрочки (количество дней просрочки) При выходе на просрочку учет ведется ежедневно, поэтому параметр всегда равен или 0 (займ без просрочки на эту дату), или 1 (займ в просрочке на эту дату).
overdue_principal_fee Пени на просроченную ссуду
overdue_principal _interest Проценты на просроченную ссуду
overdue_principal _interest_fee Пени на просроченные проценты по просроченной ссуде Не применяется
payment Фактический платеж
payment_balance Фактический платеж в счет будущих периодов Остаток на балансе клиента после распределения по типу начислений
payment_interest Фактический платеж на оплату процентов
payment_overdue _interest_fee Фактический платеж на оплату пени на просроченные проценты Не применяется
payment_overdue _principal Фактический платеж на оплату просроченной ссуды
payment_overdue _principal_fee Фактический платеж на оплату пени на просроченную ссуду
payment_overdue _principal_interest Фактический платеж на оплату процентов на просроченную ссуду
payment_overdue _principal_interest_fee Фактический платеж на оплату пени на просроченные проценты по просроченной ссуде Не применяется
payment_principal Фактический платеж на погашение основного долга Здесь и далее payment_* показывает распределение суммы платежа по типу начислений
payment_total Сумма к распределению с учетом переплаты прошлого периода, всего По сути равна фактическому платежу в эту дату, плюс переплата с прошлых периодов
principal_balance Остаток суммы основного долга в соответствии по факту Для текущей и прошлых дат равен фактическому остатку основного долга на конец отчетного периода. Для будущих дат равен фактическому остатку на момент формирования отчета
scheduled_balance Остаток суммы основного долга в соответствии с плановым графиком платежей Остаток долга на конец отчетного периода в соответствии с графиком платежей из договора
scheduled_payment _interest Плановый платеж в соответствии с графиком платежей на оплату процентов
scheduled_payment _principal Плановый платеж в соответствии с графиком платежей на погашение основного долга
scheduled_payment _total Плановый платеж в соответствии с графиком платежей При наличии заяавления о полном досрочном погашении содержит сумму из заявления в дату платежа
start_unpaid_interest Cумма задолженности нарастающим итогом по оплате процентов, на начало периода
start_unpaid _overdue_interest_fee Cумма задолженности нарастающим итогом по пени на просроченные проценты, на начало периода Не применяется
start_unpaid _overdue_principal_fee Cумма задолженности нарастающим итогом по пени на просроченную ссуду, на начало периода
start_unpaid _overdue_principal _interest Cумма задолженности нарастающим итогом по процентам на просроченную ссуду, на начало периода
start_unpaid _overdue_principal _interest_fee Cумма задолженности нарастающим итогом по пени на просроченные проценты по просроченной ссуде, на начало периода Не применяется
start_unpaid _principal Cумма задолженности нарастающим итогом по основному долгу, на начало периода
start_unpaid_total Cумма задолженности нарастающим итогом, на начало периода, всего
unpaid_interest Cумма задолженности нарастающим итогом по оплате процентов, на конец периода
unpaid_overdue _interest_fee Cумма задолженности нарастающим итогом по пени на просроченные проценты, на конец периода Не применяется
unpaid_overdue _principal Cумма задолженности нарастающим итогом на просроченную ссуду, на конец периода
unpaid_overdue _principal_fee Cумма задолженности нарастающим итогом по пени на просроченную ссуду, на конец периода
unpaid_overdue _principal_interest Cумма задолженности нарастающим итогом по процентам на просроченную ссуду, на конец периода
unpaid_overdue _principal_interest_fee Cумма задолженности нарастающим итогом по пени на просроченные проценты по просроченной ссуде, на конец периода Не применяется
unpaid_principal Cумма задолженности нарастающим итогом по основному долгу, на конец периода
unpaid_total Cумма задолженности нарастающим итогом, на конец периода, всего

# Пример 6. Получить график плановых платежей по договору 0000013184-000117-0003-1318410

Запрос

GET https://api.psp.io/common/api/v2/clients/117/loans/0000013184-000117-0003-1318410/payments_accounting

Ответ


{
	"payment_table": {
		"client_id": 117,
		"contract_id": "0000013184-000117-0003-1318410",
		"id": 21672,
		"data": [            {
                "date": "2020-04-14",
                "extra_payment": 0,
                "overdue_interest_fee": 0,
                "overdue_period": 1,
                "overdue_principal_fee": 3.52,
                "overdue_principal_interest": 6.46,
                "overdue_principal_interest_fee": 0,
                "payment": 0,
                "payment_balance": 0,
                "payment_interest": 0,
                "payment_overdue_interest_fee": 0,
                "payment_overdue_principal": 0,
                "payment_overdue_principal_fee": 0,
                "payment_overdue_principal_interest": 0,
                "payment_overdue_principal_interest_fee": 0,
                "payment_principal": 0,
                "payment_total": 0,
                "principal_balance": 13020.53,
                "scheduled_balance": 6599.37,
                "scheduled_payment_interest": 0,
                "scheduled_payment_principal": 0,
                "scheduled_payment_total": 0,
                "start_unpaid_interest": 405.84,
                "start_unpaid_overdue_interest_fee": 0,
                "start_unpaid_overdue_principal_fee": 3.52,
                "start_unpaid_overdue_principal_interest": 6.46,
                "start_unpaid_overdue_principal_interest_fee": 0,
                "start_unpaid_principal": 6421.16,
                "start_unpaid_total": 6836.98,
                "unpaid_interest": 405.84,
                "unpaid_overdue_interest_fee": 0,
                "unpaid_overdue_principal": 6421.16,
                "unpaid_overdue_principal_fee": 7.04,
                "unpaid_overdue_principal_interest": 12.92,
                "unpaid_overdue_principal_interest_fee": 0,
                "unpaid_principal": 0,
                "unpaid_total": 6846.96
            },
			{
				"еще несколько элементов": "с такой же структурой"
			}
		]
	}
}