Создание платежа

Один POST создаёт платёж и возвращает адрес страницы оплаты. Способ оплаты в запросе не указывается — плательщик выбирает его сам на странице оплаты, поэтому добавление нового способа не требует от вас релиза.

POST /api/v1/payments

curl -X POST https://takemypay.net/api/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "order-123",
    "amount": "1000.00",
    "description": "Order #123",
    "return_url": "https://shop.example.com/ok",
    "fail_url":   "https://shop.example.com/fail"
  }'

Поля запроса

Что означает amount

В режиме по умолчанию комиссию платит мерчант: amount — это сумма, которую видит и платит плательщик, а вам зачисляется остаток за вычетом комиссии.

Если в настройках переключить режим на «комиссию платит плательщик», amount становится вашей чистой суммой: комиссия добавляется сверху, с плательщика списывается больше, а вы получаете ровно переданное число. В этом режиме сверяйте заказ по полю amount_net из webhook — оно равно тому, что вы передали сюда.

Максимальная сумма

Один платёж — не больше 199 999 ₽. Ограничение действует на СБП и обе карточные линии; криптовалюты оно не касается, у неё такого предела нет.

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

Что происходит с суммой выше потолка: платёж создаётся, но на странице оплаты фиатные способы выключены с пометкой, а оплатить можно криптовалютой. Ответ на создание в этом случае обычный. Исключение одно — если криптовалюта у вас недоступна: платить было бы нечем, поэтому создание сразу отвечает 422 с кодом amount_above_maximum.

Ответ

{
  "id": "6f1c8f7e-...",
  "checkout_url": "https://takemypay.net/c/8f3a...",
  "status": "pending",
  "expires_at": "2026-05-19T12:30:00Z",
  "warnings": []
}

• id — идентификатор платежа, он же приходит в webhook.
• checkout_url — адрес страницы оплаты, куда нужно отправить плательщика.
• status — статус на момент создания, всегда pending.
• expires_at — момент, после которого платёж не может быть оплачен.
• warnings — непрерывающие проблемы интеграции. Сейчас возможно одно значение: webhook_not_configured — у проекта не указан адрес webhook, поэтому об успешной оплате вам никто не сообщит и попытка доставки даже не будет предпринята. Список всегда присутствует и может быть пустым; неизвестные коды игнорируйте — он пополняется без смены версии.

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

Повторный POST с тем же external_order_id в том же проекте возвращает 200 и уже существующий платёж, а не создаёт второй и не отвечает ошибкой. Первое создание отвечает 201.

Поэтому запрос безопасно повторять после сетевого таймаута: новый идентификатор заказа для этого придумывать не нужно. Различайте 201 и 200, если вам важно знать, был ли платёж создан именно сейчас.

GET /api/v1/payments/{id}

curl https://takemypay.net/api/v1/payments/PAYMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "6f1c8f7e-...",
  "external_order_id": "order-123",
  "amount": "1000.00",
  "status": "succeeded",
  "expires_at": "2026-05-19T12:30:00Z",
  "paid_at": "2026-05-19T12:01:32Z",
  "is_test": false
}

Основной канал уведомлений — webhook. Этот эндпоинт нужен, чтобы восстановить состояние, когда webhook не дошёл; строить на нём поллинг вместо webhook не следует.

Ключ проекта видит только платежи своего проекта: запрос чужого платежа отвечает 404, а не 403, — по ответу нельзя выяснить, существует ли такой платёж.

Статусы

pending → processing → succeeded / declined / expired.

• pending — платёж создан, плательщик ещё не выбрал способ оплаты.
• processing — оплата начата и ждёт подтверждения на стороне процессора.
• succeeded — деньги получены; это единственный статус, по которому можно отгружать.
• declined — отказ.
• expired — истёк срок, оплата больше невозможна.

Срок жизни платежа

При создании expires_at ставится на 30 минут вперёд. Когда плательщик выбирает способ оплаты, у которого срок другой, expires_at пересчитывается: для криптовалюты окно — 60 минут, потому что перевод должен успеть подтвердиться сетью.

Не зашивайте 30 минут в свой код. Читайте expires_at из ответа — это единственное место, где срок указан верно для конкретного платежа.

Настроить проекты и ключи — на странице проектов.