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

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

.. contents::
  :local:

.. role:: ex

.. role:: code

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

Card reference ID and Recurring Payment ID creation is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_v4_card-ref-id_request_url>` and the :ref:`parameters<v4_card-ref-id_request_parameters>` specified below. Use :ref:`RSA-SHA256` for authentication.

.. _api_v4_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/v4/create-card-ref/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v4/create-card-ref/ENDPOINTID`
   * - :ex:`https://sandbox.payneteasy.com/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID`


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

.. note::
  | Request must have content-type=application/x-www-form-urlencoded and :ref:`Authorization headers<RSA-SHA256>`.

.. _v4_card-ref-id_request_parameters:

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

   * - Sale 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.

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>`.

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_v4_card-ref-id_response_parameters:

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

   * - Registration Response Parameter
     - Description
   * - :code:`type`
     - The type of response. May be :ex:`create-card-ref-response`, :ex:`validation-error`, :ex:`error`. 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 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:`recurring-payment-id`
     - Payer’s tokenized cardholder's data ID, referred as Recurring Payment ID (RPI).
   * - :code:`dst-card-ref-id`
     - Receiver’s card reference ID used in subsequent recurring payments. Can be used only in transfer APIs.
   * - :code:`dst-unq-card-ref-id`
     - Receiver’s unique card reference ID to each :ex:`PAN`. It can be used by Connecting Party for loyalty programs or fraud control. Can be used only in transfer APIs.
   * - :code:`dst-recurring-payment-id`
     - Receiver’s tokenized cardholder's data ID, referred as Recurring Payment ID (RPI). Can be used only in transfer APIs.
   * - :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.
   * - :code:`status`
     - See :ref:`status_list` for details.

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

.. code-block:: none

    POST /paynet/api/v4/create-card-ref/39915 HTTP/1.1
    Host: sandbox.payneteasy.com
    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

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

.. 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


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

.. 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 Collection
^^^^^^^^^^^^^^^^^^

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

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

| Insert PKCS#1 PEM private key for sandbox environment in the field below. Request builder supports up to 4096 key length.

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