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

Справочник API

Здесь описаны все методы API: платежи, способы оплаты для автоплатежей, возвраты и уведомления.

Адрес API — https://api.avantpay.io/v3.

Примеры берут ID магазина и секретный ключ из переменных окружения AVANTPAY_SHOP_ID и AVANTPAY_SECRET_KEY. Язык примеров выберите в любом блоке кода — он запомнится на всех страницах.

Аутентификация​

Адрес API — https://api.avantpay.io/v3. Пути методов добавляются к нему: https://api.avantpay.io/v3/payments. Запросы — только по HTTPS.

Отправляйте запросы только со своего сервера. Не вызывайте API из браузера или мобильного приложения: в их код пришлось бы положить секретный ключ, а там его может прочитать кто угодно. Браузер такой запрос и не выполнит: API не разрешает запросы со страниц сайтов (CORS выключен).

API использует HTTP Basic:

  • логин — ID магазина, например 33661;
  • пароль — секретный ключ.

В cURL это параметр -u. Без cURL передайте заголовок Authorization со словом Basic и строкой <ID магазина>:<секретный ключ> в Base64. Почти все HTTP-библиотеки собирают этот заголовок сами, если передать логин и пароль.

Где взять ID магазина и секретный ключ​

  1. Войдите в личный кабинет.
  2. Откройте Ещё → Разработчикам → API-ключ (открыть сразу).
  3. ID магазина и адрес API — в блоке «Авторизация запросов».
  4. Нажмите Создать ключ. Ключ показывается целиком только один раз. Скопируйте его сразу.

Если раздела «Разработчикам» нет, попросите владельца магазина добавить вас в разделе «Пользователи» с ролью «Разработчик».

Как хранить ключ​

  • Храните ключ в переменных окружения или в хранилище секретов сервера.
  • Не кладите ключ в код, в репозиторий, в логи и в письма.
  • Если ключ мог утечь, нажмите Перевыпустить в том же разделе. Старый ключ сразу перестанет работать. Замените ключ на сервере. Если у ключа включено право «Возвраты», перевыпустить или удалить его может только владелец магазина.
  • Тем же ключом AvantPay подписывает уведомления. После перевыпуска уведомления подписываются новым ключом.

Права ключа​

В блоке «Права ключа» видно, что можно делать этим ключом. Для создания платежей нужно право «Платежи», для возвратов — право «Возвраты».

  • Права включает поддержка AvantPay. В личном кабинете их можно только посмотреть. Чтобы включить право, напишите на support@avantpay.io.
  • Без права «Платежи» запрос POST /v3/payments получит ошибку 403 forbidden. Без права «Возвраты» — запрос POST /v3/refunds.
  • Право «Возвраты» по умолчанию выключено. Поддержка может разрешить возвраты только с IP-адресов ваших серверов: тогда запрос POST /v3/refunds с другого адреса получит 403 forbidden. Адреса укажите в письме.
  • Запросы GET (платежи, возвраты, списки) работают с любым действующим ключом магазина.

Лимит запросов​

  • Не больше 50 запросов в секунду на магазин. Сверх лимита API ответит 429 too_many_requests.
  • В ответе 429 есть поле retry_after — через сколько миллисекунд повторить, и заголовок Retry-After — то же в секундах.
  • Повторяйте запрос на создание платежа или возврата после 429 с тем же Idempotence-Key.

Проверка ключей: запрос возвращает последний платёж магазина и ничего не меняет.

curl "https://api.avantpay.io/v3/payments?limit=1" \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY"

Ответ 200 — ключи верные. Ответ 401 invalid_credentials — неверный ID магазина или ключ:

{
  "type": "error",
  "id": "0d8e4c1a-6b2f-4e3d-9a7c-5f1b2e3d4c5a",
  "code": "invalid_credentials",
  "description": "Invalid credentials: use HTTP Basic authentication with the shop ID as the username and the API secret key as the password",
  "parameter": "Authorization"
}

Заголовок Authorization без cURL:

Authorization: Basic MzM2NjE6dGVzdF9zZWNyZXRfa2V5

Здесь MzM2NjE6dGVzdF9zZWNyZXRfa2V5 — это Base64 от строки 33661:test_secret_key.

Ответ 429 — больше 50 запросов в секунду:

{
  "type": "error",
  "id": "5a1c3e2b-7d4f-4a6b-8c9d-0e1f2a3b4c5d",
  "code": "too_many_requests",
  "description": "Too many requests: the shop exceeded the request rate limit. Retry later with the same Idempotence-Key",
  "retry_after": 1000
}

Ошибки аутентификации​

HTTPcodeКогдаЧто делать
401invalid_credentialsНет заголовка Authorization, неверный ID магазина или ключ, ключ перевыпущен или удалён. parameter — Authorization.Проверьте ID магазина и ключ. Если ключ потерян — перевыпустите его.
403forbiddenУ ключа нет права «Платежи» или «Возвраты», магазин не активен или возврат отправлен с IP-адреса, которого нет в списке ключа.Напишите в поддержку: support@avantpay.io.
429too_many_requestsС вашего IP-адреса за минуту пришло больше 20 запросов с неверными ключами. До конца этой минуты API отвечает 429 на все запросы с этого адреса.Исправьте ключи и повторите через retry_after миллисекунд.

Идемпотентность​

Идемпотентность означает, что повторный запрос обрабатывается так же, как первый: получив повтор с теми же данными, AvantPay вернёт результат исходного запроса и второй платёж или возврат не создаст. Если соединение прервалось, запрос можно безопасно повторить.

Для этого передавайте заголовок Idempotence-Key — любое значение, уникальное для операции на вашей стороне, до 64 символов. Рекомендуется UUID версии 4. Ключ обязателен для всех POST-запросов. GET-запросам он не нужен.

Повтор с тем же ключом и теми же данными вернёт результат первого запроса. Тот же ключ с другими данными — ошибка 400 invalid_request, "parameter": "Idempotence-Key". Если первый запрос ещё выполняется, API ответит 202 с полем retry_after — через сколько миллисекунд повторить запрос с тем же ключом.

AvantPay обеспечивает идемпотентность в течение 24 часов после первого запроса. Позже запрос с тем же ключом обрабатывается как новый.

Выполните эту команду дважды. Второй ответ вернёт тот же платёж с тем же id.

curl https://api.avantpay.io/v3/payments \
  -X POST \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY" \
  -H "Idempotence-Key: 5b8e2f3a-6c1d-4e7f-9a0b-1c2d3e4f5a6b" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": "100.00",
      "currency": "RUB"
    },
    "capture": true,
    "confirmation": {
      "type": "redirect",
      "return_url": "https://example.com/orders/2"
    },
    "description": "Заказ №2",
    "metadata": {
      "email": "buyer@example.com",
      "order_id": "2"
    }
  }'

Ответ 202 — запрос с этим ключом ещё выполняется:

{
  "type": "processing",
  "description": "Request accepted",
  "retry_after": 2000
}

Ответ 400 на тот же ключ с другим телом:

{
  "type": "error",
  "id": "9c3b7a1e-2f4d-4b6a-8e5c-1d2f3a4b5c6d",
  "code": "invalid_request",
  "description": "Idempotence key duplicated: this key was already used with a different request body. Use a new Idempotence-Key for a new request",
  "parameter": "Idempotence-Key"
}

Формат запросов и ответов​

Запросы​

API поддерживает POST- и GET-запросы. POST-запросы передают параметры в теле в формате JSON с заголовком Content-Type: application/json, GET-запросы — в строке запроса. Тело запроса — не больше 5 МБ. Параметры, которых нет в справочнике, API отбрасывает без ошибки.

Ответы​

Ответ содержит код HTTP, стандартные заголовки и тело в формате JSON. При успехе (HTTP 200) в теле — созданный или запрошенный объект или список объектов. При ошибке — объект ошибки (Ошибки). В каждом ответе есть заголовок X-Request-Id: укажите его, если обращаетесь в поддержку.

Сумма​

Сумма — объект с полями value и currency. value — строка, рубли и копейки через точку, не больше двух знаков после точки: "100.00". currency — код валюты по ISO-4217, "RUB".

Дата и время​

Даты — в формате ISO 8601 по UTC: 2026-10-18T10:15:30.123Z.

metadata​

metadata — ваши данные к платежу или возврату: до 16 ключей, имя ключа — до 32 символов, значение — строка до 512 символов. В запросе на создание платежа обязателен ключ email — email покупателя (покупатель из Telegram — <telegram_id>@telegram.org). metadata возвращается в объекте платежа или возврата и в уведомлениях.

Сумма:

{
  "value": "100.00",
  "currency": "RUB"
}

metadata с email покупателя и номером заказа:

{
  "email": "buyer@example.com",
  "order_id": "123",
  "customer_id": "1042"
}

Покупатель из Telegram:

{
  "email": "123456789@telegram.org",
  "order_id": "124"
}

Ошибки​

Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).

Объект ошибки​

requiredtype
string

Всегда error.

requiredid
string

ID ошибки. Укажите его, если пишете в поддержку.

requiredcode
string

Код ошибки из таблицы ниже. По нему решайте, что делать.

requireddescription
string

Что не так и как исправить. На английском. Пишите в логи, покупателю не показывайте.

optionalparameter
string

Какое поле, заголовок или параметр неверны. Например: amount.value, metadata.email, Idempotence-Key, Authorization, payment_id, refund_id, limit.

optionalretry_after
integer

Через сколько миллисекунд повторить запрос. Есть у ответов 429.

Ошибка 400 — в запросе нет email покупателя:

{
  "type": "error",
  "id": "6daac9fa-342d-4264-91c5-b5eafd1a0010",
  "code": "invalid_request",
  "description": "metadata.email is required: pass the buyer's email address, for a Telegram buyer use <id or username>@telegram.org",
  "parameter": "metadata.email"
}

Ошибка 400 — поле, которого нет в API:

{
  "type": "error",
  "id": "1f4e2a7c-8b3d-4c6e-9a5f-0d1c2b3a4e5f",
  "code": "not_supported",
  "description": "receipt is not supported: AvantPay does not register fiscal receipts (54-FZ), remove receipt from the request",
  "parameter": "receipt"
}

Ошибка 429:

{
  "type": "error",
  "id": "5a1c3e2b-7d4f-4a6b-8c9d-0e1f2a3b4c5d",
  "code": "too_many_requests",
  "description": "Too many requests: the shop exceeded the request rate limit. Retry later with the same Idempotence-Key",
  "retry_after": 1000
}

Коды​

HTTPcodeКогдаЧто делать
200—Запрос выполнен. Создание платежа и возврата — тоже 200.—
202—Запрос на создание платежа с этим ключом идемпотентности ещё выполняется, у сценария qr — банк ещё выдаёт QR-код. Тело: {"type": "processing", "description": "Request accepted", "retry_after": 2000}.Подождать retry_after миллисекунд и повторить с тем же Idempotence-Key.
400invalid_requestНеверный запрос: нет поля или заголовка (например, metadata.email), неверный формат, сумма вне лимитов, ключ идемпотентности уже использован с другим телом, тело не JSON. Для возврата — ещё платёж, который нельзя вернуть сейчас (parameter — payment_id).Исправить запрос по parameter и description. Без исправления не повторять.
400not_supportedПередано поле или значение, которого нет в API (например, receipt или "capture": false), или вызван метод, которого нет.Убрать поле или не вызывать метод. Без исправления не повторять.
401invalid_credentialsНет заголовка Authorization, неверный ID магазина или секретный ключ, заголовок Bearer. parameter — Authorization.Проверить ID магазина и ключ. Без исправления не повторять.
403forbiddenУ ключа нет права «Платежи» или «Возвраты», магазин не активен, сценарий qr не включён для магазина или возврат отправлен с IP-адреса, которого нет в списке ключа.Написать в поддержку: support@avantpay.io.
404not_foundПлатежа или возврата с таким id нет у вашего магазина (parameter — payment_id или refund_id). Или такого адреса нет.Проверить id и адрес.
405invalid_requestМетод HTTP не подходит для этого адреса. Например, PUT /v3/payments. Допустимые методы — в заголовке Allow.Исправить метод.
413invalid_requestТело запроса больше 5 МБ.Уменьшить тело.
415invalid_requestУ POST-запроса нет заголовка Content-Type: application/json.Передать JSON с этим заголовком.
429too_many_requestsБольше 50 запросов в секунду от магазина, много запросов с неверными ключами с одного IP-адреса, в эту же секунду создаются другие платежи того же покупателя или у магазина уже 20 возвратов в статусе pending.Подождать retry_after миллисекунд (заголовок Retry-After — в секундах) и повторить с тем же Idempotence-Key.
500internal_server_errorСбой у AvantPay. Результат запроса неизвестен: платёж или возврат мог создаться.Повторить с тем же Idempotence-Key и тем же телом. Платёж можно проверить и запросом GET.

Другой код 5xx или ответ не в JSON обрабатывайте как 500.

Когда повторять запрос​

ОтветПовторять?
400, 401, 403, 404, 405, 413, 415Нет. Сначала исправьте запрос, ключи или настройки. Новый ключ идемпотентности — только для нового запроса на создание, который вы раньше не отправляли.
400, 401 или 403 на повтор создания возврата после таймаута или ответа 500Да, после исправления — с тем же Idempotence-Key. Возврат мог создаться первым запросом: повтор вернёт его или создаст сейчас. Новый ключ здесь может вернуть деньги дважды. Подробнее
202, 429Да, через retry_after миллисекунд, с тем же Idempotence-Key.
500, таймаут, обрыв связиДа, с тем же Idempotence-Key и тем же телом. Повторяйте 1–2 минуты, потом покажите покупателю «Платёж создаётся» и продолжайте в фоне с тем же ключом, но не дольше 24 часов.

Запрос на создание возврата после 500, таймаута или обрыва повторяйте так же: с тем же ключом и тем же телом, не дольше 24 часов.

Не создавайте платёж или возврат с новым ключом, пока не знаете, чем кончился прежний запрос. Иначе покупатель может заплатить дважды или получить деньги дважды.

Объект платежа​

Объект платежа (Payment) содержит всю информацию о платеже, актуальную на текущий момент времени. Он формируется при создании платежа и приходит в ответ на любой запрос, связанный с платежами.

Объект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.

Поля​

requiredid
string

ID платежа, UUID из 36 символов. Сохраните его в заказе: по нему вы получите платёж.

requiredstatus
string

Статус платежа: pending, succeeded или canceled. Что делать в каждом — на странице Статусы платежа.

requiredpaid
boolean

true, если платёж оплачен (status равен succeeded). Иначе false.

requiredamount
object

Сумма платежа — ровно та, что вы передали при создании. Покупатель платит эту сумму.

Вложенные параметры
requiredvalue
string

Сумма строкой с двумя знаками после точки.

Пример: "1000.00"
requiredcurrency
string

Валюта: RUB.

optionalincome_amount
object

Сколько получит магазин: amount минус комиссия AvantPay. Бывает только у платежей со статусом succeeded. Может не быть и у них, например пока AvantPay проверяет оплату. Не решайте по этому полю, оплачен ли платёж.

Вложенные параметры
requiredvalue
string

Сумма строкой с двумя знаками после точки.

Пример: "975.00"
requiredcurrency
string

Валюта: RUB.

optionaldescription
string

Описание, которое вы передали при создании. Есть, только если вы его передали.

requiredrecipient
object

Получатель платежа — ваш магазин.

Вложенные параметры
requiredaccount_id
string

ID магазина строкой.

optionalgateway_id
string

ID счёта в AvantPay, на который зачисляются деньги. Появляется, когда выбран способ оплаты. Для интеграции не нужен.

optionalpayment_method
object

Способ оплаты. Появляется, когда способ выбран: сразу, если вы передали payment_method_data, иначе — когда покупатель выберет способ на странице оплаты. Если магазину подключены другие способы, type может быть и другим — на незнакомом значении код не должен падать.

Вложенные параметры
Способ оплаты
requiredtype
string

Значение — sbp.

requiredid
string

ID способа оплаты. У сохранённого способа — его ID: передавайте его в payment_method_id для автоплатежей (способы оплаты). У несохранённого равен id платежа.

requiredsaved
boolean

true — способ сохранён для автоплатежей.

requiredstatus
string

Статус сохранения: pending — платёж с save_payment_method ждёт оплаты, active — способ сохранён, inactive — не сохранён.

optionaltitle
string

Название способа.

optionalcaptured_at
string

Когда платёж оплачен. Бывает только у платежей со статусом succeeded. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-18T10:17:02.418Z.

requiredcreated_at
string

Когда платёж создан. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-18T10:15:30.123Z.

requiredexpires_at
string

До какого момента покупатель может заплатить: 20 минут после создания платежа, у сценария qr — срок QR-кода (10 минут после выдачи). Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-18T10:35:30.123Z.

optionalconfirmation
object

Как покупатель платит — сценарий, который вы передали при создании. Нет у платежа со сценарием qr, у которого нет QR-кода: AvantPay отклонил платёж при создании (canceled, причина fraud_suspected), банк не выдал QR-код (canceled) или QR-код ещё выдаётся (pending после ответа 202 на создание: повторите запрос создания с тем же Idempotence-Key).

Вложенные параметры
Сценарий
requiredtype
string

redirect — страница оплаты AvantPay.

optionalconfirmation_url
string

Ссылка на страницу оплаты. Отправьте покупателя по ней, только если status равен pending. Может не быть у платежа, который отменён при создании.

optionalreturn_url
string

Адрес возврата покупателя, который вы передали.

requiredtest
boolean

Тестовый ли платёж. Всегда false: тестового режима нет.

optionalrefunded_amount
object

Сколько денег уже вернули покупателю: сумма выполненных возвратов (статус succeeded) — через API и в личном кабинете. Есть, только если был выполненный возврат. Статус платежа после возврата остаётся succeeded.

Вложенные параметры
requiredvalue
string

Сумма строкой с двумя знаками после точки.

Пример: "300.00"
requiredcurrency
string

Валюта: RUB.

requiredrefundable
boolean

Можно ли сейчас вернуть платёж запросом POST /v3/refunds. true — запрос пройдёт проверки. false — нельзя: платёж не оплачен, уже возвращён полностью, по нему идёт другой возврат или вернуть его можно только через поддержку. Право ключа «Возвраты» и деньги на счёте магазина здесь не учитываются.

requiredmetadata
object

Ваши данные из запроса на создание: email покупателя, номер заказа и другие ключи, которые вы передали. Значения — строки.

Вложенные параметры
requiredemail
string

Email покупателя, который вы передали.

optionalorder_id
string

Номер заказа, если вы его передали.

optionalcancellation_details
object

Кто отменил платёж и почему. Бывает только у платежей со статусом canceled.

Вложенные параметры
requiredparty
string

Кто отменил: merchant, avantpay или payment_network. Что значит каждое — на странице Статусы платежа.

requiredreason
string

Причина отмены. Все причины — на странице Статусы платежа.

Покупатель оплатил картой:

{
  "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "975.00",
    "currency": "RUB"
  },
  "description": "Заказ №123",
  "recipient": {
    "account_id": "33661",
    "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
    "saved": false,
    "status": "inactive",
    "title": "Банковская карта"
  },
  "captured_at": "2026-10-18T10:17:02.418Z",
  "created_at": "2026-10-18T10:15:30.123Z",
  "expires_at": "2026-10-18T10:35:30.123Z",
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://avantpay.io/checkout?paymentId=2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
    "return_url": "https://example.com/orders/123"
  },
  "test": false,
  "refundable": true,
  "metadata": {
    "email": "buyer@example.com",
    "order_id": "123"
  }
}

Создать платёж​

POSThttps://api.avantpay.io/v3/payments

Создаёт платёж и возвращает объект платежа со статусом pending и ссылкой на оплату confirmation.confirmation_url.

к сведению

Email покупателя обязателен: передайте его в metadata.email. Покупатель из Telegram — <telegram_id>@telegram.org, например 123456789@telegram.org.

Заголовки​

Все три заголовка обязательны.

ЗаголовокЗначение
AuthorizationHTTP Basic: ID магазина и секретный ключ. В cURL — параметр -u со значением "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY".
Idempotence-KeyКлюч идемпотентности: уникальная строка до 64 символов, лучше UUID. Новый для каждой попытки оплаты, тот же при повторе запроса. Подробнее
Content-Typeapplication/json

Параметры запроса​

requiredamount
object

Сумма платежа. Покупатель заплатит ровно её. Комиссию AvantPay платит магазин: она вычитается из этой суммы.

Вложенные параметры
requiredvalue
string

Сумма строкой, рубли и копейки через точку. Больше нуля, не больше двух знаков после точки. Должна укладываться в лимиты способов оплаты — они есть в личном кабинете: Ещё → Способы оплаты.

Пример: "1000.00"
requiredcurrency
string

Валюта: RUB.

requiredcapture
boolean

Указывается true.

required без payment_method_idconfirmation
object

Как покупатель будет платить.

Вложенные параметры
Сценарий
requiredtype
string

redirect — покупатель переходит на страницу оплаты AvantPay.

requiredreturn_url
string

Куда вернуть покупателя после оплаты или отказа от неё. Адрес http:// или https://, до 2048 символов. AvantPay открывает его как есть, без параметров, поэтому укажите в нём свой заказ.

optionaldescription
string

Описание платежа, до 128 символов. Его видит покупатель на странице оплаты и вы в личном кабинете.

optionalpayment_method_data
object

Способ оплаты. Если не передать, покупатель выберет способ на странице оплаты. Способ должен быть включён у магазина.

Вложенные параметры
Способ оплаты
requiredtype
string

Значение — sbp.

optionalclient_ip
string

IP-адрес покупателя, IPv4 или IPv6.

optionalsave_payment_method
boolean

true — сохранить способ оплаты для автоплатежей. ID сохранённого способа — payment_method.id в ответе (подробнее).

optionalpayment_method_id
string

ID сохранённого способа оплаты, до 64 символов: списание без участия покупателя. confirmation и metadata.email не нужны (подробнее).

requiredmetadata
object

Ваши данные к платежу. Обязателен ключ email. Всего до 16 ключей, имя ключа до 32 символов, значение — строка до 512 символов. Вернутся в объекте платежа и в уведомлениях. Подробнее — в разделе metadata.

Вложенные параметры
requiredemail
string

Email покупателя, до 254 символов. Покупатель из Telegram — <telegram_id>@telegram.org, например 123456789@telegram.org. Нет email или адрес неверный — ошибка 400 invalid_request, parameter — metadata.email.

optionalorder_id
string

Ваш номер заказа. Вернётся в объекте платежа и в уведомлениях. API не проверяет, что номер уникален: от двойного платежа защищает ключ идемпотентности.

Ответ​

В ответ на запрос придёт объект платежа в актуальном статусе.

Пример запроса

curl https://api.avantpay.io/v3/payments \
  -X POST \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY" \
  -H "Idempotence-Key: e1d2c3b4-a5f6-4789-8abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": "1000.00",
      "currency": "RUB"
    },
    "capture": true,
    "confirmation": {
      "type": "redirect",
      "return_url": "https://example.com/orders/123"
    },
    "description": "Заказ №123",
    "metadata": {
      "email": "buyer@example.com",
      "order_id": "123"
    }
  }'

Пример ответа

Объект платежа со ссылкой на оплату

Content typeapplication/json
{
  "id": "3d6f0a8e-5b2c-4e1f-9a7d-2c4b6e8f0a1b",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "description": "Заказ №123",
  "recipient": {
    "account_id": "33661"
  },
  "created_at": "2026-10-18T10:15:30.123Z",
  "expires_at": "2026-10-18T10:35:30.123Z",
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://avantpay.io/checkout?paymentId=3d6f0a8e-5b2c-4e1f-9a7d-2c4b6e8f0a1b",
    "return_url": "https://example.com/orders/123"
  },
  "test": false,
  "refundable": false,
  "metadata": {
    "email": "buyer@example.com",
    "order_id": "123"
  }
}

Ошибки​

Формат ошибок и общие коды — в разделе Ошибки. Ошибки этого метода:

HTTPcodeparameterКогдаЧто делать
400invalid_requestmetadata.emailНет metadata, нет ключа email, он пустой или это не email (больше 254 символов, неверный адрес …@telegram.org).Передать email покупателя. Покупатель из Telegram — <telegram_id>@telegram.org.
400invalid_requestIdempotence-KeyНет ключа, ключ длиннее 64 символов, переданы Idempotence-Key и Idempotency-Key с разными значениями, тот же ключ уже использован с другим телом запроса.Передать один ключ до 64 символов. Для нового платежа — новый ключ.
400invalid_requestcaptureНет capture или это не true/false (например, строка "true").Передать "capture": true.
400not_supportedcapture"capture": false.Передать "capture": true.
400invalid_requestamount, amount.valueНет суммы, сумма не число, больше двух знаков после точки, не больше нуля или вне лимитов способов оплаты.Исправить сумму. Лимиты — в личном кабинете, Ещё → Способы оплаты.
400invalid_requestamount.currencyВалюта не RUB или у магазина нет способов оплаты в этой валюте.Передать "RUB".
400invalid_request—У магазина не включён ни один способ оплаты.Написать в поддержку: support@avantpay.io.
400invalid_requestconfirmation, confirmation.type, confirmation.return_urlНет confirmation, неизвестный тип, нет return_url, return_url — не адрес http:// или https:// либо длиннее 2048 символов, qr без "payment_method_data": {"type": "sbp"}.Передать return_url. Для qr — ещё способ sbp.
400not_supportedconfirmation.typeТип, кроме redirect и qr.Передать redirect или qr.
400invalid_requestpayment_method_data.typeТакого способа нет у магазина, он не работает в рублях, или включено несколько способов этого типа.Передать sbp или bank_card, идентификатор способа из description либо не передавать payment_method_data.
400invalid_requestdescriptionДлиннее 128 символов.Сократить описание.
400invalid_requestclient_ipСценарий qr, а client_ip — не IPv4 и не IPv6. У redirect неверный адрес ошибки не даёт, но и не сохраняется.Передать IP покупателя или не передавать поле.
400invalid_requestmetadatametadata — не объект, больше 16 ключей, длинное имя ключа или значение, значение — массив или объект.Привести к правилам из раздела metadata.
400invalid_requestmetadata.<ключ>Для магазина по договору с AvantPay обязательны ещё некоторые ключи metadata, а их нет.Передать ключ, названный в parameter.
400invalid_requestorder_id, webhook_url, expires_at, avantpayПередано поле, которого в запросе нет.Номер заказа передать в metadata.order_id. Адрес уведомлений указать в личном кабинете. Срок оплаты не передавать: он 20 минут.
400not_supportedимя поляПередано поле, которого нет в API: receipt, payment_method_data.card и другие.Убрать поле из запроса.
400invalid_request—Тело запроса — не JSON.Передать правильный JSON.
401invalid_credentialsAuthorizationНеверный ID магазина или ключ.Проверить ключи.
403forbidden—У ключа нет права «Платежи» или магазин не активен.Написать в поддержку: support@avantpay.io.
403forbiddenconfirmation.typeСценарий (обычно qr) не включён для магазина.Использовать redirect или написать в поддержку.
413invalid_request—Тело запроса больше 5 МБ.Уменьшить тело.
415invalid_request—Нет заголовка Content-Type: application/json.Передать заголовок.
429too_many_requests—Больше 50 запросов в секунду.Подождать retry_after миллисекунд и повторить с тем же ключом.
429too_many_requests—В эту же секунду создаются другие платежи этого покупателя. Платёж не создан.Подождать retry_after миллисекунд и повторить с тем же ключом.
202——Запрос с этим ключом ещё выполняется, у сценария qr — банк ещё выдаёт QR-код. Тело: {"type": "processing", ...}.Подождать retry_after миллисекунд и повторить с тем же ключом.
500internal_server_error—Сбой у AvantPay. Платёж мог создаться.Повторить с тем же ключом.

Если ответа нет совсем (таймаут, обрыв связи), поступите так же, как при ответе 500: повторите запрос с тем же Idempotence-Key и тем же телом. Если повтор вернул "status": "canceled", платёж не создался до конца: создайте новый с новым ключом.

Получить платёж​

GEThttps://api.avantpay.io/v3/payments/{payment_id}

Возвращает объект платежа в текущем состоянии.

Параметры пути​

requiredpayment_id
string

id платежа из ответа на его создание.

Ответ​

В ответ на запрос придёт объект платежа в актуальном статусе.

Пример запроса

curl https://api.avantpay.io/v3/payments/2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY"

Пример ответа

Content typeapplication/json
{
  "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "975.00",
    "currency": "RUB"
  },
  "description": "Заказ №123",
  "recipient": {
    "account_id": "33661",
    "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
    "saved": false,
    "status": "inactive",
    "title": "Банковская карта"
  },
  "captured_at": "2026-10-18T10:17:02.418Z",
  "created_at": "2026-10-18T10:15:30.123Z",
  "expires_at": "2026-10-18T10:35:30.123Z",
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://avantpay.io/checkout?paymentId=2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
    "return_url": "https://example.com/orders/123"
  },
  "test": false,
  "refundable": true,
  "metadata": {
    "email": "buyer@example.com",
    "order_id": "123"
  }
}

Ошибки​

HTTPcodeКогдаЧто делать
404not_foundПлатежа с таким id нет у вашего магазина. Платёж другого магазина тоже даёт 404. parameter — payment_id.Проверить id.
401invalid_credentialsНеверный ID магазина или ключ.Проверить ключи.
403forbiddenМагазин не активен.Написать в поддержку: support@avantpay.io.
429too_many_requestsБольше 50 запросов в секунду.Повторить через retry_after миллисекунд.
500internal_server_errorСбой у AvantPay.Повторить запрос позже.

Список платежей​

GEThttps://api.avantpay.io/v3/payments

Возвращает платежи вашего магазина от новых к старым. Можно отфильтровать по дате, статусу и способу оплаты. Список отдаётся страницами. Заголовок Idempotence-Key этому методу не нужен. Тела у запроса нет.

Параметры запроса​

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

optionallimit
integer

Сколько платежей на странице: от 1 до 100. По умолчанию 10.

optionalcursor
string

Значение next_cursor из предыдущего ответа — чтобы получить следующую страницу. Передавайте как есть.

optionalstatus
string

Только платежи с этим статусом: pending, succeeded или canceled.

optionalpayment_method
string

Только платежи этим способом: sbp или bank_card.

optionalcreated_at.gte
string

Созданы в этот момент или позже. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-01T00:00:00.000Z.

optionalcreated_at.gt
string

Созданы позже этого момента. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-01T00:00:00.000Z.

optionalcreated_at.lte
string

Созданы в этот момент или раньше. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-31T23:59:59.999Z.

optionalcreated_at.lt
string

Созданы раньше этого момента. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-11-01T00:00:00.000Z.

optionalcaptured_at.gte
string

Оплачены в этот момент или позже. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-01T00:00:00.000Z.

optionalcaptured_at.gt
string

Оплачены позже этого момента. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-01T00:00:00.000Z.

optionalcaptured_at.lte
string

Оплачены в этот момент или раньше. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-31T23:59:59.999Z.

optionalcaptured_at.lt
string

Оплачены раньше этого момента. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-11-01T00:00:00.000Z.

Фильтра по номеру заказа нет: запрос с order_id получит ошибку 400 not_supported. Номер заказа храните в metadata.order_id, а платёж получайте по id, который сохранили в заказе: GET /v3/payments/{payment_id}.

Ответ​

В ответ на запрос придёт объект списка: платежи в items — объекты платежа в актуальном статусе.

requiredtype
string

Всегда list.

requireditems
array

Платежи — объекты платежа, от новых к старым. Если ничего не нашлось — пустой массив [].

optionalnext_cursor
string

Курсор следующей страницы. Нет на последней странице.

Как получить все страницы​

  1. Отправьте запрос с нужными фильтрами.
  2. Если в ответе есть next_cursor, повторите запрос с теми же фильтрами и параметром cursor=<значение next_cursor>.
  3. Повторяйте, пока в ответе не будет next_cursor.

Новые платежи, пока вы получаете страницы, порядок не сдвигают: платежи не повторяются и не пропадают. Примеры на Python, Node.js и PHP получают все страницы сами.

Пример запроса

Оплаченные платежи с 1 октября 2026 года, по 2 на странице

curl "https://api.avantpay.io/v3/payments?status=succeeded&created_at.gte=2026-10-01T00:00:00.000Z&limit=2" \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY"

Пример ответа

Объект списка, первая страница

Content typeapplication/json
{
  "type": "list",
  "items": [
    {
      "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
      "status": "succeeded",
      "paid": true,
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "income_amount": {
        "value": "975.00",
        "currency": "RUB"
      },
      "description": "Заказ №123",
      "recipient": {
        "account_id": "33661",
        "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
      },
      "payment_method": {
        "type": "bank_card",
        "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
        "saved": false,
        "status": "inactive",
        "title": "Банковская карта"
      },
      "captured_at": "2026-10-18T10:17:02.418Z",
      "created_at": "2026-10-18T10:15:30.123Z",
      "expires_at": "2026-10-18T10:35:30.123Z",
      "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://avantpay.io/checkout?paymentId=2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
        "return_url": "https://example.com/orders/123"
      },
      "test": false,
      "refundable": true,
      "metadata": {
        "email": "buyer@example.com",
        "order_id": "123"
      }
    },
    {
      "id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
      "status": "succeeded",
      "paid": true,
      "amount": {
        "value": "250.00",
        "currency": "RUB"
      },
      "income_amount": {
        "value": "243.75",
        "currency": "RUB"
      },
      "description": "Заказ №122",
      "recipient": {
        "account_id": "33661",
        "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
      },
      "payment_method": {
        "type": "sbp",
        "id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
        "saved": false,
        "status": "inactive",
        "title": "СБП"
      },
      "captured_at": "2026-10-17T18:41:09.004Z",
      "created_at": "2026-10-17T18:39:55.871Z",
      "expires_at": "2026-10-17T18:59:55.871Z",
      "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://avantpay.io/checkout?paymentId=c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
        "return_url": "https://example.com/orders/122"
      },
      "test": false,
      "refunded_amount": {
        "value": "50.00",
        "currency": "RUB"
      },
      "refundable": true,
      "metadata": {
        "email": "buyer@example.com",
        "order_id": "122"
      }
    }
  ],
  "next_cursor": "MjAyNi0xMC0xN1QxODozOTo1NS44NzFafGM0YThlMmYxLTliM2QtNGY2YS04ZTFjLTdkMmI1YTlmM2U2MA"
}

Ошибки​

HTTPcodeКогдаЧто делать
400invalid_requestlimit — не целое число от 1 до 100, cursor — не из next_cursor, дата не в формате ISO 8601, status — незнакомое значение, параметр передан дважды. Имя параметра — в parameter.Исправить параметр.
400not_supportedПередан order_id. parameter — order_id.Убрать параметр. Получать платёж по id из заказа.
401invalid_credentialsНеверный ID магазина или ключ.Проверить ключи.
403forbiddenМагазин не активен.Написать в поддержку: support@avantpay.io.
429too_many_requestsБольше 50 запросов в секунду.Повторить через retry_after миллисекунд.
500internal_server_errorСбой у AvantPay.Повторить запрос позже.

Объект способа оплаты​

Объект способа оплаты (PaymentMethod) содержит информацию о способе оплаты, сохранённом для автоплатежей: тип, статус и данные карты или банка. Способ сохраняется платежом с save_payment_method: true или запросом на создание. Как проводить автоплатежи — на странице Автоплатежи.

Объект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.

Поля​

requiredtype
string

Тип способа оплаты: bank_card или sbp.

requiredid
string

ID способа оплаты. Передавайте его в payment_method_id при создании платежа для автоплатежа.

requiredsaved
boolean

true — способ сохранён: по нему можно проводить автоплатежи.

requiredstatus
string

Статус способа оплаты: pending — ждёт действий покупателя, active — сохранён, inactive — не сохранён (ошибка, истёк срок привязки) или покупатель отключил автоплатежи.

optionaltitle
string

Название способа оплаты.

optionalcard
object

Данные карты. Есть у сохранённой карты (bank_card).

Вложенные параметры
optionalfirst6
string

Первые 6 цифр номера карты (BIN).

requiredlast4
string

Последние 4 цифры номера карты.

optionalexpiry_month
string

Месяц окончания срока действия, MM.

optionalexpiry_year
string

Год окончания срока действия, YYYY.

requiredcard_type
string

Платёжная система: Mir, Visa, MasterCard, UnionPay или Unknown.

optionalissuer_country
string

Страна банка-эмитента, код ISO 3166-1 alpha-2.

optionalissuer_name
string

Банк-эмитент.

requiredholder
object

Магазин, для которого сохранён способ оплаты.

Вложенные параметры
requiredaccount_id
string

ID магазина.

optionalpayer_bank_details
object

Банк покупателя. Есть у СБП (sbp), если банк известен.

Вложенные параметры
requiredbank_id
string

ID банка в СБП.

optionalmetadata
object

Ваши данные из запроса на создание способа оплаты. Есть, только если вы их передали.

optionalconfirmation
object

Подтверждение способа оплаты покупателем. Есть у способа в статусе pending, созданного запросом.

Вложенные параметры
requiredtype
string

Значение — redirect.

requiredconfirmation_url
string

Ссылка, по которой покупатель подтверждает сохранение карты. Перенаправьте его по ней.

optionalreturn_url
string

Куда вернётся покупатель — из запроса на создание.

Карта сохранена:

{
  "type": "bank_card",
  "id": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
  "saved": true,
  "status": "active",
  "title": "Bank card *4444",
  "card": {
    "first6": "220220",
    "last4": "4444",
    "expiry_month": "07",
    "expiry_year": "2030",
    "card_type": "Mir",
    "issuer_country": "RU",
    "issuer_name": "Sberbank"
  },
  "holder": {
    "account_id": "33661"
  },
  "metadata": {
    "customer_id": "1042"
  }
}

Создать способ оплаты​

POSThttps://api.avantpay.io/v3/payment_methods

Создаёт способ оплаты — банковскую карту — без платежа и возвращает объект способа оплаты в статусе pending со ссылкой confirmation.confirmation_url. Перенаправьте покупателя по ссылке: он подтвердит карту, на ней заблокируется и сразу вернётся 1 ₽. Когда карта сохранится, статус станет active и придёт уведомление payment_method.active. Ссылка действует 1 час.

к сведению

Автоплатежи и сохранение карты без платежа включает поддержка AvantPay по письму на support@avantpay.io. Без этого API ответит 403 forbidden.

Заголовки​

Все три заголовка обязательны.

ЗаголовокЗначение
AuthorizationHTTP Basic: ID магазина и секретный ключ. В cURL — параметр -u со значением "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY".
Idempotence-KeyКлюч идемпотентности: уникальная строка до 64 символов. Подробнее
Content-Typeapplication/json

Параметры запроса​

requiredtype
string

Значение — bank_card. СБП без платежа не сохраняется: создайте платёж с save_payment_method: true.

requiredconfirmation
object

Сценарий подтверждения: покупатель переходит по ссылке и подтверждает карту, на ней блокируется и сразу возвращается 1 ₽.

Вложенные параметры
requiredtype
string

Значение — redirect.

requiredreturn_url
string

Куда вернуть покупателя после подтверждения. Адрес http:// или https://, до 2048 символов.

optionalmetadata
object

Ваши данные к способу оплаты: до 16 ключей, имя ключа до 32 символов, значение — строка до 512 символов. Вернутся в объекте способа оплаты.

Ответ​

В ответ на запрос придёт объект способа оплаты в статусе pending.

Пример запроса

curl https://api.avantpay.io/v3/payment_methods \
  -X POST \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY" \
  -H "Idempotence-Key: 3c6e9a1f-2b4d-4f8a-9c7e-5d1b3a2f4e6c" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_card",
    "confirmation": {
      "type": "redirect",
      "return_url": "https://example.com/account/cards"
    },
    "metadata": {
      "customer_id": "1042"
    }
  }'

Пример ответа

Способ оплаты ждёт подтверждения покупателем

Content typeapplication/json
{
  "type": "bank_card",
  "id": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
  "saved": false,
  "status": "pending",
  "holder": {
    "account_id": "33661"
  },
  "metadata": {
    "customer_id": "1042"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://avantpay.io/checkout/bind?paymentMethodId=9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
    "return_url": "https://example.com/account/cards"
  }
}

Ошибки​

Формат ошибок и общие коды — в разделе Ошибки. Ошибки этого метода:

HTTPcodeparameterКогдаЧто делать
400invalid_requestIdempotence-KeyНет ключа, ключ длиннее 64 символов или уже использован с другим телом запроса.Передать новый ключ до 64 символов.
400invalid_requesttypeНет type, значение не bank_card или у магазина нет карты, которую можно сохранить.Передать bank_card. Если ошибка повторяется — написать в поддержку: support@avantpay.io.
400not_supportedtypetype равен sbp.Сохранить СБП платежом с save_payment_method: true.
400not_supportedcardПереданы данные карты.Убрать card: покупатель вводит карту на странице по confirmation_url.
400invalid_requestconfirmation, confirmation.type, confirmation.return_urlНет confirmation, type не redirect или return_url — не адрес http:// или https://.Передать confirmation с type redirect и адресом возврата.
400invalid_requestmetadatametadata — не объект, больше 16 ключей, длинное имя ключа или значение.Привести к правилам из раздела metadata.
401invalid_credentialsAuthorizationНеверный ID магазина или ключ.Проверить ключи.
403forbidden—Автоплатежи или сохранение карты без платежа не включены, у ключа нет права «Платежи» или магазин не активен.Написать в поддержку: support@avantpay.io.
429too_many_requests—Больше 50 запросов в секунду.Повторить через retry_after миллисекунд с тем же ключом.
500internal_server_error—Сбой у AvantPay.Повторить с тем же ключом и тем же телом.

Получить способ оплаты​

GEThttps://api.avantpay.io/v3/payment_methods/{payment_method_id}

Возвращает объект способа оплаты в текущем состоянии.

Параметры пути​

requiredpayment_method_id
string

ID способа оплаты: payment_method.id из платежа или id из ответа на создание способа.

Ответ​

В ответ на запрос придёт объект способа оплаты в актуальном статусе.

Пример запроса

curl https://api.avantpay.io/v3/payment_methods/9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY"

Пример ответа

Карта сохранена

Content typeapplication/json
{
  "type": "bank_card",
  "id": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
  "saved": true,
  "status": "active",
  "title": "Bank card *4444",
  "card": {
    "first6": "220220",
    "last4": "4444",
    "expiry_month": "07",
    "expiry_year": "2030",
    "card_type": "Mir",
    "issuer_country": "RU",
    "issuer_name": "Sberbank"
  },
  "holder": {
    "account_id": "33661"
  },
  "metadata": {
    "customer_id": "1042"
  }
}

Ошибки​

HTTPcodeКогдаЧто делать
404not_foundСпособа оплаты с таким id нет у вашего магазина. parameter — payment_method_id.Проверить id.
401invalid_credentialsНеверный ID магазина или ключ.Проверить ключи.
403forbiddenМагазин не активен.Написать в поддержку: support@avantpay.io.
429too_many_requestsБольше 50 запросов в секунду.Повторить через retry_after миллисекунд.
500internal_server_errorСбой у AvantPay.Повторить запрос позже.

Объект возврата​

Объект возврата (Refund) содержит всю информацию о возврате, актуальную на текущий момент времени. Он формируется при создании возврата и приходит в ответ на любой запрос, связанный с возвратами. Как сделать возврат — на странице Возвраты.

Объект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.

Поля​

requiredid
string

ID возврата, UUID из 36 символов. Сохраните его: по нему вы узнаете, чем кончился возврат.

requiredpayment_id
string

ID платежа, по которому сделан возврат.

requiredstatus
string

Статус возврата: pending, succeeded или canceled. Что значит каждый — в разделе Статусы возврата.

optionalcancellation_details
object

Кто отменил возврат и почему. Бывает только у возвратов со статусом canceled.

Вложенные параметры
requiredparty
string

Кто отменил: avantpay или refund_network. Что значит каждое — в разделе Кто отменил возврат.

requiredreason
string

Причина отмены: insufficient_funds или general_decline. Что делать — в разделе Кто отменил возврат.

requiredcreated_at
string

Когда возврат создан. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-19T09:40:12.305Z.

requiredamount
object

Сумма возврата — та, что вы передали при создании. В валюте платежа.

Вложенные параметры
requiredvalue
string

Сумма строкой с двумя знаками после точки.

Пример: "300.00"
requiredcurrency
string

Валюта: RUB.

optionaldescription
string

Комментарий, который вы передали при создании. Есть, только если вы его передали.

requiredmetadata
object

Ваши произвольные данные из запроса на создание возврата. Значения — строки. Если вы их не передали или возврат сделан в личном кабинете — пустой объект {}.

Статусы возврата​

statusЧто значитЧто делать магазину
pendingВозврат создан и выполняется. Покупатель ещё не получил деньги.Ждать уведомления refund.succeeded или запросить возврат позже.
succeededВозврат выполнен: деньги отправлены покупателю. Статус больше не меняется.Отметить в заказе, что деньги вернули.
canceledВозврат не выполнен: покупатель денег не получил, сумма возврата осталась на счёте магазина или вернулась на него. Статус больше не меняется. Причина — в cancellation_details.Смотреть по причине — в разделе Кто отменил возврат.

Обычно возврат становится succeeded или canceled через несколько секунд или минут. Уведомление приходит только о выполненном возврате — refund.succeeded. Уведомления об отмене нет: отмену видно в ответе на GET /v3/refunds/{refund_id}.

Если возврат в pending дольше часа, напишите в поддержку: support@avantpay.io, укажите id возврата. Не считайте его отменённым и не создавайте новый: API не примет новый возврат по этому платежу, пока этот не завершится.

Кто отменил возврат​

У возврата со статусом canceled есть поле cancellation_details с полями party и reason.

partyКто
avantpayAvantPay: на счёте магазина не хватило денег, возврат остановила проверка или его не удалось отправить.
refund_networkБанк или платёжная система, через которые идёт возврат: они отклонили возврат. Сумма вернётся на счёт магазина, но до 3 дней может быть в резерве.
reasonЧто случилосьЧто делать
insufficient_fundsУ avantpay — на счёте магазина не хватило денег на возврат. У refund_network — так ответил банк или платёжная система.У avantpay — дождаться, когда на счёте будет нужная сумма, и создать новый возврат с новым ключом идемпотентности. Остаток счёта виден в личном кабинете на странице «Обзор», через API его не узнать. У refund_network — написать в поддержку.
general_declineПричина не уточняется.Написать в поддержку: support@avantpay.io, указать id возврата.

Если придёт значение, которого нет в таблице, обработайте его как general_decline.

Покупателю вернули 300 ₽ из 1000 ₽:

{
  "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
  "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
  "status": "succeeded",
  "created_at": "2026-10-19T09:40:12.305Z",
  "amount": {
    "value": "300.00",
    "currency": "RUB"
  },
  "description": "Возврат по заказу №123",
  "metadata": {
    "order_id": "123"
  }
}

Создать возврат​

POSThttps://api.avantpay.io/v3/refunds

Создаёт возврат по оплаченному платежу и возвращает объект возврата. У нового возврата статус pending. Можно вернуть всю сумму платежа или часть. Деньги вернутся покупателю тем же способом, которым он платил.

к сведению

Для возвратов у ключа должно быть включено право «Возвраты». По умолчанию оно выключено: его включает поддержка AvantPay по письму на support@avantpay.io. Без права API ответит 403 forbidden.

Заголовки​

Все три заголовка обязательны.

ЗаголовокЗначение
AuthorizationHTTP Basic: ID магазина и секретный ключ. В cURL — параметр -u со значением "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY".
Idempotence-KeyКлюч идемпотентности: уникальная строка до 64 символов. Один ключ — один возврат: новый для каждого возврата, тот же при повторе запроса. Подробнее
Content-Typeapplication/json

Параметры запроса​

requiredpayment_id
string

id платежа, который нужно вернуть, — 36 символов. Платёж вашего магазина в статусе succeeded: проверьте, что у него refundable равен true.

requiredamount
object

Сумма возврата: вся сумма платежа или часть. Со счёта магазина спишется вся эта сумма.

Вложенные параметры
requiredvalue
string

Сумма строкой, рубли и копейки через точку, не больше двух знаков после точки. Не больше остатка — суммы платежа минус уже возвращённое. Не меньше 1 ₽: меньше можно вернуть, только если это весь остаток.

Пример: "300.00"
requiredcurrency
string

Валюта платежа: RUB.

optionaldescription
string

Комментарий к возврату, до 250 символов. Вернётся в объекте возврата.

optionalmetadata
object

Ваши произвольные данные к возврату. Правила — как у metadata платежа, но email не нужен: до 16 ключей, имя ключа до 32 символов, значение — строка до 512 символов. Вернутся в объекте возврата и в уведомлении refund.succeeded. Подробнее — в разделе metadata.

Правила возврата​

  • Вернуть можно только оплаченный платёж — в статусе succeeded. Проверьте заранее, что у платежа refundable равен true.
  • Деньги вернутся тем же способом, которым платил покупатель. Выбрать другой способ нельзя.
  • Частичных возвратов по одному платежу может быть несколько, пока не вернули всю сумму. Всего — не больше 10 возвратов на платёж, отменённые не считаются.
  • Минимальная сумма возврата — 1 ₽. Меньше можно вернуть, только если это весь остаток платежа.
  • По платежу одновременно выполняется только один возврат. Следующий создавайте, когда прежний стал succeeded или canceled. Пока прежний в статусе pending, API ответит 400.
  • Со счёта магазина спишется вся сумма возврата. Комиссия AvantPay за платёж не возвращается.
  • Если на счёте магазина не хватит денег, API всё равно ответит 200 и создаст возврат. Потом возврат перейдёт в canceled с причиной insufficient_funds.

Ответ​

В ответ на запрос придёт объект возврата в актуальном статусе.

Пример запроса

curl https://api.avantpay.io/v3/refunds \
  -X POST \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY" \
  -H "Idempotence-Key: refund-123-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
    "amount": {
      "value": "300.00",
      "currency": "RUB"
    },
    "description": "Возврат по заказу №123",
    "metadata": {
      "order_id": "123"
    }
  }'

Пример ответа

Новый возврат в статусе pending

Content typeapplication/json
{
  "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
  "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
  "status": "pending",
  "created_at": "2026-10-19T09:40:12.305Z",
  "amount": {
    "value": "300.00",
    "currency": "RUB"
  },
  "description": "Возврат по заказу №123",
  "metadata": {
    "order_id": "123"
  }
}

Ошибки​

Формат ошибок и общие коды — в разделе Ошибки. Ошибки этого метода:

HTTPcodeparameterКогдаЧто делать
400invalid_requestIdempotence-KeyНет ключа, ключ длиннее 64 символов или переданы Idempotence-Key и Idempotency-Key с разными значениями.Передать один ключ до 64 символов.
400invalid_requestIdempotence-KeyКлюч уже использован с другим телом запроса. Значит, возврат с этим ключом уже создан.Не создавать новый возврат, пока не найдёте этот в списке возвратов по payment_id. Новый ключ — только если вы по ошибке взяли этот ключ для другого возврата.
400invalid_requestpayment_idНет payment_id или в нём не 36 символов.Передать id платежа.
400invalid_requestpayment_idПлатёж не оплачен: его статус pending или canceled.Вернуть можно только платёж в статусе succeeded.
400invalid_requestpayment_idПо платежу уже выполняется возврат.Дождаться, когда он станет succeeded или canceled, и создать следующий возврат с новым ключом.
400invalid_requestpayment_idПлатёж уже возвращён полностью.Ничего: возвращать больше нечего.
400invalid_requestpayment_idПо платежу уже 10 возвратов.Написать в поддержку: support@avantpay.io.
400invalid_requestpayment_idПлатёж нельзя вернуть через API: способ оплаты не поддерживает возвраты, платёж проверяет AvantPay или он не зачислен на счёт магазина.Написать в поддержку: support@avantpay.io.
400invalid_requestamount, amount.valueНет суммы, сумма не число, больше двух знаков после точки, не больше нуля, больше остатка платежа (остаток — в description) или меньше 1 ₽, но не весь остаток.Исправить сумму.
400invalid_requestamount.currencyНет валюты, это не код валюты или она не совпадает с валютой платежа.Передать "RUB".
400invalid_requestdescriptionДлиннее 250 символов или не строка.Сократить комментарий.
400invalid_requestmetadatametadata — не объект, больше 16 ключей, длинное имя ключа или значение, значение — массив или объект.Привести к правилам из раздела metadata.
400not_supportedимя поляПередано поле receipt, sources, deal или refund_method_data с непустым значением.Убрать поле: деньги возвращаются тем же способом оплаты, чеки AvantPay не отправляет.
400invalid_request—Тело запроса — не JSON.Передать правильный JSON.
401invalid_credentialsAuthorizationНеверный ID магазина или ключ.Проверить ключи.
403forbidden—У ключа нет права «Возвраты».Написать в поддержку: support@avantpay.io.
403forbidden—Возвраты разрешены только с IP-адресов из списка ключа, а запрос пришёл с другого.Отправлять запрос с сервера, IP-адрес которого есть в списке, или попросить поддержку добавить адрес.
403forbidden—Магазин не активен.Написать в поддержку: support@avantpay.io.
404not_foundpayment_idПлатежа с таким id нет у вашего магазина.Проверить id платежа.
413invalid_request—Тело запроса больше 5 МБ.Уменьшить тело.
415invalid_request—Нет заголовка Content-Type: application/json.Передать заголовок.
429too_many_requests—Больше 50 запросов в секунду или у магазина уже 20 возвратов в статусе pending.Подождать retry_after миллисекунд и повторить с тем же ключом.
500internal_server_error—Сбой у AvantPay. Возврат мог создаться.Повторить с тем же ключом и тем же телом.

Если ответа нет совсем (таймаут, обрыв связи), поступите так же, как при ответе 500: повторите запрос с тем же Idempotence-Key и тем же телом.

Если это повтор после таймаута или ответа 500 и пришла ошибка 400, 401 или 403, ключ не меняйте: возврат мог создаться первым запросом. Исправьте причину и повторите с тем же ключом (подробнее).

Отказы по платежу — ошибки 400 с "parameter": "payment_id" — отличаются только текстом description. Не разбирайте этот текст в коде: покажите его сотруднику или запишите в лог. Чтобы понять причину в коде, запросите платёж GET /v3/payments/{payment_id}:

  • status не succeeded — платёж не оплачен;
  • refunded_amount.value равен amount.value — платёж возвращён полностью;
  • запрос GET /v3/refunds?payment_id=<id платежа>&status=pending вернул возврат — по платежу идёт возврат: дождитесь его итога;
  • иначе, если refundable равен false, — вернуть платёж можно только через поддержку: support@avantpay.io.

Получить возврат​

GEThttps://api.avantpay.io/v3/refunds/{refund_id}

Возвращает объект возврата в текущем состоянии.

Параметры пути​

requiredrefund_id
string

id возврата из ответа на его создание или из списка возвратов.

Ответ​

В ответ на запрос придёт объект возврата в актуальном статусе.

Пример запроса

curl https://api.avantpay.io/v3/refunds/5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87 \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY"

Пример ответа

Content typeapplication/json
{
  "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
  "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
  "status": "succeeded",
  "created_at": "2026-10-19T09:40:12.305Z",
  "amount": {
    "value": "300.00",
    "currency": "RUB"
  },
  "description": "Возврат по заказу №123",
  "metadata": {
    "order_id": "123"
  }
}

Ошибки​

HTTPcodeКогдаЧто делать
404not_foundВозврата с таким id нет у вашего магазина. Возврат другого магазина тоже даёт 404. parameter — refund_id.Проверить id.
401invalid_credentialsНеверный ID магазина или ключ.Проверить ключи.
403forbiddenМагазин не активен.Написать в поддержку: support@avantpay.io.
429too_many_requestsБольше 50 запросов в секунду.Повторить через retry_after миллисекунд.
500internal_server_errorСбой у AvantPay.Повторить запрос позже.

Список возвратов​

GEThttps://api.avantpay.io/v3/refunds

Возвращает возвраты вашего магазина от новых к старым: и созданные через API, и сделанные в личном кабинете. Можно отфильтровать по платежу, статусу и дате создания. Список отдаётся страницами. Заголовок Idempotence-Key этому методу не нужен. Тела у запроса нет.

Параметры запроса​

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

optionallimit
integer

Сколько возвратов на странице: от 1 до 100. По умолчанию 10.

optionalcursor
string

Значение next_cursor из предыдущего ответа — чтобы получить следующую страницу. Передавайте как есть.

optionalpayment_id
string

Только возвраты этого платежа: его id.

optionalstatus
string

Только возвраты с этим статусом: pending, succeeded или canceled.

optionalcreated_at.gte
string

Созданы в этот момент или позже. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-01T00:00:00.000Z.

optionalcreated_at.gt
string

Созданы позже этого момента. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-01T00:00:00.000Z.

optionalcreated_at.lte
string

Созданы в этот момент или раньше. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-10-31T23:59:59.999Z.

optionalcreated_at.lt
string

Созданы раньше этого момента. Указывается по UTC и передаётся в формате ISO 8601. Пример: 2026-11-01T00:00:00.000Z.

Ответ​

В ответ на запрос придёт объект списка: возвраты в items — объекты возврата в актуальном статусе.

requiredtype
string

Всегда list.

requireditems
array

Возвраты — объекты возврата, от новых к старым. Если ничего не нашлось — пустой массив [].

optionalnext_cursor
string

Курсор следующей страницы. Нет на последней странице.

Как получить все страницы​

  1. Отправьте запрос с нужными фильтрами.
  2. Если в ответе есть next_cursor, повторите запрос с теми же фильтрами и параметром cursor=<значение next_cursor>.
  3. Повторяйте, пока в ответе не будет next_cursor.

Новые возвраты, пока вы получаете страницы, порядок не сдвигают. Примеры на Python, Node.js и PHP получают все страницы сами.

Пример запроса

Все возвраты по платежу

curl "https://api.avantpay.io/v3/refunds?payment_id=c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60&limit=10" \
  -u "$AVANTPAY_SHOP_ID:$AVANTPAY_SECRET_KEY"

Пример ответа

Content typeapplication/json
{
  "type": "list",
  "items": [
    {
      "id": "a3c9e7b1-2d4f-4e6a-9b8c-1f0e2d3c4b5a",
      "payment_id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
      "status": "canceled",
      "cancellation_details": {
        "party": "avantpay",
        "reason": "insufficient_funds"
      },
      "created_at": "2026-10-18T08:12:44.019Z",
      "amount": {
        "value": "100.00",
        "currency": "RUB"
      },
      "metadata": {}
    },
    {
      "id": "9d4b2e6f-1a3c-4d5e-8f7a-6b5c4d3e2f10",
      "payment_id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
      "status": "succeeded",
      "created_at": "2026-10-17T19:05:31.642Z",
      "amount": {
        "value": "50.00",
        "currency": "RUB"
      },
      "description": "Возврат по заказу №122",
      "metadata": {
        "order_id": "122"
      }
    }
  ]
}

Ошибки​

HTTPcodeКогдаЧто делать
400invalid_requestlimit — не целое число от 1 до 100, cursor — не из next_cursor, дата не в формате ISO 8601, status — незнакомое значение, параметр передан дважды. Имя параметра — в parameter.Исправить параметр.
401invalid_credentialsНеверный ID магазина или ключ.Проверить ключи.
403forbiddenМагазин не активен.Написать в поддержку: support@avantpay.io.
429too_many_requestsБольше 50 запросов в секунду.Повторить через retry_after миллисекунд.
500internal_server_errorСбой у AvantPay.Повторить запрос позже.

Объект уведомления​

Уведомление — POST-запрос от AvantPay на ваш сервер о событии (Уведомления).

Запрос приходит с заголовком Content-Type: application/json и телом из трёх полей:

requiredtype
string

Всегда notification.

requiredevent
string

Событие: payment.succeeded, payment.canceled или refund.succeeded.

requiredobject
object

Объект на момент события. У payment.succeeded и payment.canceled — объект платежа, как в ответе на GET /v3/payments/{payment_id}. У refund.succeeded — объект возврата, как в ответе на GET /v3/refunds/{refund_id}.

События​

payment.succeeded, payment.canceled, refund.succeeded, payment_method.active — когда приходит каждое, на странице Уведомления. Уведомления об отмене возврата нет.

Заголовки​

ЗаголовокЧто в нём
Signature-TimestampВремя отправки, Unix-время в секундах.
SignatureПодпись: v1= и HMAC-SHA256 строки <Signature-Timestamp>.<тело запроса> секретным ключом API в шестнадцатеричном виде. Как проверить — в разделе Подпись.

Ответьте кодом 200 не позже чем через 10 секунд. Иначе AvantPay повторит уведомление (расписание повторов).

Платёж отменён: покупатель не заплатил вовремя.

{
  "type": "notification",
  "event": "payment.canceled",
  "object": {
    "id": "8d0e4b52-7c19-4a6e-b3f1-5e2a9c7d1b40",
    "status": "canceled",
    "paid": false,
    "amount": {
      "value": "500.00",
      "currency": "RUB"
    },
    "description": "Заказ №125",
    "recipient": {
      "account_id": "33661"
    },
    "created_at": "2026-10-18T12:00:00.000Z",
    "expires_at": "2026-10-18T12:20:00.000Z",
    "confirmation": {
      "type": "redirect",
      "confirmation_url": "https://avantpay.io/checkout?paymentId=8d0e4b52-7c19-4a6e-b3f1-5e2a9c7d1b40",
      "return_url": "https://example.com/orders/125"
    },
    "test": false,
    "refundable": false,
    "metadata": {
      "email": "buyer@example.com",
      "order_id": "125"
    },
    "cancellation_details": {
      "party": "avantpay",
      "reason": "expired_on_confirmation"
    }
  }
}

Заголовки запроса:

POST /avantpay/webhook HTTP/1.1
Host: example.com
Content-Type: application/json
Signature-Timestamp: 1792324800
Signature: v1=07181d18b6de6cfe0c882fd02f7e40c8c0e735f19dc67062c39f57c8d75c995b

Возврат выполнен:

{
  "type": "notification",
  "event": "refund.succeeded",
  "object": {
    "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
    "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
    "status": "succeeded",
    "created_at": "2026-10-19T09:40:12.305Z",
    "amount": {
      "value": "300.00",
      "currency": "RUB"
    },
    "description": "Возврат по заказу №123",
    "metadata": {
      "order_id": "123"
    }
  }
}

Пример уведомления payment.succeeded — в быстром старте.