NAV Navbar

Быстрый старт

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

Что дальше:

  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"
        },
        "description": "Заказ №72"
      }'
<?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',
            ),
            'description' => 'Заказ №72',
        ),
        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"
    },
    "description": "Заказ №72"
})

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

Запрос отправьте с уникальным ключом идемпотентности.

Шаг 2. Отобразите страницу оплаты

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

{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "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=22d6d597-000f-5000-9000-145f6df21d6f"
  },
  "created_at": "2018-07-10T14:25:27.535Z",
  "description": "Заказ №72",
  "metadata": {},
  "test": false
}

Перенаправьте пользователя на confirmation_url, полученный в теле ответа. Это страница на стороне Яндекс.Кассы, на которой пользователь сможет выбрать способ оплаты и заплатить.

Шаг 3. Дождитесь оплаты

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

{
  "type": "notification",
  "event": "payment.waiting_for_capture",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "waiting_for_capture",
    "paid": true,
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000"
    },
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Заказ №72",
    "expires_at": "2018-07-17T14:28:32.484Z",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22d6d597-000f-5000-9000-145f6df21d6f",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2021",
        "card_type": "MasterCard"
      },
      "title": "Bank card *4444"
    },
    "test": false
  }
}

Как только пользователь выберет способ и подтвердит оплату, платеж перейдет в статус 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": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-07-10T14:38:32.295Z",
  "created_at": "2018-07-10T14:27:54.691Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2021",
      "card_type": "MasterCard"
    },
    "title": "Bank card *4444"
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

Объект платежа (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"
        },
        "description": "Заказ №72"
      }'
<?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',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22d6d9be-000f-5000-9000-1427689709c4",
  "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=22d6d9be-000f-5000-9000-1427689709c4"
  },
  "created_at": "2018-07-10T14:43:10.782Z",
  "description": "Заказ №72",
  "metadata": {},
  "test": false
}

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

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

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

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

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, и деньги вернутся пользователю. Если вы отменили платеж, Яндекс.Касса не будет удерживать комиссию за его проведение.

Отмененные платежи

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

{
  "id": "22979b7b-000f-5000-9000-1a603a795739",
  "status": "canceled",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-05-23T15:24:43.812Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22979b7b-000f-5000-9000-1a603a795739",
    "saved": false
  },
  "recipient": {
    "account_id": "67192",
    "gateway_id": "352780"
  },
  "test": false,
  "cancellation_details": {
    "party": "payment_network",
    "reason": "payment_method_restricted"
  }
}

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

Чтобы вы могли лучше понимать, что произошло и что с этим делать, Яндекс.Касса пришлет в объекте платежа (Payment) комментарий к отмене платежа (cancellation_details). В нем будут указаны инициатор (cancellation_details.party) и причина отмены (cancellation_details.reason). Вы можете использовать эти данные для анализа и решения проблем, вывода сообщений покупателю и любых других целей.

Возможные инициаторы отмены платежа

Значение Описание
merchant Продавец товаров и услуг (вы)
yandex_checkout Яндекс.Касса
payment_network «Внешние» участники платежного процесса — все остальные участники платежного процесса, кроме Яндекс.Кассы и вас (например, эмитент, сторонний платежный сервис)

Возможные причины отмены платежа

Значение Описание
3d_secure_failed Не пройдена аутентификация по 3-D Secure. Покупателю следует повторить платеж, обратиться в банк за уточнениями или использовать другое платежное средство
call_issuer Оплата данным платежным средством отклонена по неизвестным причинам. Покупателю следует обратиться в организацию, выпустившую платежное средство
card_expired Истек срок действия банковской карты. Покупателю следует использовать другое платежное средство
country_forbidden Нельзя заплатить банковской картой, выпущенной в этой стране. Покупателю следует использовать другое платежное средство.
Вы можете настроить ограничения на оплату иностранными банковскими картами
fraud_suspected Платеж заблокирован из-за подозрения в мошенничестве. Покупателю следует использовать другое платежное средство
general_decline Причина не детализирована. Покупателю следует обратиться к инициатору отмены платежа за уточнением подробностей
identification_required Превышены ограничения на платежи для кошелька в Яндекс.Деньгах. Покупателю следует идентифицировать кошелек или выбрать другое платежное средство
insufficient_funds Не хватает денег для оплаты. Покупателю следует пополнить баланс или использовать другое платежное средство
invalid_card_number Неправильно указан номер карты. Покупателю следует повторить платеж и ввести корректные данные
invalid_csc Неправильно указан код CVV2 (CVC2, CID). Покупателю следует повторить платеж и ввести корректные данные
issuer_unavailable Организация, выпустившая платежное средство, недоступна. Покупателю следует повторить платеж позже или использовать другое платежное средство
payment_method_limit_exceeded Исчерпан лимит платежей для данного платежного средства или вашего магазина. Покупателю следует повторить платеж на следующий день или использовать другое платежное средство
payment_method_restricted Запрещены операции данным платежным средством (например, карта заблокирована из-за утери, кошелек — из-за взлома мошенниками). Покупателю следует обратиться в организацию, выпустившую платежное средство

Обратите внимание: статус canceled — финальный и неизменяемый. Чтобы повторить платеж, вы должны создать новый объект платежа (Payment) с другим ключом идемпотентности.

Вы можете протестировать отмену платежа с помощью тестовых банковских карт.

Нативные платежные формы

Нативные платежные формы позволяют встроить процесс приема платежей непосредственно на ваш сайт или в мобильное приложение: пользователю не придется во время оплаты переходить на сайт Яндекс.Кассы.

Чтобы встроить нативные платежные формы, вам необходимо:

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

В некоторых способах оплаты необходимо реализовать определенный сценарий подтверждения пользователем:

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

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

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

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

{
  "id": "22cfeb68-000f-5000-9000-170954758639",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "created_at": "2018-07-05T08:32:40.935Z",
  "expires_at": "2018-07-12T08:32:44.505Z",
  "description": "Оплата заказа №12345",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22cfeb68-000f-5000-9000-170954758639",
    "saved": false,
    "card": {
      "first6": "420000",
      "last4": "1111",
      "expiry_month": "01",
      "expiry_year": "2020",
      "card_type": "Visa"
    },
    "title": "Bank card *1111"
  },
  "test": false
}
  1. Получите платежный токен в клиентской библиотеке (YandexCheckout.js, YandexCheckout UI, мобильные SDK).
  2. Передайте на ваш сервер сгенерированный платежный токен и выбранный способ оплаты.
  3. Создайте платеж:
    • в параметре payment_token передайте платежный токен;
    • в зависимости от выбранного способа оплаты в объекте confirmation передайте параметры для подтверждения оплаты пользователем.
  4. При необходимости выведите пользователю информацию, которая ему нужна для подтверждения оплаты.
  5. Дождитесь выполнения платежа: подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже.
  6. Подтвердите платеж с помощью метода capture.

Возвраты

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

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"
        },
        "description": "Заказ №72",
        "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',
            ),
            'description' => 'Заказ №72',
            '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"
    },
    "description": "Заказ №72",
    "save_payment_method": "true"
})

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

{
  "id": "22e18a2f-000f-5000-a000-1db6312b7767",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "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"
    },
    "title": "Bank card *4444"
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

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

Создайте запрос на оплату. Передайте в запросе 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": "<Идентификатор сохраненного способа оплаты>",
        "description": "Заказ №105"
      }'
<?php
    $payment = $client->createPayment(
        array(
            'amount' => array(
                'value' => 2.0,
                'currency' => 'RUB',
            ),
            'payment_method_id' => '<Идентификатор сохраненного способа оплаты>',
            'description' => 'Заказ №105',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_id": "<Идентификатор сохраненного способа оплаты>",
    "description": "Заказ №105"
})

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

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

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

Шаг 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"
        },
        "description": "Заказ №72",
        "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"
            ),
            "description" => "Заказ №72",
            "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"
    },
    "description": "Заказ №72",
    "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).

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

API Яндекс.Кассы позволяет принимать платежи как от частных лиц, так и от юридических лиц и ИП (B2B-платежи).

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

Если в запросе не передать параметр payment_method_data, пользователь сможет выбрать способ оплаты на стороне Яндекс.Кассы.

Прием платежей от частных лиц

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

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

Информация по этим платежам будет приходить в реестре платежей от частных лиц.

Платежи некоторыми способами можно вернуть.

Прием платежей от юридических лиц и ИП

Сейчас API Яндекс.Кассы поддерживает один способ оплаты: b2b_sberbank — Сбербанк Бизнес Онлайн (интернет-банк Сбербанка для юридических лиц и ИП). Для этого способа оплаты нужно реализовать сценарий подтверждения 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"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?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',
            ),
            'description' => 'Заказ №72',
        ),
        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"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d173-000f-5000-9000-1bdf241d4651",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://www.merchant-website.com/return_url",
    "confirmation_url": "https://money.yandex.ru/payments/external/confirmation?orderId=22c5d173-000f-5000-9000-1bdf241d4651"
  },
  "created_at": "2018-06-27T16:39:15.865Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22c5d173-000f-5000-9000-1bdf241d4651",
    "saved": false
  },
  "test": false
}

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

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип bank_card;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).
  2. Перенаправьте пользователя на страницу для внесения оплаты (ссылка на страницу придет в параметре confirmation_url).
  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": "yandex_money"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'yandex_money',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "yandex_money"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d0f0-000f-5000-8000-13ece77bc6c1",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/payments/internal/confirmation?orderId=22c5d0f0-000f-5000-8000-13ece77bc6c1"
  },
  "created_at": "2018-06-27T16:37:04.513Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "yandex_money",
    "id": "22c5d0f0-000f-5000-8000-13ece77bc6c1",
    "saved": false
  },
  "test": false
}

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

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип yandex_money;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).
  2. Перенаправьте пользователя на страницу для подтверждения оплаты (ссылка на страницу придет в параметре confirmation_url).
  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"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'sberbank',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "sberbank"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d21b-000f-5000-8000-1ff9ebc96611",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://online.sberbank.ru/CSAFront/payOrderPaymentLogin.do?ReqId=21990df19c919689374dd7387966def7"
  },
  "created_at": "2018-06-27T16:42:03.515Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "sberbank",
    "id": "22c5d21b-000f-5000-8000-1ff9ebc96611",
    "saved": false
  },
  "test": false
}

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

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип sberbank;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).
  2. Перенаправьте пользователя на страницу для подтверждения оплаты (ссылка на страницу придет в параметре confirmation_url).
  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"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'sberbank',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'external',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "sberbank",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "external"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22e2724d-000f-5000-a000-1269c483ca3e",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "external"
  },
  "created_at": "2018-07-19T09:49:01.683Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "sberbank",
    "id": "22e2724d-000f-5000-a000-1269c483ca3e",
    "saved": false
  },
  "test": false
}

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

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип sberbank и телефон пользователя, привязанный к Сбербанк Онлайн;
    • в объекте confirmation передайте тип external.
  2. Сообщите пользователю, что ему необходимо подтвердить оплату.
  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": "alfabank",
          "login": "79990000000"
        },
        "confirmation": {
          "type": "external"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'alfabank',
                'login' => '79990000000',
            ),
            'confirmation' => array(
                'type' => 'external',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "alfabank",
        "login": "79990000000"
    },
    "confirmation": {
        "type": "external"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "external"
  },
  "created_at": "2018-06-29T09:22:09.367Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "alfabank",
    "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
    "saved": false
  },
  "test": false
}

Чтобы принять оплату через Альфа-Клик, необходимо создать платеж с типом оплаты alfabank и реализовать сценарий подтверждения External.

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

Apple Pay

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

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

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

Чтобы принять оплату с использованием криптограммы Apple Pay:

  1. Создайте криптограмму.
  2. Создайте платеж.
  3. Подтвердите платеж.

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

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

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

Шаг 2. Создайте платеж

Пример запроса на создание платежа с криптограммой 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>"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'apple_pay',
                'payment_data' => '<paymentData>',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "apple_pay",
        "payment_data": "<paymentData>"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22e290a5-000f-5000-9000-13324c06cacb",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-19T11:58:29.196Z",
  "description": "Заказ №72",
  "expires_at": "2018-07-26T11:58:32.019Z",
  "metadata": {},
  "payment_method": {
    "type": "apple_pay",
    "id": "22e290a5-000f-5000-9000-13324c06cacb",
    "saved": false
  },
  "test": false
}

Отправьте Яндекс.Кассе запрос на создание платежа, в объекте payment_method_data передайте тип apple_pay и криптограмму Apple Pay (paymentData).

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

Подтвердите платеж с помощью метода capture. После этого платеж перейдет в статус succeeded.

Google Pay

Чтобы принять оплату с использованием криптограммы Google Pay:

  1. Получите данные для оплаты.
  2. Создайте платеж.
  3. Подтвердите платеж.

Шаг 1. Получите данные для оплаты

Сгенерируйте на устройстве пользователя криптограмму Google Pay (paymentMethodToken) и получите идентификатор транзакции Google (googleTransactionId). Для этого следуйте инструкциям Google Pay для Android.

При создании объекта PaymentDataRequest задайте следующие параметры токенизации:

Параметр токенизации Значение
type PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY
gateway yandexcheckout
gatewayMerchantId Идентификатор магазина (shopId в личном кабинете)

Шаг 2. Создайте платеж

Пример запроса на создание платежа с криптограммой Google 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": "google_pay",
          "google_transaction_id": "<googleTransactionId>",
          "payment_method_token": "<paymentMethodToken>"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'google_pay',
                'google_transaction_id' => '<googleTransactionId>',
                'payment_method_token' => '<paymentMethodToken>',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "google_pay",
        "google_transaction_id": "<googleTransactionId>",
        "payment_method_token": "<paymentMethodToken>"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22f504f4-000f-5000-8000-10d80496bbca",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-08-02T11:55:33.562Z",
  "description": "Заказ №72",
  "expires_at": "2018-08-09T11:55:36.108Z",
  "metadata": {},
  "payment_method": {
    "type": "google_pay",
    "id": "22f504f4-000f-5000-8000-10d80496bbca",
    "saved": false
  },
  "test": false
}

Отправьте Яндекс.Кассе запрос на создание платежа, в объекте payment_method_data передайте тип google_pay, криптограмму Google Pay (payment_method_token) и идентификатор транзакции Google (google_transaction_id).

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

Подтвердите платеж с помощью метода capture. После этого платеж перейдет в статус succeeded.

QIWI Кошелек

Пример запроса на создание платежа с оплатой из QIWI Кошелька

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": "qiwi",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'qiwi',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "qiwi",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d258-000f-5000-a000-1c541a0670fc",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://w.qiwi.com/order/external/main.action?successUrl=https%3A%2F%2Fwww.merchant-website.com%2Freturn_url&failUrl=https%3A%2F%2Fwww.merchant-website.com%2Freturn_url&shop=474093&transaction=62059088b185a4408118654c31894e8bQW"
  },
  "created_at": "2018-06-27T16:43:04.184Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "qiwi",
    "id": "22c5d258-000f-5000-a000-1c541a0670fc",
    "saved": false
  },
  "test": false
}

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

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

Webmoney

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

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": "webmoney"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'webmoney',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "webmoney"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d32a-000f-5000-a000-176b8fb6c8a9",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://merchant.webmoney.ru/lmi/payment.asp?gid=007A174F-3EE6-48B6-80D9-4E2406780E23"
  },
  "created_at": "2018-06-27T16:46:34.782Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "webmoney",
    "id": "22c5d32a-000f-5000-a000-176b8fb6c8a9",
    "saved": false
  },
  "test": false
}

Чтобы принять оплату через Webmoney, необходимо создать платеж с типом оплаты webmoney и реализовать сценарий подтверждения Redirect.

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип webmoney;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).
  2. Перенаправьте пользователя на страницу для подтверждения оплаты (ссылка на страницу придет в параметре confirmation_url).
  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": "mobile_balance",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "external"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'mobile_balance',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'external',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "mobile_balance",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "external"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "external"
  },
  "created_at": "2018-06-29T09:22:09.367Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "mobile_balance",
    "id": "22c80e01-000f-5000-a000-14ce15eb7b74",
    "saved": false
  },
  "test": false
}

Чтобы принять оплату с баланса мобильного телефона, необходимо создать платеж с типом оплаты mobile_balance и реализовать сценарий подтверждения External.

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип mobile_balance и телефон пользователя, с баланса которого планируется принять оплату;
    • в объекте confirmation передайте тип external.
  2. Сообщите пользователю, что ему необходимо подтвердить оплату.
  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": "cash",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'cash',
                'phone' => '79000000000',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "cash",
        "phone": "79000000000"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d3e2-000f-5000-8000-10a783a9392b",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/api-pages/v2/payment-confirm/cash?orderId=22c5d3e2-000f-5000-8000-10a783a9392b"
  },
  "created_at": "2018-06-27T16:49:38.669Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "cash",
    "id": "22c5d3e2-000f-5000-8000-10a783a9392b",
    "saved": false
  },
  "test": false
}

Чтобы принять оплату наличными через терминал или в офисе партнера, необходимо создать платеж с типом оплаты cash и реализовать сценарий подтверждения Redirect.

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип cash и, если известен, телефон пользователя, на который придет код подтверждения платежа;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).
  2. Перенаправьте пользователя на страницу для получения кода платежа (ссылка на страницу придет в параметре confirmation_url).
  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": "installments"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 2,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'installments',
            ),
            'confirmation' => array(
                'type' => 'redirect',
                'return_url' => 'https://www.merchant-website.com/return_url',
            ),
            'description' => 'Заказ №72',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "payment_method_data": {
        "type": "installments"
    },
    "confirmation": {
        "type": "redirect",
        "return_url": "https://www.merchant-website.com/return_url"
    },
    "description": "Заказ №72"
})

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

{
  "id": "22c5d4d1-000f-5000-a000-1060585f5f12",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://money.yandex.ru/credit/order/step/options?orderId=22c5d4d1-000f-5000-a000-1060585f5f12"
  },
  "created_at": "2018-06-27T16:53:37.322Z",
  "description": "Заказ №72",
  "metadata": {},
  "payment_method": {
    "type": "installments",
    "id": "22c5d4d1-000f-5000-a000-1060585f5f12",
    "saved": false
  },
  "test": false
}

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

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип installments;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).
  2. Перенаправьте пользователя на страницу для подтверждения оплаты (ссылка на страницу придет в параметре confirmation_url).
  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": "50.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "b2b_sberbank",
          "payment_purpose": "Оплата заказа №2134",
          "vat_data": {
            "type": "calculated",
            "rate": 18,
            "amount": {
              "value": 9.00,
              "currency": "RUB"
            }
          }
        },
        "confirmation": {
          "type": "redirect"
        },
        "capture": true,
        "description": "Оплата заказа №2134"
      }'
<?php
    $client->createPayment(
        array(
            'amount' => array(
                'value' => 50,
                'currency' => 'RUB',
            ),
            'payment_method_data' => array(
                'type' => 'b2b_sberbank',
                'payment_purpose' => 'Оплата заказа №2134',
                'vat_data' => array(
                    'type' => 'calculated',
                    'rate' => 18,
                    'amount' => array(
                        'value' => 9,
                        'currency' => 'RUB',
                    ),
                ),
            ),
            'confirmation' => array(
                'type' => 'redirect',
            ),
            'capture' => true,
            'description' => 'Оплата заказа №2134',
        ),
        uniqid('', true)
    );
?>
payment = Payment.create({
    "amount": {
        "value": "50.00",
        "currency": "RUB"
    },
    "payment_method_data": {
      "type": "b2b_sberbank",
      "payment_purpose": "Оплата заказа №2134",
      "vat_data": {
        "type": "calculated",
        "rate": 18,
        "amount": {
          "value": 9.00,
          "currency": "RUB"
        }
      }
    },
    "confirmation": {
        "type": "redirect"
    },
    "capture": true,
    "description": "Оплата заказа №2134"
})

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

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "50.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "http://b2bsberbank.confirmation.url?orderId=1da5c87d-0984-50e8-a7f3-8de646dd9ec9"
  },
  "created_at": "2017-06-29T22:20:00.000Z",
  "description": "Оплата заказа №2134",
  "metadata": {},
  "payment_method": {
    "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
    "type": "b2b_sberbank",
    "saved": false,
    "payment_purpose": "Оплата заказа №2134",
    "vat_data": {
      "type": "calculated",
      "amount": {
        "value": "9.00",
        "currency": "RUB"
      },
      "rate": "18"
    }
  },
  "test": false,
}

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

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "50.00",
    "currency": "RUB"
  },
  "captured_at": "2017-06-29T22:30:00.000Z",
  "created_at": "2017-06-29T22:20:00.000Z",
  "description": "Оплата заказа №2134",
  "metadata": {},
  "payment_method": {
    "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
    "type": "b2b_sberbank",
    "saved": false,
    "payer_bank_details": {
      "account": "40702810355002135468",
      "address": "197111, Российская Федерация, г.Санкт-Петербург, ул.3-й Северовокзальный, д.17, корп./стр.2, кв.16",
      "bank_bik": "044030653",
      "bank_branch": "СЕВЕРО-ЗАПАДНЫЙ БАНК СБЕРБАНКА РФ",
      "bank_name": "СЕВЕРО-ЗАПАДНЫЙ БАНК ПАО СБЕРБАНК",
      "full_name": "Общество с ограниченной ответственностью 'Организация'",
      "inn": "7728662610",
      "kpp": "783501610",
      "short_name": "ООО 'Организация'"
    },
    "payment_purpose": "Оплата заказа №2134",
    "vat_data": {
      "type": "calculated",
      "amount": {
        "value": "9.00",
        "currency": "RUB"
      },
      "rate": "18"
    }
  },
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

Этот способ оплаты позволяет получать деньги от ИП и юридических лиц, которые подключены к сервису Сбербанк Бизнес Онлайн.

Чтобы подключить этот способ оплаты, вам нужно:

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

  1. Создайте платеж:
    • в объекте payment_method_data передайте тип b2b_sberbank, опишите назначение платежа и укажите информацию об НДС;
    • в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url);
    • в параметре capture передайте значение true, чтобы платеж автоматически перешел в статус succeded после оплаты пользователем.
  2. Перенаправьте пользователя на страницу для подтверждения оплаты (ссылка на страницу придет в параметре confirmation_url).
  3. Дождитесь подтверждения платежа пользователем: подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже.

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

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

Подключение

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

Переход на ФФД 1.05

С 1 января 2019 года вступает в силу новый формат фискальных документов (ФФД 1.05), и в чеке нужно будет передавать дополнительные параметры:

Если вы уже пользуетесь решением Яндекс.Кассы, вам нужно перейти на новый формат. Порядок перехода зависит от вашей онлайн-кассы.

АТОЛ Онлайн

  1. Сначала доработайте интеграцию по API Яндекс.Кассы и начните передавать новые параметры (payment_subject и payment_mode).
  2. Когда всё будет настроено, зайдите в личный кабинет АТОЛ и переключитесь на новый формат фискальных документов.

Orange Data

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

МодульКасса и Бизнес.Ру Онлайн-Чеки

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

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

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

До начала проведения платежей вы должны выбрать в настройках в личном кабинете способ отправки чека онлайн-кассе:

Проведение платежа с учетом требований 54-ФЗ

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

<?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": "227cf565-000f-5000-8000-1c9d1c6000fb",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-05-03T10:17:31.487Z",
  "created_at": "2018-05-03T10:17:09.337Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "227cf565-000f-5000-8000-1c9d1c6000fb",
    "saved": false,
    "card": {
      "first6": "411111",
      "last4": "1111",
      "expiry_month": "01",
      "expiry_year": "2020",
      "card_type": "Visa"
    },
    "title": "Bank card *1111"
  },
  "receipt_registration": "pending",
  "recipient": {
    "account_id": "67192",
    "gateway_id": "352780"
  },
  "refunded_amount": {
    "value": "2.00",
    "currency": "RUB"
  }
}
  1. Создайте платеж, в объекте receipt передайте данные для формирования чека. Эти данные Яндекс.Касса отправит вашей онлайн-кассе.

  2. При необходимости дождитесь, когда платеж перейдет в статус waiting_for_capture, и подтвердите его.

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

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

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

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

<?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:

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

Код системы налогообложения передается в объекте 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

Признак предмета расчета

Признак предмета расчета передается в объекте receipt, в параметре payment_subject. Возможные значения:

Значение Описание
commodity Товар
excise Подакцизный товар
job Работа
service Услуга
gambling_bet Ставка в азартной игре
gambling_prize Выигрыш в азартной игре
lottery Лотерейный билет
lottery_prize Выигрыш в лотерею
intellectual_activity Результаты интеллектуальной деятельности
payment Платеж
agent_commission Агентское вознаграждение
composite Несколько вариантов
another Другое

Признак способа расчета

Признак способа расчета передается в объекте receipt, в параметре payment_mode. Возможные значения:

Значение Описание
full_prepayment Полная предоплата
partial_prepayment Частичная предоплата
advance Аванс
full_payment Полный расчет
partial_payment Частичный расчет и кредит
credit Кредит
credit_payment Выплата по кредиту

Уведомления

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

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

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

{
  "type": "notification",
  "event": "payment.waiting_for_capture",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "waiting_for_capture",
    "paid": true,
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000"
    },
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Заказ №72",
    "expires_at": "2018-07-17T14:28:32.484Z",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22d6d597-000f-5000-9000-145f6df21d6f",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2021",
        "card_type": "MasterCard"
      },
      "title": "Bank card *4444"
    },
    "test": false
  }
}

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

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

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

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

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

Как отвечать

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

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

Как обрабатывать с помощью SDK

Как получить данные из POST-запроса

<?php
  $source = file_get_contents('php://input');
  $json = json_decode($source, true);
?>
Как создать объект класса уведомления
NotificationSucceeded или NotificationWaitingForCapture

<?php
try {
  $notification = ($json['event'] === YandexCheckout\Model\NotificationEventType::PAYMENT_SUCCEEDED)
    ? new NotificationSucceeded($json)
    : new NotificationWaitingForCapture($json);
} catch (Exception $e) {
  // Обработка ошибок при неверных данных
}
?>
Как получить объект платежа

<?php
  $payment = $notification->getObject();
?>
# Как получить данные из POST-запроса

import json
from django.http import HttpResponse

def my_webhook_handler(request):
    event_json = json.loads(request.body)
    return HttpResponse(status=200)
# Как создать объект класса уведомления
# NotificationSucceeded или NotificationWaitingForCapture

try:
    notification_object = WebhookNotification(event_json)
except Exception:
    # обработка ошибок

# Как получить объект платежа
   payment = notification_object.object
# Пример обработки уведомления

import json
from django.http import HttpResponse
from yandex_checkout import WebhookNotification


def my_webhook_view(request):
    event_json = json.loads(request.body)
    try:
        notification_object = WebhookNotification(event_json)
    except Exception:

    return HttpResponse(status=200)

Вы можете обрабатывать уведомления с помощью наших библиотек:

  1. Получите данные из POST-запроса от Яндекс.Кассы.

  2. Cоздайте объект класса уведомлений в зависимости от события.

  3. Получите объект платежа.

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

Тестовый магазин

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

Тестовый магазин появится в личном кабинете Яндекс.Кассы после того, как вы заполните анкету об организации (и менеджер ее проверит) и отправите технические настройки.

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

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

Возможности

Вы можете протестировать всю функциональность API для следующих способов оплаты:

Оплата банковской картой

Для тестовых магазинов необходимо использовать только тестовые банковские карты:

Проверка успешных сценариев

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

Номер Тип карты
5555555555554477 MasterCard (с 3-D Secure)
5555555555554444 MasterCard
6759649826438453 Maestro
4111111111111111 Visa
4175001000000017 Visa Electron
370000000000002 American Express
3528000700000000 JCB
36700102000000 Diners Club

Проверка неуспешных сценариев

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

Если вы хотите проверить значение параметра cancellation_details при отмене платежа «внешними» участниками платежного процесса или Яндекс.Кассой, используйте тестовые банковские карты:

Отмена транзакции «внешними» участниками платежного процесса (payment_network)

Номер карты Причина отмены платежа
5555555555554592 3d_secure_failed
5555555555554535 call_issuer
5555555555554543 card_expired
5555555555554568 fraud_suspected
5555555555554527 general_decline
5555555555554600 insufficient_funds
5555555555554618 invalid_card_number
5555555555554626 invalid_csc
5555555555554501 issuer_unavailable
5555555555554576 payment_method_limit_exceeded
5555555555554550 payment_method_restricted

Отмена транзакции Яндекс.Кассой (yandex_checkout)

Номер карты Причина отмены платежа
5555555555554584 country_forbidden
5555555555554634 fraud_suspected

Оплата из кошелька в Яндекс.Деньгах

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

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

Реестры

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

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

Реестры платежей от частных лиц

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

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

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

Реестры платежей от юридических лиц и ИП

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

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

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

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

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

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