Платежная форма WATA
Создание платежной ссылки
Наиболее востребованный сценарий, более простой для интеграции мерчантом. Платежная форма находится на стороне WATA, открывается в отдельном окне или в iframe на сайте или в приложении мерчанта. На платежной форме WATA могут находиться несколько методов оплаты, например оплата картой и через СБП, в зависимости от выданного терминала. Платежная ссылка может быть одноразовой, становится недействительной после первой успешной оплаты, или многоразовой, становится недействительной по истечении заданного времени.
Не рекомендуется реализовывать логику обработки платежей по идентификатору платёжной ссылки. Платежная ссылка временный объект, она не сохраняется после истечения срока жизни (expirationDateTime). Для обработки платежа опираетесь на «orderId» — уникальный идентификатор заказа в вашей системе
Платежная ссылка создаётся для того терминала, access token которого был указан в заголовке запроса
Свяжитесь с менеджером, чтобы узнать как подключить функционал подписки
Параметры запроса
| Параметр | Тип | Комментарий |
|---|---|---|
| amount | Число | Сумма платежа. Всего после точки может быть 2 цифры для копеек или центов. Пример: 1188.00. Минимальное значение: 10 RUB, 1 USD, 1 EUR. Максимальное допустимое значение 999 999.99. Фактическое ограничение на размер платежа устанавливается шлюзом, его можно уточнить у вашего менеджера |
| currency | Строка | Валюта платежа (RUB, EUR, USD) |
| description | Строка | Описание заказа в произвольной форме |
| orderId | Строка | Уникальный идентификатор (номер) заказа в системе мерчанта. Наиболее важный параметр по которому можно найти транзакцию или операцию возврата |
| successRedirectUrl | Строка | Адрес страницы терминала, на который произойдет редирект плательщика в случае успешной оплаты заказа |
| failRedirectUrl | Строка | Адрес страницы терминала, на который произойдет редирект плательщика в случае неуспешной оплаты заказа |
| expirationDateTime | Дата | Время жизни платежной ссылки. По умолчанию действительна 3 дня. Минимальный срок жизни – 10 минут. Максимальный срок жизни – 30 дней |
| isArbitraryAmountAllowed | Булево поле | Разрешается произвольное значение суммы платежа, значения: true/false. Значением из amount предзаполняется форма ввода суммы |
| arbitraryAmountPrompts | Объект | Подсказка на платежной форме рекомендуемой суммы платежа. Поле возможно использовать только при isArbitraryAmountAllowed=true. Значения выводятся в подсказке под полем ввода. Пример массива: [100, 300, 500]. Значения не могут быть меньше amount. Рекомендуемое количество подсказок 3-4, максимальное – 6. При заполнении строки подсказок работает горизонтальный скроллинг |
| type | Строка | Тип платежной ссылки. Одноразовая ссылка – OneTime, многоразовая ссылка – ManyTime. Если ничего не передать, то создается одноразовая ссылка |
| subscription | Объект | Используется только для функционала подписок, который должен быть разрешён на терминале |
| ├ period | Число | Частота списания. Например, 2 week — списание раз в две недели, а 3 month — квартальное |
| ├ interval | Строка | Интервал, через который происходи списание. Week — по неделям, month — по месяцам |
| ├ maxPeriods | Число | Количество последующих периодов списания, исключая первый. Например, вы продали годовую подписку с ежемесячным списанием, тогда нужно указать 11 периодов, т.к. первый уже будет закрыт текущей оплатой |
| ├ amount | Число | Сумма списаний. Если не указать, будет использоваться сумма из запроса. Поле требуется заполнять, если вы используете промо-период. Например, первый месяц за 39 ₽, а последующие за 99 ₽ |
| └ startDate | Дата | Дата списания по подписке должна быть в будущем. Применимо, когда, к примеру, клиент оплатил впервые 9 января, а регулярные списания у вас всегда 1-го числа. В таком случае указывается дата 01.02. Другой кейс, когда промо-период у вас короткий: 3 дня за 1 ₽, а дальше 1000 ₽ в месяц |
Параметры ответа
| Параметр | Тип | Комментарий |
|---|---|---|
| id | UUID | Идентификатор платежной ссылки в системе WATA (не является UUID транзакции) |
| amount | Строка | Сумма платежа. Всего после точки может быть 2 цифры для копеек или центов. Пример: 1188.00 |
| currency | Строка | Валюта платежа (RUB, EUR, USD) |
| status | Строка | Статус платежной ссылки. Opened — открыта, действительна. Closed — закрыта оплата по ссылке |
| url | Строка | Адрес платежной ссылки |
| terminalName | Строка | Название терминала мерчанта в котором создана платёжная ссылка |
| terminalPublicId | UUID | Уникальны идентификатор терминала мерчанта |
| creationTime | Дата | Дата и время создания платежной ссылки в UTC |
| type | Строка | Тип платежной ссылки. Одноразовая ссылка – OneTime, многоразовая ссылка – ManyTime |
| orderId | Строка | Уникальный идентификатор (номер) заказа в системе мерчанта |
| description | Строка | Описание заказа в произвольной форме |
| expirationDateTime | Дата | Время жизни платежной ссылки. По умолчанию действительна 3 дня. Минимальный срок жизни – 10 минут. Максимальный срок жизни – 30 дней |
| isArbitraryAmountAllowed | Булево поле | Разрешается произвольное значение суммы платежа, значения: true/false. Значением из amount предзаполняется форма ввода суммы |
| arbitraryAmountPrompts | Объект | Подсказка на платежной форме рекомендуемой суммы платежа. Пример – [100, 300, 500] |
| successRedirectUrl | Строка | Адрес страницы терминала, на который произойдет редирект плательщика в случае успешной оплаты заказа |
| failRedirectUrl | Строка | Адрес страницы терминала, на который произойдет редирект плательщика в случае неуспешной оплаты заказа |
→ Пример запроса и ответа на создание платёжной ссылки
Подписки
Через API возможно только создать подписку. Функционал получения информации о ней временно доступен только в личном кабинете мерчанта в разделе «Подписки»
Ответственно относитесь к функционалу подписок, особенно к использованию промо-периодов. Убедитесь, что у вас в явном виде указана цена после окончания этого периода. Изменение стоимости подписки веское основание для чарджбэков. Если условия спрятаны глубоко в оферте или используются иные dark pattern, у клиента могут быть основания для оспаривания транзакции.
За чарджбэки мерчанту не возвращается комиссия, а также могут быть наложены штрафы. При большом числе оспариваемых транзакций терминал может быть отключен в одностороннем порядке, а средства заморожены до 180 дней.
Получение платежной ссылки по UUID
Параметры запроса
| Параметр | Тип | Комментарий |
|---|---|---|
| id | UUID | Идентификатор платежной ссылки (не транзакции) |
Параметры ответа
| Параметр | Тип | Комментарий |
|---|---|---|
| id | UUID | Идентификатор платежной ссылки в системе WATA (не является UUID транзакции) |
| amount | Строка | Сумма платежа. Всего после точки может быть 2 цифры для копеек или центов. Пример: 1188.00 |
| currency | Строка | Валюта платежа (RUB, EUR, USD) |
| status | Строка | Статус платежной ссылки (Opened, Closed) |
| url | Строка | Адрес платежной ссылки |
| terminalName | Строка | Название терминала мерчанта в котором создана платёжная ссылка |
| terminalPublicId | UUID | Уникальны идентификатор терминала мерчанта |
| creationTime | Дата | Дата и время создания платежной ссылки в UTC |
| type | Строка | Тип платежной ссылки. Одноразовая ссылка – OneTime, многоразовая ссылка – ManyTime |
| orderId | Строка | Уникальный идентификатор (номер) заказа в системе мерчанта |
| expirationDateTime | Дата | Время жизни платежной ссылки |
| isArbitraryAmountAllowed | Булево поле | Разрешается произвольное значение суммы платежа, значения: true/false |
| arbitraryAmountPrompts | Объект | Подсказка на платежной форме рекомендуемой суммы платежа. Пример – [100, 300, 500] |
| description | Строка | Описание заказа в произвольной форме |
| successRedirectUrl | Строка | Адрес страницы терминала, на который произойдет редирект плательщика в случае успешной оплаты заказа |
| failRedirectUrl | Строка | Адрес страницы терминала, на который произойдет редирект плательщика в случае неуспешной оплаты заказа |
→ Пример запроса и ответа на получение ссылки по UUID
Поиск платежных ссылок
→ GET /api/h2h/links/?{conditions}
По запросу происходит поиск платежных ссылок, удовлетворяющих определенным условиям. Например, сумма платежа от 1000.01 до 2999.99 в RUB дата создания с 01.02.2027 по 02.03.2027
Важно: платежная ссылка хранится в системе WATA только до истечения срока жизни (expirationDateTime). Если вы не меняли значение, то она действительна 3 дня, после чего удаляется
Параметры запроса
| Параметр | Тип | Комментарий |
|---|---|---|
| orderId | Строка | Уникальный идентификатор заказа в системе мерчанта |
| creationTimeFrom | Дата | Дата создания от |
| creationTimeTo | Дата | Дата создания до |
| amountFrom | Число | Сумма платежа от |
| amountTo | Число | Сумма платежа до |
| currencies | Строка | Валюта платежа |
| statuses | Строка | Статус платежной ссылки: Opened (действительна), Closed (не действительна) |
| sorting | Строка | Поле, по которому будет сортироваться список ссылок в ответе. Доступные варианты orderId, сreationTime, amount. К имени поля можно добавить суффикс desc, если нужна сортировка по убыванию |
| skipCount | Число | Количество записей, которые нужно пропустить. Используется для пагинации. Например, когда нужно получить более 1000 ссылок. Если указать значение skipCount=2000, то первые две тысячи ссылок будут пропущены и в ответе придёт список, начиная с 2001-й |
| maxResultCount | Число | Количество записей, которые нужно выдать. По умолчанию 10, максимум 1000 |
Параметры ответа
| Параметр | Тип | Комментарий |
|---|---|---|
| items | Объект | Список найденных платежных ссылок |
| ├ id | UUID | Идентификатор платежной ссылки в системе WATA (не является UUID транзакции) |
| ├ amount | Строка | Сумма платежа. Всего после точки может быть 2 цифры для копеек или центов. Пример: 1188.00 |
| ├ currency | Строка | Валюта платежа (RUB, EUR, USD) |
| ├ status | Строка | Статус платежной ссылки (Opened, Closed) |
| ├ url | Строка | Адрес платежной ссылки |
| ├ terminalName | Строка | Название терминала мерчанта в котором создана платёжная ссылка |
| ├ terminalPublicId | UUID | Уникальный идентификатор терминала мерчанта |
| ├ creationTime | Дата | Дата и время создания платежной ссылки в UTC |
| ├ type | Строка | Тип платежной ссылки. Одноразовая ссылка – OneTime, многоразовая ссылка – ManyTime |
| ├ orderId | Строка | Уникальный идентификатор (номер) заказа в системе мерчанта |
| ├ expirationDateTime | Дата | Время жизни платежной ссылки |
| ├ isArbitraryAmountAllowed | Булево поле | Разрешается произвольное значение суммы платежа, значения: true/false |
| └ arbitraryAmountPrompts | Объект | Подсказка на платежной форме рекомендуемой суммы платежа. Пример – [100, 300, 500] |
| totalCount | Число |
→ Пример запроса и ответа на поиск платежной ссылки