## Работа со сделками

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

Объект сделки `DealResponse` содержит всю информацию о сделке, актуальную на текущий момент времени. Объект формируется при создании сделки и приходит в ответ на любой запрос, связанный со сделками.

* [Запрос на создание сделки](#Запрос-на-создание-сделки)
* [Запрос на создание сделки через билдер](#Запрос-на-создание-сделки-через-билдер)
* [Запрос на создание платежа с привязкой к сделке](#Запрос-на-создание-платежа-с-привязкой-к-сделке)
* [Запрос на выплату продавцу](#Запрос-на-выплату-продавцу)
* [Получить информацию о сделке](#Получить-информацию-о-сделке)
* [Получить список сделок с фильтрацией](#Получить-список-сделок-с-фильтрацией)
* [Получить информацию о выплате](#Получить-информацию-о-выплате)

---

### Запрос на создание сделки <a name="Запрос-на-создание-сделки"></a>

[Создание сделки в документации](https://yookassa.ru/developers/api?lang=php#create_deal)

Запрос `CreateDealRequest` позволяет создать сделку, в рамках которой необходимо принять оплату от покупателя и перечислить ее продавцу.

В ответ на запрос придет объект сделки — `DealResponse` — в актуальном статусе.

```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

try {
    $response = $client->createDeal(
        [
            'type' => \YooKassa\Model\Deal\DealType::SAFE_DEAL,
            'fee_moment' => \YooKassa\Model\Deal\FeeMoment::PAYMENT_SUCCEEDED,
            'metadata' => [
                'order_id' => '37',
            ],
            'description' => 'SAFE_DEAL 123554642-2432FF344R',
        ],
        uniqid('', true)
    );
    echo $response->getStatus();
} catch (\Exception $e) {
    $response = $e;
}

if (!empty($response)) {
    print_r($response);
}
```
---

### Запрос на создание платежа через билдер <a name="Запрос-на-создание-сделки-через-билдер"></a>

[Создание платежа в документации](https://yookassa.ru/developers/api?lang=php#create_payment)

Билдер позволяет создать объект платежа — `CreateDealRequest` — программным способом, через объекты.

```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

try {
    try {
    $builder = \YooKassa\Request\Deals\CreateDealRequest::builder();
    $builder->setType(\YooKassa\Model\Deal\DealType::SAFE_DEAL)
        ->setFeeMoment(\YooKassa\Model\Deal\FeeMoment::PAYMENT_SUCCEEDED)
        ->setMetadata([
            'order_id' => '37',
        ])
        ->setDescription('SAFE_DEAL 123554642-2432FF344R');

    // Создаем объект запроса
    $request = $builder->build();

    // Можно изменить данные, если нужно
    $request->setDescription($request->getDescription() . ' - merchant comment');

    $idempotenceKey = uniqid('', true);
    $response = $client->createDeal($request, $idempotenceKey);
    
    // Получаем данные объекта
    echo $response->getStatus();
} catch (\Exception $e) {
    $response = $e;
}

var_dump($response);
```
---

### Запрос на создание платежа с привязкой к сделке <a name="Запрос-на-создание-платежа-с-привязкой-к-сделке"></a>

[Создание платежа в документации](https://yookassa.ru/developers/api?lang=php#create_payment)

Чтобы принять оплату от покупателя, отправьте ЮKassa запрос на создание платежа, передайте в нём данные, которые нужны для оплаты, в зависимости от выбранного сценария интеграции, и следующие данные для проведения платежа в рамках сделки:
* Объект `amount` с общей суммой платежа за сделку (сумма вознаграждения продавца и вознаграждения вашей платформы). Эту сумму ЮKassa спишет с покупателя. Комиссия ЮKassa за проведение платежа рассчитывается из этой суммы, а взимается из вашего вознаграждения. Сумма платежа должна соответствовать ограничениям на минимальный и максимальный размер платежа. [Подробнее о лимитах платежей](https://yookassa.ru/docs/support/payments/limits)
* Объект `deal` с данными о сделке: идентификатор сделки и массив settlements с данными о том, какую сумму нужно выплатить продавцу. Разница между суммой платежа и суммой выплаты должна быть больше эквайринговой комиссии ЮKassa. Сумма выплаты должна соответствовать ограничениям на минимальный и максимальный размер выплаты. [Подробнее о лимитах выплат](https://yookassa.ru/developers/solutions-for-platforms/safe-deal/integration/payouts#specifics)

В ответ на запрос придет объект платежа — `PaymentResponse` — в актуальном статусе.

```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

$paymentId = '21b23b5b-000f-5061-a000-0674e49a8c10';
$request = [
    'amount' => [
        'value' => '100.00',
        'currency' => 'RUB',
    ],
    'confirmation' => [
        'type' => 'redirect',
        'locale' => 'ru_RU',
        'return_url' => 'https://testna5.ru/',
    ],
    'description' => 'Оплата заказа на сумму 100 руб',
    'metadata' => [
        'order_id' => '37'
    ],
    'capture' => true,
    'deal' => [
        'id' => 'dl-2909e77d-0022-5000-8000-0c37205b3208',
        'settlements' => [
            [
                'type' => 'payout',
                'amount' => [
                    'value' => '80.00',
                    'currency' => 'RUB',
                ]
            ],
        ],
    ],
    'merchant_customer_id' => 'merchant@shop.com'
];
$idempotenceKey = uniqid('', true);
try {
    $result = $client->createPayment($request, $idempotenceKey);
} catch (\Exception $e) {
    $result = $e;
}

var_dump($result);
```
[Подробнее о приеме оплаты от покупателя](https://yookassa.ru/developers/solutions-for-platforms/safe-deal/integration/payments)

---

### Запрос на выплату продавцу <a name="Запрос-на-выплату-продавцу"></a>

[Выплата продавцу в документации](https://yookassa.ru/developers/api?lang=php#create_payout)

Запрос позволяет перечислить продавцу оплату за выполненную услугу или проданный товар в рамках «Безопасной сделки». Выплату можно сделать на банковскую карту или в кошелек ЮMoney.

В ответ на запрос придет объект выплаты — `PayoutResponse` — в актуальном статусе.
```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

$request = [
    'amount' => [
        'value' => '80.00',
        'currency' => 'RUB',
    ],
    'payout_destination_data' => [
        'type' => \YooKassa\Model\Payout\PayoutDestinationType::YOO_MONEY,
        'accountNumber' => '4100116075156746',
    ],
    'description' => 'Выплата по заказу №37',
    'metadata' => [
        'order_id' => '37'
    ],
    'deal' => [
        'id' => 'dl-2909e77d-0022-5000-8000-0c37205b3208',
    ],
];
$idempotenceKey = uniqid('', true);
try {
    $result = $client->createPayout($request, $idempotenceKey);
} catch (\Exception $e) {
    $result = $e;
}

var_dump($result);
```
[Подробнее о проведении выплат](https://yookassa.ru/developers/solutions-for-platforms/safe-deal/integration/payouts)

---

### Получить информацию о сделке <a name="Получить-информацию-о-сделке"></a>

[Информация о сделке в документации](https://yookassa.ru/developers/api?lang=php#get_deal)

Запрос позволяет получить информацию о текущем состоянии сделки по ее уникальному идентификатору.

В ответ на запрос придет объект сделки — `DealResponse` — в актуальном статусе.

```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

$dealId = 'dl-215d8da0-000f-50be-b000-0003308c89be';
try {
    $response = $client->getDealInfo($dealId);
} catch (\Exception $e) {
    $response = $e;
}

var_dump($response);
```
---

### Получить список сделок с фильтрацией <a name="Получить-список-сделок-с-фильтрацией"></a>

[Список платежей в документации](https://yookassa.ru/developers/api?lang=php#get_deals_list)

Запрос позволяет получить список сделок, отфильтрованный по заданным критериям.

В ответ на запрос вернется список сделок с учетом переданных параметров. В списке будет информация о сделках, созданных за последние 3 года. Список будет отсортирован по времени создания сделок в порядке убывания.

Если результатов больше, чем задано в `limit`, список будет выводиться фрагментами. В этом случае в ответе на запрос вернется фрагмент списка и параметр `next_cursor` с указателем на следующий фрагмент.

```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

$cursor = null;
$params = [
    'limit' => 30,
    'status' => \YooKassa\Model\Deal\DealStatus::OPENED,
    'full_text_search' => 'DEAL',
    'created_at_gte' => '2021-10-01T00:00:00.000Z',
    'created_at_lt' => '2021-11-01T23:59:59.999Z',
];
try {
    do {
        $params['cursor'] = $cursor;
        $deals = $client->getDeals($params);
        foreach ($deals->getItems() as $deal) {
            $res = [
                $deal->getCreatedAt()->format('Y-m-d H:i:s'),
                $deal->getBalance()->getValue() . ' ' . $deal->getBalance()->getCurrency(),
                $deal->getPayoutBalance()->getValue() . ' ' . $deal->getBalance()->getCurrency(),
                $deal->getStatus(),
                $deal->getId(),
            ];
            echo implode(' - ', $res) . "\n";
        }
    } while ($cursor = $deals->getNextCursor());
} catch (\Exception $e) {
    $response = $e;
    var_dump($response);
}
```
[Подробнее о работе со списками](https://yookassa.ru/developers/using-api/lists)

---

### Получить информацию о выплате <a name="Получить-информацию-о-выплате"></a>

[Информация о выплате в документации](https://yookassa.ru/developers/api?lang=php#get_payout)

Запрос позволяет получить информацию о текущем состоянии выплаты по ее уникальному идентификатору.

В ответ на запрос придет объект выплаты — `PayoutResponse` — в актуальном статусе.

```php
require_once 'vendor/autoload.php';

$client = new \YooKassa\Client();
$client->setAuth('xxxxxx', 'test_XXXXXXX');

$payoutId = 'po-285c0ab7-0003-5000-9000-0e1166498fda';
try {
    $response = $client->getPayoutInfo($payoutId);
} catch (\Exception $e) {
    $response = $e;
}

var_dump($response);
```