Частые вопросы
Нужна ли библиотека или SDK?
Нет. Подойдёт любой HTTP-клиент. Примеры на cURL, Python, Node.js и PHP — в справочнике API и в быстром старте.
Обязательно ли передавать email покупателя?
Да. Передавайте email покупателя в metadata.email в каждом запросе на создание платежа. Без него или с неверным адресом API ответит 400 invalid_request, "parameter": "metadata.email".
Где взять email покупателя из Telegram?
Если покупатель пришёл из Telegram и email у вас нет, передайте <telegram_id>@telegram.org — числовой ID пользователя Telegram, например 123456789@telegram.org.
Как связать платёж с заказом?
Передайте номер заказа в 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 — запросом POST /v3/refunds — или в личном кабинете. Для возвратов через API у ключа должно быть включено право «Возвраты»: его включает поддержка AvantPay. Как сделать возврат — на странице Возвраты.
Можно ли вернуть только часть суммы?
Да. Передайте в amount.value нужную сумму, но не меньше 1 ₽: меньше можно вернуть, только если это весь остаток. По одному платежу одновременно выполняется только один возврат: следующий создавайте, когда прежний стал succeeded или canceled. Всего — не больше 10 возвратов на платёж.
Ответ на создание возврата — pending. Деньги вернулись?
Ещё нет: на запрос, который создал возврат, всегда приходит pending. Дождитесь уведомления refund.succeeded или запросите возврат GET /v3/refunds/{refund_id}. Деньги вернули, когда status равен succeeded. Повтор с тем же ключом вернёт тот же возврат в текущем статусе — он может быть уже succeeded или canceled. Если возврат в pending дольше часа, напишите в поддержку и не создавайте новый.
Возврат отменён. Что делать?
Посмотрите cancellation_details. Причина insufficient_funds у "party": "avantpay" — на счёте магазина не хватило денег: дождитесь, когда сумма будет на счёте, и создайте новый возврат с новым ключом идемпотентности. Остаток счёта виден в личном кабинете на странице «Обзор», через API его не узнать. "party": "refund_network" — возврат отклонил банк: сумма вернётся на счёт магазина, но до 3 дней может быть в резерве. В этом и в остальных случаях напишите в поддержку. Уведомления об отмене возврата нет: проверяйте возврат запросом.
Возвращается ли комиссия при возврате?
Нет. Со счёта магазина списывается вся сумма возврата, комиссия AvantPay за платёж не возвращается.
Есть ли тестовый режим?
Нет. Проверьте интеграцию без оплаты и одним настоящим платежом на минимальную сумму, потом верните деньги — через API или в личном кабинете. Как — на странице Проверка интеграции.
AvantPay отправляет чеки 54-ФЗ?
Нет. Не передавайте receipt: запрос с ним получит ошибку 400 not_supported.
Можно ли сохранить карту и списывать без покупателя?
Нет. Сохранения способов оплаты и автоплатежей нет.
В какой валюте принимать платежи?
В рублях: "currency": "RUB".
Какая минимальная и максимальная сумма?
Зависит от способа оплаты. Лимиты — в личном кабинете: Ещё → Способы оплаты. Если сумма вне лимитов, API ответит 400 с "parameter": "amount.value".
Одно уведомление пришло два раза. Это ошибка?
Нет, так бывает. Обрабатывайте уведомления так, чтобы повтор ничего не менял: не выполняйте заказ второй раз.
Уведомления не приходят. Что проверить?
Адрес и события в Ещё → Разработчикам → HTTP-уведомления. Адрес должен быть https://, на порту 443 или 8443, с действующим сертификатом. Попытки отправки видны в Ещё → Разработчикам → Логи запросов. Платежи, созданные до того, как указан адрес, уведомлений не получат никогда: проверьте их запросом GET /v3/payments/{payment_id}.
Пришло уведомление о платеже, которого нет в моих заказах. Что это?
Например, счёт, выставленный в личном кабинете: о таких платежах уведомления приходят тоже. Ответьте 200 и ничего не делайте. Так же — если запрос платежа вернул 404.
Ответ 401 invalid_credentials. Что не так?
Неверный ID магазина или секретный ключ. Возможно, ключ перевыпустили. Проверьте их в Ещё → Разработчикам → API-ключ и проверьте адрес: https://api.avantpay.io/v3.
Ответ 403 forbidden. Что не так?
У ключа нет права «Платежи» (для POST /v3/refunds — права «Возвраты») или магазин не активен. Ещё возвраты могут быть разрешены только с IP-адресов из списка ключа, а запрос пришёл с другого. Напишите в поддержку: support@avantpay.io. Если 403 пришёл на повтор возврата после таймаута или ответа 500, после исправления повторите запрос с тем же ключом: возврат мог создаться первым запросом.
Ответ 404 на любой запрос. Что не так?
Скорее всего, адрес. Правильно: https://api.avantpay.io/v3/payments и https://api.avantpay.io/v3/refunds — во множественном числе, версия v3.
Ответ 429 too_many_requests. Что не так?
Больше 50 запросов в секунду от магазина. Подождите retry_after миллисекунд и повторите с тем же Idempotence-Key.
Ответ 500 или нет ответа. Платёж создан?
Неизвестно. Повторите тот же запрос с тем же Idempotence-Key: придёт созданный платёж или он создастся сейчас. Не создавайте платёж с новым ключом, иначе покупатель может заплатить дважды. Если повтор вернул "status": "canceled", платёж не создался до конца: вот тогда создайте новый с новым ключом.
С возвратом — так же: повторите запрос с тем же ключом и тем же телом. Запрос с новым ключом может создать второй возврат (если прежний уже завершён и у платежа есть остаток), и покупатель получит деньги дважды.
Повторил запрос с тем же ключом, но с другой суммой — пришла ошибка 400. Почему?
Один ключ идемпотентности — один платёж. Тот же ключ с другим телом запроса API отклоняет: "description": "Idempotence key duplicated…". Для нового платежа нужен новый ключ.
У возврата такой ответ значит: возврат с этим ключом уже создан. Не создавайте новый, пока не найдёте его в списке возвратов по платежу: GET /v3/refunds?payment_id=<id платежа>.
Повторил запрос с тем же ключом через два дня — создался новый платёж. Почему?
Повтор с тем же ключом работает 24 часа. Позже запрос с тем же ключом обрабатывается как новый: создаётся новый платёж или возврат. Чтобы узнать, чем кончился первый запрос, запросите платёж по id из заказа. У возврата — найдите его в списке возвратов по платежу по вашим данным в metadata.
Можно ли вызывать API из браузера или мобильного приложения?
Нет. Для запроса нужен секретный ключ, а в браузере и приложении его может прочитать кто угодно. Браузер такой запрос и не выполнит: CORS выключен. Вызывайте API со своего сервера.
Где посмотреть запросы к API?
В личном кабинете: Ещё → Разработчикам → Логи запросов. Там видны запросы и уведомления с ответами.
Куда писать, если ничего не помогло?
support@avantpay.io. Укажите id платежа или возврата, id ошибки из ответа и значение заголовка X-Request-Id.