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

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

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

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

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

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

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

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

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

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

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

• amount — сумма платежа в рублях.

• customerCode — уникальный код клиента.

• purpose — назначение платежа, которое увидит перешедший по платёжной ссылке покупатель.

• paymentMode — способ оплаты. Возможные значения:

  • card — оплата картой
  • tinkoff — оплата через T-pay
  • sbp — оплата по QR-коду
  • dolyame — оплата через сервис «Долями»

подсказка

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

Чтобы узнать доступные способы приёма платежей, используйте метод Get Retailers — они будут в массиве paymentModes в данных ритейлера.

к сведению

Если оплат через T-pay и Долями нет в списке доступных, оставьте заявку на их подключение в интернет-банке. Обычно подключение занимает 2–3 рабочих дня.

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

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

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

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

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

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

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

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

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

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

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

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

• amount — сумма платежа в рублях.

• customerCode — уникальный код клиента.

• purpose — назначение платежа, которое увидит перешедший по платёжной ссылке покупатель.

• paymentMode — способ оплаты. Возможные значения:

  • card — оплата картой
  • tinkoff — оплата через T-pay
  • sbp — оплата по QR-коду
  • dolyame — оплата через сервис «Долями»

подсказка

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

Чтобы узнать доступные способы приёма платежей, используйте метод Get Retailers — они будут в массиве paymentModes в данных ритейлера.

к сведению

Если оплат через T-pay и Долями нет в списке доступных, оставьте заявку на их подключение в интернет-банке. Обычно подключение занимает 2–3 рабочих дня.

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

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

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

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

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

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

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

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

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

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

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

• phone — номер телефона поставщика
• name — название его компании или ФИО, если поставщик — ИП
• taxCode — ИНН поставщика

к сведению

Данные о поставщике можно указать как отдельным объектом supplier, так и внутри объекта items. Если использовать оба способа одновременно, данные в items.supplier будут приоритетнее.

Например, у вас 10 разных товаров, и вы передаёте такие данные:

• Для 3 товаров — данные их поставщиков в items.supplier
• Для остальных 7 товаров вы не заполняете items.supplier
• В отдельном объекте supplier вы указываете другого поставщика

После оплаты в фискальном чеке будет указано:

• Для 3 товаров — поставщики из items.supplier
• Для остальных 7 — поставщик из отдельного объекта supplier

Чтобы сразу узнать об оплате по ссылке, вы можете настроить вебхук с событием 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 дней.

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

Когда нужно рассчитать приход и комиссию за эквайринг за день, удобнее получать транзакции не по отдельности, а реестром. Он будет содержать всю нужную информацию:

• Сумму всех платежей за день
• Сумму каждого платежа
• Суммарную комиссию за эквайринг с оплат картами и через T-pay
• Размер комиссии за эквайринг с каждого платежа
• Прочие данные платежей и возвратов

к сведению

В реестр попадают только платежи и возвраты в статусах:

• APPROVED
• REFUNDED
• REFUNDED_PARTIALLY
• WAIT_FULL_PAYMENT

Чтобы получить реестр платежей, используйте метод Get Payment Registry. В нём есть обязательные параметры:

• customerCode — ваш уникальный код. Его можно узнать, вызвав метод Get Customers List.
• merchantId — идентификатор вашей торговой точки в интернет-эквайринге. Можно получить с помощью метода Get Retailers — он будет внутри объекта с данными торговой точки.
• date — день, за который нужно сформировать реестр.

к сведению

Если формировать реестр за текущую дату, в него не попадут транзакции по картам, выполненные в этот день — они ещё обрабатываются процессингом и не завершены.