NAV Navbar
cURL PHP Python
  • Быстрый старт
  • Платежи
  • Способы оплаты
  • Оплата по 54-ФЗ
  • Уведомления
  • Тестирование
  • Реестры
  • Быстрый старт

    Мы предполагаем, что если вы здесь, значит, вы уже зарегистрировались в Яндекс.Кассе, у вас есть аккаунт в личном кабинете и секретный ключ, сгенерированный в настройках.

    1. Создайте платеж и получите ссылку для оплаты
    2. Перенаправьте пользователя на страницу оплаты
    3. Дождитесь уведомления о платеже
    4. Подтвердите готовность его принять

    Шаг 1. Создайте платеж с выбором способа оплаты на стороне Яндекс.Кассы

    <Идентификатор магазина> — shopId в личном кабинете.

    <Секретный ключ> выпустите по инструкции.

    В качестве <Ключа идемпотентности> используйте любое значение, уникальное для этого запроса. Мы рекомендуем v4 UUID.

    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "confirmation": {
              "type": "redirect",
              "return_url": "https://www.merchant-website.com/return_url"
            }
          }'
    
    <?php
        use YandexCheckout\Client;
    
        $client = new Client();
        $client->setAuth('<Идентификатор магазина>', '<Секретный ключ>');
        $payment = $client->createPayment(
            array(
                'amount' => array(
                    'value' => 2.0,
                    'currency' => 'RUB'
                ),
                'confirmation' => array(
                    'type' => 'redirect',
                    'return_url' => 'https://www.merchant-website.com/return_url',
                ),
            ),
            uniqid('', true)
        );
    ?>
    
    from yandex_checkout import Configuration, Payment
    
    Configuration.account_id = <Идентификатор магазина>
    Configuration.secret_key = <Секретный ключ>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://www.merchant-website.com/return_url"
        }
    })
    

    Если вы отправляете запрос на создание платежа и не указываете конкретный способ оплаты (payment_method), пользователь сможет выбрать способ оплаты на стороне Яндекс.Кассы. В запросе нужно передать сумму, валюту и URL страницы на вашей стороне, на которую пользователь вернется после оплаты.

    Шаг 2. Перенаправьте пользователя на страницу в Яндекс.Кассе

    Пример тела ответа

    {
      "id": "21740069-000f-50be-b000-0486ffbf45b0",
      "status": "pending",
      "paid": false,
      "amount": {
        "value": "2.00",
        "currency": "RUB"
      },
      "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=21740069-000f-50be-b000-0486ffbf45b0"
      },
      "created_at": "2017-10-14T10:53:29.072Z",
      "metadata": {}
    }
    

    Перенаправьте пользователя на confirmation_url, полученный в теле ответа.

    Шаг 3. Дождитесь уведомления о платеже

    Уведомление от Яндекс.Кассы о переходе платежа в статус waiting_for_capture

    {
      "type": "notification",
      "event": "payment.waiting_for_capture",
      "object": {
        "id": "21740069-000f-50be-b000-0486ffbf45b0",
        "status": "waiting_for_capture",
        "paid": true,
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "created_at": "2017-10-14T10:53:29.072Z",
        "metadata": {},
        "payment_method": {
          "type": "yandex_money",
          "id": "731714f2-c6eb-4ae0-aeb6-8162e89c1065",
          "saved": false,
          "account_number": "410011066000000",
          "title": "Yandex.Money wallet 410011066000000"
        }
      }
    }
    

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

    Статус waiting_for_capture означает, что платеж прошел успешно. Теперь вам нужно подтвердить готовность принять платеж.

    Шаг 4. Подтвердите платеж или отмените

    Подтверждение платежа. В качестве payment_id необходимо указать id платежа, полученный от Яндекс.Кассы

    curl https://payment.yandex.net/api/v3/payments/{payment_id}/capture \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json'
    
    <?php
        $payment = $notification->getObject();
        $client->capturePayment(
            array(
                'amount' => $payment->amount,
            ),
            $payment->id,
            uniqid('', true)
        );
    ?>
    
    Payment.capture(payment_id)
    

    После того, как платеж перейдет в статус waiting_for_capture, у вас есть:

    Когда это время пройдет, платеж автоматически будет отменен и перейдет в статус canceled.

    Подтвердить платеж можно с помощью метода capture. В запросе передается окончательная сумма оплаты и валюта. После этого платеж перейдет в статус succeeded и деньги будут зачислены на ваш расчетный счет (по условиям договора с Яндекс.Кассой).

    Если вы не готовы принять платеж, вам необходимо его отменить с помощью метода cancel.

    Платежи

    Пример объекта платежа (Payment) в статусе succeeded

    {
      "id": "215d8da0-000f-50be-b000-0003308c89be",
      "status": "succeeded",
      "paid": true,
      "amount": {
        "value": "4.00",
        "currency": "RUB"
      },
      "charge": {
        "value": "4.00",
        "currency": "RUB"
      },
      "created_at": "2017-09-27T10:13:52.588Z",
      "metadata": {},
      "payment_method": {
        "type": "bank_card",
        "id": "012b57fe-1904-493a-a2de-48cd42c4f356",
        "saved": false,
        "card": {
          "last4": "4448",
          "expiry_month": "04",
          "expiry_year": "2020",
          "card_type": "MasterCard"
        },
        "title": "Bank card *4448"
      }
    }
    

    Объект платежа (Payment) — основная сущность для работы с приемом платежей. У платежа линейный жизненный цикл, он последовательно переходит из статуса в статус.

    Статусы платежа

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

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

    Для создания объекта платежа (Payment) вам необходимо передать сумму платежа, валюту и дополнительную информацию (зависит от сценария проведения оплаты).

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

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

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

    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "confirmation": {
              "type": "redirect",
              "return_url": "https://www.merchant-website.com/return_url"
            }
          }'
    
    <?php
        $payment = $client->createPayment(
            array(
                'amount' => array(
                    'value' => 2.0,
                    'currency' => 'RUB'
                ),
                'confirmation' => array(
                    'type' => 'redirect',
                    'return_url' => 'https://www.merchant-website.com/return_url',
                ),
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://www.merchant-website.com/return_url"
        }
    })
    

    Пример платежа, ожидающего подтверждения по сценарию redirect

    {
      "id": "21740069-000f-50be-b000-0486ffbf45b0",
      "status": "pending",
      "paid": false,
      "amount": {
        "value": "2.00",
        "currency": "RUB"
      },
      "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=21740069-000f-50be-b000-0486ffbf45b0"
      },
      "created_at": "2017-10-14T10:53:29.072Z",
      "metadata": {}
    }
    

    В некоторых случаях пользователям необходимо совершить определенные действия для подтверждения платежа. Например, ввести код подтверждения 3D-Secure при оплате банковской картой, подтвердить оплату в платежном сервисе нашего партнера, оплатить счет в интернет-банке или ответить на смс.

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

    Без подтверждения Redirect External
    bank_card
    apple_pay
    bank_card
    yandex_money
    sberbank
    qiwi
    webmoney
    cash
    mobile_balance
    sberbank
    alfabank

    Подтверждение и отмена

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

    curl https://payment.yandex.net/api/v3/payments/{payment_id}/capture \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            }
          }'
    
    <?php
        $client->capturePayment(
            array(
                'amount' => array(
                    'value' => 2.0,
                    'currency' => 'RUB',
                ),
            ),
            $paymentId,
            uniqid('', true)
        );
    ?>
    
    payment = Payment.capture(payment_id, {
        {
            "amount": {
                "value": "2.00",
                "currency": "RUB"
            }
        }
    })
    

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

    curl https://payment.yandex.net/api/v3/payments/{payment_id}/cancel \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json'
    
    <?php
        $client->cancelPayment(
            $paymentId,
            uniqid('', true)
        );
    ?>
    
    payment = Payment.cancel(payment_id)
    

    По умолчанию все платежи по API Яндекс.Кассы в статусе waiting_for_capture требуют вашего подтверждения. Если вы хотите подтвердить платеж автоматически, передайте при его создании в параметре capture значение true. Такие платежи сразу перейдут в статус succeeded после того, как будут совершены все необходимые действия в статусе pending.

    Как только платеж перешел в статус waiting_for_capture, у вас есть:

    Время, в течение которого нужно подтвердить платеж, передается в поле expires_at. Если вы не подтвердите платеж в отведенное время, он автоматически перейдет в статус canceled, и деньги вернутся пользователю.

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

    Если вы не можете оказать услугу или выдать товар, необходимо отменить платеж при помощи метода cancel. В таком случае платеж перейдет в статус canceled и деньги вернутся пользователю. Если вы отменили платеж, Яндекс.Касса не будет удерживать комиссию за его проведение.

    Продажа авиабилетов

    При продаже авиабилетов вы можете передавать информацию о билетах, перелетах и пассажирах (так называемая «длинная запись»). Дополнительные данные используются только при оплате банковской картой, они нужны, чтобы снизить вероятность мошеннических операций.

    Шаг 1. Создание платежа с дополнительными данными

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

    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "10000.00",
              "currency": "RUB"
            },
            "payment_method_data": {
              "type": "bank_card"
            },
            "confirmation": {
              "type": "redirect",
              "return_url": "https://www.merchant-website.com/return_url"
            },
            "airline": {
              "booking_reference": "IIIKRV",
              "passengers": [
                {
                  "first_name": "SERGEI",
                  "last_name": "IVANOV"
                  }
                ],
              "legs": [
                {
                  "departure_airport": "LED",
                  "destination_airport": "AMS",
                  "departure_date": "2018-06-20"
                }
              ]
            }
          }'
    
    <?php
         $payment = $client->createPayment(
            array(
                "amount" =>  array(
                  "value" => "10000.00",
                  "currency" => "RUB"
                ),
                "payment_method_data" => array(
                    "type" => "bank_card"
                ),
                "confirmation" => array(
                    "type" => "redirect",
                    "return_url" => "https://www.merchant-website.com/return_url"
                ),
                "airline" => array(
                    "booking_reference" => "IIIKRV",
                    "passengers" => array(
                        array(
                            "first_name" => "SERGEI",
                            "last_name" => "IVANOV"
                        )
                    ),
                    "legs" => array(
                        array(
                            "departure_airport" => "LED",
                            "destination_airport" => "AMS",
                            "departure_date" => "2018-06-20"
                        )
                    )
                )
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "10000.00",
            "currency": "RUB"
        },
        "payment_method_data": {
            "type": "bank_card"
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://www.merchant-website.com/return_url"
        },
        "airline": {
            "booking_reference": "IIIKRV",
            "passengers": [
                {
                    "first_name": "SERGEI",
                    "last_name": "IVANOV"
                }
            ],
            "legs": [
                {
                    "departure_airport": "LED",
                    "destination_airport": "AMS",
                    "departure_date": "2018-06-20"
                }
            ]
        }
    })
    

    Информация о пассажирах и билетах передается при создании платежа — в объекте airline. В этот момент номер билета еще не известен, поэтому указывается номер брони (booking_reference).

    Информация о пассажирах передается в объекте passengers (не больше 4 пассажиров в одном платеже).

    Информация о перелетах передается в объекте legs (не больше 4 перелетов в одном платеже). Перелет — это фрагмент маршрута. Если пользователь летит без пересадки, это один перелет. Если есть одна пересадка — два перелета.

    Шаг 2. Подтверждение платежа

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

    curl https://payment.yandex.net/api/v3/{payment_id}/capture \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "10000.00",
              "currency": "RUB"
            },
            "airline": {
              "booking_reference": "IIIKRV",
              "ticket_number": "5554916004417",
              "passengers": [
                {
                  "first_name": "SERGEI",
                  "last_name": "IVANOV"
                  }
                ],
              "legs": [
                {
                  "departure_airport": "LED",
                  "destination_airport": "AMS",
                  "departure_date": "2018-06-20"
                }
              ]
            }
          }'
    
    <?php
         $payment = $client->createPayment(
            array(
                "amount" =>  array(
                  "value" => "10000.00",
                  "currency" => "RUB"
                ),
                "payment_method_data" => array(
                    "type" => "bank_card"
                ),
                "confirmation" => array(
                    "type" => "redirect",
                    "return_url" => "https://www.merchant-website.com/return_url"
                ),
                "airline" => array(
                    "booking_reference" => "IIIKRV",
                    "ticket_number" => "5554916004417",
                    "passengers" => array(
                        array(
                            "first_name" => "SERGEI",
                            "last_name" => "IVANOV"
                        )
                    ),
                    "legs" => array(
                        array(
                            "departure_airport" => "LED",
                            "destination_airport" => "AMS",
                            "departure_date" => "2018-06-20"
                        )
                    )
                )
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "10000.00",
            "currency": "RUB"
        },
        "airline": {
            "booking_reference": "IIIKRV",
            "ticket_number": "5554916004417",
            "passengers": [
                {
                    "first_name": "SERGEI",
                    "last_name": "IVANOV"
                }
            ],
            "legs": [
                {
                    "departure_airport": "LED",
                    "destination_airport": "AMS",
                    "departure_date": "2018-06-20"
                }
            ]
        }
    })
    

    Когда платеж переходит в статус waiting_for_capture, можно его подтвердить (если всё в порядке и вы готовы принять оплату). При подтверждении номер брони передавать не нужно, вместо него необходимо передать номер билета (ticket_number).

    Возвраты

    Пример запроса на частичный возврат

    curl https://payment.yandex.net/api/v3/refunds \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "payment_id": "21740069-000f-50be-b000-0486ffbf45b0"
          }'
    
    <?php
        $client->createRefund(
            array(
                'amount' => array(
                    'value' => 2.0,
                    'currency' => 'RUB',
                ),
                'payment_id' => '21740069-000f-50be-b000-0486ffbf45b0',
            ),
            uniqid('', true)
        );
    ?>
    
    refund = Refund.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_id": "21740069-000f-50be-b000-0486ffbf45b0"
    })
    

    Пример успешно созданного возврата

      {
        "id": "216749f7-0016-50be-b000-078d43a63ae4",
        "status": "succeeded",
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "created_at": "2017-10-04T19:27:51.407Z",
        "payment_id": "216749da-000f-50be-b000-096747fad91e"
      }
    

    Чтобы вернуть платеж, необходимо создать объект возврата (Refund) и указать сумму, валюту и уникальный идентификатор платежа, который вы возвращаете (payment_id).

    Вы можете сделать сколько угодно частичных возвратов, если:

    Возвраты доступны не для всех способов оплаты. Какие платежи можно вернуть

    Повторы платежей

    API Яндекс.Кассы позволяет сохранять способ оплаты (со всеми платежными данными) при платежах из кошелька в Яндекс.Деньгах или банковской картой и использовать для повторных списаний.

    Такие платежи не требуют подтверждения пользователем.

    Шаг 1. Сохранение способа оплаты

    Пример проведения платежа сохраненным способом оплаты

    curl https://payment.yandex.net/api/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.merchant-website.com/return_url"
            },
            "save_payment_method": "true"
          }'
    
    
    <?php
        $payment = $client->createPayment(
            array(
                'amount' => array(
                    'value' => 2.0,
                    'currency' => 'RUB',
                ),
                'payment_method_data' => array(
                    'type' => 'bank_card',
                ),
                'confirmation' => array(
                    'type' => 'redirect',
                    'return_url' => 'https://www.merchant-website.com/return_url',
                ),
                'save_payment_method' => true,
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_method_data": {
            "type": "bank_card"
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://www.merchant-website.com/return_url"
        },
        "save_payment_method": "true"
    })
    

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

    {
      "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "status": "succeeded",
      "amount": {
        "value": "10.00",
        "currency": "RUB"
      },
      "created_at": "2015-11-19T17:05:07+03:00",
      "payment_method": {
        "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
        "type": "bank_card",
        "saved": true,
        "title": "Bank card **** **** **** 7918",
        "card": {
            "last4": "7918",
            "expiry_year": "2017",
            "expiry_month": "07",
            "card_type": "MasterCard"
        }
      },
      "paid": true
    }
    

    Чтобы сохранить способ оплаты, нужно провести успешный платеж.

    Создайте запрос на оплату. Передайте в запросе save_payment_method со значением true (это значит, что нужно сохранить способ оплаты). Платеж можно проводить любым способом: с вводом данных карты или кошелька на странице Яндекс.Кассы, с передачей данных карты или по платежному токену.

    После того как платеж перейдет в статус succeeded, значение payment_method.saved изменится на true. Это значит, что вы можете использовать идентификатор способа оплаты payment_method.id для следующих безакцептных платежей.

    Шаг 2. Проведение платежа сохраненным способом оплаты

    Пример проведения платежа сохраненным способом оплаты

    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "payment_method_id": "<Идентификатор сохраненного способа оплаты>"
          }'
    
    <?php
        $payment = $client->createPayment(
            array(
                'amount' => array(
                    'value' => 2.0,
                    'currency' => 'RUB',
                ),
                'payment_method_id' => '<Идентификатор сохраненного способа оплаты>',
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_method_id": "<Идентификатор сохраненного способа оплаты>"
    })
    

    Создайте запрос на оплату из кошелька или банковской картой. Передайте идентификатор сохраненного способа оплаты в параметре payment_method_id (вы получили его в ответе на успешный запрос, при проведении которого сохранили данные карты). Такой платеж не потребует дополнительного подтверждения от пользователя.

    Способы оплаты

    Сейчас в API Яндекс.Кассы доступны следующие способы оплаты:

    Чтобы инициировать оплату конкретным способом, нужно создать платеж, передавая сумму, валюту и способ оплаты (payment_method_data) со всеми необходимыми параметрами.

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

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

    curl https://payment.yandex.net/api/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.merchant-website.com/return_url"
            }
          }'
    
    <?php
        $client->createPayment(
            array(
                'amount' => array(
                    'value' => 2,
                    'currency' => 'RUB',
                ),
                'payment_method_data' => array(
                    'type' => 'bank_card',
                ),
                'confirmation' => array(
                    'type' => 'redirect',
                    'return_url' => 'https://www.merchant-website.com/return_url',
                ),
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_method_data": {
            "type": "bank_card"
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://www.merchant-website.com/return_url"
        }
    })
    

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

    {
      "id": "21740069-000f-50be-b000-0486ffbf45b0",
      "status": "pending",
      "paid": true,
      "amount": {
        "value": "4.00",
        "currency": "RUB"
      },
      "confirmation": {
        "type": "redirect",
        "return_url": "http://www.example.com/",
        "confirmation_url": "https://money.yandex.ru/payments/kassa/confirmation?orderId=21740069-000f-50be-b000-0486ffbf45b0"
      },
      "created_at": "2017-09-27T10:13:52.588Z",
      "metadata": {},
      "payment_method": {
        "type": "bank_card",
        "id": "012b57fe-1904-493a-a2de-48cd42c4f356",
        "saved": false
      }
    }
    

    Чтобы принять оплату банковской картой с вводом данных на стороне Яндекс.Кассы, необходимо создать платеж с типом оплаты bank_card и реализовать сценарий подтверждения redirect.

    1. Создайте платеж, в объекте payment_method_data передайте тип bank_card, в параметре return_url — адрес страницы на вашей стороне, на которую пользователь вернется после оплаты.
    2. Реализуйте сценарий подтверждения redirect.
    3. Дождитесь подтверждения платежа пользователем: подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже.
    4. Подтвердить платеж с помощью метода capture.

    Сбербанк Онлайн (смс)

    Пример запроса на создание платежа через Сбербанк Онлайн с подтверждением по смс

    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "payment_method_data": {
              "type": "sberbank",
              "phone": "79000000000"
            },
            "confirmation": {
              "type": "external"
            }
          }'
    
    <?php
        $client->createPayment(
            array(
                'amount' => array(
                    'value' => 2,
                    'currency' => 'RUB',
                ),
                'payment_method_data' => array(
                    'type' => 'sberbank',
                    'phone' => '79000000000',
                ),
                'confirmation' => array(
                    'type' => 'external',
                ),
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_method_data": {
            "type": "sberbank",
            "phone": "79000000000"
        },
        "confirmation": {
            "type": "external"
        }
    })
    

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

    {
      "id": "21740069-000f-50be-b000-0486ffbf45b0",
      "status": "pending",
      "paid": true,
      "amount": {
        "value": "4.00",
        "currency": "RUB"
      },
      "confirmation": {
        "type": "external"
      },
      "created_at": "2017-09-27T10:13:52.588Z",
      "metadata": {},
      "payment_method": {
        "type": "sberbank",
        "id": "21740069-000f-50be-b000-0486ffbf45b0",
        "saved": false
      }
    }
    

    Чтобы принять оплату через Сбербанк Онлайн с подтверждением по смс, необходимо создать платеж с типом оплаты sberbank и реализовать сценарий подтверждения external.

    1. Создайте платеж. В объекте payment_method_data передайте тип sberbank и телефон пользователя, привязанный к Сбербанку Онлайн. В объекте confirmation передайте тип external.
    2. Реализуйте сценарий подтверждения external.
    3. Дождитесь подтверждения платежа пользователем: подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже.
    4. Подтвердить платеж с помощью метода capture.

    Apple Pay

    Чтобы подключить этот способ оплаты, нужно передать Яндекс.Кассе сертификат, с помощью которого Apple будет шифровать данные банковских карт. Для этого:

    1. Напишите менеджеру и попросите создать для вас запрос на сертификат (CSR).
    2. Загрузите CSR в панели разработчика Apple.
    3. Скачайте получившийся сертификат и пришлите менеджеру.

    Подробная инструкция (см. раздел 3 «Обмен сертификатами»)

    Шаг 1. Создайте криптограмму

    Сгенерируйте криптограмму Apple Pay (paymentData) на устройстве пользователя и получите содержимое объекта PKPaymentToken.

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

    Шаг 2. Передайте криптограмму (paymentData) в Яндекс.Кассу

    Пример запроса с криптограммой Apple Pay

    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "payment_method_data": {
              "type": "apple_pay",
              "payment_data": "<paymentData>"
            }
          }'
    
    <?php
        $client->createPayment(
            array(
                "amount" => array(
                    "value" => "2.00",
                    "currency" => "RUB"
                ),
                "payment_method_data"=> array(
                    "type" => "apple_pay",
                    "payment_data" => "<paymentData>"
                )
            ),
            uniqid('', true)
        );
    ?>
    
    payment = Payment.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_method_data": {
            "type": "apple_pay",
            "payment_data": "<paymentData>"
        }
    })
    

    Пример тела ответа

    {
      "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "status": "waiting_for_capture",
      "amount": {
        "value": "10.00",
        "currency": "RUB"
      },
      "created_at": "2015-11-19T17:05:07+03:00",
      "payment_method": {
        "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
        "type": "apple_pay",
        "saved": false,
      },
      "paid": true
    }
    

    При оплате с использованием криптограммы Apple Pay дополнительное подтверждение пользователем не требуется.

    Шаг 3. Вызовите метод capture

    После этого платеж перейдет в статус succeeded.

    Оплата по 54-ФЗ

    Решение Яндекс.Кассы для работы по 54-ФЗ позволяет настроить взаимодействие с вашей онлайн-кассой: отправлять онлайн-кассе запрос на формирование чека и получать результат.

    Подключение

    1. Купите или возьмите в аренду онлайн-кассу одного из наших партнеров.
    2. Заключите договор с оператором фискальных данных (ОФД).
    3. Получите квалифицированную электронную подпись (КЭП).
    4. Зарегистрируйте онлайн-кассу на сайте налоговой (в личном кабинете юрлица).
    5. Заполните настройки для работы по 54-ФЗ в личном кабинете Яндекс.Кассы.
    6. Передавайте Яндекс.Кассе данные для формирования чека в запросах на оплату.

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

    Пример запроса на оплату с параметрами для чека

    <?php
        $client->createPayment(
            array(
                "amount" => array(
                    "value" => "600.00",
                    "currency" => "RUB"
                ),
                "confirmation" => array(
                    "type" => "redirect",
                    "return_url" => "https://www.merchant-website.com/return_url"
                ),
                "receipt" => array(
                    "phone" => "79000000000",
                    "items" => array(
                        array(
                            "description" => "Наименование товара 1",
                            "quantity" => "2.00",
                            "amount" => array(
                                "value" => "250.00",
                                "currency" => "RUB"
                            ),
                            "vat_code" => "2"
                        ),
                        array(
                            "description" => "Наименование товара 2",
                            "quantity" => "1.00",
                            "amount" => array(
                                "value" => "100.00",
                                "currency" => "RUB"
                            ),
                            "vat_code" => "2"
                        )
                    )
                )
            ),
            uniqid('', true)
        );
    ?>
    
    curl https://payment.yandex.net/api/v3/payments \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "600.00",
              "currency": "RUB"
            },
            "confirmation": {
              "type": "redirect",
              "return_url": "https://www.merchant-website.com/return_url"
            },
            "receipt": {
              "phone": "79000000000",
              "items": [
                {
                  "description": "Наименование товара 1",
                  "quantity": "2.00",
                  "amount": {
                    "value": "250.00",
                    "currency": "RUB"
                  },
                  "vat_code": "2"
                },
                {
                  "description": "Наименование товара 2",
                  "quantity": "1.00",
                  "amount": {
                    "value": "100.00",
                    "currency": "RUB"
                  },
                  "vat_code": "2"
                }
              ]
            }
          }'
    
    payment = Payment.create({
        "amount": {
            "value": "600.00",
            "currency": "RUB"
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://www.merchant-website.com/return_url"
        },
        "receipt": {
            "phone": "79000000000",
            "items": [
                {
                    "description": "Наименование товара 1",
                    "quantity": "2.00",
                    "amount": {
                        "value": "250.00",
                        "currency": "RUB"
                    },
                    "vat_code": "2"
                },
                {
                    "description": "Наименование товара 2",
                    "quantity": "1.00",
                    "amount": {
                        "value": "100.00",
                        "currency": "RUB"
                    },
                    "vat_code": "2"
                }
            ]
        },
    })
    

    Пример ответа

    {
      "id": "21740069-000f-50be-b000-0486ffbf45b0",
      "status": "pending",
      "paid": false,
      "amount": {
        "value": "600.00",
        "currency": "RUB"
      },
      "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=21740069-000f-50be-b000-0486ffbf45b0"
      },
      "created_at": "2017-10-14T10:53:29.072Z",
      "metadata": {}
    }
    
    1. Создайте платеж, в объекте receipt передайте параметры, которые нужны для формирования чека.

    2. Мы отправим эти параметры вашей онлайн-кассе. Момент, в который это происходит, зависит от ваших настроек в личном кабинете.

      • При настройке за 5 минут отправка чека проводится после того, как пользователь подтвердил оплату. Если чек в вашей онлайн-кассе не сформируется в течении 5 минут, платеж перейдет в статус canceled. Если регистрация чека пройдет успешно, платеж перейдет в статус waiting_for_capture.
      • При настройке за 7 дней отправка чека проводится после вашего запроса на подтверждение платежа. Если чек не сформируется, вам придется отправить его самостоятельно.
    3. Дождитесь, пока платеж перейдет в статус waiting_for_capture. Вы можете узнать, сформировался ли чек, по значению параметра receipt_registration.

    Частичное подтверждение

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

    <?php
        $client->capturePayment(
            array(
                "amount" => array(
                    "value" => "500.00",
                    "currency" => "RUB"
                ),
                "receipt" => array(
                    "phone" => "79000000000",
                    "items" => array(
                        array(
                            "description" => "Наименование товара",
                            "quantity" => "2.00",
                            "amount" => array(
                                "value" => "250.00",
                                "currency" => "RUB"
                            ),
                            "vat_code" => "2"
                        )
                    )
                )
            ),
            uniqid('', true)
        );
    ?>
    
    curl https://payment.yandex.net/api/v3/payments/<payment-id>/capture \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "amount": {
              "value": "500.00",
              "currency": "RUB"
            },
            "receipt": {
              "phone": "79000000000",
              "items": [
                {
                  "description": "Наименование товара",
                  "quantity": "2.00",
                  "amount": {
                    "value": "250.00",
                    "currency": "RUB"
                  },
                  "vat_code": "2"
                }
              ]
            }
          }'
    
    payment = Payment.capture({
        "amount": {
            "value": "500.00",
            "currency": "RUB"
        },
        "receipt": {
            "phone": "79000000000",
            "items": [
                {
                    "description": "Наименование товара",
                    "quantity": "2.00",
                    "amount": {
                        "value": "250.00",
                        "currency": "RUB"
                    },
                    "vat_code": "2"
                }
            ]
        },
    })
    

    Если вы хотите изменить сумму платежа при подтверждении, передайте в запросе:

    Возврат

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

    <?php
        $client->createRefund(
            array(
                "payment_id" => "<Идентификатор возвращаемого платежа>",
                "amount" => array(
                    "value" => "600.00",
                    "currency" => "RUB"
                ),
                "receipt" => array(
                    "phone" => "79000000000",
                    "items" => array(
                        array(
                            "description" => "Наименование товара 1",
                            "quantity" => "2.00",
                            "amount" => array(
                                "value" => "250.00",
                                "currency" => "RUB"
                            ),
                            "vat_code" => "2"
                        ),
                         array(
                            "description" => "Наименование товара 2",
                            "quantity" => "1.00",
                            "amount" => array(
                                "value" => "100.00",
                                "currency" => "RUB"
                            ),
                            "vat_code" => "2"
                        )
                    )
                ),
    
            ),
            uniqid('', true)
        );
    ?>
    
    curl https://payment.yandex.net/api/v3/refunds \
      -X POST \
      -u <Идентификатор магазина>:<Секретный ключ> \
      -H 'Idempotence-Key: <Ключ идемпотентности>' \
      -H 'Content-Type: application/json' \
      -d '{
            "payment_id": "<Идентификатор возвращаемого платежа>",
            "amount": {
              "value": "600.00",
              "currency": "RUB"
            },
            "receipt": {
              "phone": "79000000000",
              "items": [
                {
                  "description": "Наименование товара 1",
                  "quantity": "2.00",
                  "amount": {
                    "value": "250.00",
                    "currency": "RUB"
                  },
                  "vat_code": "2"
                },
                {
                  "description": "Наименование товара 2",
                  "quantity": "1.00",
                  "amount": {
                    "value": "100.00",
                    "currency": "RUB"
                  },
                  "vat_code": "2"
                }
              ]
            }
          }'
    
    refund = Refund.create({
        "payment_id": "<Идентификатор возвращаемого платежа>",
        "amount": {
            "value": "600.00",
            "currency": "RUB"
        },
        "receipt": {
            "phone": "79000000000",
            "items": [
                {
                    "description": "Наименование товара 1",
                    "quantity": "2.00",
                    "amount": {
                        "value": "250.00",
                        "currency": "RUB"
                    },
                    "vat_code": "2"
                },
                {
                    "description": "Наименование товара 2",
                    "quantity": "1.00",
                    "amount": {
                        "value": "100.00",
                        "currency": "RUB"
                    },
                    "vat_code": "2"
                }
            ]
        },
    })
    
    1. Создайте новый возврат, в объекте receipt передайте параметры, которые нужны для формирования чека возврата. Если возврат полный — они будут совпадать с параметрами из исходного платежа, если частичный — укажите только товары, которые возвращаете.

    2. Как только возврат будет создан, мы отправим вашей онлайн-кассе данные для регистрации чека.

    Коды систем налогообложения

    Код системы налогообложения передается в объекте receipt, в параметре tax_system_code. Возможные значения — цифра от 1 до 6.

    Код Система налогообложения
    1 Общая система налогообложения
    2 Упрощенная (УСН, доходы)
    3 Упрощенная (УСН, доходы минус расходы)
    4 Единый налог на вмененный доход (ЕНВД)
    5 Единый сельскохозяйственный налог (ЕСН)
    6 Патентная система налогообложения

    Коды ставок НДС

    Код системы налогообложения передается в объекте receipt, в параметре vat_code. Возможные значения — цифра от 1 до 6.

    Код Ставка НДС
    1 Без НДС
    2 НДС по ставке 0%
    3 НДС по ставке 10%
    4 НДС чека по ставке 18%
    5 НДС чека по расчетной ставке 10/110
    6 НДС чека по расчетной ставке 18/118

    Уведомления

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

    Доступные события

    Пример тела уведомления payment.waiting_for_capture

    {
      "type": "notification",
      "event": "payment.waiting_for_capture",
      "object": {
        "id": "012b57fe-1904-493a-a2de-48cd42c4f356",
        "status": "waiting_for_capture",
        "paid": true,
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "created_at": "2017-10-24T10:37:16.007Z",
        "expires_at": "2017-10-31T10:39:15.469Z",
        "metadata": {},
        "payment_method": {
          "type": "bank_card",
          "id": "8f8daf85-86ce-4f7b-94e1-196b4a56f12e",
          "saved": false,
          "card": {
            "last4": "4448",
            "expiry_month": "04",
            "expiry_year": "2018",
            "card_type": "MasterCard"
          },
          "title": "Bank card *7682"
        }
      }
    }
    

    Сейчас вы можете получать такие уведомления:

    Как только платеж перейдет в этот статус, на URL, которй вы указали в личном кабинете, придет уведомление. В нем будут все данные об объекте на момент, когда это событие произошло.

    Когда использовать

    Уведомления стоит использовать при асинхронном процессе оплаты. Например, если пользователь подтверждает платеж в своем интернет-банке или вносит деньги через терминал. В таких сценариях процесс оплаты может занимать от нескольких минут до нескольких часов.

    При таком сценарии вы можете:

    Как отвечать

    Чтобы подтвердить получение уведомления, необходимо ответить HTTP-кодом 200. Мы проигнорируем всё, что будет находиться в теле или заголовках ответа. Ответы с любыми другими HTTP-кодами будут считаться невалидными, и мы продолжим доставлять уведомление в течение 24 часов, начиная с момента, когда событие произошло.

    Перед тем как предпринимать какие-либо действия после получения уведомления, проверьте, в каком статусе находится объект: запросите информацию о нем методом GET. Это позволит избежать ситуаций, когда кто-то отправляет вам поддельное уведомление об успешном платеже.

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

    Прежде чем принимать реальные платежи, вы можете проверить свою интеграцию в тестовом магазине. Он появляется в личном кабинете Яндекс.Кассы после того, как вы заполните анкету об организации (и менеджер ее проверит) и отправите технические настройки. У тестового магазина свой идентификатор магазина (shopId) и секретный ключ с префиксом test_. И то, и другое можно посмотреть и получить в личном кабинете Яндекс.Кассы.

    Подробнее о тестовом магазине

    Возможности

    Вы можете протестировать следующие платежные сценарии:

    В рамках этих платежных сценариев вы можете протестировать:

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

    Тестовые банковские карты

    Для тестовых магазинов можно использовать только тестовую банковскую карту 1111 1111 1111 1026. Месяц и год может быть любой, но больше текущей даты. Для управления подтверждением оплаты по 3D-Secure можно использовать следующие CVC-коды:

    CVC Сценарий
    000 3D-Secure отключен
    123 3D-Secure включен

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

    Реестры

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

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

    Реестры платежей

    Тема письма

    РЕЕСТР ПЛАТЕЖЕЙ В <Название магазина>. № <номер реестра по порядку>

    Тело реестра

    РЕЕСТР ПЛАТЕЖЕЙ В <Название магазина>. № <номер>
    Дата платежей:
    Идентификатор платежа; Сумма платежа; Валюта платежа; Сумма за вычетом комиссии; Время платежа; Идентификатор платежного средства; Описание; Тип платежа

    <Данные платежей>

    Сумма принятых платежей типа <Тип платежа>: <общая сумма успешных платежей этого типа за сутки>
    Сумма принятых платежей за вычетом комиссии типа <Тип платежа>: <сумма успешных платежей этого типа минус комиссия Яндекс.Кассы>
    Число платежей типа <Тип платежа>: <количество платежей этого типа>

    Сумма принятых платежей: <общая сумма успешных платежей за сутки>
    Сумма принятых платежей за вычетом комиссии: <сумма успешных платежей минус комиссия Яндекс.Кассы>
    Число платежей: <количество платежей>

    Кому: <Название магазина>

    (По договору <номер договора между вашей компанией и Яндекс.Деньгами>)

    Поля в реестре

    Поле в реестре Описание
    Идентификатор платежа Уникальный идентификатор платежа в Яндекс.Кассе, приходит в ответе при создании платежа, в поле id.
    Сумма платежа Сумма транзакции. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует.
    Валюта платежа Трехбуквенный код валюты (RUB — рубль РФ).
    Сумма за вычетом комиссии Сумма, которая зачисляется на ваш расчетный счет. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует.
    Время платежа Время создания платежа в Яндекс.Кассе. Указывается по UTC и передается в формате ISO 8601. Пример: 2017-11-03T11:52:31.827Z
    Идентификатор платежного средства Номер кошелька в Яндекс.Деньгах, из которого произведена оплата. Для других способов оплаты — внутренний номер счета на стороне Яндекс.Кассы.
    Описание Значение поля description, приходит в ответе при создании платежа.
    Тип платежа Код способа оплаты на стороне Яндекс.Кассы, в запросах не используется.

    Примеры реестров

    Реестр возвратов

    Тема письма

    РЕЕСТР ВОЗВРАТОВ ОТ <Название магазина>. № <номер реестра по порядку>

    Тело реестра

    РЕЕСТР ВОЗВРАТОВ ОТ <Название магазина>. № <номер>
    Дата возвратов:

    Идентификатор возврата; Идентификатор платежа; Сумма возврата; Валюта возврата; Время зачисления возврата на счет плательщика; Идентификатор платежного средства; Сумма возврата в валюте товара; Валюта платежа; Тип платежа; Описание

    <Данные возвратов>

    Сумма возвратов: <общая сумма возвратов за сутки>
    Число возвратов: <количество возвратов>

    От: <Название магазина>

    (По договору <номер договора между вашей компанией и Яндекс.Деньгами>)

    Поля в реестре

    Поле в реестре Описание
    Идентификатор возврата Уникальный идентификатор возврата в Яндекс.Кассе, приходит в ответе при создании возврата, в поле id.
    Идентификатор платежа Уникальный идентификатор исходного платежа в Яндекс.Кассе.
    Сумма возврата Сумма транзакции. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует.
    Валюта возврата Трехбуквенный код валюты (RUB — рубль РФ).
    Время зачисления возврата на счет плательщика Время создания платежа в Яндекс.Кассе. Указывается по UTC и передается в формате ISO 8601. Пример: 2017-11-03T11:52:31.827Z
    Идентификатор платежного средства Номер кошелька в Яндекс.Деньгах, из которого произведена оплата. Для других способов оплаты — внутренний номер счета на стороне Яндекс.Кассы.
    Сумма возврата в валюте товара
    Валюта платежа Трехбуквенный код валюты (RUB — рубль РФ).
    Тип платежа Код способа оплаты на стороне Яндекс.Кассы, в запросах не используется.
    Описание Значение поля description, приходит в ответе при создании платежа.

    Примеры реестров