.. _/api/v2/pan-eligibility/:

/api/v2/pan-eligibility
########################

.. contents::
  :local:

.. role:: ex

.. role:: code

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

PAN Eligibility is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_v2_pan-eligibility_request_url>` and the :ref:`parameters<api_v2_pan-eligibility_request_parameters>` specified below. Use :ref:`OAuth HMAC-SHA1<HMAC-SHA1>` for authentication. See :ref:`statuses`.

.. _api_v2_pan-eligibility_request_url:

PAN Eligibility API URLs
^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
    | The path in API URL should not be hardcoded, as it may be changed in future.
.. list-table::
   :widths: 15, 45, 40
   :header-rows: 1
   :class: longtable

   * - Method
     - Integration
     - Production
   * - Sending-only
     - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/pan-eligibility/send/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/send/ENDPOINTID`
   * - Receiving-only
     - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/pan-eligibility/receive/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/receive/ENDPOINTID`
   * - Both
     - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/pan-eligibility/both/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/both/ENDPOINTID`


.. _api_v2_pan-eligibility_request_parameters:

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

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

.. tabs::

   .. tab:: Sending-only

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

         * - Parameter
           - Description
           - Value
         * - :code:`client_orderid`
           - Connecting Party order ID.
           - | ``Necessity``: Required
             | ``Type``: String
             | ``Length``: 128
         * - :code:`sending-card-number`
           - | Sender`s credit card number.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 19
         * - :code:`card-printed-name`
           - | Sender`s card printed name.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: String
             | ``Length``: 128
         * - :code:`expire-month`
           - | Sender credit card’s month of expiration.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 2
         * - :code:`expire-year`
           - | Sender credit card’s year of expiration.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 4
         * - :code:`sending-card-ref-id`
           - | Sender`s card ref ID.
             | (if :ex:`sending-card-number` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 20
         * - :code:`server_callback_url`
           - | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`notify_url`. If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).
           - | ``Necessity``: Optional
             | ``Type``: String
             | ``Length``: 1024
         * - :code:`notify_url`
           - | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`notify_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`server_callback_url`. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status.
           - | ``Necessity``: Optional
             | ``Type``: String
             | ``Length``: 1024

   .. tab:: Receiving-only

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

         * - Parameter
           - Description
           - Value
         * - :code:`client_orderid`
           - Connecting Party order ID.
           - | ``Necessity``: Required
             | ``Type``: String
             | ``Length``: 128
         * - :code:`receiving-card-number`
           - | Receiver`s credit card number.
             | (if :ex:`receiving-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 19
         * - :code:`receiving-card-ref-id`
           - | Receiver`s card ref ID.
             | (if :ex:`receiving-card-number` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``:
         * - :code:`server_callback_url`
           - | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`notify_url`. If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).
           - | ``Necessity``: Optional
             | ``Type``: String
             | ``Length``: 1024
         * - :code:`notify_url`
           - | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`notify_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`server_callback_url`. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status.
           - | ``Necessity``: Optional
             | ``Type``: String
             | ``Length``: 1024

   .. tab:: Both

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

         * - Parameter
           - Description
           - Value
         * - :code:`client_orderid`
           - Connecting Party order ID.
           - | ``Necessity``: Required
             | ``Type``: String
             | ``Length``: 128
         * - :code:`sending-card-number`
           - | Sender`s card number.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 19
         * - :code:`card-printed-name`
           - | Sender`s card printed name.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: String
             | ``Length``: 128
         * - :code:`expire-month`
           - | Sender credit card’s month of expiration.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 2
         * - :code:`expire-year`
           - | Sender credit card’s year of expiration.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 4
         * - :code:`sending-card-ref-id`
           - | Sender`s card ref ID.
             | (if :ex:`sending-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 20
         * - :code:`receiving-card-number`
           - | Receiver`s card number.
             | (if :ex:`receiving-card-ref-id` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``: 19
         * - :code:`receiving-card-ref-id`
           - | Receiver`s card ref ID.
             | (if :ex:`receiving-card-number` is not specified)
           - | ``Necessity``: Required
             | ``Type``: Numeric
             | ``Length``:
         * - :code:`server_callback_url`
           - | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`notify_url`. If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).
           - | ``Necessity``: Optional
             | ``Type``: String
             | ``Length``: 1024
         * - :code:`notify_url`
           - | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`notify_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`server_callback_url`. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status.
           - | ``Necessity``: Optional
             | ``Type``: String
             | ``Length``: 1024

.. _api_v2_pan-eligibility_response_parameters:

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.

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

   * - 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:`paynet-order-id`
     - Order id assigned to the order by Payneteasy.
   * - :code:`merchant-order-id`
     - Connecting Party order id.
   * - :code:`serial-number`
     - Unique number assigned by Payneteasy server to particular request from the Connecting Party.
   * - :code:`error-message`
     - If status is :ex:`error` this parameter contains the reason for decline or error details.
   * - :code:`error-code`
     - The error code is case of :ex:`error` status.

Send Request Example
^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

   POST /paynet/api/v2/pan-eligibility/send/39907 HTTP/1.1
   Host: sandbox.payneteasy.com
   User-Agent: curl/7.83.0
   Accept: */*
   Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1687507082",oauth_nonce="XQkXQgLxhCE",oauth_signature_method="HMAC-SHA1",oauth_signature="lLTiOEyUY%2FwibmGVA%2F5rY6qIS9I%3D"
   Content-Length: 192
   Content-Type: application/x-www-form-urlencoded
   Connection: close

   client_orderid=1234567890
   &oauth_consumer_key=test_merch
   &oauth_nonce=XQkXQgLxhCE
   &oauth_signature_method=HMAC-SHA1
   &oauth_timestamp=1687507082
   &oauth_version=1.0
   &sending-card-ref-id=1461790

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

.. code-block:: javascript

   HTTP/1.1 200
   Server: server
   Date: Wed, 21 Jun 2023 11:19:20 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: 147

   type=async-response
   &serial-number=00000000-0000-0000-0000-000002ecbcba
   &merchant-order-id=1234567890
   &paynet-order-id=7216063
   &end-point-id=39907

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

.. code-block:: text

   HTTP/1.1 200 OK
   Server: server
   Date: Mon, 22 Aug 2022 11:19:20 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: 154

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

Receive Request Example
^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

   POST /paynet/api/v2/pan-eligibility/receive/39907 HTTP/1.1
   Host: sandbox.payneteasy.com
   User-Agent: curl/7.83.0
   Accept: */*
   Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1687507082",oauth_nonce="XQkXQgLxhCE",oauth_signature_method="HMAC-SHA1",oauth_signature="lLTiOEyUY%2FwibmGVA%2F5rY6qIS9I%3D"
   Content-Length: 192
   Content-Type: application/x-www-form-urlencoded
   Connection: close

   client_orderid=1234567890
   &oauth_consumer_key=test_merch
   &oauth_nonce=XQkXQgLxhCE
   &oauth_signature_method=HMAC-SHA1
   &oauth_timestamp=1687507082
   &oauth_version=1.0
   &receiving-card-number=4444555566661111

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

.. code-block:: javascript

   HTTP/1.1 200
   Server: server
   Date: Wed, 21 Jun 2023 12:19:20 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: 147

   type=async-response
   &serial-number=00000000-0000-0000-0000-000002ecbcba
   &merchant-order-id=1234567890
   &paynet-order-id=7216063
   &end-point-id=39907

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

.. code-block:: text

   HTTP/1.1 200 OK
   Server: server
   Date: Mon, 22 Aug 2022 12:19:29 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: 154

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

Both Request Example
^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

   POST /paynet/api/v2/pan-eligibility/both/39907 HTTP/1.1
   Host: sandbox.payneteasy.com
   User-Agent: curl/7.83.0
   Accept: */*
   Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1687513856",oauth_nonce="T0z9qml2rDZ",oauth_signature_method="HMAC-SHA1",oauth_signature="rsHewN7TRIxzPQAtd99z5eoSyJY%3D"
   Content-Length: 231
   Content-Type: application/x-www-form-urlencoded
   Connection: close

   client_orderid=1234567890
   &oauth_consumer_key=test_merch
   &oauth_nonce=T0z9qml2rDZ
   &oauth_signature_method=HMAC-SHA1
   &oauth_timestamp=1687513856
   &oauth_version=1.0
   &receiving-card-number=4444555566661111
   &sending-card-ref-id=1461790

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

.. code-block:: javascript

   HTTP/1.1 200
   Server: server
   Date: Fri, 23 Jun 2023 09:51:15 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: 146

   type=async-response
   &serial-number=00000000-0000-0000-0000-000002ecbcc2
   &merchant-order-id=1234567890
   &paynet-order-id=7216068
   &end-point-id=39907

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

.. code-block:: text

   HTTP/1.1 200 OK
   Server: server
   Date: Mon, 22 Aug 2022 13:19:29 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: 154

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

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

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

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

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