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

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

.. contents::
  :local:

.. role:: ex

.. role:: code

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

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

.. _api_v2_pan-eligibility_form_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-form/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/send-form/ENDPOINTID`
   * - Receiving-only
     - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/pan-eligibility/receive-form/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/receive-form/ENDPOINTID`
   * - Both
     - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/pan-eligibility/both-form/ENDPOINTID`
     - :ex:`https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/both-form/ENDPOINTID`

.. _api_v2_pan-eligibility_form_request_parameters:

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

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

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

  * - Parameter Name
    - Description
    - Value
  * - :code:`client_orderid`
    - Unique order identifier assigned by Connecting Party.
    - | ``Necessity``: Required
      | ``Type``: String
      | ``Length``: 128
  * - :code:`redirect_url`
    - | URL, where the Payer is redirected to upon completion of the transaction.
        Please note that redirection is performed in any case, no matter whether transaction is :ex:`approved`, :ex:`declined` in any other final :ref:`status<statuses>`.
      | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
        Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Pass :ex:`https://doc.payneteasy.com` if you have no need to return payer anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 128
  * - :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``: 128
  * - :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``: 128

.. _api_v2_pan-eligibility-form_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-form Request Example
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

    POST /paynet/api/v2/pan-eligibility/send-form/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="javid_test_merch",oauth_timestamp="1687507473",oauth_nonce="Gs2vcwIXv6H",oauth_signature_method="HMAC-SHA1",oauth_signature="sMQWXIUY0OTgBzt2OavSFhT3Q3s%3D"
    Content-Length: 192
    Content-Type: application/x-www-form-urlencoded
    Connection: close

    client-order-id=1234567890
    &oauth_consumer_key=test_merch
    &oauth_nonce=Gs2vcwIXv6H
    &oauth_signature_method=HMAC-SHA1
    &oauth_timestamp=1687507473
    &oauth_version=1.0
    &redirect-url=http%3A%2F%2Fsandbox.payneteasy.com%2Fdoc%2Fdummy.htm

Send-form 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-000002ec863e
   &merchant-order-id=1234567890
   &paynet-order-id=7211136
   &redirect-url=https%3A%2F%2Fsandbox.payneteasy.com%2Fpaynet%2Fform%2Fpan-eligibility%2Finit%2FBB3757784F4A53585143535A554E2F4D6A3264715A616E744C6C31667043414962654534575039376E636F343D

Send-form Fail Response Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

   HTTP/1.1 200 OK
   Server: server
   Date: Mon, 22 Aug 2022 12:59:09 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-form Request Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

   POST /paynet/api/v2/pan-eligibility/receive-form/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="javid_test_merch",oauth_timestamp="1687511712",oauth_nonce="cRmRev3FdaP",oauth_signature_method="HMAC-SHA1",oauth_signature="6zWG0Sli0dehdFikhoGdoEqhcQA%3D"
   Content-Length: 226
   Content-Type: application/x-www-form-urlencoded
   Connection: close

   client-order-id=1234567890
   &oauth_consumer_key=test_merch
   &oauth_nonce=cRmRev3FdaP
   &oauth_signature_method=HMAC-SHA1
   &oauth_timestamp=1687511712
   &oauth_version=1.0
   &redirect-url=http%3A%2F%2Fsandbox.payneteasy.com%2Fdoc%2Fdummy.htm

Receive-form 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-000002ec863e
   &merchant-order-id=1234567890
   &paynet-order-id=7211136
   &redirect-url=https%3A%2F%2Fsandbox.payneteasy.com%2Fpaynet%2Fform%2Fpan-eligibility%2Finit%2FBB3757784F4A53585143535A554E2F4D6A3264715A616E744C6C316670434149626545436159574254497A4D3D

Receive-form Fail Response Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

   HTTP/1.1 200 OK
   Server: server
   Date: Mon, 22 Aug 2022 12:59:09 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-form Request Example
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

    POST /paynet/api/v2/pan-eligibility/both-form/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="javid_test_merch",oauth_timestamp="1687512444",oauth_nonce="Nu8SL8l70H2",oauth_signature_method="HMAC-SHA1",oauth_signature="wypHgzYjxmKrdshhj1CabwPGnnA%3D"
    Content-Length: 226
    Content-Type: application/x-www-form-urlencoded
    Connection: close

    client-order-id=1234567890
    &oauth_consumer_key=test_merch
    &oauth_nonce=Gs2vcwIXv6H
    &oauth_signature_method=HMAC-SHA1
    &oauth_timestamp=1687507765
    &oauth_version=1.0
    &redirect-url=http%3A%2F%2Fsandbox.payneteasy.com%2Fdoc%2Fdummy.htm

Both-form Success Response Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

   HTTP/1.1 200
   Server: server
   Date: Wed, 21 Jun 2023 13: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-000002ec863e
   &merchant-order-id=1234567890
   &paynet-order-id=7211136
   &redirect-url=https%3A%2F%2Fsandbox.payneteasy.com%2Fpaynet%2Fform%2Fpan-eligibility%2Finit%2FBB3757784F4A53585143535A554E2F4D6A3264715A616E744C6C31667043414962654534575039376E636F343D

Both-form Fail Response Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

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

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

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