.. meta::
   :description: Endpoint API /api/v4/create-card-ref Payneteasy: создание рекуррентной ссылки на карту (токена) из ранее одобренной v4-транзакции.

.. _api-v4-card-ref-id:

/api/v4/create-card-ref
########################


.. role:: ex

.. role:: code

Введение
^^^^^^^^^^^^

Создание Card reference ID и Recurring Payment ID инициируется через :code:`HTTPS POST` запрос с использованием :ref:`URL<api_v4_card-ref-id_request_url>` и :ref:`параметров<v4_card-ref-id_request_parameters>`, указанных ниже. Для аутентификации используйте :ref:`RSA-SHA256`.

.. _api_v4_card-ref-id_request_url:

API URL
^^^^^^^^

.. note::
    | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее.

.. list-table::
   :widths: 50, 50
   :header-rows: 1
   :class: longtable

   * - Интеграционная среда
     - Производственная среда
   * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v4/create-card-ref/ENDPOINTID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v4/create-card-ref/ENDPOINTID`
   * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID`


Параметры запроса
^^^^^^^^^^^^^^^^^^

.. note::
  | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации<RSA-SHA256>`.

.. _v4_card-ref-id_request_parameters:

.. list-table::
   :widths: 25, 75
   :header-rows: 1
   :class: longtable

   * - Параметры запроса Sale
     - Описание
   * - :code:`login`
     - | Логин Присоединяющейся стороны в Системе.
   * - :code:`client_orderid`
     - | Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной.
   * - :code:`orderid`
     - | Идентификатор заказа транзакции, присвоенный Платёжным Шлюзом.

Присоединяющаяся Сторона должна предоставить:code:`orderid` и:code:`client_orderid`, связанные с первой платёжной транзакцией. Это подчёркивает, что первый платёж является обязательным шагом для обработки рекуррентных платежей. Для авторизации кредитной карты информация о ней должна быть достаточной, а первоначальный платёж должен находиться в:ref:`финальном статусе<statuses>`.

Параметры ответа
^^^^^^^^^^^^^^^^^^^

.. note::
  | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра.

.. _api_v4_card-ref-id_response_parameters:

.. list-table::
   :widths: 35, 65
   :header-rows: 1
   :class: longtable

   * - Параметр ответа на регистрацию
     - Описание
   * - :code:`type`
     - Тип ответа. Может быть :ex:`create-card-ref-response`, :ex:`validation-error`, :ex:`error`. Если type равен :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` содержат детали ошибки.
   * - :code:`serial-number`
     - Уникальный номер, присваиваемый сервером Payneteasy конкретному запросу от Присоединяющейся стороны.
   * - :code:`card-ref-id`
     - Card reference ID, используемый в последующих рекуррентных платежах.
   * - :code:`unq-card-ref-id`
     - Уникальный идентификатор ссылки на карту для каждого :ex:`PAN`. Может использоваться Присоединяющейся стороной для программ лояльности или контроля мошенничества.
   * - :code:`recurring-payment-id`
     - ID токенизированных данных держателя карты Плательщика, называемый Recurring Payment ID (RPI).
   * - :code:`dst-card-ref-id`
     - Card reference ID Получателя, используемый в последующих рекуррентных платежах. Может использоваться только в transfer API.
   * - :code:`dst-unq-card-ref-id`
     - Уникальный card reference ID Получателя для каждого :ex:`PAN`. Может использоваться Присоединяющейся Стороной для программ лояльности или контроля фрода. Может использоваться только в transfer API.
   * - :code:`dst-recurring-payment-id`
     - ID токенизированных данных держателя карты Получателя, называемый Recurring Payment ID (RPI). Может использоваться только в transfer API.
   * - :code:`error-message`
     - Для транзакций в статусе:ex:`declined` или:ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке.
   * - :code:`error-code`
     - Код ошибки для транзакций в статусе:ex:`declined` или:ex:`error`.
   * - :code:`status`
     - Подробности см. в :ref:`status_list`.

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

.. code-block:: none

    POST /paynet/api/v4/create-card-ref/39915 HTTP/1.1
    Host: sandbox.payneteasy.ru
    User-Agent: curl/7.83.0
    Accept: */*
    Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="KT6cZmuVGqg0V6Jm2RE3q4o79KXC1v2q", oauth_signature="KucF0eYk3WZCV7oKwOi1z6PR%2BkHxiZwPucD6Sx%2BX2mV%2BbaidPy9K9USh8ciMKM60NNl1LYYjywdaErB1uTIdFFbQ8ZKs8M1smaMPOaHDaApceTOlDh6E7u3BzBTKYhBc%2BWnksZz9Wyz8%2B39lHCIODo0KZmNmXCTjjZmlx%2FrFNkK%2FhwJV9Kwq1nPbA5QZTkF686O0O0lHFy3Prx649AIRgsrqDLb5%2FgHL9M8fSScVUPnGdLGJ2hSgKJFpIOFibT0nC89Xg8odn1hR9WIa1650glaqZntSkocBzXAkOKa7kIbSOZW1sFCiBjksy6o1sny9hmc%2F9cC9t86RoEY1QhVYuvOLztQm1dLhpRy%2FPOL9LCmIzO3B%2FUB2wJUXPkEyFsSLZVeqQl%2B0IukljV6Cr1ZfuyUktbvvXJsnod5AK%2FsV2GaxEf%2BttqqWv%2FFNjPLoUZYrPB6rKsIpw%2FOftinIwIxYzLY3FMmbKQd6zxnMJLJm7M2s6cQFGiAnfgvZFAMZhugBuuigy4T9Ckq1t5N9vQkl2htDv0TTnswx50wpF%2F7OKiXTVFNqOE%2FCj%2F07ZwZbxbD%2FMxKhOhfNMME1jGxzgI0wEj1166eKpxnCOk%2BTlYTJvNW5%2BbKuGnU43Q2Nmga0aQ007NKRfIV%2FWk6e%2BUuGO48wGdi0CiKxS9hpnpvjyPLc%2BsA%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1673335450", oauth_version="1.0"
    Content-Length: 40
    Content-Type: application/x-www-form-urlencoded
    Connection: close

    client_orderid=34T43R77N
    &orderid=6868305

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

.. code-block:: none

    HTTP/1.1 200
    Server: server
    Date: Tue, 10 Jan 2023 07:24:36 GMT
    Content-Type: text/html;charset=utf-8
    Connection: close
    Vary: Accept-Encoding
    X-XSS-Protection: 1
    X-Content-Type-Options: nosniff
    Strict-Transport-Security: max-age=31536000
    Content-Language: en-US
    Strict-Transport-Security: max-age=31536000
    Content-Length: 174

    type=create-card-ref-response
    &serial-number=00000000-0000-0000-0000-000002de3113
    &card-ref-id=1461608
    &recurring-payment-id=1491863
    &dst-card-ref-id=1461608
    &status=approved


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

.. code-block:: none

    HTTP/1.1 403
    Server: server
    Date: Tue, 10 Jan 2023 07:34:08 GMT
    Content-Type: text/html
    Content-Length: 735
    Connection: close
    X-XSS-Protection: 1
    X-Content-Type-Options: nosniff
    Strict-Transport-Security: max-age=31536000

    <!DOCTYPE html>
    <html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
        <title>403</title>

        <style type="text/css">
            body {
                font-family: Arial, sans-serif;
                font-size: 130%;
                background-color: #eee;
            }

            p {
                margin: 10em auto 0;
                width: 500px;
                border: 1px solid gray;
                text-align: center;
                vertical-align: middle;
                padding: 40px 20px;
                background-color: #fff;
                -webkit-border-radius: 20px;
                -moz-border-radius: 20px;
                border-radius: 20px;
            }
        </style>
    </head>

    <body>
        <p>Access is denied</p>
    </body>
    </html>


Коллекция Postman
^^^^^^^^^^^^^^^^^^

.. raw:: html
    :file: ../_static/Postman/Postman_recurrent_v4.html

Конструктор запросов
^^^^^^^^^^^^^^^

| Вставьте приватный ключ PKCS#1 PEM для среды sandbox в поле ниже. Конструктор запросов поддерживает длину ключа до 4096.

.. raw:: html
      :file: ../_static/examples/recurrent_transaction_Request_V4_Debug.html