Универсальный токен для платежей и выплат

Только для банковских карт

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

Как это работает

Универсальный токен — это сохраненный способ оплаты, который используется для автоплатежей или выплат.

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

Чтобы сделать выплату, вам нужно передать идентификатор способа оплаты в запросе на создание выплаты, а чтобы сделать платеж — передать идентификатор в запросе на создание платежа. Платежи с использованием идентификатора способа оплаты будут безакцептными — пользователю не нужно будет подтверждать списание денег.

Есть два вида сохранения способа оплаты:

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

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

Общий сценарий создания и использования токена

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

Сохранение способа оплаты

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

Общий сценарий сохранения способа оплаты

Вы сообщаете пользователю, что сохраните данные его банковской карты и будете их использовать для платежей и выплат.
Пользователь соглашается с условиями.
Вы создаете платеж — отправляете ЮKassa POST-запрос с указанием, что нужно сохранить способ оплаты.
ЮKassa возвращает вам созданный объект платежа в статусе pending и ссылку на страницу оплаты.
Вы перенаправляете пользователя на страницу оплаты.
Пользователь вводит данные банковской карты.
ЮKassa передает данные эквайеру.
При необходимости эквайер просит пользователя пройти аутентификацию по 3-D Secure.
Пользователь проходит проверку.
Эквайер сообщает ЮKassa результаты проведения платежа.
ЮKassa сообщает пользователю результаты проведения платежа.
Пользователь возвращается на ваш сайт.
Вы запрашиваете информацию о платеже — отправляете ЮKassa GET-запрос с идентификатором платежа.
ЮKassa возвращает вам созданный объект платежа в актуальном статусе — waiting_for_capture (деньги авторизованы и ожидают списания) или canceled (платеж отменен).
Если объект в статусе waiting_for_capture, вы проверяете, что способ оплаты сохранен, и сохраняете идентификатор способа оплаты.
Вы отменяете платеж — отправляете ЮKassa POST-запрос с идентификатором платежа.
ЮKassa возвращает вам объект платежа в статусе canceled.
Вы отображаете пользователю результат сохранения способа оплаты.

Выплата

Общий сценарий проведения выплаты с использованием сохраненного способа оплаты

Вы создаете выплату — отправляете ЮKassa POST-запрос с идентификатором способа оплаты.
ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
Эквайер обрабатывает запрос и сообщает результат выполнения операции.
ЮKassa возвращает вам объект выплаты с финальным статусом — succeeded (выплата успешна) или canceled (выплата отменена).

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

Платеж с использованием сохраненного способа оплаты

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

Вы создаете платеж — отправляете ЮKassa POST-запрос с идентификатором способа оплаты.
ЮKassa отправляет эквайеру распоряжение на списание денег с банковской карты пользователя.
Эквайер обрабатывает запрос и сообщает результат выполнения операции.
ЮKassa возвращает вам объект платежа с финальным статусом — succeeded (платеж успешен) или canceled (платеж отменен).

Если вы проводите платеж в две стадии, платеж вернется в статусе waiting_for_capture (деньги авторизованы и ожидают списания) или canceled (платеж отменен). Если платеж в статусе waiting_for_capture, для завершения платежа вам нужно списать оплату или отменить платеж.

Подготовка к интеграции

Для подключения сообщите менеджеру ЮKassa, что хотите принимать платежи и проводить выплаты с использованием универсального токена. Менеджер при необходимости создаст вам магазин или шлюз (если у вас их не было).

Формат взаимодействия

Формат взаимодействия для платежей и выплат одинаковый, отличие только в данных для аутентификации запросов: для приема платежей нужно использовать логин и секретный ключ магазина, а для проведения выплат — логин и секретный ключ шлюза.

Подготовка к сохранению способа оплаты и приему платежей

Что нужно для приема платежей:

Получить идентификатор магазина и секретный ключ.
Согласовать с менеджером ЮKassa использование автоплатежей.
Настроить уведомления.
Выбрать вид сохранения способа оплаты:
- Привязка во время платежа (с последующей отменой платежа при необходимости)
- Привязка на нулевую сумму
Выбрать сценарий интеграции. Рекомендуется использовать те варианты интеграции, где есть только банковская карта:
- Оплата банковской картой на готовой странице ЮKassa
- Виджет ЮKassa в виде отдельной формы для оплаты банковской картой (доступно только после согласования с менеджером)
- Checkout.js (нужно согласовать с менеджером)
- Оплата банковской картой в вашей платежной форме (нужен сертификат соответствия PCI DSS)
Реализовать сохранение способа оплаты.
Реализовать проведение автоплатежа (платеж с использованием сохраненного способа оплаты).

Подготовка к проведению выплат

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

Сохранение способа оплаты

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

Шаг 1. Сообщите пользователю, что ему нужно привязать к вашему сервису свою банковскую карту. Подробно расскажите, что это значит и как это работает:

Как вы будете использовать данные этой карты: с какой регулярностью вы будете списывать деньги и делать выплаты, на какую сумму.
Как можно отказаться от использования карты для платежей и выплат.

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

Шаг 3. Сохраните способ оплаты подходящим вам способом:

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

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

Шаг 5. Сохраните полученный идентификатор способа оплаты. Рекомендуется сохранять его в связке с идентификатором пользователя в вашей системе. Это нужно, чтобы в дальнейшем вы могли соотнести пользователя и его платежные данные.

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

Для аутентификации запроса нужно использовать идентификатор и секретный ключ вашего шлюза ЮKassa для выплат.

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

в объекте amount передайте сумму, которую нужно выплатить пользователю; сумма должна укладываться в лимиты;
в параметре description передайте описание выплаты;
в параметре payment_method_id передайте идентификатор сохраненного способа оплаты.

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

cURL

PHP

Python

curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор шлюза>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "5.00",
          "currency": "RUB"
        },
        "payment_method_id": "<Идентификатор сохраненного способа оплаты>",
        "description": "Выплата по заказу №37",
        "metadata": {
          "order_id": "37"
        }
      }'

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

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

JSON

{
  "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
  "amount": {
    "value": "5.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "555555",
      "last4": "4477",
      "card_type": "Mir",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
  },
  "description": "Выплата по заказу №37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "metadata": {
    "order_id": "37"
  },
  "test": false
}

Если вы получили объект выплаты в статусе pending, дождитесь, когда статус изменится на succeeded или canceled. Для этого подождите, когда придет уведомление от ЮKassa, или запрашивайте информацию о выплате с возрастающим разумным интервалом.

Пример запроса на получение информации о выплате

cURL

PHP

Python

curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Идентификатор шлюза>:<Секретный ключ> \

Пример объекта выплаты в статусе succeeded

JSON

{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "5.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "bank_card",
        "card": {
          "first6": "555555",
          "last4": "4477",
          "card_type": "Mir",
          "issuer_country": "RU",
          "issuer_name": "Sberbank Of Russia"
        }
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "succeeded_at": "2021-06-21T14:29:17.141Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}

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

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

в объекте amount передайте сумму, которую нужно списать с карты пользователя;
в параметре description передайте описание платежа;
в параметре payment_method_id передайте идентификатор сохраненного способа оплаты;
в параметре capture передайте значение true, если хотите провести платеж в одну стадию и сразу списать деньги, и значение false, если хотите провести платеж в две стадии и списать деньги потом.

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

cURL

PHP

Python

curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "capture": true,
        "payment_method_id": "<Идентификатор сохраненного способа оплаты>",
        "description": "Заказ №37"
      }'

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

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

JSON

{
  "id": "255350c9-000f-5000-a000-1f211b3ea0a7",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "603668680243",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2018-07-18T17:20:50.825Z",
  "created_at": "2018-07-18T17:18:39.345Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22e18a2f-000f-5000-a000-1db6312b7767",
    "saved": true,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "test": false
}

Если проводите платеж в две стадии, подтвердите или отмените платеж.

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

Выплаты на банковские карты

Выплаты самозанятым

Тестирование выплат

Неуспешные выплаты

Коды ответа (состояния) HTTP