К документации
Войти

Документация Aeris API

Справочник по авторизации, созданию платежей и выплат, webhook-уведомлениям и проверке статусов.

Скачать Postman-документацию

Основные разделы

Базовый URL
https://aeris-psp.net
Формат данных
application/json

Первый платёж

Пройдите путь от настройки доступа до подтверждённого заказа. Примеры используют демонстрационные данные; отправка с production-ключом создаёт реальную операцию.

Перед началом

  • Получите проект и пару public_key / secret_key. Для проверки используйте отдельный тестовый проект.
  • Добавьте исходящий IP вашего backend в список API IP. Для виджета отдельно разрешите домен сайта.
  • Подготовьте HTTPS-обработчик webhook и страницы возврата. Секретный ключ храните только на backend.
Путь платежа
Обычный платёж СБП через окно Aeris: создать → получить ссылку → открыть оплату → проверить результат.
Выберите, кто управляет оплатой

Как устроена интеграция

Выберите, кто управляет оплатой

Платёжное окно
Aeris показывает форму, QR и банковские кнопки. Вы открываете payment_url или встраиваете виджет.
Host-to-Host
Ваш интерфейс получает прямую ссылку или next_action. Обработку переходов и 3DS реализуете вы.
Общее окно
Покупатель выбирает СБП или SberPay. Ответ с checkout_id описывает сессию выбора; это не подтверждённый платёж.
merchant_order_id
Ваш уникальный номер заказа. Нужен для сопоставления операции и безопасной проверки после потери ответа.
id
Идентификатор транзакции Aeris. Сохраните из ответа и используйте в запросе статуса.
project_url
Адрес сайта или Telegram-бота, для которого создан заказ. Не адрес webhook и не страница возврата.
callback_url
Backend-обработчик уведомления. Входящий запрос от Aeris, а не переход покупателя.
redirect_url_success
Страница возврата покупателя после успешного сценария. Не является подтверждением зачисления.

API-ключи

Основной ключ создаётся вместе с проектом. В кабинете можно выпустить до четырёх дополнительных ключей. Там же задаются адрес для уведомлений, IP/CIDR серверов и HTTPS-домены виджета. Просмотр ключей и сохранение изменений подтверждаются через Telegram или приложение-аутентификатор.

Dashboard
Settings → API keys
Primary key + up to 4 additional keys

Settings → Webhook and access
Webhook URL → default notification endpoint
API IP → server addresses
Checkout origins → website domains

Авторизация

Каждый запрос подписывается HMAC-SHA256. Timestamp передаётся в Unix-секундах и действует в коротком временном окне. JSON сериализуйте компактно, без пробелов. Для GET не отправляйте HTTP-тело, но в подпись включайте {}.

HMAC-SHA256 · API
body = compact_json_ascii(request_body)  # GET: "{}"
message = body + ":" + unix_timestamp + "++"
signature = hex(hmac_sha256(base64(secret_key), message))

X-API-KEY: <public_key>
X-TIMESTAMP: <unix_seconds>
X-SIGNATURE: <signature>
  • Для POST подпишите компактное JSON-тело с ASCII-экранированием Unicode (\uXXXX), как json.dumps(..., separators=(",", ":"), ensure_ascii=True). Для GET не отправляйте HTTP-тело, но используйте строку {} при вычислении подписи.
  • base64(secret_key) означает Base64-кодирование UTF-8 строки секрета, не декодирование. Timestamp — Unix-секунды, не миллисекунды.
  • Для исходящего API-запроса используйте согласованную пару ключей: основной или выпущенный дополнительный. Не смешивайте public_key одной пары с secret_key другой.
Создать платёжСБП, SberPay и банковские карты

Платёжное окно

Aeris показывает покупателю готовую страницу оплаты.

H2H

Ваш backend получает прямую ссылку или next_action и сам управляет интерфейсом.

Платёжное окно

СБП + SberPay

Одно платёжное окно с доступными покупателю способами. Платёж создаётся после выбора способа.

Когда выбиратьОсновной checkout, когда способ оплаты выбирает покупатель.
Путь платежа
Выберите шаг, чтобы открыть пояснение и пример.

Платёжная форма Aeris

Заказ 10001

Оплата заказа

Demo Store

9 000 ₽

Результат появится на этой странице

Иллюстрация интерфейса. Демонстрационные данные, не действующая платёжная ссылка.

    Рекуррентные платежи СБП

    Подписка хранит согласованную сумму и период. Инициатор — Aeris по расписанию или ваш backend; правила списания и история начислений одинаковые.

    Все пути ниже начинаются с /api/v1/merchant. Подписывайте запросы как обычные платежи. GET /recurring/capabilities возвращает доступные методы и состояние списаний.

    Путь платежа
    Выберите шаг, чтобы открыть пояснение и пример.

    Управление и ограничения

    Одно начисление за период и одно незавершённое списание. Не более трёх отправленных попыток за 24 часа, с промежутком минимум час; повтор допускается только после подтверждённого отказа. Таймаут не освобождает ограничение. Пропущенные периоды не догоняются. Отключение списаний останавливает и API, и планировщик, но не сверку отправленных платежей.

    Для изменения или остановки укажите текущий expected_version. Превышение согласованной цены, изменение периода или продление согласованного срока требуют нового подтверждения. Смена initiator не сбрасывает историю и лимиты. Пауза и отмена не возвращают деньги и не отменяют уже отправленный платёж.

    POST /api/v1/merchant/recurring/subscriptions/action
    {
  "subscription_id": "e5a0c035-bef2-48a5-b59b-035cbd877eaf",
  "expected_version": 2,
  "action": "pause"
}
    HTTP 200 · application/json
    {
  "id": "e5a0c035-bef2-48a5-b59b-035cbd877eaf",
  "merchant_subscription_id": "subscription-10001",
  "customer_id": "customer-10001",
  "name": "Monthly access",
  "payment_token": "938b3f2e-5927-4b4e-85d1-1a4b7e0c9040",
  "plan_id": null,
  "terms": {
    "amount": 990,
    "currency": "RUB",
    "interval": "month",
    "period": 1,
    "start_at": "2030-01-31T10:00:00+03:00",
    "timezone": "Europe/Moscow",
    "end_at": null,
    "max_payments": 12,
    "customer_fee_percent": "0",
    "retry_policy": {
      "retry_delays_seconds": [
        3600,
        86400
      ],
      "on_exhausted": "pause"
    }
  },
  "status": "paused",
  "reason": "merchant_request",
  "version": 3,
  "paid_cycles": 0,
  "initiator": "merchant",
  "confirmation_url": null,
  "next_payment_at": null,
  "cancel_at": null,
  "project_url": "https://merchant.example",
  "consent_reference": "consent-10001",
  "created_at": "2029-12-31T10:00:00+00:00",
  "preview": [
    {
      "cycle_number": 0,
      "payment_at": "2030-01-31T07:00:00+00:00",
      "amount": 990,
      "currency": "RUB"
    },
    {
      "cycle_number": 1,
      "payment_at": "2030-02-28T07:00:00+00:00",
      "amount": 990,
      "currency": "RUB"
    },
    {
      "cycle_number": 2,
      "payment_at": "2030-03-31T07:00:00+00:00",
      "amount": 990,
      "currency": "RUB"
    }
  ]
}

    Подписка с первым платёжным запросом

    Можно добавить save_payment_method и recurring к POST /payins/sbp. payment_url ведёт на подтверждение условий в Aeris, а subscription содержит идентификатор подписки. Для скидки на первую оплату передайте её итоговую сумму в amount, а обычную цену — в recurring.amount.

    Запрос и код
    POST /api/v1/merchant/payins/sbp
    # Set PUBLIC_KEY and SECRET_KEY in your environment first.
: "${PUBLIC_KEY:?Set PUBLIC_KEY}"
: "${SECRET_KEY:?Set SECRET_KEY}"
BODY='{"amount":100,"currency":"RUB","merchant_order_id":"recurring-first-10001","payer_ip":"203.0.113.10","project_url":"https://merchant.example","callback_url":"https://merchant.example/webhooks/payment","redirect_url_success":"https://merchant.example/payment/success","save_payment_method":true,"customer_id":"customer-10001","consent_granted":true,"consent_reference":"consent-10001","subscription_purpose":"Monthly access","payer_phone":"+79991234567","recurring":{"amount":990,"currency":"RUB","interval":"month","period":1,"start_at":"2030-01-31T10:00:00+03:00","timezone":"Europe/Moscow","max_payments":12,"customer_fee_percent":0,"retry_policy":{"retry_delays_seconds":[3600,86400],"on_exhausted":"pause"},"merchant_subscription_id":"subscription-first-10001"}}'
TIMESTAMP=$(date +%s)
HMAC_KEY=$(printf '%s' "$SECRET_KEY" | openssl base64 -A)
SIGNATURE=$(printf '%s' "$BODY:$TIMESTAMP++" | openssl dgst -sha256 -hmac "$HMAC_KEY" -r | cut -d ' ' -f 1)

curl --fail-with-body --request POST \
  "https://aeris-psp.net/api/v1/merchant/payins/sbp" \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: $PUBLIC_KEY" \
  --header "X-TIMESTAMP: $TIMESTAMP" \
  --header "X-SIGNATURE: $SIGNATURE" \
  --data-raw "$BODY"
    HTTP 200 · application/json
    {
  "id": "5ce82d35-c78e-4181-b39b-e004421952ef",
  "merchant_order_id": "recurring-first-10001",
  "amount": 100,
  "order_amount": 100,
  "customer_fee_amount": 0,
  "status": "pending",
  "currency": "RUB",
  "payment_method": "sbp",
  "payment_url": "https://aeris-psp.net/checkout?session=RESPONSE_SESSION",
  "next_action": null,
  "payment_token": "938b3f2e-5927-4b4e-85d1-1a4b7e0c9040",
  "payment_token_status": "pending",
  "subscription": {
    "id": "e5a0c035-bef2-48a5-b59b-035cbd877eaf",
    "merchant_subscription_id": "subscription-first-10001",
    "customer_id": "customer-10001",
    "name": "",
    "payment_token": "938b3f2e-5927-4b4e-85d1-1a4b7e0c9040",
    "plan_id": null,
    "terms": {
      "amount": 990,
      "currency": "RUB",
      "interval": "month",
      "period": 1,
      "start_at": "2030-01-31T10:00:00+03:00",
      "timezone": "Europe/Moscow",
      "end_at": null,
      "max_payments": 12,
      "customer_fee_percent": "0",
      "retry_policy": {
        "retry_delays_seconds": [
          3600,
          86400
        ],
        "on_exhausted": "pause"
      }
    },
    "status": "awaiting_confirmation",
    "reason": "",
    "version": 1,
    "paid_cycles": 0,
    "initiator": "aeris",
    "confirmation_url": "https://aeris-psp.net/checkout?session=RESPONSE_SESSION",
    "next_payment_at": null,
    "cancel_at": null,
    "project_url": "https://merchant.example",
    "consent_reference": "consent-10001",
    "created_at": "2029-12-31T10:00:00+00:00",
    "preview": [
      {
        "cycle_number": 0,
        "payment_at": "2030-01-31T07:00:00+00:00",
        "amount": 990,
        "currency": "RUB"
      },
      {
        "cycle_number": 1,
        "payment_at": "2030-02-28T07:00:00+00:00",
        "amount": 990,
        "currency": "RUB"
      },
      {
        "cycle_number": 2,
        "payment_at": "2030-03-31T07:00:00+00:00",
        "amount": 990,
        "currency": "RUB"
      }
    ]
  }
}

    H2H без окна Aeris

    Доступен после отдельного одобрения Aeris и принятия условий. В POST /recurring/subscriptions передайте confirmation_mode: merchant, явный consent_granted: true и consent_evidence. consent_reference идентифицирует ваш архив согласия; document_sha256 — SHA-256 полного документа условий, а не произвольная строка. accepted_at — исходное время согласия с часовым поясом; при повторе запроса не меняйте его. Без допуска вернётся HTTP 403.

    Покажите покупателю точные суммы, период и срок в своём интерфейсе. Ответ содержит initial_payment_url для первой банковской оплаты и confirmation_url: null. Согласие мерчанта само по себе не активирует подписку: нужны успешная первая оплата СБП и активная привязка. По запросу предоставьте исходные подтверждения согласия на заявленный тариф в течение 24 часов; исключения и последствия определены принятыми условиями.

    Условия рекуррентных платежей

    Запрос и код
    POST /api/v1/merchant/recurring/subscriptions
    # Set PUBLIC_KEY and SECRET_KEY in your environment first.
: "${PUBLIC_KEY:?Set PUBLIC_KEY}"
: "${SECRET_KEY:?Set SECRET_KEY}"
BODY='{"merchant_subscription_id":"subscription-10001","name":"Monthly access","initiator":"merchant","initial_amount":1,"customer_id":"customer-10001","terms":{"amount":990,"currency":"RUB","interval":"month","period":1,"start_at":"2030-01-31T10:00:00+03:00","timezone":"Europe/Moscow","max_payments":12,"customer_fee_percent":0,"retry_policy":{"retry_delays_seconds":[3600,86400],"on_exhausted":"pause"}},"consent_granted":true,"consent_reference":"consent-10001","payer_ip":"203.0.113.10","payer_phone":"+79991234567","project_url":"https://merchant.example","callback_url":"https://merchant.example/webhooks/payment","confirmation_mode":"merchant","consent_evidence":{"accepted_at":"2026-10-19T10:00:00+03:00","document_version":"tariff-1","document_sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}'
TIMESTAMP=$(date +%s)
HMAC_KEY=$(printf '%s' "$SECRET_KEY" | openssl base64 -A)
SIGNATURE=$(printf '%s' "$BODY:$TIMESTAMP++" | openssl dgst -sha256 -hmac "$HMAC_KEY" -r | cut -d ' ' -f 1)

curl --fail-with-body --request POST \
  "https://aeris-psp.net/api/v1/merchant/recurring/subscriptions" \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: $PUBLIC_KEY" \
  --header "X-TIMESTAMP: $TIMESTAMP" \
  --header "X-SIGNATURE: $SIGNATURE" \
  --data-raw "$BODY"
    HTTP 200 · application/json
    {
  "id": "e5a0c035-bef2-48a5-b59b-035cbd877eaf",
  "merchant_subscription_id": "subscription-10001",
  "customer_id": "customer-10001",
  "name": "Monthly access",
  "payment_token": "938b3f2e-5927-4b4e-85d1-1a4b7e0c9040",
  "plan_id": null,
  "terms": {
    "amount": 990,
    "currency": "RUB",
    "interval": "month",
    "period": 1,
    "start_at": "2030-01-31T10:00:00+03:00",
    "timezone": "Europe/Moscow",
    "end_at": null,
    "max_payments": 12,
    "customer_fee_percent": "0",
    "retry_policy": {
      "retry_delays_seconds": [
        3600,
        86400
      ],
      "on_exhausted": "pause"
    }
  },
  "status": "awaiting_confirmation",
  "reason": "",
  "version": 1,
  "paid_cycles": 0,
  "initiator": "merchant",
  "confirmation_url": null,
  "next_payment_at": null,
  "cancel_at": null,
  "project_url": "https://merchant.example",
  "consent_reference": "consent-10001",
  "created_at": "2029-12-31T10:00:00+00:00",
  "preview": [
    {
      "cycle_number": 0,
      "payment_at": "2030-01-31T07:00:00+00:00",
      "amount": 990,
      "currency": "RUB"
    },
    {
      "cycle_number": 1,
      "payment_at": "2030-02-28T07:00:00+00:00",
      "amount": 990,
      "currency": "RUB"
    },
    {
      "cycle_number": 2,
      "payment_at": "2030-03-31T07:00:00+00:00",
      "amount": 990,
      "currency": "RUB"
    }
  ],
  "confirmation_mode": "merchant",
  "initial_payment_url": "https://bank.example/sbp/enrollment"
}

    Уведомления и кабинет

    Завершённую оплату подтверждает подписанный платёжный webhook со status: completed. Связанные платежи содержат subscription_id, invoice_id, attempt_id и payment_token. События recurring.subscription.* описывают состояние подписки, а не результат оплаты. Кабинет → Рекуррентные платежи: планы, подписки, начисления и способы оплаты; изменения защищены OTP.

    API
    GET /api/v1/merchant/recurring/settings
GET /api/v1/merchant/recurring/plans
GET /api/v1/merchant/recurring/subscriptions
GET /api/v1/merchant/recurring/invoices
GET /api/v1/merchant/recurring/audit
    Создать выплатуБанковская карта в RUB и USDT в сети TRON

    Метод выплаты

    Банковская карта в RUB и USDT в сети TRON

    Банковская карта

    Выплата на банковскую карту

    Перевод рублей по номеру карты. Для создания нужны телефон и имя получателя; результат подтверждается статусом выплаты.

    Когда выбиратьВозвраты, вознаграждения и массовые выплаты физическим лицам в России.
    Путь платежа
    Выберите шаг, чтобы открыть пояснение и пример.
    availableсозданиеfrozencompleted → списано
    failed → возвращено

    Webhook

    Запрос API и входящий webhook используют одну формулу, но выбор ключа отличается. Уведомления подписываются основной парой ключей проекта, даже если платёж создан дополнительным API-ключом.

    1. Прочитайте исходное тело запроса до JSON.parse. Не меняйте порядок полей, пробелы или Unicode перед проверкой подписи.
    2. Сверьте X-API-KEY с основным public_key проекта. HMAC вычисляйте с основным secret_key и X-TIMESTAMP из заголовка.
    3. Сравнивайте подписи безопасным сравнением. После проверки сохраните X-Event-ID и обработайте событие один раз.
    4. Ответьте HTTP 2xx после надёжного сохранения события. На повторный X-Event-ID также ответьте 2xx, без повторной выдачи заказа.
    HMAC-SHA256 · webhook
    body = raw_request_body_utf8
timestamp = header["X-TIMESTAMP"]
message = body + ":" + timestamp + "++"
signature = hex(hmac_sha256(base64(primary_secret_key), message))

X-API-KEY: <primary_public_key>
X-TIMESTAMP: <unix_seconds>
X-SIGNATURE: <signature>
X-Event-ID: <event_id>
    Путь платежа
    Покупатель возвращается на сайт независимо от доставки webhook. Источник результата — проверенный webhook или GET статуса.

    Операции

    Здесь только чтение общего состояния. Создание платежей и выплат описано в разделах конкретных методов выше.

    PAYMENTS

    Платежи

    Получить одну операцию, реестр с фильтром или XLSX-выгрузку.

    GET /api/v1/merchant/transactions/{transaction_id}
GET /api/v1/merchant/transactions?page_number=1&items_per_page=50&status=completed
GET /api/v1/merchant/transactions/export?status=completed
    PAYOUTS

    Выплаты

    Получить одну выплату по локальному или внешнему ID либо список с фильтром по статусу.

    GET /api/v1/merchant/payouts/{payout_id}
GET /api/v1/merchant/payouts?page_number=1&items_per_page=50
GET /api/v1/merchant/payouts?page_number=1&items_per_page=50&status=pending
    PROJECT

    Баланс и время

    Проверить доступный и зарезервированный баланс либо синхронизировать timestamp для подписи.

    GET /api/v1/merchant/balance
GET /api/v1/merchant/timestamp

    Проверка перед запуском

    Проверьте оба направления связи до подключения реального трафика.

    • Тестовый запрос подписан на backend, ключ не попал в браузер или репозиторий.
    • После оплаты заказ подтверждается по completed, а не по redirect_url_success.
    • Одинаковый webhook дважды не выдаёт товар и не меняет ваш баланс повторно.
    • После таймаута сначала проверяется существующая заявка; новая с другим номером не создаётся вслепую.
    • Отклонение, истечение срока и необходимость 3DS обработаны; интерфейс проверен на телефоне.

    Если запрос не прошёл

    401
    Проверьте пару ключей, исходящий IP backend, Unix-секунды и подписанное тело. GET /timestamp тоже требует авторизации.
    422
    Сверьте названия и форматы полей с выбранным методом. Не копируйте настройки другого сценария.
    409 / таймаут
    Найдите существующую операцию по вашему номеру заказа. Не создавайте повторное списание до выяснения результата.