Терминология

Здесь собраны основные понятия и идентификаторы, которые встречаются в документации.

Авторизация

JWT-токен — токен для долгоживущего доступа к методам API. Подходит, если интеграцией пользуетесь только вы. Срок жизни задаётся вручную или делается бессрочным.

accesstoken_client — токен доступа к методам API. Действует 24 часа, затем его нужно получить заново.

accesstoken_hybrid — токен доступа, полученный в гибридном потоке OAuth 2.0 (доступ к счетам, балансу, выпискам и так далее). Действует 24 часа.

refreshtoken_hybrid — токен для получения нового Access Token Hybrid после истечения срока. Действует 30 дней.

id_token — токен безопасности с параметрами аутентификации пользователя. Представлен в формате JWT.

code — код авторизации, полученный через редирект браузера пользователя. Действует 5 минут.

redirect_uri — адрес, указанный при регистрации приложения в интернет-банке. На него происходит редирект для получения токенов.

client_id — идентификатор приложения.

client_secret — пароль приложения.

consent_id — идентификатор списка разрешений (согласия клиента в OAuth 2.0).

Разрешение (доступ, scope) — право на конкретные действия в API, например ReadBalances или MakeAcquiringOperation. Выдаётся токену. Если у токена нет нужного разрешения, метод вернёт ошибку 403.

Идентификаторы

customerCode — идентификатор вашей компании в API (строка до 9 символов). Нужен в большинстве методов. Получить можно методом Get Customers List — берите значение из объекта с customerType: "Business".

accountId — идентификатор счёта: номер счёта и БИК банка через слеш, например 40817810802000000008/044525104 (до 40 символов).

merchantId — идентификатор торговой точки (ТСП). Нужен, если торговых точек несколько. В интернет-эквайринге — 15 цифр, получить можно методом Get Retailers. В СБП получить можно методом Get Merchants List. Формат будет отличаться от интернет-эквайринга, merchantId у СБП начинается с букв MA или MB и имеет 10 цифр после.

legalId — уникальный идентификатор юридического лица в СБП. Присваивается при регистрации юрлица в СБП.

operationId — идентификатор операции (платежа или подписки). Используется, например, для возврата платежа или для списания по подписке.

paymentLinkId — идентификатор заказа, который вы задаёте при создании платёжной ссылки. Виден покупателю и должен быть уникальным.

consumerId — идентификатор покупателя. Приходит, если покупатель согласился сохранить карту, и используется, чтобы предложить ему сохранённую карту при следующих оплатах.

qrcId — идентификатор QR-кода СБП.

statementId — идентификатор выписки. Возвращается при создании выписки методом Init Statement, по нему забирают готовую выписку.

documentId — идентификатор счёта на оплату или закрывающего документа.

bankCode — БИК банка. БИК Точка Банка — 044525104.

Платежи и эквайринг

Интернет-эквайринг — приём оплат за товары и услуги в интернете: картой, через СБП и другими способами.

Платёжная ссылка — ссылка, по которой покупатель оплачивает заказ выбранным способом.

Подписка (рекуррентный платёж) — автоматические списания с карты покупателя по графику или по запросу.

ТСП — торгово-сервисное предприятие (торговая точка), от лица которого принимается оплата. Идентифицируется полем merchantId.

СБП — Система быстрых платежей: оплата по QR-кодам.

Статический QR-код — многоразовый код с одним идентификатором, действует бессрочно, принимает неограниченное число оплат. Сумму можно задать при создании или оставить ввод покупателю.

Динамический QR-код — одноразовый код с суммой, заданной при создании. По нему можно принять оплату только один раз. По умолчанию действует 72 часа (меняется параметром ttl).

Кассовый QR-код — подтип статического с признаками динамического: один идентификатор, но перед каждой оплатой код нужно активировать заново. По умолчанию активен 5 минут (до 20 через ttl).

B2B QR-код — одноразовый код для приёма платежей только от ИП и организаций. По умолчанию действует 72 часа.

Двухэтапная оплата — сценарий, когда деньги сначала замораживаются на карте покупателя (статус AUTHORIZED), а списываются позже отдельным вызовом (статус APPROVED).

Фискализация — отправка данных об оплате и возврате оператору фискальных данных (ОФД) по 54-ФЗ. Чеки оформляют партнёры Точки.

Реестр платежей — сводка платежей и комиссий за день по платёжным ссылкам.

Вебхук — POST-запрос, который Точка отправляет на ваш URL при наступлении события (например, поступил или ушёл платёж). В теле — подписанный JWT.

Балансы и выписки

Типы баланса — значения, в которых приходит остаток по счёту: OpeningAvailable (начальный остаток без учёта овердрафта и блокировок), ClosingAvailable (доступный остаток за вычетом блокировок), Expected (сумма заблокированных денег), OverdraftAvailable (доступный лимит овердрафта).

Резерв — деньги, заблокированные на счёте после оплаты картой или снятия наличных. Пока сумма в резерве, использовать её нельзя — она ждёт окончательного списания.

Авторизованная карточная операция — операция по карте, которая уже встала в резерв, но ещё не попала в выписку. Списание происходит позже (обычно 3–5 рабочих дней, иногда до 30).

Овердрафт — кредитный лимит на счёте. В балансе отражается полем OverdraftAvailable.

amountNat — сумма транзакции в рублях по курсу Центробанка (в выписке). Рядом поле amount — та же сумма в валюте счёта.

creditDebitIndicator — признак направления операции в выписке: credit — приход, debit — расход.

Мемориальный ордер — вид платёжного документа: банк обязан перечислить деньги, но платёж ещё проходит статусы перед отправкой. Встречается в поле transactionTypeCode.

Исходящие платежи и документы

Платёжное поручение (платёжка) — поручение банку перевести деньги по реквизитам (исходящий платёж).

«На подпись» — раздел интернет-банка, куда попадает созданная платёжка. Деньги уходят получателю только после подписания.

Право подписи — тип доступа сотрудника в интернет-банке, который позволяет подписывать платежи (по смс-коду).

Счёт на оплату — документ, который продавец выставляет покупателю для оплаты сделки. Создаётся методом Create Invoice.

Закрывающие документы — документы, подтверждающие передачу товаров или оказание услуг: счёт-фактура, акт выполненных работ, накладная ТОРГ-12, УПД.

УПД — универсальный передаточный документ. Объединяет счёт-фактуру и закрывающий документ. Бывает двух видов: СЧФДОП (с НДС, подходит для налогового вычета) и ДОП (без НДС).

Форматы данных

Сумма (amount) — единица измерения зависит от метода: в одних суммы передаются в рублях, в других — в копейках. Всегда сверяйтесь с описанием конкретного метода.

Валюта — в формате ISO 4217, например RUB.

Дата и время — в формате ISO 8601, например 2019-01-01T06:06:06.364+00:00.