Банковская карта

Особенности

Тип способа оплаты в API: bank_card
Сценарий подтверждения: Redirect
Срок оплаты: 1 час
Холдирование: 7 дней, доступно полное и частичное списание оплаты
Код в реестре: AC
Возврат: да, полный и частичный
Срок возврата: от 0 до 3 дней (зависит от эмитента)
Автоплатежи: да
Лимиты: минимальный размер платежа — 1 рубль, максимальный — 350 000 рублей, есть дополнительные ограничения

Сценарии интеграции

Готовые решения:

Умный платеж
MCP-сервер ЮKassa
Виджет ЮKassa
Мобильные SDK для iOS и Android
Платежная форма для веба в вашем дизайне — Checkout.js

Самостоятельная интеграция:

Оплата на странице ЮKassa
Оплата с вводом данных на вашей стороне (PCI-DSS)
Управление 3-D Secure

Оплата на странице ЮKassa

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

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

Какие способы оплаты доступны:

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

Пример платежной формы

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

Как провести платеж

Шаг 1. Создайте платеж, в объекте payment_method_data передайте тип bank_card, в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую вернется пользователь (в параметре return_url).

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

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"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Заказ №72"
      }'

Шаг 2. Перенаправьте пользователя на страницу ЮKassa (ссылка на нее придет в параметре confirmation_url). На этой странице пользователь введет данные карты и подтвердит платеж.

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

JSON

{
  "id": "22c5d173-000f-5000-9000-1bdf241d4651",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://www.example.com/return_url",
    "confirmation_url": "https://yoomoney.ru/payments/external/confirmation?orderId=22c5d173-000f-5000-9000-1bdf241d4651"
  },
  "created_at": "2021-04-12T13:59:33.681Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22c5d173-000f-5000-9000-1bdf241d4651",
    "saved": false
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

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

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

Если пользователь ввел данные банковской карты, в объекте payment_method вернется код способа оплаты bank_card.

Пример успешного платежа при оплате банковской картой

JSON

{
  "id": "22c5d173-000f-5000-9000-1bdf241d4651",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "description": "Заказ №72",
  "captured_at": "2021-04-12T13:59:33.681Z",
  "created_at": "2021-04-12T13:49:33.026Z",
  "income_amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "Mir",
      "card_product": {
          "code": "MCP",
          "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    }
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false,
  "authorization_details": {
    "rrn": "603668680243",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": false
    }
  },
  "metadata": {}
}

Если пользователь провел оплату через Mir Pay, в объекте payment_method вернется код способа оплаты bank_card, в параметре card.source вернется значение mir_pay.

Пример успешного платежа через Mir Pay

JSON

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "captured_at": "2021-04-12T13:59:33.681Z",
  "created_at": "2021-04-12T13:49:33.026Z",
  "income_amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "Sberbank",
      "source": "mir_pay"
    }
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false,
  "authorization_details": {
    "rrn": "603668680243",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": false
    }
  }
}

Если при оплате пользователь выбрал SberPay, в объекте payment_method вернется код способа оплаты sberbank.

Пример успешного платежа через SberPay

JSON

{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"succeeded",
   "paid":true,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "captured_at":"2021-04-13T09:27:09.960Z",
   "created_at":"2021-04-13T09:25:13.087Z",
   "description":"Заказ №72",
   "income_amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "payment_method":{
      "type":"sberbank",
      "id":"22e12f66-000f-5000-8000-18db351245c7",
      "saved":false,
      "card":{
         "first6":"555555",
         "last4":"4444",
         "expiry_year":"2022",
         "expiry_month":"07",
         "card_type":"MasterCard"
         }
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":true,
   "refunded_amount":{
      "value":"0.00",
      "currency":"RUB"
   },
   "test":false,
   "authorization_details":{
     "rrn":"10000000000",
     "auth_code":"000000",
     "three_d_secure":{
       "applied":false
     }
   }
}

Готово!

Оплата с вводом данных на вашей стороне

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

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

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

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

Как провести платеж

Шаг 1. Создайте платеж, в объекте payment_method_data передайте тип bank_card и объект card с данными банковской карты, в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).

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

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"
        },
        "payment_method_data": {
          "type": "bank_card",
          "card": {
            "cardholder": "MR CARDHOLDER",
            "csc": "213",
            "expiry_month": "01",
            "expiry_year": "2030",
            "number": "5555555555554477"
          }
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Заказ №72"
      }'

Шаг 2. Перенаправьте пользователя на страницу аутентификации по 3-D Secure (ссылка на нее придет в параметре confirmation_url).

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

JSON

{
    "id": "22c5d173-000f-5000-9000-1bdf241d4651",
    "status": "pending",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "description": "Заказ №72",
    "payment_method": {
        "type": "bank_card",
        "id": "22c5d173-000f-5000-9000-1bdf241d4651",
        "saved": false,
        "title": "Bank card *4477",
        "card": {
            "first6": "555555",
            "last4": "4477",
            "expiry_month": "01",
            "expiry_year": "2030",
            "card_type": "Mir",
            "card_product": {
              "code": "MCP",
              "name": "MIR Privilege"
            },
            "issuer_country": "RU",
            "issuer_name": "Sberbank"
    },
    "created_at": "2021-04-12T13:49:33.026Z",
    "confirmation": {
        "type": "redirect",
        "confirmation_url": "<URL для аутентификации по 3-D Secure>"
    },
    "test": true,
    "paid": false,
    "refundable": false,
    "metadata": {}
}

Пример успешного платежа

JSON

{
  "id": "22c5d173-000f-5000-9000-1bdf241d4651",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "description": "Заказ №72",
  "captured_at": "2021-04-12T13:59:33.681Z",
  "created_at": "2021-04-12T13:49:33.026Z",
  "income_amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "Mir",
      "card_product": {
          "code": "MCP",
          "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    }
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false,
  "authorization_details": {
    "rrn": "603668680243",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": false
    }
  },
  "metadata": {}
}

Готово!

Управление 3-D Secure

Нужно согласовать с менеджером ЮKassa.

Вы можете отключить 3-D Secure, тогда передавать объект confirmation не нужно. Если вы хотите запросить прохождение 3-D Secure пользователем, в объекте confirmation передайте тип redirect, адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url) и параметр enforce со значением true.

Особые требования

Для некоторых типов платежей нужно передавать дополнительные данные:

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

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

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

Неуспешные платежи

Отправка чеков в налоговую

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