API ЮKassa
Инструкции
Старые версии API
Помощь
Подключить ЮKassa
Справочник
API ЮKassa: Инструкции
API ЮKassa: Справочник
Старые версии API
Помощь

|

Подключить ЮKassa
English
Универсальный токен для платежей и выплат
С помощью ЮKassa вы можете получить специальный токен банковской карты, который можно использовать одновременно для приема платежей и проведения выплат.
Как это работает
Универсальный токен — это сохраненный способ оплаты, который используется для автоплатежей.
Чтобы получить универсальный токен, вам нужно сохранить способ оплаты — привязать банковскую карту пользователя к вашему магазину. Для этого нужно провести успешный платеж. Идентификатором сохраненного способа оплаты станет идентификатор успешно проведенного платежа. Этот идентификатор и есть универсальный токен.
Чтобы сделать выплату, вам нужно передать идентификатор сохраненного способа оплаты в запросе на создание выплаты, а чтобы сделать платеж  — передать идентификатор в запросе на создание платежа. Платежи с использованием идентификатора сохраненного способа оплаты будут безакцептными — пользователю не нужно будет подтверждать списание денег.
Сохранить способ оплаты можно двумя способами: сделать платеж на минимальную сумму, а затем отменить его, чтобы деньги вернулись пользователю, или сохранить способ оплаты во время оплаты товара или услуги.
Для платежа с сохранением способа оплаты можно использовать любой сценарий интеграции, если там есть оплата банковской картой. Рекомендуется выбрать те варианты интеграции, где есть только карта и нет других способов оплаты. Рекомендуемые варианты интеграции приведены в разделе Подготовка к интеграции этой статьи.
Общий сценарий создания и использования токена
Сначала сохраните способ оплаты, затем используйте его при выплатах и платежах.
Сохранение способа оплаты
Общий сценарий сохранения способа оплаты
  1. Вы сообщаете пользователю, что сохраните данные его банковской карты и будете их использовать для платежей и выплат.
  2. Пользователь соглашается с условиями.
  3. Вы создаете платеж — отправляете ЮKassa POST-запрос с указанием, что нужно сохранить способ оплаты.
  4. ЮKassa возвращает вам созданный объект платежа в статусе pending и ссылку на страницу оплаты.
  5. Вы перенаправляете пользователя на страницу оплаты.
  6. Пользователь вводит данные банковской карты.
  7. ЮKassa передает данные эквайеру.
  8. При необходимости эквайер просит пользователя пройти аутентификацию по 3-D Secure.
  9. Пользователь проходит проверку.
  10. Эквайер сообщает ЮKassa результаты проведения платежа.
  11. ЮKassa сообщает пользователю результаты проведения платежа.
  12. Пользователь возвращается на ваш сайт.
  13. Вы запрашиваете информацию о платеже — отправляете ЮKassa GET-запрос с идентификатором платежа.
  14. ЮKassa возвращает вам созданный объект платежа в актуальном статусе — waiting_for_capture (деньги авторизованы и ожидают списания) или canceled (платеж отменен).
  15. Если объект в статусе waiting_for_capture, вы проверяете, что способ оплаты сохранен, и сохраняете идентификатор способа оплаты.
  16. Вы отменяете платеж — отправляете ЮKassa POST-запрос с идентификатором платежа.
  17. ЮKassa возвращает вам объект платежа в статусе canceled.
  18. Вы отображаете пользователю результат сохранения способа оплаты.
Выплата
Общий сценарий проведения выплаты с использованием сохраненного способа оплаты
  1. Вы создаете выплату — отправляете ЮKassa POST-запрос с идентификатором сохраненного способа оплаты.
  2. ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
  3. Эквайер обрабатывает запрос и сообщает результат выполнения операции.
  4. ЮKassa возвращает вам объект выплаты с финальным статусом — succeeded (выплата успешна) или canceled (выплата отменена).
Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе pending, это значит, что эквайер еще обрабатывает распоряжение на перевод. Чтобы узнать финальный статус, повторяйте запрос на проведение выплаты с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).
Платеж с использованием сохраненного способа оплаты
Общий сценарий проведения платежа с использованием сохраненного способа оплаты
  1. Вы создаете платеж — отправляете ЮKassa POST-запрос с идентификатором сохраненного способа оплаты.
  2. ЮKassa отправляет эквайеру распоряжение на списание денег с банковской карты пользователя.
  3. Эквайер обрабатывает запрос и сообщает результат выполнения операции.
  4. ЮKassa возвращает вам объект платежа с финальным статусом — succeeded (платеж успешен) или canceled (платеж отменен).
Если вы проводите платеж в две стадии, платеж вернется в статусе waiting_for_capture (деньги авторизованы и ожидают списания) или canceled (платеж отменен). Если платеж в статусе waiting_for_capture, для завершения платежа вам нужно списать оплату или отменить платеж.
Подготовка к интеграции
Для подключения сообщите менеджеру ЮKassa, что хотите принимать платежи и проводить выплаты с использованием универсального токена. Менеджер при необходимости создаст вам магазин или шлюз (если у вас их не было).
Формат взаимодействия
Формат взаимодействия для платежей и выплат одинаковый, отличие только в данных для аутентификации запросов: для приема платежей нужно использовать логин и секретный ключ магазина, а для проведения выплат — логин и секретный ключ шлюза.
Подготовка к сохранению способа оплаты и приему платежей
Что нужно для приема платежей:
Подготовка к проведению выплат
Вам нужно получить идентификатор шлюза и секретный ключ и реализовать проведение выплаты с использованием сохраненного способа оплаты. Дополнительно согласовывать ничего не надо.
Сохранение способа оплаты
Чтобы сохранить способ оплаты, нужно в запросе на создание платежа передать параметр save_payment_method со значением true.
Есть два варианта, как сохранить способ оплаты:
Только сохранение способа оплаты
Шаг 1. Сообщите пользователю, что ему нужно привязать к вашему сервису свою банковскую карту. Подробно расскажите, что это значит и как это работает:
  • Как вы будете использовать данные этой карты: с какой регулярностью вы будете списывать деньги и делать выплаты, на какую сумму.
  • Что нужно сделать для привязки: расскажите, что пользователю нужно сделать платеж на минимальную сумму. Для оплаты нужно использовать ту карту, которую он хочет привязать к вашему сервису. Деньги потом вернутся ему на счет.
  • Как можно отказаться от использования карты для платежей и выплат.
Получите от пользователя согласие на привязку его карты для проведения выплат и безакцептных платежей.
Шаг 2. Когда пользователь перейдет к привязке банковской карты, начните проводить платеж с сохранением способа оплаты в соответствии с выбранным сценарием интеграции. В запросе на создание платежа дополнительно передайте параметр save_payment_method со значением true, чтобы сохранить способ оплаты, и параметр capture со значением 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": "1.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "capture": false,
        "save_payment_method": true,
        "description": "Оплата заказа №37",
        "metadata": {
          "order_id": "37"
        }
      }'
Шаг 3. Если платеж вернулся в статусе pending и с параметром confirmation_url, перенаправьте пользователя на confirmation_url для подтверждения платежа.
Пример платежа в статусе pending
JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "pending",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Оплата заказа №37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": false
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.com/return_url",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2a217a2d-000f-5000-9000-1bd6f124af9c"
  },
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  }
}
Шаг 4. Дождитесь, когда пользователь подтвердит оплату и платеж перейдет в статус waiting_for_capture. Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
Шаг 5. Убедитесь, что оплата была банковской картой и способ оплаты сохранен: в объекте платежа параметр payment_method.type со значением bank_card, а значение параметра payment_method.saved изменилось на true.
Пример платежа в статусе waiting_for_capture
JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "waiting_for_capture",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Оплата заказа №37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": true,
    "title": "Bank card *4444",
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "12",
      "card_type": "MasterCard",
      "issuer_country": "RU"
    }
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "expires_at": "2022-06-02T11:37:55.385Z",
  "test": false,
  "paid": true,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  }
}
Шаг 6. Сохраните идентификатор способа оплаты payment_method.id. Этот идентификатор и будет универсальным токеном. Его нужно будет использовать при проведении выплат и безакцептных платежей.
Шаг 7. Отмените платеж .
Пример запроса на отмену платежа
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{

      }'
Пример платежа в статусе canceled
JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "canceled",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Оплата заказа №37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": true,
    "title": "Bank card *4444",
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "12",
      "card_type": "MasterCard",
      "issuer_country": "RU"
    }
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  },
  "cancellation_details": {
    "party": "merchant",
    "reason": "canceled_by_merchant"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  }
}
Шаг 8. Сообщите пользователю результаты сохранения данных банковской карты.
Платеж с сохранением способа оплаты
Шаг 1. Сообщите пользователю, что при оплате сохраните данные его банковской карты. Подробно расскажите, что это значит и как это работает:
  • Как вы будете использовать данные этой карты: с какой регулярностью вы будете списывать деньги и делать выплаты, на какую сумму.
  • Как можно отказаться от использования карты для платежей и выплат.
Получите от пользователя согласие на привязку его карты для проведения выплат и безакцептных платежей.
Шаг 2. Когда пользователь перейдет к оплате товара или услуги, начните проводить платеж с сохранением способа оплаты в соответствии с выбранным сценарием интеграции. В запросе на создание платежа дополнительно передайте параметр save_payment_method со значением true.
Пример платежа банковской картой с сохранением способа оплаты
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "1.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "capture": false,
        "save_payment_method": true,
        "description": "Оплата заказа №37",
        "metadata": {
          "order_id": "37"
        }
      }'
Шаг 3. Если платеж вернулся в статусе pending и с параметром confirmation_url, перенаправьте пользователя на confirmation_url для подтверждения платежа.
Пример платежа в статусе pending
JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "pending",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Оплата заказа №37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": false
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.com/return_url",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2a217a2d-000f-5000-9000-1bd6f124af9c"
  },
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  }
}
Шаг 4. Дождитесь, когда пользователь подтвердит оплату и платеж перейдет в статус succeeded или waiting_for_capture (если проводили платеж в две стадии). Чтобы узнать статус платежа, подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .
Шаг 5. Убедитесь, что оплата была банковской картой и способ оплаты сохранен: в объекте платежа параметр payment_method.type со значением bank_card, а значение параметра payment_method.saved изменилось на true.
Пример платежа в статусе waiting_for_capture
JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "waiting_for_capture",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Оплата заказа №37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": true,
    "title": "Bank card *4444",
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "12",
      "card_type": "MasterCard",
      "issuer_country": "RU"
    }
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "expires_at": "2022-06-02T11:37:55.385Z",
  "test": false,
  "paid": true,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  }
}
Шаг 6. Сохраните идентификатор способа оплаты payment_method.id. Этот идентификатор и будет универсальным токеном. Его нужно будет использовать при проведении выплат и безакцептных платежей.
Шаг 7. Если платеж проходит в две стадии, подтвердите или отмените платеж.
Шаг 8. Сообщите пользователю результаты платежа.
Проведение выплаты
Создайте выплату 
: отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для выплаты на банковскую карту с использованием сохраненного способа оплаты:
  • в объекте amount передайте сумму, которую нужно выплатить пользователю; сумма должна укладываться в лимиты;
  • в параметре description передайте описание выплаты;
  • в параметре payment_method_id передайте идентификатор сохраненного способа оплаты.
Пример запроса на создание выплаты
cURL
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор шлюза>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "100.00",
          "currency": "RUB"
        },
        "payment_method_id": "<Идентификатор сохраненного способа оплаты>",
        "description": "Выплата по заказу №1",
        "metadata": {
          "order_id": "37"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект выплаты .
Пример созданного объекта выплаты
JSON
{
  "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
  "amount": {
    "value": "100.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. Для этого повторяйте запрос с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом.
Пример запроса на получение информации о выплате
cURL
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Идентификатор шлюза>:<Секретный ключ> \
Пример объекта выплаты в статусе succeeded
JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "100.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",
    "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": "Заказ №105"
      }'
В ответ на запрос ЮKassa вернет созданный объект платежа . При успешной оплате в объекте payment_method будет отображаться информация о платежных данных сохраненного способа, который вы использовали при платеже.
Пример платежа в статусе succeeded
JSON
{
  "id": "255350c9-000f-5000-a000-1f211b3ea0a7",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "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": "MasterCard",
      "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
Юридические документы
Правила работы сервиса ЮKassaСоглашение об ЭДО
Вы не разработчик?
Модули для CMSВыставление счетовПлатежи для лендингов
8 800 250-66-99
Задать вопросПомощь
© 2023, ООО НКО «ЮМани»