Перейти к основному содержимому

Платёжные ссылки

Для работы с платёжными ссылками нужны разрешения MakeAcquiringOperation, ReadAcquiringData и ReadCustomerData.

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

Без фискализации чеков​

методы по работе с платёжными ссылками без фискализации чеков

Подключение платёжных ссылок​

Перед работой с API платёжных ссылок нужно оставить заявку на подключение интернет-эквайринга внутри интернет-банка. Сделать это может руководитель или распорядитель с правом подписи в разделе «Сервисы» → «Интернет-эквайринг».

В течение рабочего дня с момента заявки с вами свяжутся специалисты для подтверждения заявки.

Проверить статус подключения интернет-эквайринга можно с помощью метода Get Retailers.
Статус REG и значение isActive: «true» будут означать, что настройка завершена — можно приступать к работе с платёжными ссылками.

Генерация платёжной ссылки​

Для создания платёжной ссылки нужно вызвать метод Create Payment Operation и передать:

  • amount — сумма платежа в рублях.
  • customerCode — уникальный код клиента.
  • purpose — назначение платежа, которое увидит перешедший по платёжной ссылке покупатель.
  • paymentMode — способ оплаты. Можно выбрать оплату только по карте (card), через T-Pay (tinkoff) или по QR-коду (sbp), либо указать все три варианта, чтобы при переходе по ссылке покупатель сам выбирал способ оплаты.

Дополнительно можно указать:​

  • redirectUrl — URI-адрес, на который нужно переправить покупателя после оплаты.
  • failRedirectUrl — URI-адрес, на который нужно переправить покупателя если оплата не прошла.
  • saveCard — параметр, указывающий, будет ли покупателю предложено сохранить карту для следующих платежей.
  • merchantId — идентификатор торговой точки в интернет-эквайринге. Параметр является обязательным, если у вас подключено несколько торговых точек для работы с интернет-эквайрингом.
  • consumerId — идентификатор покупателя. Если ранее был указан параметр saveCard и клиент согласился с сохранением карты, то из ответа можно взять consumerId и подставить в запрос, чтобы покупатель мог выбрать карту, по которой уже происходила оплата.
  • ttl — время действия платёжной ссылки в минутах, можно указать от 1 до 44 640 минут. Если при создании ссылки не передать этот параметр, срок действия составит 10 080 минут.
  • preAuthorization — поле показывает, будет ли использоваться двухэтапная оплата. Неактуально для оплат через Систему быстрых платежей (СБП). Значение по умолчанию — false.

Чтобы сразу узнать об оплате по ссылке вы можете настроить вебхук с событием acquiringInternetPayment на свой URL.

C фискализацией чеков от партнёров Точки​

методы по работе с платёжными ссылками с фискализацией чеков от партнёров Точки

Подключение платёжных ссылок​

Перед работой с API платёжных ссылок нужно отправить заявку на подключение интернет-эквайринга и выбрать партнёра, который будет фискализировать ваши чеки по 54-ФЗ.

Сделать это может руководитель или распорядитель с правом подписи в разделе «Сервисы» → «Интернет-эквайринг».

В течение рабочего дня с момента заявки с вами свяжутся специалисты для подтверждения заявки.

Проверить статус подключения интернет-эквайринга можно с помощью метода Get Retailers.
Статус REG и значение isActive: «true» будут означать, что настройка завершена — можно приступать к работе с платёжными ссылками.

Генерация платёжной ссылки​

Для создания платёжной ссылки нужно вызвать метод Create Payment Operation With Receipt и передать:

  • amount — сумма платежа в рублях.
  • customerCode — уникальный код клиента.
  • paymentMode — способ оплаты. Можно выбрать оплату только по карте (card), через T-Pay (tinkoff) или по QR-коду (sbp), либо указать все три варианта, чтобы при переходе по ссылке покупатель сам выбирал способ оплаты.
  • purpose — назначение платежа, которое увидит перешедший по платёжной ссылке покупатель.

Client — объект, содержащий данные покупателя.

  • Email — электронная почта покупателя, на которую будет отправлен чек.

Items — объект, содержащий список товаров в заказе.

  • name — название товара или услуги.
  • amount — цена за единицу товара или услуги.
  • quantity — количество товаров или оказанных услуг.

Дополнительно можно указать:​

  • redirectUrl — URI-адрес, на который нужно переправить покупателя после оплаты.
  • failRedirectUrl — URI-адрес, на который нужно переправить покупателя если оплата не прошла.
  • saveCard — параметр, указывающий, будет ли покупателю предложено сохранить карту для следующих платежей.
  • consumerId — идентификатор покупателя. Если ранее был указан параметр saveCard и клиент согласился с сохранением карты, то из ответа можно взять consumerId и подставить в запрос, чтобы покупатель мог выбрать карту, по которой уже происходила оплата.
  • taxSystemCode — система налогообложения, которая используется в организации.
  • merchantId — идентификатор торговой точки в интернет-эквайринге. Параметр является обязательным, если у вас подключено несколько торговых точек для работы с интернет-эквайрингом.
  • ttl — время действия платёжной ссылки в минутах, можно указать от 1 до 44 640 минут. Если при создании ссылки не передать этот параметр, срок действия составит 10 080 минут.
  • preAuthorization — поле показывает, будет ли использоваться двухэтапная оплата. Неактуально для оплат через Систему быстрых платежей (СБП). Значение по умолчанию — false.

Client — объект, содержащий данные покупателя.

  • name — наименование плательщика. Для юрлица — название организации, для ИП и физического лица — ФИО.
  • phone — телефон покупателя для отправки чека.

Items — объект, содержащий список товаров в заказе.

  • vatType — ставка НДС в позициях.
  • paymentMethod — тип оплаты. full_payment — полная оплата, full_prepayment — полная предоплата.
  • paymentObject — признак предмета расчёта. goods — товары, service — услуги, work — работа.
  • measure — единица измерения. По умолчанию ставится штуки.

Supplier — объект, содержащий информацию о поставщике. Если вы работаете как агент и продаёте не свой товар, 54-ФЗ требует указывать в чеке данные поставщика.

  • phone — номер телефона поставщика.
  • name — наименование поставщика.
  • taxCode — ИНН поставщика.

Чтобы сразу узнать об оплате по ссылке, вы можете настроить вебхук с событием acquiringInternetPayment на свой URL.

Получение списка торговых точек​

Метод Get Retailers возвращает информацию о подключённых торговых точках для работы с интернет-эквайрингом. В этом методе передаётся следующая информация:

  • status — статус регистрации. Работать с платёжными ссылками можно только при наличии статуса REG.
  • isActive — статус готовности к работе у торговой точки. Работать с платёжными ссылками только при наличии статуса true.
  • mcc — MCC-код, соответствующий вашей деятельности.
  • rate — сумма взимаемой комиссии, при платеже на карту.
  • name — наименование торговой точки.
  • url — адрес сайта регистрации торговой точки.
  • merchantId — идентификатор торговой точки.
  • terminalId — идентификатор интернет-эквайринга.
  • paymentModes — доступные способы оплаты у торговой точки.
  • cashbox — информация о наличии подключённой онлайн-кассы.

Получение списка операций по платёжным ссылкам​

Метод Get Payment Operation List позволяет получить список всех операций и их статусы.
Лучше всего указывать значения дат fromDate и toDate, чтобы не получить огромный список операций за всё время работы с Точкой.

С методом Get Payment Operation Info вы сможете получить информацию по одной конкретной операции.
Для вызова этого метода понадобится operationId, который вы можете получить из нашего вебхука с событием acquiringInternetPayment, либо найдя нужную операцию в полученном методом Get Payment Operation List списке.

Создание ссылки с двухэтапной оплатой​

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

За двухэтапную оплату отвечает поле preAuthorization в методах Create Payment Operation и Create Payment Operation With Receipt. Порядок действий для использования двухэтапной оплаты такой:

  1. Создайте платёжную ссылку, указав в теле метода "preAuthorization": true.
  2. Когда клиент перейдёт по ссылке и оплатит картой, если денег будет достаточно, они заморозятся на его счёте, но ещё не спишутся.
  3. Вам отправится вебхук с событием acquiringInternetPayment. Внутри этого события будет поле status со значением AUTHORIZED — это означает, что деньги успешно заморожены.
  4. Вызовите метод Capture Payment, чтобы списать замороженные деньги.
  5. После успешного списания вам придёт вебхук с событием acquiringInternetPayment, внутри которого будет "status": "APPROVED" — подтверждение, что оплата прошла успешно.

Для оплат через Систему быстрых платежей (СБП) двухэтапной оплаты не предусмотрено. Поэтому в событии acquiringInternetPayment поле status всегда будет приходить в значении APPROVED.

Несколько особенностей в работе с платёжными ссылками​

  • если у вас подключено несколько торговых точек для работы с интернет-эквайрингом, то указывать merchantId нужно обязательно. Этот параметр можно получить, вызвав метод Get Retailers. merchantId для работы с платёжными ссылками состоит из 15 цифр.
  • для вызова большинства методов по работе с платёжными ссылками нужен параметр customerCode — это ваш уникальный код в системе банка.
    Узнать его можно, вызвав метод Get Customers List. Параметр customerCode необходимо брать из поля customerType: "Business".
  • платёжная ссылка действует 168 часов. С момента перехода по ссылке у покупателя есть 1 час на оплату. По истечении этого срока он увидит ошибку, но при повторном переходе по ссылке сформируется новая рабочая страничка для оплаты.

Возврат платежа, поступившего через платёжную ссылку​

Проводить возврат можно только для платежей в статусе APPROVED.

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

Для возврата платежа, полученного через платёжную ссылку, нужно вызвать метод Refund Payment Operation и передать operationId.

Получить operationId можно несколькими способами:

  • Вызвать метод Get Payment Operation List и найти нужную вам транзакцию, взяв operationId.
  • Если у вас настроен вебхук с событием acquiringInternetPayment, в теле вебхука мы передадим operationId, который можно использовать для возврата.

Скорость возврата платежа​

Если платёж поступил с помощью QR-кода, то возврат происходит практически мгновенно.
Если платили банковской картой, то возврат обычно проходит за 3-7 календарных дней, хотя по правилам платёжных систем может занимать до 30 дней.