Documentación de Aeris API

Referencia de autenticación, creación de pagos y pagos salientes, webhooks y consulta de estados.

Secciones principales

URL base: https://aeris-psp.net
Formato de datos: application/json

Tu primer pago

Sigue el recorrido desde la configuración del acceso hasta un pedido confirmado. Los ejemplos son demostrativos; enviarlos con una clave de producción crea una operación real.

Requisitos

Obtén un proyecto y un par public_key / secret_key. Usa un proyecto de prueba separado.
Permite la IP saliente del backend en API IP. Para el widget, permite el dominio web por separado.
Prepara un webhook HTTPS y páginas de retorno. Guarda el secreto solo en el backend.

Pago SBP normal con la página Aeris: crear → recibir URL → abrir el pago → verificar el resultado.

Elige quién controla el pago

Cómo funciona la integración

Elige quién controla el pago

Página de pago: Aeris muestra formulario, QR y botones bancarios. Abre payment_url o integra el widget.
Host-to-Host: Tu interfaz recibe una URL directa o next_action. Tú implementas redirecciones y 3DS.
Página compartida: El cliente elige SBP o SberPay. checkout_id describe una sesión de selección, no un pago confirmado.

merchant_order_id: Tu número único de pedido. Permite asociar operaciones y comprobar respuestas perdidas.
id: Identificador de transacción Aeris. Guárdalo para consultar el estado.
project_url: Sitio web o bot de Telegram al que pertenece el pedido. No es webhook ni URL de retorno.
callback_url: Backend que recibe notificaciones de Aeris. No es navegación del cliente.
redirect_url_success: Página de retorno del cliente después del flujo exitoso. No confirma la recepción de fondos.

Claves API

La clave principal se crea con el proyecto. En el panel puedes emitir hasta cuatro claves adicionales. Allí también se configuran la URL de notificaciones, las IP/CIDR de servidores y los dominios HTTPS del widget. Ver claves y guardar cambios requiere confirmación por Telegram o una aplicación de autenticación.

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

Autenticación

Cada solicitud se firma con HMAC-SHA256. Envía el timestamp en segundos Unix dentro de la ventana permitida. Serializa JSON de forma compacta, sin espacios. Para GET no envíes cuerpo HTTP, pero incluye {} en la firma.

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>

Para POST, firma JSON compacto con Unicode escapado a ASCII (\uXXXX), como json.dumps(..., separators=(",", ":"), ensure_ascii=True). Para GET, no envíes cuerpo HTTP, pero usa la cadena {} para calcular la firma.
base64(secret_key) codifica la cadena UTF-8 del secreto, no la decodifica. Usa segundos Unix, no milisegundos.
Firma las solicitudes API con un par principal o adicional completo. No mezcles public_key y secret_key de pares distintos.

Crear un pagoSBP, SberPay y tarjetas bancarias

Página de pago

Aeris muestra al cliente una página de pago lista para usar.

H2H

Tu backend recibe una URL directa o next_action y controla la interfaz.

Página de pago

SBP + SberPay

Una página de pago con los métodos disponibles. El pago se crea después de elegir el método.

Cuándo usarloCheckout principal cuando el cliente elige el método de pago.

Selecciona un paso para ver la explicación y el ejemplo.

Página de pago Aeris

Pago del pedido

Demo Store

9000 RUB

El resultado aparecerá en esta página

Ilustración de la interfaz. Datos demostrativos, no un enlace de pago real.

Pagos recurrentes por SBP

La suscripción conserva el precio y período acordados. Aeris o tu backend inicia los cobros con las mismas obligaciones, límites e historial.

Las rutas comienzan con /api/v1/merchant. Firma como los pagos normales. GET /recurring/capabilities devuelve métodos y controles de cobro.

Selecciona un paso para ver la explicación y el ejemplo.

Gestión y límites

Una obligación por período y un cobro pendiente. Máximo tres intentos enviados en 24 horas móviles, separados al menos una hora; reintentos solo tras rechazo confirmado. Un timeout mantiene el bloqueo. No se recuperan períodos omitidos. Desactivar bloquea API y planificador, no la conciliación.

Incluye expected_version actual. Superar el precio acordado, cambiar período o ampliar duración requiere nueva confirmación. Cambiar initiator no reinicia historial ni límites. Pausar o cancelar no reembolsa ni retira pagos enviados.

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"
    }
  ]
}

Suscripción con el primer pago

Añade save_payment_method y recurring a POST /payins/sbp. payment_url abre la confirmación Aeris y subscription contiene el ID. Para descuento inicial, usa el importe descontado en amount y el precio normal en recurring.amount.

Solicitud y código

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 sin la ventana de Aeris

Requiere aprobación separada de Aeris y aceptación de las condiciones. En POST /recurring/subscriptions envía confirmation_mode: merchant, consent_granted: true explícito y consent_evidence. consent_reference identifica tu archivo de pruebas; document_sha256 es el SHA-256 del documento completo, no una cadena arbitraria. accepted_at conserva la fecha original con zona horaria; no la cambies al reintentar. Sin aprobación se devuelve HTTP 403.

Muestra importes exactos, período y duración en tu interfaz. La respuesta contiene initial_payment_url para el primer pago bancario y confirmation_url: null. La declaración del comercio no activa la suscripción: son obligatorios el primer pago SBP completado y un vínculo activo. Entrega las pruebas originales del consentimiento al precio declarado dentro de 24 horas tras solicitarlas; excepciones y consecuencias según las condiciones aceptadas.

Condiciones de pagos recurrentes

Solicitud y código

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"
}

Notificaciones y panel

El webhook firmado con status: completed confirma el pago. Los cobros vinculados incluyen subscription_id, invoice_id, attempt_id y payment_token. recurring.subscription.* describe el ciclo de vida, no confirma pagos. Panel → Pagos recurrentes: planes, suscripciones, cobros y métodos; cambios con 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

Crear un pago salienteTarjeta bancaria en RUB y USDT en TRON

Método de pago saliente

Tarjeta bancaria en RUB y USDT en TRON

Tarjeta bancaria

Pago saliente a tarjeta bancaria

Transferencia de RUB por número de tarjeta. Para crearla se necesitan teléfono y nombre del beneficiario; el estado es el resultado final.

Cuándo usarloReembolsos, recompensas y pagos masivos a particulares en Rusia.

Selecciona un paso para ver la explicación y el ejemplo.

availablecreaciónfrozencompleted → debitado
failed → liberado

Webhook

API y webhook usan la misma fórmula, pero distintas reglas de elección de claves. Las notificaciones usan el par principal del proyecto, aunque el pago se haya creado con una clave adicional.

Lee el cuerpo original antes de JSON.parse. No cambies el orden, espacios o Unicode antes de verificar.
Compara X-API-KEY con el public_key principal. Calcula HMAC con el secret_key principal y X-TIMESTAMP del encabezado.
Compara las firmas de forma segura. Guarda X-Event-ID y procesa el evento una sola vez.
Devuelve HTTP 2xx tras guardar el evento de forma duradera. Repite 2xx para el mismo X-Event-ID, sin entregar dos veces.

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>

El retorno del cliente y el webhook son independientes. El resultado proviene de un webhook verificado o de GET del estado.

Operaciones

Esta sección contiene operaciones de solo lectura. La creación de pagos y pagos salientes se describe en cada método.

PAYMENTS

Pagos

Consulta una operación, una lista filtrada o una exportación 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

Pagos salientes

Consulta un pago saliente por ID local o externo, o una lista filtrada por estado.

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

Saldo y hora

Consulta los saldos disponible y reservado o sincroniza el timestamp de firma.

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

Antes de producción

Comprueba ambos sentidos de comunicación antes de recibir tráfico real.

El backend firma la prueba; la clave no aparece en el navegador ni en el repositorio.
completed confirma el pedido, no redirect_url_success.
Dos webhooks iguales no entregan ni acreditan dos veces.
Tras un timeout se comprueba la operación existente antes de crear otra.
Se gestionan rechazo, caducidad y 3DS; la interfaz funciona en móvil.

Si falla una solicitud

401: Comprueba el par, IP saliente, segundos Unix y cuerpo firmado. GET /timestamp también exige autenticación.
422: Comprueba campos y formatos del método elegido. No copies ajustes de otro flujo.
409 / timeout: Busca la operación por el número de pedido. No cobres otra vez hasta conocer el resultado.