Привязка на нулевую сумму — Прием платежей по API ЮKassa

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

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

Для создания привязки на нулевую сумму нужны данные карты: номер, срок действия и CVC-код. Вы можете получать их двумя способами: на стороне ЮKassa или на вашей стороне (для этого у вас должен быть сертификат на соответствие требованиям PCI DSS).

Особенности

Доступные способы оплаты

Привязка на нулевую сумму доступна только для банковских карт. Для привязки на нулевую сумму подходят карты Мир, Visa и Mastercard, выпущенные в России, и некоторые зарубежные карты.

Тестирование

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

Для партнеров

Если вы партнер и для аутентификации запросов используете OAuth-токен, вы можете привязывать платежное средство только во время платежа. Привязка на нулевую сумму для этого формата взаимодействия недоступна.

Порядок работы

Привязка на нулевую сумму проходит следующим образом:

Вы создаете привязку c данными банковской карты или без них — зависит от того, как вы их получаете (самостоятельно или на стороне ЮKassa).
ЮKassa возвращает вам идентификатор способа оплаты.[object Object][object Object] Его пока нельзя использовать для автоплатежей, нужно дождаться, когда ЮKassa проверит карту.
ЮKassa проводит аутентификацию пользователя по 3-D Secure и проверяет, что с картой всё в порядке, ее можно использовать для последующих автоплатежей.
ЮKassa привязывает банковскую карту к вашему магазину.
Вы сохраняете идентификатор способа оплаты. Он нужен, чтобы проводить автоплатежи.

Cценарий привязки на нулевую сумму

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

Сценарий привязки с вводом платежных данных на стороне ЮKassa

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

Если аутентификация пользователя по 3-D Secure не требуется, то пункты 6-8 пропускаются. Когда пользователь введет данные карты, ЮKassa сразу отправит ее на проверку в платежную систему.

Привязка с вводом платежных данных на стороне ЮKassa

Как это работает
Как создать привязку

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

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

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

Для интеграции добавьте на ваш сайт кнопку, по которой можно перейти к привязке. Когда пользователь перейдет по кнопке, получите от ЮKassa ссылку на готовую страницу привязки, и перенаправьте на неё пользователя. Срок жизни этой ссылки — 1 час. На странице привязки пользователь введет данные карты, а ЮKassa проверит, что с картой все в порядке, и отобразит результат привязки.

Страница привязки ЮKassa

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

Как создать привязку

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

Шаг 2. Создайте объект способа оплаты . Передайте в запросе следующие данные:

параметр type со значением bank_card;
объект confirmation с типом redirect и адресом страницы на вашей стороне, на которую пользователь вернется после привязки (в параметре return_url).

Пример запроса

cURL
curl https://api.yookassa.ru/v3/payment_methods \
    -X POST \
    -u <Идентификатор магазина>:<Секретный ключ> \
    -H 'Idempotence-Key: <Ключ идемпотентности>' \
    -H 'Content-Type: application/json' \
    -d '{
         "confirmation": {
           "type": "redirect",
           "return_url": "https://www.example.com/return_url"
         },
         "type": "bank_card",
       }'

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

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

JSON
{
  "type": "bank_card",
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "saved": false,
  "status": "pending",
  "holder": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/checkout/payment-methods/v1/contract?orderId=22e12f66-000f-5000-8000-18db351245c7"
  }
}

Шаг 3. Перенаправьте пользователя на confirmation_url, который придет в объект способа оплаты . Это ссылка на страницу ЮKassa, на которой пользователь введет данные карты.

Чтобы сохранить идентификатор способа оплаты:

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

Шаг 2. Убедитесь, что способ оплаты сохранен: в объекте способа оплаты будут параметры status=active и saved=true .

Если в процессе привязки возникла ошибка (например, карта заблокирована), то в объекте способа оплаты вернутся параметры status=inactive и saved=false . Для уточнения причин ошибки обратитесь в техническую поддержку ЮKassa.

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

JSON
{
  "type": "bank_card",
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "saved": true,
  "status": "active",
  "title": "Bank card *4477",
  "holder": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "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"
  }
}

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

Шаг 4. Сообщите пользователю результаты сохранения способа оплаты.

Готово!

Вы сохранили способ оплаты и теперь можете проводить автоплатежи. Также идентификатор способа оплаты можно использовать для проведения выплат (только для банковских карт).

Привязка с вводом платежных данных на вашей стороне

Как это работает
Как создать привязку

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

Чтобы использовать эту возможность, вам нужно получить сертификат на соответствие требованиям PCI DSS.

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

Для интеграции добавьте на свою страницу кнопку, по которой пользователь перейдет к привязке карты, а также форму для получения данных банковской карты. Далее всё зависит от того, используете ли вы аутентификацию по 3-D Secure:

Если используете 3-D Secure, то получите от ЮKassa ссылку на страницу аутентификации и перенаправьте по ней пользователя, а затем запросите у ЮKassa результаты привязки и сообщите их пользователю.
Если не используете 3-D Secure, то запросите результаты привязки и сообщите их пользователю.

Как создать привязку

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

Шаг 3. Создайте объект способа оплаты . Передайте в запросе следующие данные:

параметр type со значением bank_card;
объект confirmation с типом redirect и адресом страницы на вашей стороне, на которую пользователь вернется после аутентификации по 3-D Secure (в параметре return_url);
объект card с данными банковской карты.

Пример запроса

cURL
curl https://api.yookassa.ru/v3/payment_methods \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
       "confirmation": {
         "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "type": "bank_card",
        "card": {
          "cardholder": "MR CARDHOLDER",
          "csc": "213",
          "expiry_year": "2030",
          "expiry_month": "01",
          "number": "5555555555554477"
         }
      }'

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

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

JSON
{
  "type": "bank_card",
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "saved": false,
  "status": "pending",
  "title": "Bank card *4477",
  "holder": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "<URL для аутентификации по 3-D Secure>"
  }
}

Шаг 4. Перенаправьте пользователя на страницу аутентификации по 3-D Secure (ссылка на нее придет в параметре confirmation_url). Если вы отключили аутентификацию по 3-D Secure через менеджера ЮKassa, пропустите этот шаг.

Чтобы сохранить идентификатор способа оплаты:

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

Шаг 2. Убедитесь, что способ оплаты сохранен: в объекте способа оплаты будут параметры status=active и saved=true.

Если в процессе привязки возникла ошибка (например, карта заблокирована), то в объекте способа оплаты вернутся параметры status=inactive и saved=false. Для уточнения причин ошибки обратитесь в техническую поддержку ЮKassa.

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

JSON
{
  "type": "bank_card",
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "saved": true,
  "status": "active",
  "title": "Bank card *4477",
  "holder": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "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"
  }
}

Шаг 4. Сообщите пользователю результаты сохранения способа оплаты.

Готово!

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

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