Сплитование платежей: прием оплаты — Прием платежей по API ЮKassa

Прием платежей

Если вы используете Сплитование платежей, вы можете в одном платеже принимать оплату товаров из разных магазинов. Также вам доступна возможность взимать с магазинов комиссию за проданные товары и услуги. Для этого нужно передать ЮKassa один общий запрос на создание платежа с дополнительными данными о том, как распределить деньги между магазинами и какую комиссию с каждого из них удержать.

Сценарий взаимодействия

Отправьте ЮKassa запрос на создание платежа, передайте в нём все необходимые параметры, включая данные о распределении денег между магазинами и о комиссии, которую вы хотите удержать.
При необходимости инициируйте сценарий подтверждения платежа пользователем.
Если вы проводите платеж в две стадии, подтвердите, что вы готовы принять платеж. На этом этапе вы можете изменить размер комиссии или отказаться от нее.

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

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

Чтобы принять платеж от пользователя, отправьте ЮKassa запрос на создание платежа . В запросе передайте сумму платежа в параметре amount, данные для оплаты выбранным способом и данные о распределении денег между магазинами в двух форматах:

для перечисления денег продавцам: массив transfers с данными о магазинах ЮKassa, между которыми распределяете оплату, суммой вашей комиссии (при необходимости) и дополнительной информацией, которая отобразится у продавца в личном кабинете;
для отображения пользователю при оплате: параметр description с информацией о продавцах, которым ЮKassa перечислит деньги. Для каждого продавца необходимо указать его юридическое наименование и перечисляемую сумму, например: ООО «Компания» 900 руб.Дополнительно в этом параметре вы можете передать любую другую информацию, которую пользователь увидит при оплате, например номер заказа.

При необходимости вы можете передать для каждого магазина дополнительные данные, например номер заказа или перечень товаров. ЮKassa вернет их без изменений. Данные необходимо передавать в массиве transfers в объекте metadata в виде набора пар «ключ-значение».

В запрос можно добавить дополнительные параметры , кроме объекта receipt. Если вы используете решение ЮKassa для работы по 54-ФЗ, передавайте данные для формирования чека в отдельном запросе.

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "17000.00",
          "currency": "RUB"
        },
        "capture": false,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Заказ №1: ООО «Компания 1» 5000 руб., ООО «Компания 2» 12000 руб.",
        "transfers": [
        {
          "account_id": "123",
          "amount": {
            "value": "5000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
            "value": "50.00",
            "currency": "RUB"
          },
          "description": "Заказ маркетплейса №1",
          "metadata": {
            "order_id": "1"
          }
        },
        {
          "account_id": "456",
          "amount": {
            "value": "12000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
             "value": "120.00",
             "currency": "RUB"
          },
          "description": "Заказ маркетплейса №1",
          "metadata": {
            "order_id": "1"
          }
        }
       ]
      }'

В ответ ЮKassa отправит вам объект платежа в актуальном статусе.

Пример объекта платежа

JSON
{
  "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "17000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "created_at": "2019-08-16T10:44:12.717Z",
  "description": "Заказ №1: ООО «Компания 1» 5000 руб., ООО «Компания 2» 12000 руб.",
  "expires_at": "2019-08-23T10:44:14.664Z",
  "metadata": {
  },
  "payment_method": {
    "type": "bank_card",
    "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
    "saved": false,
    "card": {
      "ﬁrst6": "666666",
      "last4": "4444",
      "expiry_month": "06",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Tinkoff Bank"
    },
    "title": "Bank card *4444"
   },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "10001"
  },
  "transfers": [
   {
     "account_id": "123",
     "amount": {
        "value": "5000.00",
        "currency": "RUB"
     },
     "platform_fee_amount": {
        "value": "50.00",
        "currency": "RUB"
     },
     "description": "Заказ маркетплейса №1",
     "metadata": {
       "order_id": "1"
     },
     "status": "waiting_for_capture"
   },
   {
     "account_id": "456",
     "amount": {
       "value": "12000.00",
       "currency": "RUB"
     },
     "platform_fee_amount": {
        "value": "120.00",
        "currency": "RUB"
     },
     "description": "Заказ маркетплейса №1",
     "metadata": {
       "order_id": "1"
     },
     "status": "waiting_for_capture"
    }
   ],
  "refundable": false,
  "test": false
 }

Подтверждение платежа

Если вы проводите платеж в две стадии, вам необходимо его подтвердить — отправить ЮKassa запрос на подтверждение .

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

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json'

Если вы подтверждаете часть платежа (например, если в магазине нет одного или нескольких товаров) или изменяете размер взимаемой комиссии, в запросе передайте ЮKassa объект transfers с актуальным распределением денег: сколько в какой магазин нужно перевести и какую комиссию с какого магазина удержать. Объект metadata передавать не нужно: его нельзя изменить при подтверждении платежа.

Если на этапе подтверждения вы по каким-то причинам решили не удерживать комиссию, в запросе нужно передать параметр platform_fee_amount.value со значением 0.

Запрос на подтверждение платежа нужно передавать без объекта receipt. После частичного подтверждения платежа нужно сформировать два новых чека: чек возврата прихода первоначального платежа (на полную сумму) и чек прихода с учетом скорректированных данных.

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
         "amount": {
           "value": "11000.00",
           "currency": "RUB"
         },
         "transfers": [
         {
           "account_id": "123",
           "amount": {
             "value": "2000.00",
             "currency": "RUB"
           },
           "platform_fee_amount": {
              "value": "20.00",
              "currency": "RUB"
          }
         },
         {
           "account_id": "456",
           "amount": {
             "value": "9000.00",
             "currency": "RUB"
           },
           "platform_fee_amount": {
              "value": "90.00",
              "currency": "RUB"
           }
         }
        ]
      }'

При успешном подтверждении платеж перейдет в статус succeeded. Чтобы узнать текущий статус платежа, вы можете запросить информацию о платеже или настроить уведомления от ЮKassa.

Пример объекта платежа

JSON
{
  "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "11000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2019-08-16T12:23:12.849Z",
  "created_at": "2019-08-16T10:44:12.717Z",
  "description": "Заказ №1: ООО «Компания 1» 5000 руб., ООО «Компания 2» 12000 руб.",
  "metadata": {
  },
  "payment_method": {
    "type": "bank_card",
    "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
    "saved": false,
    "card": {
      "ﬁrst6": "555555",
      "last4": "4444",
      "expiry_month": "06",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Tinkoff Bank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "10001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "transfers": [
    {
       "account_id": "123",
       "amount": {
         "value": "2000.00",
         "currency": "RUB"
       },
       "platform_fee_amount": {
         "value": "20.00",
         "currency": "RUB"
       },
       "description": "Заказ маркетплейса №1",
       "metadata": {
         "order_id": "1"
       },
       "status": "succeeded"
     },
     {
       "account_id": "456",
       "amount": {
         "value": "9000.00",
         "currency": "RUB"
       },
       "platform_fee_amount": {
         "value": "90.00",
         "currency": "RUB"
       },
       "description": "Заказ маркетплейса №1",
       "metadata": {
         "order_id": "1"
       },
       "status": "succeeded"
     }
 ],
 "test": false
}

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

Получение информации о магазине продавца по API Возврат платежей Отправка чеков Оплата с соблюдением требований 54-ФЗ