# ЮKassa: POST /deals — Создание сделки

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

Документация: https://yookassa.ru/developers/api#create_deal

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Idempotence-Key` | header | string | да | Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7 |
| `type` | body | string (safe_deal) | да | Тип сделки. Фиксированное значение: safe_deal — Безопасная сделка. |
| `fee_moment` | body | string (payment_succeeded, deal_closed) | да | Момент, когда вам зачисляется вознаграждение маркетплейса. Возможные значения: payment_succeeded — после успешной оплаты; deal_closed — после закрытия сделки по итогам успешной выплаты. |
| `metadata` | body | object | нет | Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, не более 32 символов в названии ключа, не более 512 символов в значении ключа, тип данных — строка в формате UTF-8. |
| `description` | body | string | нет | Описание сделки (не более 128 символов). Используется для фильтрации при получении списка сделок. |

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

```
{
  "type": "safe_deal",
  "fee_moment": "payment_succeeded"
}
```

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

```json
{
  "type": "safe_deal",
  "id": "dl-d68d2fe4-2abb-47e5-8112-32e28f87fb52",
  "balance": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "closed",
  "created_at": "2020-07-03T11:52:31.827Z",
  "expires_at": "2021-01-03T18:31:22.532Z",
  "test": false,
  "fee_moment": "payment_succeeded"
}
```

## Базовые URL

- Основной: `https://api.yookassa.ru/v3`

## Авторизация

Тип: Basic Auth

HTTP Basic Auth: имя пользователя — идентификатор магазина (shopId, раздел Настройки — Магазин) или шлюза для выплат (agentId, раздел Настройки выплат), пароль — секретный ключ (раздел Интеграция — Ключи API). Для тестового магазина ключ выпускается автоматически. Участники партнерской программы используют OAuth 2.0 и передают Bearer-токен. Секретный ключ и OAuth-токен нельзя публиковать.

```
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>
```

## Нюансы

- capture по умолчанию false: без capture: true платеж останется в статусе waiting_for_capture и в момент expires_at отменится автоматически, деньги вернутся покупателю.
- Для POST и DELETE обязателен заголовок Idempotence-Key — до 64 символов, рекомендуется UUID. Повтор с тем же ключом в течение 24 часов вернет результат первого запроса; для новой операции нужен новый ключ.
- HTTP 500 не значит, что операция не прошла: результат неизвестен. Повтори запрос с теми же данными и тем же ключом идемпотентности или запроси объект через GET.
- Возврат покупателя на return_url не означает успешную оплату — статус проверяй на сервере или по HTTP-уведомлению.
- Сумма — строка с точкой и двумя знаками: "1000.00", вместе с кодом валюты.
- Методы /webhooks работают только с OAuth-токеном в партнерской программе. Обычный магазин настраивает уведомления в личном кабинете.
- Вернуть платеж можно в течение трех лет с момента создания. Комиссия ЮKassa за платеж не возвращается.
- Для Чеков от ЮKassa частичная предоплата, аванс и кредит не поддерживаются.

---

Если этого недостаточно — официальная документация: https://yookassa.ru/developers/api#create_deal
Вся интеграция одним документом: https://mcp-everything.ru/integrations/yookassa.md