.. _api-v2-card-ref-id:

/api/v2/create-card-ref
####################################

.. contents::
  :local:

.. role:: ex

.. role:: code

Introduction
^^^^^^^^^^^^^^^^^^^^^^^^^^

Card reference ID creation is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_v2_card-ref-id_request_url>` and the :ref:`parameters<card-ref-id_request_parameters>` specified below. Use :ref:`SHA-1<SHA1>` for authentication.

.. _api_v2_card-ref-id_request_url:

API URLs
^^^^^^^^^^^^^^^^^^^^^^

.. note::
    | The path in API URL should not be hardcoded, as it may be changed in future.

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

   * - Integration
     - Production
   * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/create-card-ref/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/create-card-ref/ENDPOINTID`
   * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID`

Request Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
  | Request must have content-type=application/x-www-form-urlencoded.

.. _card-ref-id_request_parameters:

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

   * - Get Card Ref Request Parameters
     - Description
   * - :code:`login`
     - | Connecting Party's login name.
   * - :code:`client_orderid`
     - | Connecting Party’s order identifier of the transaction.
   * - :code:`orderid`
     - | Transaction order identifier assigned by Payment Gateway.
   * - :code:`control`
     - | Checksum generated by :ref:`SHA-1<SHA1>`. Control string is represented as concatenation of the following parameters:
       | 1. Request parameter: :ex:`login`
       | 2. Request parameter: :ex:`client_orderid`
       | 3. Request parameter: :ex:`orderid`
       | 4. :ex:`merchant_control` (Control key assigned to Connecting Party account in the Payneteasy gateway system).

Connecting Party has to supply :code:`orderid` and :code:`client_orderid` associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurring payments. To authorize the credit card the information about it must be sufficient and an initial payment must be in :ref:`final status<statuses>`.

The returned Recurring Payment ID and/or Card Reference ID is a token that refers to cardholder data stored on Payment Gateway side. See the required API command to find which type of token is supported in request parameters. This ID has the following usage:
1. In direct API commands it can be passed instead of cardholder data to initiate new transaction.
2. In form API commands it can be passed to prefill the payment form with previously saved cardholder data.

Response Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
  | Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.

.. _api_v2_card-ref-id_response_parameters:

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

   * - Registration Response Parameters
     - Description
   * - :code:`type`
     - | The type of response. May be :ex:`async-response`, :ex:`validation-error`, :ex:`error` etc.
       | If type equals :ex:`validation-error` or :ex:`error`, :ex:`error-message` and :ex:`error-code` parameters contain error details.
   * - :code:`serial-number`
     - Unique number assigned by Payneteasy server to particular request from the Connecting Party.
   * - :code:`card-ref-id`
     - Card reference ID to used in subsequent recurring payments.
   * - :code:`unq-card-ref-id`
     - Unique card reference ID to each :ex:`PAN`. It can be used by Connecting Party for loyalty programs or fraud control.
   * - :code:`status`
     - | See :ref:`Status List<status_list>` for details.
   * - :code:`error-message`
     - If status is :ex:`declined` or :ex:`error` this parameter contains the reason for decline.
   * - :code:`error-code`
     - The error code is case of :ex:`declined` or :ex:`error` status.

Request Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: none

    POST /paynet/api/v2/create-card-ref/46750 HTTP/1.1
    Host: https://sandbox.payneteasy.com
    User-Agent: curl/7.85.0
    Accept: */*
    Content-Length: 100
    Content-Type: application/x-www-form-urlencoded
    Connection: close

    login=login
    &client_orderid=902B4FF5
    &orderid=6937242
    &control=717349cab3fcab2c13c93ff5770ae07a7b8e0727

Success Response Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: none

    HTTP/1.1 200
    Server: server
    Date: Tue, 07 Feb 2023 08:46:24 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: 144

    type=create-card-ref-response
    &serial-number=00000000-0000-0000-0000-000002e110a2
    &card-ref-id=1461670
    &unq-card-ref-id=2463777
    &status=approved

Fail Response Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: none

    HTTP/1.1 200
    Server: server
    Date: Tue, 07 Feb 2023 08:55:26 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: 123

    type=validation-error
    &serial-number=00000000-0000-0000-0000-000002e110ad
    &error-message=INVALID_CONTROL_CODE
    &error-code=2

Postman Collection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Request Builder
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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