Частые вопросы
Нужна ли библиотека или SDK?
Нет. Подойдёт любой HTTP-клиент. Примеры на cURL, Python, Node.js и PHP — в справочнике API и в быстром старте.
Обязательно ли передавать email покупателя?
Да. Передавайте email покупателя в metadata.email в каждом запросе на создание платежа. Без него или с неверным адресом API ответит 400 invalid_request, "parameter": "metadata.email".
Где взять email покупателя из Telegram?
Если покупатель пришёл из Telegram и email у вас нет, передайте <id или username>@telegram.org: числовой ID пользователя Telegram ([email protected]) или его имя пользователя без @ в начале.
Как связать платёж с заказом?
Передайте номер заказа в metadata.order_id и сохраните id платежа в заказе сразу после ответа. Номер заказа вернётся в объекте платежа и в уведомлениях, а платёж получайте по id: GET /v3/payments/{payment_id}. Фильтра по номеру заказа в списке платежей нет.
Почему ошибка «capture is required»?
В запросе нет "capture": true. В AvantPay платёж списывается сразу после оплаты, поэтому capture обязателен и всегда равен true. "capture": false тоже даёт ошибку 400.
Покупатель вернулся на return_url. Платёж оплачен?
Не обязательно. Покупатель возвращается и после оплаты, и после отказа. Запросите платёж GET /v3/payments/{payment_id} и смотрите на status.
Как на странице return_url понять, о каком платеже речь?
AvantPay открывает return_url как есть, без параметров. Поэтому укажите в нём адрес страницы заказа, например https://example.com/orders/123. На этой странице возьмите id платежа из заказа и запросите платёж.
Нужно ли передавать способ оплаты?
Нет. Без payment_method_data покупатель выберет СБП или карту на странице оплаты.
Как оплатить заказ ещё раз, если платёж отменён?
Создайте новый платёж с новым ключом идемпотентности. Номер заказа в metadata.order_id можно оставить тем же.
Можно ли отменить платёж?
Нет. Неоплаченный платёж отменится сам после expires_at — через 20 минут после создания платежа. Если заказ больше не нужен, просто не показывайте покупателю ссылку на оплату. Запрос /cancel ответит 400 not_supported.
Можно ли изменить сумму платежа?
Нет. Создайте новый платёж с новой суммой и новым ключом идемпотентности. Старый платёж не засчитывайте: если его всё же оплатят, верните деньги в личном кабинете. Поэтому перед выполнением заказа сверяйте amount платежа с суммой заказа.
Есть ли двухстадийные платежи (холдирование)?
Нет. Деньги списываются сразу после оплаты. Передавайте "capture": true. Запрос /capture ответит 400 not_supported.
Как вернуть деньги покупателю?
В личном кабинете. Через API вернуть деньги нельзя.
Есть ли тестовый режим?
Нет. Проверьте интеграцию без оплаты и одним настоящим платежом на минимальную сумму, потом верните деньги в личном кабинете. Как — на странице Проверка интеграции.
AvantPay отправляет чеки 54-ФЗ?
Нет. Не передавайте receipt: запрос с ним получит ошибку 400 not_supported.
Можно ли сохранить карту и списывать без покупателя?
Нет. Сохранения способов оплаты и автоплатежей нет.
В какой валюте принимать платежи?
В рублях: "currency": "RUB".
Какая минимальная и максимальная сумма?
Зависит от способа оплаты. Лимиты — в личном кабинете: Ещё → Способы оплаты. Если сумма вне лимитов, API ответит 400 с "parameter": "amount.value".
Пришло payment.canceled, а потом payment.succeeded. Что это?
Поздняя оплата: банк подтвердил оплату после отмены платежа. Деньги пришли. Выполните заказ или верните деньги в личном кабинете. Подробнее — в разделе Поздняя оплата.
Одно уведомление пришло два раза. Это ошибка?
Нет, так бывает. Обрабатывайте уведомления так, чтобы повтор ничего не менял: не выполняйте заказ второй раз.
Уведомления не приходят. Что проверить?
Адрес и события в Ещё → Разработчикам → HTTP-уведомления. Адрес должен быть https://, на порту 443 или 8443, с действующим сертификатом. Попытки отправки видны в Ещё → Разработчикам → Логи запросов. Платежи, созданные до того, как указан адрес, уведомлений не получат никогда: проверьте их запросом GET /v3/payments/{payment_id}. Чтобы не пропускать оплаты, сверяйтесь с API по расписанию — как.
Пришло уведомление о платеже, которого нет в моих заказах. Что это?
Например, счёт, выставленный в личном кабинете: о таких платежах уведомления приходят тоже. Ответьте 200 и ничего не делайте. Так же — если запрос платежа вернул 404.
Ответ 401 invalid_credentials. Что не так?
Неверный ID магазина или секретный ключ. Возможно, ключ перевыпустили. Проверьте их в Ещё → Разработчикам → API-ключ и проверьте адрес: https://api.avantpay.io/v3.
Ответ 403 forbidden. Что не так?
У ключа нет права «Платежи» или магазин не активен. Напишите в поддержку: [email protected].
Ответ 404 на любой запрос. Что не так?
Скорее всего, адрес. Правильно: https://api.avantpay.io/v3/payments — payments во множественном числе, версия v3.
Ответ 429 too_many_requests. Что не так?
Больше 50 запросов в секунду от магазина. Подождите retry_after миллисекунд и повторите с тем же Idempotence-Key.
Ответ 500 или нет ответа. Платёж создан?
Неизвестно. Повторите тот же запрос с тем же Idempotence-Key: придёт созданный платёж или он создастся сейчас. Не создавайте платёж с новым ключом, иначе покупатель может заплатить дважды. Если повтор вернул "status": "canceled", платёж не создался до конца: вот тогда создайте новый с новым ключом.
Повторил запрос с тем же ключом, но с другой суммой — пришла ошибка 400. Почему?
Один ключ идемпотентности — один платёж. Тот же ключ с другим телом запроса API отклоняет: "description": "Idempotence key duplicated…". Для нового платежа нужен новый ключ.
Повторил запрос с тем же ключом через два дня — пришла ошибка 400. Почему?
Повтор с тем же ключом работает 24 часа. Позже API отвечает 400, а не прежним платежом. Чтобы узнать, чем кончился тот запрос, запросите платёж по id из заказа.
Можно ли вызывать API из браузера или мобильного приложения?
Нет. Для запроса нужен секретный ключ, а в браузере и приложении его может прочитать кто угодно. Браузер такой запрос и не выполнит: CORS выключен. Вызывайте API со своего сервера.
Где посмотреть запросы к API?
В личном кабинете: Ещё → Разработчикам → Логи запросов. Там видны запросы и уведомления с ответами.
Куда писать, если ничего не помогло?
[email protected]. Укажите id платежа, id ошибки из ответа и значение заголовка X-Request-Id.