Безопасная сделка: быстрый старт на примере доски объявлений

Быстрый старт — Доска объявлений

С помощью этой статьи вы можете провести свою первую Безопасную сделку в ЮKassa. В этом сценарии платформа получит вознаграждение при закрытии сделки.

В статье описан самый простой сценарий интеграции. Все возможности ЮKassa и подробные инструкции по интеграции описаны в разделе Интеграция.

Описание сценария

Доска объявлений — это платформа, на которой одни пользователи могут разместить объявления о продаже товаров, а другие — откликнуться на эти объявления. Пользователи продают товары не постоянно, а при необходимости, разово. Платформа получает вознаграждение только при успешной сделке.

На платформе покупатель собирается купить товар за 800 рублей. Если всё пройдет хорошо, платформа получит 200 рублей за проведение сделки. Продавец хочет получить выплату на банковскую карту.

Чтобы провести Безопасную сделку:

Создайте сделку
Примите оплату от покупателя
Получите данные для выплаты
Сделайте выплату продавцу

Шаг 1. Создайте сделку

Создайте сделку, в рамках которой будете принимать оплату от покупателя и делать выплату продавцу. Для этого отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности (подойдет любое случайное значение), типом сделки (safe_deal — Безопасная сделка) и с указанием, что вознаграждение платформы нужно перечислить при закрытии сделки (fee_moment=deal_closed).

Пример запроса на создание сделки

cURL
PHP
Python
curl https://api.yookassa.ru/v3/deals \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "safe_deal",
        "fee_moment": "deal_closed",
        "metadata": {
          "order_id": "37"
        },
        "description": "SAFE_DEAL 123554642-2432FF344R"
      }'

В ответ на запрос ЮKassa вернет созданный объект сделки.

Пример созданного объекта сделки

JSON
{
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
  "balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "status": "opened",
  "created_at": "2021-06-22T21:42:47.672298Z",
  "expires_at": "2021-06-24T21:42:47.672321Z",
  "metadata": {
    "order_id": "37"
  },
  "description": "SAFE_DEAL 123554642-2432FF344R",
  "test": true
}

Сохраните идентификатор сделки (значение параметра id в созданном объекте). Он понадобится вам при проведении операций в составе сделки и получения информации о сделке.

Шаг 2. Примите оплату от покупателя

Проведите один платеж, в рамках которого покупатель оплатит сразу все затраты за проведение Безопасной сделки.

Пример: товар продавца стоит 800 рублей, проведение сделки на вашей платформе — 200 рублей. Всего покупатель заплатит 1 000 рублей. От этой суммы ЮKassa рассчитает свое вознаграждение за проведение платежа. Например, если комиссия 4,5%, вознаграждение ЮKassa составит 45 рублей. Свою комиссию ЮKassa взимает из вашего вознаграждения, поэтому в итоге продавец получит 800 рублей, ЮKassa — 45 рублей, а вы — 155 рублей.

1. Создайте платеж

Отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для проведения платежа в составе сделки:

В объекте amount передайте общую сумму платежа, которую ЮKassa спишет с покупателя (сумма вознаграждения продавца и вознаграждения вашей платформы). Комиссия ЮKassa за проведение платежа рассчитывается из этой суммы, а взимается из вашего вознаграждения.
В объекте deal передайте данные о сделке: идентификатор сделки и массив settlements с данными о том, какую сумму нужно выплатить продавцу. Разница между суммой платежа и суммой выплаты должна быть больше эквайринговой комиссии ЮKassa.

Пример запроса на создание платежа в составе сделки

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "1000.00",
          "currency": "RUB"
        },
        "capture": true,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "description": "Заказ №37",
        "deal": {
          "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
          "settlements": [{
            "type": "payout",
            "amount": {
              "value": "800.00",
              "currency": "RUB"
            }
          }]
        },
        "metadata": {
          "order_id": "37"
        }
      }'

В ответ на запрос ЮKassa вернет созданный объекта платежа в статусе pending. Это значит, что платеж создан, но покупатель его еще не подтвердил.

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

JSON
{
    "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
    "status": "pending",
    "paid": false,
    "amount": {
        "value": "1000.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=28646d50-000f-5000-a000-1fe4f81e5e88"
    },
    "created_at": "2021-06-22T21:43:44.794Z",
    "deal": {
        "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
        "settlements": [{
            "type": "payout",
            "amount": {
                "value": "800.00",
                "currency": "RUB"
            }
        }]
    },
    "description": "Заказ №37",
    "metadata": {
        "order_id": "37"
    },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
    "refundable": false,
    "test": true
}

Сохраните идентификатор платежа (значение параметра id в созданном объекте). Он понадобится вам для получения информации о платеже, для проведения возвратов и отправки данных для чеков (при необходимости).

Сохраните confirmation_url — он понадобится для оплаты.

2. Реализуйте нужный сценарий подтверждения

Для оплаты перенаправьте покупателя на confirmation_url, чтобы он мог подтвердить платеж.

Сейчас, при проведении пробной сделки, перейдите по ссылке из confirmation_url, введите данные для оплаты и подтвердите платеж. Если вы сейчас проводите платеж для тестовой интернет-площадки, для оплаты используйте банковскую карту со следующими данными:

номер — 5555555555554477
срок действия — 01/30 (или другая дата, больше текущей)
CVC — 123 (или три любые цифры)
код для прохождения 3-D Secure — 123 (или три любые цифры)

3. Дождитесь подтверждения платежа покупателем

Платеж можно считать успешным, как только он перешел в статус succeeded. Если покупатель передумает платить или что-то пойдет не так, платеж перейдет в статус canceled.

Чтобы узнать статус платежа, подпишитесь на уведомления от ЮKassa. Также вы можете следить за статусом, запрашивая информацию о платеже с удобной для вас периодичностью (например, после того, как пользователь вернулся на return_url). Для этого вам понадобится идентификатор платежа.

Пример платежа в статусе succeeded

JSON
{
    "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
    "status": "succeeded",
    "paid": true,
    "amount": {
        "value": "1000.00",
        "currency": "RUB"
    },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
    "captured_at": "2021-06-22T21:44:55.506Z",
    "created_at": "2021-06-22T21:43:44.794Z",
    "deal": {
        "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
        "settlements": [{
            "type": "payout",
            "amount": {
                "value": "800.00",
                "currency": "RUB"
            }
        }]
    },
    "description": "Заказ №37",
    "income_amount": {
        "value": "955.00",
        "currency": "RUB"
    },
    "metadata": {
        "order_id": "37"
    },
    "payment_method": {
        "type": "bank_card",
        "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
        "saved": false,
        "card": {
            "first6": "555555",
            "last4": "4477",
            "expiry_month": "01",
            "expiry_year": "2030",
            "card_type": "MasterCard",
            "issuer_country": "US"
        },
        "title": "Bank card *4477"
    },
  "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
    },
    "refundable": true,
    "refunded_amount": {
        "value": "0.00",
        "currency": "RUB"
    },
    "test": true
}

Когда платеж перейдет в статус succeeded, ЮKassa пополнит баланс сделки. На балансе сделки окажется общая сумма платежа за вычетом эквайринговой комиссии ЮKassa, в параметре payout_balance — сумма вознаграждения продавца. Теперь вы можете делать выплату продавцу.

Пример сделки после пополнения баланса

JSON
{
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
  "balance": {
    "value": "955.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "opened",
  "created_at": "2021-06-22T21:42:47.672298Z",
  "expires_at": "2021-06-24T21:42:47.672321Z",
  "metadata": {
    "order_id": "37"
  },
  "description": "SAFE_DEAL 123554642-2432FF344R",
  "test": true
}

Шаг 3. Получите данные для выплаты

Чтобы провести выплату, вам нужно получить данные банковской карты продавца. Получение и хранение номера карты подпадает под действие стандарта PCI DSS, поэтому ЮKassa хранит эти данные на своей стороне.

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

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

Пример кода

HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Получение данных банковской карты продавца с помощью виджета ЮKassa</title>

  
  <script src="https://static.yoomoney.ru/payouts-data-widget-front/widget.js"></script>
 </head>
 <body>
  <p>Ниже отобразится форма для ввода номера банковской карты.</p>

  
  <div id="payout-form"></div>

  <script>
  //Инициализация виджета. Все параметры обязательные.
  const payoutsData = new window.PayoutsData({
    successCallback(data) {
      //Обработка ответа с токеном карты
      console.log(data)
    },
    errorCallback(error) {
      //Обработка ошибок
      console.log(error)
    }
  });

  //Отображение платежной формы в контейнере
  payoutsData.render('payout-form')
    //После отображения платежной формы метод render возвращает Promise (можно не использовать).
    .then(() => {
      //Код, который нужно выполнить после отображения платежной формы.
  });
  </script>
 </body>
</html>

Шаг 4. Сделайте выплату продавцу

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

1. Создайте выплату

Отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для выплаты на банковскую карту:

в объекте amount передайте сумму, которую нужно выплатить продавцу;
в параметре payout_token передайте синоним банковской карты продавца;
в объекте deal передайте идентификатор сделки.

Пример запроса на создание выплаты

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "800.00",
          "currency": "RUB"
        },
        "payout_token": "<Синоним банковской карты>",
        "description": "Выплата по заказу №37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-28646d17-0022-5000-8000-01e154d1324b"
        }
      }'

В ответ на запрос ЮKassa вернет созданный объект выплаты.

Пример созданного объекта выплаты

JSON
{
    "id": "po-28646e56-0003-5000-a000-07be7831c61d",
    "amount": {
        "value": "800.00",
        "currency": "RUB"
    },
    "status": "pending",
    "payout_destination": {
        "type": "bank_card",
        "card": {
            "first6": "510621",
            "last4": "1882",
            "card_type": "MasterCard",
            "issuer_country": "RU",
            "issuer_name": "YOOMONEY NBCO LLC"
        }
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-22T21:48:06.819Z",
    "deal": {
        "id": "dl-28646d17-0022-5000-8000-01e154d1324b"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": true
}

2. Дождитесь подтверждения, что выплата успешна

Дождитесь, когда банк получателя согласует выплату и ЮKassa изменит статус объекта выплаты на succeeded. При необходимости периодически отправляйте ЮKassa запросы на получение информации о выплате.

Пример успешно проведенной выплаты

JSON
{
    "id": "po-28646e56-0003-5000-a000-07be7831c61d",
    "amount": {
        "value": "800.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "bank_card",
        "card": {
            "first6": "510621",
            "last4": "1882",
            "card_type": "MasterCard",
            "issuer_country": "RU",
            "issuer_name": "YOOMONEY NBCO LLC"
        }
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-22T21:48:06.819Z",
    "deal": {
        "id": "dl-28646d17-0022-5000-8000-01e154d1324b"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": true
}

После успешной выплаты ЮKassa автоматически выплатит вознаграждение платформы и закроет сделку.

Пример закрытой сделки

JSON
{
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "id": "dl-28646d17-0022-5000-8000-01e154d1324b",
  "balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "0.00",
    "currency": "RUB"
  },
  "status": "closed",
  "created_at": "2021-06-22T21:42:47.672298Z",
  "expires_at": "2021-06-24T21:42:47.672321Z",
  "metadata": {
    "order_id": "37"
  },
  "description": "SAFE_DEAL 123554642-2432FF344R",
  "test": true
}

Готово! Вы провели свою первую Безопасную сделку с помощью ЮKassa.

Дальнейшие шаги

Ознакомьтесь с основами работы с API. Если проводили сделку для тестовой интернет-площадки, получите идентификатор и секретный ключ настоящей интернет-площадки.

Ознакомьтесь с деталями интеграции Безопасной сделки:

Общий сценарий интеграции: какие этапы еще могут быть, кроме тех, которые были в этой статье, какие из этапов нужно выполнять в строгой последовательности, а какие — нет.
Заключение сделки: дополнительные параметры, которые можно передать в запросе, условия закрытия сделки.
Прием оплаты от покупателя: какие есть возможности, отличия от стандартного процесса оплаты, примеры проведения платежей в рамках сделки.
Возврат оплаты покупателю: какие есть особенности возврата для разных сценариев проведения сделки, что важно учесть при возврате.
Отправка данных для чеков (если используете решение ЮKassa для работы по 54-ФЗ): когда нужно формировать чеки, какие данные нужны и как их отправлять.
Выплаты продавцу: какие есть возможности и ограничения, как провести выплату, какие могут быть причины отмены выплаты.

Выберите те возможности ЮKassa, которые вам нужны, и проинтегрируйтесь в соответствии с инструкциями.

Что почитать еще

Справочник API Входящие уведомления Тестирование Безопасной сделки