Войти
AGDor Pay

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

Здесь два разных сценария. Один для проектов, которые работают через API и webhook. Второй для операторов, которые создают счета вручную из панели и отправляют готовую payment page или builder view клиенту.

Через API Через панель
API Flow Автоматическая интеграция Для сайтов, SaaS, Telegram-ботов и клиентских проектов, где invoice создается программно и статус приходит вебхуком. project_code, api_key, wallet_code, invoice.confirmed Dashboard Flow Ручные счета из панели Для операторов, менеджеров и администраторов, которые сами создают invoice, настраивают шаблоны и отправляют клиенту ссылку или готовый текст. Проект, кошелек, шаблоны, payment page, builder view

Автоматическая интеграция

API-поток начинается в панели, но дальше работает без ручных действий. Вы создаете проект, привязываете к нему кошельки, сохраняете `api_key` и затем ваш сервис сам создает invoices.

1

Создайте проект

Откройте Dashboard → Projects. После сохранения проект получает `project_code`, `api_key` и `webhook_secret`. `api_key` показывается один раз.

2

Добавьте кошелек и привяжите его к проекту

В Dashboard → Wallets создайте нужный способ оплаты, а затем включите его в проекте через список разрешенных кошельков.

3

Получите методы оплаты

Ваш проект вызывает `r=payment_methods`, получает активные `wallet_code` и показывает клиенту список доступных сетей или Binance ID.

4

Создайте invoice

После выбора метода оплаты клиентом ваш сервер вызывает `r=create_invoice`, получает `invoice_id`, точную сумму и адрес назначения, а затем показывает эти данные пользователю.

5

Дождитесь подтверждения

Когда Payment Service находит платеж, он меняет статус invoice и отправляет `invoice.confirmed` в `Webhook URL` вашего проекта.

Если `api_key` потерян, его нельзя прочитать повторно. Для рабочего проекта нужно сгенерировать новый ключ в настройках проекта и обновить его у клиента.

Авторизация

Каждый API-запрос должен передавать `project_code` и `api_key`. Предпочтительный способ: HTTP-заголовки.

Поле Где передавать Описание
X-Project-Code Header Внутренний код проекта.
X-API-Key Header Секрет проекта для API-запросов.
project_code POST / GET Запасной вариант, если клиент не умеет отправлять заголовки.
api_key POST Запасной вариант для server-to-server запросов. 
curl -X POST "https://agdorpay.com/api?r=payment_methods" \
  -H "X-Project-Code: project_demo_123" \
  -H "X-API-Key: ********"

Методы API

r=ping

Проверка доступности сервиса.

GET https://agdorpay.com/api?r=ping

r=payment_methods

Возвращает активные `wallet_code`, валюту, сеть и отображаемое имя метода оплаты для выбранного проекта.

GET/POST https://agdorpay.com/api?r=payment_methods

r=create_invoice

Создает invoice и возвращает точную сумму с микро-офсетом, который должен оплатить клиент.

POST https://agdorpay.com/api?r=create_invoice

r=get_invoice

Возвращает текущее состояние invoice по `invoice_id` или `external_id`.

GET/POST https://agdorpay.com/api?r=get_invoice

r=cancel_invoice

Отменяет invoice, пока он находится в статусе `pending`.

POST https://agdorpay.com/api?r=cancel_invoice

r=confirm_invoice

Ручное подтверждение invoice со стороны проекта. Используется только для специальных сценариев.

POST https://agdorpay.com/api?r=confirm_invoice

Пример `payment_methods`

{
  "status": "success",
  "data": {
    "project_code": "project_demo_123",
    "wallets": [
      {
        "wallet_code": "usdt_trc20_main",
        "label": "USDT TRC20",
        "payment_type": "crypto_wallet",
        "currency": "USDT",
        "network": "TRC20",
        "address": "T..."
      }
    ]
  }
}

Пример `create_invoice`

curl -X POST "https://agdorpay.com/api?r=create_invoice" \
  -H "X-Project-Code: project_demo_123" \
  -H "X-API-Key: ********" \
  -d "amount=25.00" \
  -d "wallet_code=usdt_trc20_main" \
  -d "external_id=order_10452" \
  -d "customer_id=user_42"
{
  "status": "success",
  "data": {
    "invoice_id": "inv_87a3bfd",
    "project_code": "project_demo_123",
    "external_id": "order_10452",
    "customer_id": "user_42",
    "status": "pending",
    "amount_requested": "25.00",
    "amount": "25.0427",
    "currency": "USDT",
    "payment_type": "crypto_wallet",
    "network": "TRC20",
    "address": "T...",
    "wallet_code": "usdt_trc20_main",
    "wallet_label": "USDT TRC20",
    "expires_at": "2026-06-13 18:30:00",
    "confirmed_at": null,
    "txid": null,
    "payment_url": "https://agdorpay.com/pay/pay_6e18a2f4b1c8d3e5f7a9b0c1d2e3f4a5",
    "metadata": {}
  }
}
Поле amount в ответе может быть больше, чем запрошенная сумма. Оплачивать нужно именно его, иначе автоматическая привязка платежа не сработает.

PayPal Direct Transfer IPN

PayPal Direct Transfer подтверждает оплату через Instant Payment Notification (IPN), а не через API polling.

Обязательные поля кошелька

  • PayPal email: email получателя, на который плательщик отправляет деньги.
  • Код продавца: Код продавца PayPal для проверки поля receiver_id.
  • currency=USD, network=PAYPAL, provider=paypal_ipn

Настройка PayPal

  1. Создайте или отредактируйте кошелек PayPal Direct (IPN) и заполните PayPal email и Код продавца.
  2. В настройках аккаунта PayPal включите Instant Payment Notifications (IPN): открыть настройки IPN.
  3. Укажите listener URL ниже.
https://agdorpay.com/paypal_ipn
Listener URL: https://agdorpay.com/paypal_ipn. Сервер проверяет postback через PayPal notify-validate и принимает только HTTP 200 с точным ответом VERIFIED.

Проверка VERIFIED postback

PayPal IPN → POST raw body → notify-validate → HTTP 200 + VERIFIED → invoice confirmation
  • payment_status должен быть Completed.
  • txn_type должен быть send_money.
  • receiver_email и receiver_id должны совпадать с email и Код продавца кошелька.
  • mc_currency должен быть USD, а mc_gross — точной суммой invoice с двумя знаками.
  • payment_date должен попадать в окно оплаты invoice; повторные доставки обрабатываются идемпотентно.

Ограничения invoice и custom

invoice используется как предпочтительный идентификатор invoice, а custom — только как fallback. Эти поля являются подсказками: сервис дополнительно проверяет сумму, валюту, email, Код продавца, тип операции и время, и не выбирает invoice произвольно при неоднозначном совпадении.

Для старых ручных PayPal-платежей без надежной связи с invoice или custom автоматического match нет. Используйте ручное подтверждение или late-payment reconciliation в панели; один только VERIFIED postback не подтверждает такой старый платеж.

Вебхуки

После подтверждения invoice сервис отправляет POST-запрос на `Webhook URL`, указанный в проекте. Повторная отправка возможна, поэтому обработчик у клиента должен быть idempotent.

Header Описание
X-Payment-Event-Id Уникальный идентификатор webhook-события.
X-Payment-Timestamp Unix timestamp, который участвует в подписи.
X-Payment-Signature HMAC-SHA256 подпись по формуле `timestamp.payload`. 
signature = HMAC_SHA256(
  timestamp + "." + raw_json_payload,
  webhook_secret
)
{
  "event_id": "evt_...",
  "event_type": "invoice.confirmed",
  "invoice_id": "inv_87a3bfd",
  "project_code": "project_demo_123",
  "external_id": "order_10452",
  "customer_id": "user_42",
  "status": "confirmed",
  "amount_requested": "25.00",
  "amount": "25.0427",
  "currency": "USDT",
  "payment_type": "crypto_wallet",
  "network": "TRC20",
  "address": "T...",
  "wallet_code": "usdt_trc20_main",
  "wallet_label": "USDT TRC20",
  "txid": "transaction_hash",
  "confirmed_at": "2026-06-13 18:41:20",
  "payment_url": "https://agdorpay.com/pay/pay_6e18a2f4b1c8d3e5f7a9b0c1d2e3f4a5",
  "metadata": {}
}
<?php
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_PAYMENT_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_PAYMENT_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('bad signature');
}

Polling как резерв

Если вы не хотите полагаться только на webhook, можно периодически вызывать `r=get_invoice` и проверять статус. Это особенно полезно для внутренних кабинетов или длинных клиентских сессий.

Когда использовать

  • внутренний кабинет без внешнего webhook endpoint
  • резервный канал рядом с webhook
  • проверка статуса в browser session пользователя

Практика

  • опрашивать раз в 5-10 секунд
  • остановить опрос при `confirmed`, `manual_confirmed`, `cancelled`, `expired`
  • не спамить сервис параллельными запросами на один invoice

Примеры

Webhook tester в панели

Минимальный PHP-клиент

<?php
$ch = curl_init("https://agdorpay.com/api?r=create_invoice");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERAGENT => 'Mozilla/5.0 AGDor Pay Client',
    CURLOPT_HTTPHEADER => [
        'X-Project-Code: project_demo_123',
        'X-API-Key: ********',
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'amount' => '25.00',
        'wallet_code' => 'usdt_trc20_main',
        'external_id' => 'order_10452',
    ]),
]);
$response = curl_exec($ch);

Минимальный cURL-check статуса

curl "https://agdorpay.com/api?r=get_invoice" \
  -H "X-Project-Code: project_demo_123" \
  -H "X-API-Key: ********" \
  -d "invoice_id=inv_87a3bfd"

Статусы invoice

Статус Смысл
pendingСчет создан и ждет платеж.
confirmedПлатеж найден автоматически.
manual_confirmedСчет подтвержден вручную.
cancelledСчет отменен оператором или проектом.
expiredСрок invoice истек до момента подтверждения.